Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/actions/flybot-tests/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,11 @@ runs:
shell: bash
working-directory: core
run: npm test
- name: Plane tests
if: inputs.coverage != 'true'
shell: bash
working-directory: plane
run: npm test
- name: Plugin lint
if: inputs.plugins != 'false'
shell: bash
Expand Down
1 change: 1 addition & 0 deletions docs/subsystems/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Detail pages for each FlyBot subsystem. Each page lists `owned_paths`, what the
| workflow | [workflow.md](workflow.md) | `plugins/workflow/` |
| project | [project.md](project.md) | `plugins/project/` |
| social | [social.md](social.md) | `plugins/social/` |
| plane | [plane.md](plane.md) | `plane/` |
| install | [install.md](install.md) | `core/scripts/`, arch-doc tests, `plugins/README.md`, the container image (`Dockerfile`, `compose.yaml`, `docker/`) |
| team | [team.md](team.md) | `docs/subsystems/team.md` — **planned contract only** (no code paths; multi-human is not shipped) |
| interop | [interop.md](interop.md) | `dev/interop/`, `scripts/lint-interop.mjs` — offline development harness only |
Expand Down
19 changes: 19 additions & 0 deletions docs/subsystems/plane.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
subsystem: plane
owned_paths:
- plane/
---

# plane (`@flybot/plane`)

The management-plane control plane — first slice of #3113 (parent #3110). It owns accounts, workspaces and FlyBot instance metadata, the two credential families, and the lifecycle seam; it runs no agent and no docker itself.

`plane/` is a top-level package, not a core plugin: the management plane must not run inside the agent container, and `core/` is ds-bot + patches (changing it means regenerating `patches/ds-bot/`). It is also not under `/opt/flybot/packages` in the image, so `docker/profile.mjs` never bundles it — this slice ships no image and no compose changes.

Records live in one `plane.json` under the data dir (`version` at the top for migration), written temp-file-plus-rename at 0600 in a 0700 dir, the `core/src/host/private-files.js` shape. An instance name is unique inside a workspace, never across owners. The state the plane records (`stopped` stays `stopped` across a process restart) is the plane's own bookkeeping; an instance's data stays on the instance's volume.

Credentials are two non-interchangeable families: operator tokens (`op_…`) for `/api/*` and per-instance control tokens (`ctl_…`) for the plane→instance direction. Only sha256 digests are stored; verification is `timingSafeEqual`; `redact()` is what a log line may show.

The lifecycle is the `LifecycleBackend` contract (`create/start/stop/upgrade/recycle`). `MemoryBackend` moves state only; `ComposeBackend` materializes `instances/<id>/compose.yaml` plus a 0600 `control.env` — host networking and a loopback `FLYBOT_PORT`, mirroring the repo's own `compose.yaml` — and never spawns docker. `upgrade` and `recycle` throw `NotImplementedError` by design: the seam exists, the second slice fills it.

