@spunto/build 0.1.0 → 0.2.0

package/README.md

@@ -53,6 +53,28 @@ const forCodeServer = codeServerGallery(rawBlob) // the same choice, handed to t
 environment variable — and every other function takes its result. Nothing is memoized at import
 time, so one process can serve several tenants on several registries.
 
+### `@spunto/build/naming` — the names both sides have to pronounce the same way
+
+A worker is a container called `mp-worker-<id>`, with volumes and a network named after it, running
+an image called `mp-proj-<slug>:v<n>`. None of that is an implementation detail — each name is a
+contract between the script that writes it, the Docker client that looks it up and the UI that
+shows it:
+
+```ts
+import { workerContainerName, workerVolumePrefix, projectImageRef } from "@spunto/build/naming"
+
+docker.getContainer(workerContainerName(workerId))
+const ref = projectImageRef(projectId, version)   // mp-proj-my-app:v7
+```
+
+Also here: `workerNetworkName`, `workerVolumeName`, `isProjectImageRef`, `SHARED_NETWORK`, and the
+paths a worker and its control plane agree on — `WORKER_STATUS_FILE` / `workerStatusPath`,
+`EXTENSIONS_DIR`, `FEATURE_ENTRYPOINTS_DIR`, `EXTENSION_FAILURES_FILE`.
+
+**These are formats, not preferences.** Changing a value renames things that already exist on
+running machines: a live worker's container and volumes keep the name they were created with. Read
+a diff in that file as a migration, not a rename.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Spunto's shared Build engine \u2014 the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,10 @@
     "./extensions": {
       "types": "./src/extensions/index.ts",
       "import": "./src/extensions/index.ts"
+    },
+    "./naming": {
+      "types": "./src/naming/index.ts",
+      "import": "./src/naming/index.ts"
     }
   },
   "files": [

package/src/index.ts

@@ -7,3 +7,4 @@
 
 export * from "./steps/index"
 export * from "./extensions/index"
+export * from "./naming/index"

package/src/naming/index.ts

@@ -0,0 +1,105 @@
+// The names both control planes have to pronounce the same way.
+//
+// A worker is a container called `mp-worker-<id>`, with volumes named after it, on a network named
+// after it, running an image called `mp-proj-<slug>:v<n>`, writing its progress to a file at a
+// fixed path. None of that is an implementation detail: each name is a contract between the shell
+// script that writes it, the Docker client that looks it up, and the UI that shows it.
+//
+// Until now none of them had a single definition. `mp-worker-<id>` was rebuilt by hand in fourteen
+// places across two apps — and a typo in one of them doesn't fail to compile, it produces a
+// container nobody can find at runtime. Spunto Lite rebuilds the same names again, on its side.
+//
+// **These are formats, not preferences.** Changing a value here renames things that already exist
+// on real machines: a running worker's container and volumes keep the name they were created with.
+// Treat every constant below as versioned protocol, the same way `../steps` treats its markers.
+//
+// The `mp-` prefix is historical (the product was called something else) and is deliberately left
+// alone: it is baked into containers, volumes and images that are running right now.
+
+/** Container that *is* the worker. */
+export function workerContainerName(workerId: string): string {
+  return `mp-worker-${workerId}`
+}
+
+/**
+ * Per-worker bridge network. Isolates each worker at L3 so no worker can reach another worker's
+ * container IP directly, bypassing the proxy.
+ */
+export function workerNetworkName(workerId: string): string {
+  return `mp-worker-${workerId}-net`
+}
+
+/** The named volumes a worker owns, and what each holds. */
+export const WORKER_VOLUME_KINDS = ["workspace", "home", "docker", "containerd"] as const
+export type WorkerVolumeKind = (typeof WORKER_VOLUME_KINDS)[number]
+
+/** One of a worker's named volumes — `workspace` for the code, `docker`/`containerd` for DinD. */
+export function workerVolumeName(workerId: string, kind: WorkerVolumeKind): string {
+  return `mp-worker-${workerId}-${kind}`
+}
+
+/**
+ * Prefix every volume of one worker shares. Teardown and disk accounting both scan by prefix rather
+ * than by listing kinds, so that a volume added later is still found by code written before it.
+ */
+export function workerVolumePrefix(workerId: string): string {
+  return `mp-worker-${workerId}-`
+}
+
+/**
+ * Image a project's workers boot from, keyed by the project's *version* — see the image cache in
+ * docs/architecture-deep-dive.md. The slug is derived, not stored: an image ref may only hold
+ * lowercase alphanumerics and separators, and a project id is not guaranteed to.
+ */
+export function projectImageRef(projectId: string, version: number): string {
+  const slug = projectId
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+  return `mp-proj-${slug}:v${version}`
+}
+
+/** True for an image this platform built, as opposed to a base image it pulled. */
+export function isProjectImageRef(ref: string): boolean {
+  return /^mp-proj-[a-z0-9-]+:v\d+$/.test(ref)
+}
+
+/**
+ * Network every shared service joins under its slug, and every worker joins at spawn, so a
+ * workspace reaches `http://<slug>:<port>` by DNS. Spunto Lite's "shared services"; the local
+ * counterpart of the Ship pillar.
+ */
+export const SHARED_NETWORK = "mp-shared-net"
+
+/**
+ * Where a worker reports its own setup progress, read back by the control plane.
+ *
+ * Relative to the user's home rather than absolute: the remote user is a project setting, so the
+ * absolute path is only known once you know who the worker runs as — hence `workerStatusPath`.
+ */
+export const WORKER_STATUS_FILE = ".mp-status.json"
+
+/** Absolute path of the status file for a given home directory, e.g. `/home/vscode`. */
+export function workerStatusPath(home: string): string {
+  return `${home.replace(/\/+$/, "")}/${WORKER_STATUS_FILE}`
+}
+
+/**
+ * VS Code extensions are installed into the *image*, at a system path — not into a home, which is
+ * per worker and would make every worker re-download them.
+ */
+export const EXTENSIONS_DIR = "/opt/mp-extensions"
+
+/**
+ * Directory of executables a devcontainer feature can drop to have them run at container start.
+ * The devcontainer `entrypoint` contract, implemented on our side.
+ */
+export const FEATURE_ENTRYPOINTS_DIR = "/etc/mp-feature-entrypoints"
+
+/**
+ * Extensions the image build could not install, one id per line. Left in the image so a worker can
+ * tell what is missing without anyone re-reading the build log — see `EXTENSION_FAILED_MARKER` in
+ * `../steps`, which is the same information on its way out.
+ */
+export const EXTENSION_FAILURES_FILE = "/etc/mp-extension-failures"