rs2 / restspace

8.7 Versioning, rollback, and mounting code: refs

Deployed code is content-addressed and immutable per version. That property drives how you mount, upgrade, and roll back services — it's the same discipline as pinning a dependency to a hash.

Mounting a ref

A deploy yields a ref like code:my-svc@a1b2c3d4. You mount it by putting that ref in a mount's service:

{ "path": "/pay", "service": "code:my-svc@a1b2c3d4",
  "config": { "grants": { … }, "access": { … } } }

The mount names an exact version. Nothing about the running service changes until you change this ref — there's no implicit "latest."

Versions are immutable

  • Redeploying the identical bytes yields the same version — idempotent, so re-running a deploy is safe.
  • Changed bytes yield a new ref that mounts must explicitly opt into.

So a deployed version is a precise, pinned artifact. A mount can never be silently upgraded under you, and a version can never be mislabeled (the code store rejects a PUT whose claimed version doesn't equal the content hash).

Upgrading = deploy + repoint

The upgrade flow is deliberate:

  1. rs2 deploy … the new code → get a new ref code:my-svc@<new>.
  2. Update the mount's service to the new ref via PUT /services/raw (Part 10).

Because old versions remain stored and addressable, rollback is just repointing the mount back to the previous ref — no rebuild, no redeploy.

The code store is a store

The deployed-code surface (/services/code/…) obeys the store contract (3.3) with the content-addressed facet, so an editor UI drives it generically:

  • GET /services/code/ — lists bundle names.
  • GET /services/code/<name>/ — lists versions, each annotated with mountedAt: [paths] where the live config references it.
  • GET /services/code/<name>/<version> — the bundle bytes, with ETag = version and an immutable Cache-Control.

Deleting versions safely

  • DELETE /services/code/<name>/<version> — delete one version.
  • DELETE /services/code/<name>/?confirm=<name> — delete the whole bundle.

A version referenced by a live mount refuses to delete (409) — you must repoint the mount first. This stops you from yanking the code out from under a running service.

Per-tenant refs

Code refs are per-tenant: a code: ref names a version deployed to that tenant. Mounting a ref that was never deployed to the tenant yields 404 "deployed code … not found". Deploy to each tenant that needs the service.

Next: the limits your service runs under and how to diagnose failures.

← Previous: 8.6 Building, bundling, deploying · Manual home · Next: 8.8 Limits and diagnosing failures →