octoturge
42d4b3820a
The edge route had never been run. Adding a way to run it turned up that the server could not start at all, for two independent dependency reasons that typechecking could not see: - `elysia: ^1.1.26` had resolved to 1.4.30, which calls `t.Module` - a TypeBox 0.34 API - while this repo pinned TypeBox 0.33. `t.Module is not a function`. - `drizzle-typebox: ^0.2.1` resolved to a version whose peers demand `drizzle-orm >= 0.36`, against the `^0.33.0` pinned here. Importing it threw `Export named 'getViewSelectedFields' not found`. Both are caret ranges that drifted into combinations nobody chose. elysia, @sinclair/typebox and the drizzle packages are now pinned tightly, TypeBox forward to 0.34.52 (which satisfies Elysia and drizzle-typebox 0.1.1 alike), and tests/dependency_identity.test.ts fails if the TypeBox version ever differs between here and @continuum/ts-types - the skew that made every shared schema invalid, with an error message pointing at Standard Schema instead. Dropping to drizzle-typebox 0.1.1 widens `jsonb` in the generated validators, so `metadata` needs an explicit object shape in validators.ts; the column is declared `$type<Record<string, unknown>>()` and a validated body otherwise is not assignable to `.values()`. scripts/: - `install-docker.sh` - one-time host setup, kept separate because it touches the machine rather than containers. - `dev-env.sh up|down|reset|status|psql|schema|env` - Valkey + Postgres/pgvector. Uses docker-compose.yml when a daemon answers, and otherwise runs the same two services from apt. That fallback is not hypothetical: Docker cannot run in this sandbox at all. dockerd needs CAP_NET_ADMIN to build its bridge; with `--bridge=none --iptables=false` it starts but cannot unpack an image without CAP_SYS_ADMIN; with `--storage-driver=vfs` it still fails because registering a layer needs user namespaces, which are blocked outright. All three are host-level grants, so no script can work around them - hence a second path rather than a broken first one. - `e2e-edge.sh` - the test the unit tests cannot be. Seeds a farm, claims its printers, mints an edge token, runs the real continuum-proxy, and asserts live telemetry reached Postgres and a command reached a printer. It only sends a fan speed, only to a printer reporting IDLE, and puts it back afterwards. - `capture-gateway-frames.js` - records what a gateway really sends, for refreshing tests/fixtures/. Read-only unless FAN_TEST_PRINTER is set. The test comment referred to this before it existed. Verified end to end, from a dropped and freshly migrated database: `h2c` persisted as printing/RUNNING 22% layer 2/25 nozzle 230 bed 35 with 3 HMS alerts, `p1p` as idle/IDLE, and `POST /printers/:id/commands` reached the P1P's fan and came back ok:true. An unclaimed printer is refused 409 PRINTER_UNREACHABLE rather than guessed at. Two things the e2e script got wrong first, both now fixed in it: it waited for the first printer row instead of all of them, which silently tested only the v2 printer (a v1 Bambu reports one tick later); and `$!` after `( cd ... ) &` is the subshell, so cleanup left an orphaned gateway reconnecting with a token for a deleted farm and polluting the next run. Note: `drizzle/` is gitignored, so the generated migration is not committed and there is no migration history in the repo. Left as-is deliberately - that is a workflow call, flagged in PLAN.md.
77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# continuum-backend
|
|
|
|
Cloud control plane for Continuum. Bun + ElysiaJS, PostgreSQL (via pgCat/PgBouncer,
|
|
with pgvector for frame embeddings), Valkey Streams, and Cloudflare R2 storage.
|
|
|
|
## Run
|
|
|
|
```sh
|
|
bun install
|
|
scripts/dev-env.sh up # Valkey + Postgres/pgvector, and print the URLs
|
|
scripts/dev-env.sh schema # or: bun run db:migrate
|
|
cp .env.example .env # fill in the URLs it printed, plus R2_*, SUPABASE_JWT_SECRET
|
|
bun run dev
|
|
```
|
|
|
|
`scripts/dev-env.sh` uses `docker-compose.yml` when a Docker daemon is
|
|
answering, and falls back to the same two services from apt when there is no
|
|
usable container runtime - some sandboxes cannot run Docker at all, because
|
|
dockerd needs `CAP_NET_ADMIN` for its bridge and user namespaces to unpack an
|
|
image, and neither can be granted from inside. `scripts/dev-env.sh status`
|
|
says which backend is in use.
|
|
|
|
## Test
|
|
|
|
```sh
|
|
bun test # unit + protocol contract tests, no services needed
|
|
scripts/e2e-edge.sh # the whole edge path: real database, real printers
|
|
```
|
|
|
|
`scripts/e2e-edge.sh` seeds a farm, claims its printers, mints an edge token,
|
|
runs the real `continuum-proxy` against this backend, and asserts that live
|
|
telemetry reached Postgres and that a command reached a printer. It only ever
|
|
sends a fan speed, and only to a printer reporting `IDLE`.
|
|
`scripts/capture-gateway-frames.js` is the smaller tool: it stands in for this
|
|
backend and records what a gateway sends, for refreshing the fixtures in
|
|
`tests/fixtures/`.
|
|
|
|
## Layout
|
|
|
|
- `src/db/` - Drizzle schema (`printers`, `farms`, `print_jobs`, `frame_embeddings`)
|
|
and client, pointed at pgCat. `src/db/validators.ts` derives Elysia/TypeBox
|
|
request validators straight from the Drizzle tables via `drizzle-typebox`,
|
|
so the Postgres schema and the API validators come from one definition
|
|
instead of two hand-synced ones.
|
|
- `src/s3/` - R2 presigned URL helpers (`PUT` for client uploads, `GET` for the
|
|
edge proxy).
|
|
- `src/queue/` - Valkey client (`ioredis`) + `XADD` helper pushing onto
|
|
`stream:camera_frames` for `continuum-ai-worker`.
|
|
|
|
Valkey, not Redis: Redis 7.4+ is RSALv2/SSPL and 8.0+ adds AGPLv3, none of
|
|
which a commercial product can ship. Valkey is BSD-3-Clause and speaks the
|
|
same RESP protocol, so `ioredis` is unchanged - only the server differs. See
|
|
`continuum-common/docs/LICENSES.md`. `docker-compose.yml` here brings up
|
|
Valkey and Postgres+pgvector for local development.
|
|
- `src/routes/` - `/auth`, `/farms`, `/printers`, `/jobs`, and the edge-gateway
|
|
WebSocket at `/ws/edge/v1`. That route's wire format is not defined here: it
|
|
is `schemas/continuum/v1/edge/` in continuum-schemas, validated through its
|
|
TypeBox mirror in `@continuum/ts-types`, because both ends of it are separate
|
|
programs in different languages and they had already drifted apart once.
|
|
`printers.gateway_printer_id` is what maps a gateway's own printer ids
|
|
(`"p1p"`) onto rows here; telemetry for an unclaimed id is logged and skipped,
|
|
never inserted.
|
|
|
|
`frame_embeddings.embedding` requires the `vector` extension:
|
|
`CREATE EXTENSION IF NOT EXISTS vector;` (`scripts/dev-env.sh up` does this).
|
|
|
|
## Dependency pins
|
|
|
|
`elysia`, `@sinclair/typebox` and the `drizzle-*` packages are pinned tightly
|
|
on purpose, not out of caution. Caret ranges here resolved into a combination
|
|
that could not boot: `elysia: ^1.1.26` installed 1.4.30, which calls
|
|
`t.Module` and so needs TypeBox >=0.34, while `drizzle-typebox: ^0.2.1`
|
|
installed a version whose peers demand `drizzle-orm >=0.36` against the
|
|
`^0.33.0` pinned here. Typechecking passed throughout - only starting the
|
|
server failed. `tests/dependency_identity.test.ts` guards the part of this that
|
|
can silently come back.
|