anbaric-cloud-hosting

The Anbaric platform library: the hosted API, authentication middleware, build layers, dispatcher and app proxy. To run a platform, install anbaric-hosting, which boots this package with the anbaric-hosting command; this README documents the moving parts for anyone extending the platform.

Anatomy

HostingServer serves two node:http listeners:

• Public (ANBARIC_HOSTING_PORT, default 8787): /ping is open; the CLI-authorization poll is open by design (it delivers a one-time key); everything else runs through the middleware chain — bearer-token authentication when an Authorization: Bearer header is present, session authentication otherwise, then authorize(), then the Router.
• Internal (ANBARIC_INTERNAL_PORT, default 8788): no authentication, hard-whitelisted to the workflow resources (jobs, queue, consumers, state-machines, documents, secrets) — everything else 404s before the Router is consulted. Deployed apps use it; it must never be publicly reachable.

Router routes: /jobs, /queue/{enqueue,schedule,dequeue,confirm}, /consumers (registration), /apps (+ /apps/<name>/deploy), /state-machines, /documents/<collection>, /secrets, /whoami, /keys, /authorize-cli/<id>, the built platform pages (dashboard at /, /manage-keys), and finally proxies /<app-name>/* to running apps.

Authentication

Authenticator (abstract): authenticate(session, request, response) returns Promise<[User, Tenant] | undefined> — implementations write the redirect/401 themselves and return undefined when unauthenticated. authorize(user, request, response) defaults to permit. Plugins load via ANBARIC_AUTHENTICATOR naming a module with a createAuthenticator() export.

TokenAuthenticator verifies the CLI's EdDSA JWTs: kid header names a stored key, the signature is checked against its public key, exp against the clock; the request proceeds as the key's user. Keys are minted by CliAuthorizer during the browser authorization flow and stored (with client name, user and the session's tenant) in the anbaric_system schema — system tables never mix with workflow data.

Build layers

BuildLayer implementations receive the deploy tarball, bake an image from the generated Dockerfile (base image + app source; no npm install, no build step — apps run as TypeScript via tsx) and run the app:

• DockerBuildLayer (ANBARIC_BUILD_LAYER=docker): local docker daemon, one container per app on a shared network.
• FargateBuildLayer (fargate): uploads the bundle to S3, bakes with CodeBuild, runs each app as its own single-task ECS service with a Cloud Map DNS name. Configured by the ANBARIC_AWS_* variables (cluster, subnets, app security group, namespace id/name, apps ECR repository, build bucket, CodeBuild project, base image, app execution role, apps log group); the repository's gitops/modules/anbaric-platform-aws provisions every piece.

Deploys are asynchronous: deploy returns a building summary immediately and the CLI polls /apps/<name> until running (liveness-probed) or failed, streaming the build log.

Queueing

PostgresQueue implements at-least-once delivery with 30-second leases (FOR UPDATE SKIP LOCKED); confirm deletes. The Dispatcher drains the queue on an interval and POSTs message batches to each workflow's registered consumer URL, re-enqueueing anything unroutable or failed. Consumer registrations are in-memory — the platform runs as a single instance until they are persisted.

Postgres schema management is automatic on boot (ensureSchema): workflow tables in public, platform tables in anbaric_system.