`handle()` is the pure routing function (every route verifies an operator token, then the instance routes compare `instance.ownerId`); `serve()` is the `node:http` adapter bound to `127.0.0.1`; `plane/bin/plane.mjs` is the CLI (`token`, `serve`). The suite is `npm --prefix plane test` — no network, no docker — registered in `docs/testing-layers.json` as suite `plane` (L1).
9 changes: 9 additions & 0 deletions docs/testing-layers.json
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,15 @@
"dev/live-e2e/test/**"
],
"reason": "Offline unit tests for the live end-to-end harness (a fake adapter, no model). They run in the root `npm run verify` only; no CI gate runs them today. Moving them into L1 is a separate change, and the layer that does drive a real model is `live-e2e.yml`, whose row is below."
},
{
"id": "plane",
"layer": "L1",
"paths": [
"plane/test/**/*.test.js"
],
"command": "npm --prefix plane test",
"note": "管理面控制平面骨架:凭证分离、所有权、创建/启停、compose 生成;不碰网络与 Docker。"
}
],
"workflows": [
Expand Down
1 change: 1 addition & 0 deletions docs/testing-layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ The tables below are generated: edit `docs/testing-layers.json`, then run
| `patch-payload` | none (see reason) | `patches/ds-bot/files/**` | — Generated copies of the files the patches carry. They are compared against `core/` by `node scripts/ds-bot-patches.mjs check` (L2) and never run on their own; the code under test is the copy in `core/`. |
| `upstream` | none (see reason) | `ds-bot/test/**` | — The pristine upstream checkout at the pinned version. FlyBot never edits or runs it directly — `core/` is `ds-bot/` plus the patches, and the `core` suite runs the patched copies. |
| `live-e2e-unit` | none (see reason) | `dev/live-e2e/test/**` | — Offline unit tests for the live end-to-end harness (a fake adapter, no model). They run in the root `npm run verify` only; no CI gate runs them today. Moving them into L1 is a separate change, and the layer that does drive a real model is `live-e2e.yml`, whose row is below. |
| `plane` | L1 | `plane/test/**/*.test.js` | `npm --prefix plane test` |

| Workflow | Kind | Layer | Gate | Runs on | What it guarantees, or why it is not a layer |
| --- | --- | --- | --- | --- | --- |
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"node": ">=22"
},
"scripts": {
"verify": "npm --prefix core run lint && node scripts/lint-plugins.mjs && node core/scripts/build-client.mjs --check && node scripts/ds-bot-patches.mjs check && node scripts/ds-bot-patches.mjs canonical && npm --prefix core test && npm --prefix plugins/social test && npm --prefix plugins/tree test && npm --prefix plugins/timeline test && npm --prefix plugins/workflow test && npm --prefix plugins/project test && node --test \".github/scripts/*.test.mjs\" \"policy/*.test.mjs\" && npm run lint:interop && npm run test:interop && npm run lint:live-e2e && npm run test:live-e2e",
"verify": "npm --prefix core run lint && node scripts/lint-plugins.mjs && node core/scripts/build-client.mjs --check && node scripts/ds-bot-patches.mjs check && node scripts/ds-bot-patches.mjs canonical && npm --prefix core test && npm --prefix plane test && npm --prefix plugins/social test && npm --prefix plugins/tree test && npm --prefix plugins/timeline test && npm --prefix plugins/workflow test && npm --prefix plugins/project test && node --test \".github/scripts/*.test.mjs\" \"policy/*.test.mjs\" && npm run lint:interop && npm run test:interop && npm run lint:live-e2e && npm run test:live-e2e",
"lint:interop": "node scripts/lint-interop.mjs",
"test:interop": "node --import ./dev/interop/no-network.mjs --test \"dev/interop/test/*.test.mjs\"",
"demo:interop": "node --import ./dev/interop/no-network.mjs dev/interop/demo.mjs",
Expand Down
44 changes: 44 additions & 0 deletions plane/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# @flybot/plane

The FlyBot management plane — first slice of [#3113](https://github.com/ThinkFlowLab/FlyBot/issues/3113) (parent: #3110).

`plane/` is the control plane that owns accounts, workspaces and FlyBot instance records, mints the two credential families, and steers instances through an abstract lifecycle backend. It deliberately runs **no** agent and **no** docker itself: an instance is the existing FlyBot runtime on its own data volume, and the plane only records and steers it.

## Working defaults, not owner decisions

These three are replaceable working defaults chosen for this slice, following the issue's "可替换的工作默认" rule. None of them is settled by the owner:

1. **Granularity: one instance per owner (or per workspace).** Closest to today's "one instance per person" (#352). Adjustable without touching the store: the record keys on `(workspaceId, name)`.
2. **Storage: one JSON file, `plane.json`, under the data dir.** It carries a `version` field so a later migration can tell what it is reading before it reads it. The plane owns this file alone; an instance's own data stays on the instance's volume.
3. **Backend: the compose backend only *materializes* an instance project** (`instances/<id>/compose.yaml` + `control.env`, mode 0600) and never runs docker. The existing repo `compose.yaml` is one self-hosting path, not the only one; `LifecycleBackend` is the seam for others.

Also out of this slice, refusing loudly rather than pretending: `upgrade` and `recycle` throw `NotImplementedError`; no management UI, no external gateway, no real `docker compose up`.

## Credentials

Two families that never open each other's door:

- Operator tokens (`op_…`) speak to `/api/*`. `node plane/bin/plane.mjs token --data-dir <dir> --account <id>` mints one and prints it exactly once.
- Control tokens (`ctl_…`) are what the plane presents to one FlyBot instance. Each instance gets its own; the compose backend writes it into that instance's 0600 `control.env`, never into the compose file.

Only sha256 digests are persisted (`plane.json` has no plaintext). A control token presented to `/api/*` is a 401, an operator token presented as a control credential is refused, and verification uses `timingSafeEqual`. Logs that must name a token go through `redact()`.

## API

`serve()` binds `127.0.0.1` only. `handle()` is the same logic as a pure function — that is what the tests drive, with no socket.

| Route | What it does |
| --- | --- |
| `POST /api/instances` | create (needs `workspaceId`, `name`; unique per workspace; 409 otherwise; hands out the control token once) |
| `GET /api/instances` | list the caller's own instances only |
| `GET /api/instances/:id` | one instance (404 unknown, 403 someone else's) |
| `POST /api/instances/:id/start` | start (idempotent record: state moves to `running`) |
| `POST /api/instances/:id/stop` | stop (state persists as `stopped` across restarts) |

## Test

```sh
npm --prefix plane test
```

No network, no docker, no cloud. The suite (20 cases across 5 files) covers ownership (403/401 boundaries), creation (duplicate, isolation, persistence, 400), the create→start→stop→start loop, credential separation, and the compose backend's file-only contract.
53 changes: 53 additions & 0 deletions plane/bin/plane.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/usr/bin/env node
// The plane's CLI (#3113). `token` mints an operator token for an account and prints it once —
// the store keeps only the digest, so what leaves the terminal is the only copy. `serve` starts
// the HTTP surface on the loopback with a lifecycle backend of your choice; this slice ships the
// compose-generating backend, which runs nothing.
import { MemoryBackend, ComposeBackend } from '../src/lifecycle.mjs'
import { mintOperatorToken } from '../src/credentials.mjs'
import { openStore } from '../src/store.mjs'
import { serve } from '../src/server.mjs'

const usage = `@flybot/plane — the FlyBot management plane (#3113), first slice.

node plane/bin/plane.mjs token --data-dir <dir> --account <id>
Mint an operator token for <id>; printed once, only its sha256 is stored.
node plane/bin/plane.mjs serve --data-dir <dir> [--port 3090] [--backend compose|memory]
Serve /api/* on 127.0.0.1. The compose backend materializes instance projects and
never runs docker; upgrade and recycle are not implemented in this slice.
`

const flag = (name) => {
const at = process.argv.indexOf(name)
return at > 0 && at + 1 < process.argv.length ? process.argv[at + 1] : null
}

const command = process.argv[2]
const dataDir = flag('--data-dir')
if (!command || !dataDir) {
console.error(usage)
process.exit(2)
}

if (command === 'token') {
const accountId = flag('--account')
if (!accountId) { console.error('token needs --account <id>'); process.exit(2) }
const store = openStore(dataDir)
const { token } = mintOperatorToken(store, accountId)
console.log(token)
process.exit(0)
}

if (command === 'serve') {
const port = Number(flag('--port') ?? 3090)
const which = flag('--backend') ?? 'compose'
const backend = which === 'memory' ? new MemoryBackend() : new ComposeBackend({ root: dataDir })
const server = await serve({ port, dataDir, backend, log: line => console.log(line) })
console.log(`plane listening on 127.0.0.1:${port} (backend: ${which})`)
const stop = () => server.close(() => process.exit(0))
process.on('SIGINT', stop)
process.on('SIGTERM', stop)
} else {
console.error(usage)
process.exit(2)
}
30 changes: 30 additions & 0 deletions plane/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
// The public face of @flybot/plane (#3113): open one data dir, steer the instances recorded in
// it. The methods carry no authorization — that lives in the HTTP surface (`src/server.mjs`) —
// and no process handling — that lives in the lifecycle backend. `clock` is injectable so a
// later slice can test time without waiting for it. Every method is async so a caller can treat
// the plane uniformly, including the refusals: a backend seam that throws rejects the same way.
import { openStore } from './src/store.mjs'

export function createPlane({ dataDir, backend, clock = () => Date.now() } = {}) {
if (!dataDir) throw new Error('dataDir is required')
if (!backend) throw new Error('backend is required')
const store = openStore(dataDir)

const apply = async (id, report) => store.updateInstance(id, { ...report, at: clock() })

return {
store,
async createInstance({ workspaceId, name }) {
const { instance, controlToken } = store.createInstance({ workspaceId, name })
await apply(instance.id, backend.create(instance, { controlToken }))
return { instance: store.getInstance(instance.id), controlToken }
},
async startInstance(id) { return apply(id, backend.start(store.getInstance(id))) },
async stopInstance(id) { return apply(id, backend.stop(store.getInstance(id))) },
async getInstance(id) { return store.getInstance(id) },
async listInstances({ ownerId } = {}) { return store.listInstances({ ownerId }) },
// On the contract, not in this slice: they refuse loudly rather than succeed quietly.
async upgradeInstance(id) { return apply(id, backend.upgrade(store.getInstance(id))) },
async recycleInstance(id) { return apply(id, backend.recycle(store.getInstance(id))) },
}
}
9 changes: 9 additions & 0 deletions plane/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"name": "@flybot/plane",
"private": true,
"description": "Management-plane control-plane skeleton: accounts, workspaces, instance records, credentials, lifecycle (#3113).",
"type": "module",
"engines": { "node": ">=22" },
"scripts": { "test": "node --test \"test/*.test.js\"" },
"devDependencies": {}
}
70 changes: 70 additions & 0 deletions plane/src/credentials.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
// Two token families, one file, no overlap (#3113). An operator token (`op_…`) is what a person's
// API client presents to the management plane; a control token (`ctl_…`) is what the plane
// presents to one FlyBot instance. Neither verifies against the other's table, and only sha256
// digests are ever persisted — `mintOperatorToken` hands the plaintext back exactly once, and a
// log line that wants to name a token goes through `redact()`.
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'

export const OPERATOR_PREFIX = 'op_'
export const CONTROL_PREFIX = 'ctl_'

export function hash(token) {
return createHash('sha256').update(token, 'utf8').digest('hex')
}

const mint = prefix => {
const token = `${prefix}${randomBytes(16).toString('hex')}`
return { token, digest: hash(token) }
}

export function mintControlToken() {
return mint(CONTROL_PREFIX)
}

export function mintOperatorToken(store, accountId) {
const account = store.findAccount(accountId)
if (!account) throw new Error(`no account ${accountId}`)
const minted = mint(OPERATOR_PREFIX)
// The store keeps an array so a second mint does not silently retire a token that may still be
// in a client's hands; retiring one is a later slice's job.
account.operatorTokenHashes.push(minted.digest)
store.persist()
return minted
}

const bearer = authorization => {
const match = /^Bearer (.+)$/.exec(String(authorization ?? ''))
return match ? match[1] : null
}

const safeEqual = (a, b) => {
const left = Buffer.from(a, 'utf8')
const right = Buffer.from(b, 'utf8')
return left.length === right.length && timingSafeEqual(left, right)
}

// A control token never verifies here: its digest lives on an instance record, not on an account,
// so the scan below cannot match it even though the comparison itself is safe.
export function verifyOperator(store, authorization) {
const token = bearer(authorization)
if (!token || !token.startsWith(OPERATOR_PREFIX)) return null
const digest = hash(token)
for (const account of store.accounts()) {
if (account.operatorTokenHashes.some(stored => safeEqual(stored, digest))) {
return { accountId: account.id }
}
}
return null
}

export function verifyControl(instance, authorization) {
const token = bearer(authorization)
if (!token || !token.startsWith(CONTROL_PREFIX) || !instance) return false
return safeEqual(instance.controlTokenHash, hash(token))
}

export function redact(token) {
const text = String(token ?? '')
const at = text.indexOf('_')
return at > 0 ? `${text.slice(0, at + 1)}****` : '****'
}
Loading
Loading