anbaric-cloud-hosting 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# anbaric-cloud-hosting
|
|
2
|
+
|
|
3
|
+
The Anbaric platform library: the hosted API, authentication middleware,
|
|
4
|
+
build layers, dispatcher and app proxy. To *run* a platform, install
|
|
5
|
+
[`anbaric-hosting`](https://npmjs.com/package/anbaric-hosting), which boots
|
|
6
|
+
this package with the `anbaric-hosting` command; this README documents the
|
|
7
|
+
moving parts for anyone extending the platform.
|
|
8
|
+
|
|
9
|
+
## Anatomy
|
|
10
|
+
|
|
11
|
+
**`HostingServer`** serves two node:http listeners:
|
|
12
|
+
|
|
13
|
+
- **Public** (`ANBARIC_HOSTING_PORT`, default 8787): `/ping` is open; the
|
|
14
|
+
CLI-authorization poll is open by design (it delivers a one-time key);
|
|
15
|
+
everything else runs through the middleware chain — bearer-token
|
|
16
|
+
authentication when an `Authorization: Bearer` header is present, session
|
|
17
|
+
authentication otherwise, then `authorize()`, then the `Router`.
|
|
18
|
+
- **Internal** (`ANBARIC_INTERNAL_PORT`, default 8788): no authentication,
|
|
19
|
+
hard-whitelisted to the workflow resources (`jobs`, `queue`, `consumers`,
|
|
20
|
+
`state-machines`, `documents`, `secrets`) — everything else 404s before
|
|
21
|
+
the Router is consulted. Deployed apps use it; it must never be publicly
|
|
22
|
+
reachable.
|
|
23
|
+
|
|
24
|
+
**`Router`** routes: `/jobs`, `/queue/{enqueue,schedule,dequeue,confirm}`,
|
|
25
|
+
`/consumers` (registration), `/apps` (+ `/apps/<name>/deploy`),
|
|
26
|
+
`/state-machines`, `/documents/<collection>`, `/secrets`, `/whoami`,
|
|
27
|
+
`/keys`, `/authorize-cli/<id>`, the built platform pages (dashboard at `/`,
|
|
28
|
+
`/manage-keys`), and finally proxies `/<app-name>/*` to running apps.
|
|
29
|
+
|
|
30
|
+
## Authentication
|
|
31
|
+
|
|
32
|
+
**`Authenticator`** (abstract): `authenticate(session, request, response)`
|
|
33
|
+
returns `Promise<[User, Tenant] | undefined>` — implementations write the
|
|
34
|
+
redirect/401 themselves and return undefined when unauthenticated.
|
|
35
|
+
`authorize(user, request, response)` defaults to permit. Plugins load via
|
|
36
|
+
`ANBARIC_AUTHENTICATOR` naming a module with a `createAuthenticator()`
|
|
37
|
+
export.
|
|
38
|
+
|
|
39
|
+
**`TokenAuthenticator`** verifies the CLI's EdDSA JWTs: `kid` header names a
|
|
40
|
+
stored key, the signature is checked against its public key, `exp` against
|
|
41
|
+
the clock; the request proceeds as the key's user. Keys are minted by
|
|
42
|
+
**`CliAuthorizer`** during the browser authorization flow and stored (with
|
|
43
|
+
client name, user and the session's tenant) in the `anbaric_system` schema —
|
|
44
|
+
system tables never mix with workflow data.
|
|
45
|
+
|
|
46
|
+
## Build layers
|
|
47
|
+
|
|
48
|
+
`BuildLayer` implementations receive the deploy tarball, bake an image from
|
|
49
|
+
the generated Dockerfile (base image + app source; no `npm install`, no
|
|
50
|
+
build step — apps run as TypeScript via tsx) and run the app:
|
|
51
|
+
|
|
52
|
+
- **`DockerBuildLayer`** (`ANBARIC_BUILD_LAYER=docker`): local docker
|
|
53
|
+
daemon, one container per app on a shared network.
|
|
54
|
+
- **`FargateBuildLayer`** (`fargate`): uploads the bundle to S3, bakes with
|
|
55
|
+
CodeBuild, runs each app as its own single-task ECS service with a Cloud
|
|
56
|
+
Map DNS name. Configured by the `ANBARIC_AWS_*` variables (cluster,
|
|
57
|
+
subnets, app security group, namespace id/name, apps ECR repository,
|
|
58
|
+
build bucket, CodeBuild project, base image, app execution role, apps log
|
|
59
|
+
group); the repository's `gitops/modules/anbaric-platform-aws` provisions
|
|
60
|
+
every piece.
|
|
61
|
+
|
|
62
|
+
Deploys are asynchronous: `deploy` returns a `building` summary immediately
|
|
63
|
+
and the CLI polls `/apps/<name>` until `running` (liveness-probed) or
|
|
64
|
+
`failed`, streaming the build log.
|
|
65
|
+
|
|
66
|
+
## Queueing
|
|
67
|
+
|
|
68
|
+
`PostgresQueue` implements at-least-once delivery with 30-second leases
|
|
69
|
+
(`FOR UPDATE SKIP LOCKED`); `confirm` deletes. The `Dispatcher` drains the
|
|
70
|
+
queue on an interval and POSTs message batches to each workflow's registered
|
|
71
|
+
consumer URL, re-enqueueing anything unroutable or failed. Consumer
|
|
72
|
+
registrations are in-memory — the platform runs as a single instance until
|
|
73
|
+
they are persisted.
|
|
74
|
+
|
|
75
|
+
Postgres schema management is automatic on boot (`ensureSchema`): workflow
|
|
76
|
+
tables in `public`, platform tables in `anbaric_system`.
|
package/package.json
CHANGED