rs2 / restspace

10.5 Deploying and rotating custom code on a running node

Custom-code deployment is part of operating a node: the bytes live in the services code store, and mounts reference them by immutable version. This section is the operator's view of the lifecycle covered for developers in Part 8.

The code store

/services/code/… is a store (3.3) with the content-addressed facet:

Request Behavior
GET /services/code/ Lists bundle names
GET /services/code/<name>/ Lists versions; each annotated mountedAt: [paths] where the live config references it
GET /services/code/<name>/<version> The bundle bytes; ETag = version, immutable Cache-Control
POST /services/code/<name>/ Deploy (keyless create): body application/wasm or application/javascript → 201 + Location + {name, version, ref, validated}
PUT /services/code/<name>/<version> Accepted only if <version> equals the content hash (idempotent re-upload for sync tools); else 409
DELETE /services/code/<name>/<version> Delete a version — refuses 409 if a live mount references it
DELETE /services/code/<name>/?confirm=<name> Delete the whole bundle

rs2 deploy (8.6) is a convenience over POST /services/code/<name>/.

The rotate-without-downtime flow

  1. Deploy the new bytes → new ref code:<name>@<new> (old version stays stored). A compile smoke test rejects broken bundles with 502 before they become a version.
  2. Repoint the mount's service to the new ref via PUT /services/raw (10.4) — validated and hot-swapped atomically.
  3. The swap is instant and safe; in-flight requests finish on the old version, new requests use the new one.

Rollback is repointing

Because old versions remain addressable, rolling back is just pointing the mount's service back at the previous ref and PUTting the config — no rebuild, no redeploy. Keep a note of the previous ref before you rotate.

Safety properties to rely on

  • A version referenced by a live mount can't be deleted (409) — repoint first. This prevents pulling code out from under a running service.
  • A version can't be mislabeled — PUT with a wrong version hash is 409.
  • Refs are per-tenant — deploy to each tenant that needs the service (8.7).

The instruction plane angle

Deployed code lives at .rs2-code/<name>/<version> in the tenant file store and is part of the tenant's instruction plane (3.6) — the reproducible, extractable description of how the tenant behaves. Treat it as source, not as disposable data: don't hand-delete those files, and capture refs when you snapshot a tenant.

Last operator topic: handling secrets.

← Previous: 10.4 Editing config safely · Manual home · Next: 10.6 Secrets handling →