nathanbeddoe.com / flarebot
This repository has no description
Star
Fork 0
Watch
flarebot docs installation-orchestrator.md
7.9 kB
Markdown
at nathan/github-skill-folder-import

Customer installation orchestration #

The publisher installs one bundled immutable customer release using a native Cloudflare Workflow. The authenticated owner's INSTALLATIONS Durable Object remains the sole installation authority. Browser requests can end immediately after starting the operation; they do not execute or maintain the deployment.

Start and recovery #

After reserving an installation with POST /api/installations, send a same-origin URL-encoded POST /api/installations/<id>/start containing only a random 32-hex requestId. The server freshly verifies the selected account and deployment grant, requires the immutable installation account to match, verifies the publisher artifact and bridge signing key, and atomically records operation intent and request replay. The response contains safe installation metadata. Neither release URLs nor owner/account identifiers are accepted as deployment inputs from the browser. FLA-10 owns the onboarding/status presentation; FLA-12 owns selecting a newer release and upgrade policy.

The Workflow ID is the server operation ID. A duplicate request repairs a missing encrypted authorization record or missing Workflow creation without creating another operation. Each callback rechecks the active operation, its deadline, and the protected grant before loading credentials. Only owner/installation/ operation identifiers enter Workflow parameters. Step results, errors and the registry contain safe enums and resource identifiers, never credentials.

A new authorized attempt after a failed installation retains the pinned release, resource identities, prior upload marker and available encrypted bootstrap secret. An existing owned Worker never receives a replacement session secret. The last verified installed release remains distinct from the desired release; only the final idempotent completion step assigns it after all checks pass.

Worker upload, Containers creation and rollout intent are committed before their respective mutations. Lost replies are reconciled through fixed native APIs, exact Worker module hashes, configuration, namespace IDs, stable application names and rollout operation descriptions. No failure automatically deletes resources or adopts an unknown Worker/application.

If a write outcome is ambiguous and no matching resource is observable, the installation reports recovery_required. It does not blindly repeat the write. An owner can deliberately send POST /api/installations/<id>/recover with a new request ID after checking the customer account. This repeats fresh authorization, rechecks the unchanged pinned artifact and actual remote absence, then clears only the unresolved intent necessary for another attempt. It does not clear recorded namespace/application identities. If bootstrap material has already expired and the Worker remains absent, this explicit recovery creates a fresh secret; any existing Worker must instead match the original recorded identity. An explicit recover also handles an interrupted native Workflow: it terminates the old execution, preserves its mutation intent, and starts a newly authorized operation. A concurrent successful ready commit wins. Local Workflows currently retain a running status after an abrupt process restart rather than automatically resuming the interrupted callback; the acceptance gate exercises this concrete owner recovery path. A missing Workflow at a persisted startup gap is recoverable without retaining the original browser request ID.

The provider offers no documented transaction spanning these resources or create-only Worker CAS: a concurrent account administrator can still change resources between observation and mutation. Conflicting observed identities stop installation instead of being overwritten.

Native deployment sequence #

  1. Resolve the account's existing workers.dev subdomain and fix the customer origin to the reserved Worker name. No account-wide subdomain is renamed.
  2. Start an assets upload session using native precomputed BLAKE3 asset hashes, upload requested buckets with their MIME types, then upload actual Worker modules with the completion JWT, declarative SQLite exports, app variables, preserved customer variables/secrets and native Containers metadata.
  3. Verify deployed content and bindings, resolve the PersonalAgent and Sandbox namespace IDs from the active Worker version, and preserve those identities.
  4. Reconcile the native Containers application against its Sandbox namespace. An owned configuration repair uses PATCH followed by a separately reconciled rolling rollout. Native expanded VM resources are normalized to the pinned lite sizing. Unrelated configuration is retained during repair.
  5. Enable the workers.dev endpoint and perform the separately signed metadata health protocol. The customer validates identity, native parent readiness, packaged assets, authentication and actual pinned Sandbox boot and destroy. Health does not run AI inference or transfer conversations, files or model credentials. See owner login bridge.
  6. Atomically record ready and the verified installed release. Replaying this step recognizes its own completed operation. Bootstrap retirement is bounded best-effort cleanup backed by vault expiry and cannot undo readiness.

Publisher artifact and prerequisites #

Run pnpm build:release, then pnpm build:control-plane from committed source. The latter generates a publisher-only catalog of opaque Data modules. Customer JavaScript is never evaluated in the control-plane import graph, and these bytes never enter the publisher's browser assets. Generated source maps are omitted from the deployable inventory. Every inventory file has SHA-256 and size; the trusted catalog pins the exact manifest SHA-256 plus version/source revision. Asset API BLAKE3 addressing is separate from that inventory integrity.

Publication rejects dirty customer artifacts, unknown/missing files, unsupported bindings/exports, mismatched checksums and releases exceeding the bounded publisher memory budget (16 MiB Worker modules, 24 MiB total inventory). Local fixture work must explicitly use pnpm build:control-plane:fixture; production artifact loading rejects a fixture catalog. Retain catalog artifacts needed by active operations during control-plane rollouts. A missing pinned artifact fails honestly instead of silently installing a newer build.

Live installation requires a registered and verified Cloudflare OAuth client, reviewed scope-catalog capability mapping covering Workers, Assets, Containers and R2 attachment storage, Workers Paid/Containers entitlement, an existing workers.dev subdomain, and a configured bridge signing secret matching the deliberate public key pin. Local fixtures use synthetic scopes and prove native execution and request contracts; they do not certify live customer entitlement or third-party OAuth scope grants. No live account deployment is performed by the local validation gates.

The native endpoint contracts follow the installed Wrangler 4.128.0 deployment implementation and Workers multipart metadata, Static Assets direct upload, Worker content API, and the first-party Containers application and rollout client.

Versioned upgrades now extend this same native Workflow. See installation upgrades for exact immutable target selection, retained archives, compatible schema/lifecycle edges, strict native binding inheritance and forward recovery.