computerd: Move the watermarks route under /api

The route read sync revisions through rpc.sync.watermarks() but sat at
/__computerd/watermarks, alongside runtime info and process memory. Those
report on the daemon; this reports the workspace, and it returns exactly
what a session would.

It is now /api/watermarks, which draws the line where it belongs: /api is
the workspace surface, including anything that reads through it, and
/__computerd is daemon introspection.

Only the exact /api path upgrades, so a handshake aimed at the subpath
still answers 404, and the shared secret covers the new path the same way
it covered the old one.

Author: aron-cf

docs/07_injected_service.md

@@ -51,11 +51,15 @@ backend pins it to `8080`) and serves:
 | --- | --- | --- |
 | `/health` | `GET`, `HEAD` | Liveness probe; `200 ok\n` as soon as the HTTP server binds. |
 | `/__computerd/info` | `GET` | Runtime info: FUSE backend, mount point, port. |
-| `/__computerd/watermarks` | `GET` | Sync revisions: `currentRev`, `pushRev`, `fetchCursor`. |
-| `/api` | `GET` (upgrade) | WebSocket capnweb transport — the bootstrap stub is `WorkspaceRPC`. A request without an `Upgrade` header gets `400`; an unsupported `Sec-WebSocket-Version` gets `426` and the versions the server speaks. |
+| `/api` | `GET` (upgrade) | WebSocket capnweb transport — the bootstrap stub is `WorkspaceRPC`. Only the exact path upgrades. A request without an `Upgrade` header gets `400`; an unsupported `Sec-WebSocket-Version` gets `426` and the versions the server speaks. |
+| `/api/watermarks` | `GET`, `HEAD` | Sync revisions: `currentRev`, `pushRev`, `fetchCursor`. The same values `sync.watermarks()` returns, for callers that want a few numbers without holding a session. |
 | `/connect` | `POST` | Tells `computerd` to dial *out* to a caller-supplied endpoint and serve a `WorkspaceRPC` session over that outbound WebSocket. Used by the Cloudflare backend (see below). |
 | `/` | `GET` | Banner/info page. |
 
+`/api` is the workspace surface: the session itself, plus anything that
+reads through it. `/__computerd` is daemon introspection, which is why
+runtime info sits there and revisions do not.
+
 The capnweb bootstrap interface is **`WorkspaceRPC`** (defined in
 `packages/rpc/`), split into `sync` and `shell` sub-stubs.
 

packages/computerd/README.md

@@ -28,8 +28,8 @@ Current endpoints:
 - `GET /__computerd/info` returns JSON with the selected FUSE backend, mount point, and bound port.
 - `GET /__computerd/stats` returns JSON with DOFS table row counts, total inline and blob byte sizes, the orphan-blob subset, and process resident memory. Useful for watching how the store grows under load.
 - `GET /` returns `200 OK` with an empty JSON object: `{}`.
-- `GET /__computerd/watermarks` returns JSON with `currentRev`, `pushRev`, and `fetchCursor`, read through the same `watermarks()` the wire serves. For samplers that want a few numbers without opening a session.
 - `GET /api` upgrades to a WebSocket carrying the capnweb RPC surface backed by `@cloudflare/computer-rpc`. This is the container's only RPC carrier. A request without an `Upgrade` header returns `400`; a handshake naming an unsupported `Sec-WebSocket-Version` returns `426` along with the versions the server speaks.
+- `GET /api/watermarks` returns JSON with `currentRev`, `pushRev`, and `fetchCursor`, read through the same `watermarks()` the wire serves. For samplers that want a few numbers without opening a session. It sits under `/api` because it reads the workspace surface; `/__computerd` is for daemon introspection.
 
 All other paths and methods return `404`/`405` with a `text/plain` body.
 

packages/computerd/src/cli/computerd.test.ts

@@ -173,6 +173,18 @@ test("/api refuses anything that is not a websocket handshake", async (_ctx) =>
   ]);
   expect(noKey).toMatch(/^HTTP\/1\.1 400 /);
 
+  // A subpath under /api is not the session endpoint: only the exact
+  // path upgrades.
+  const subpath = await rawRequest(port, [
+    "GET /api/watermarks HTTP/1.1",
+    `Host: 127.0.0.1:${port}`,
+    "Upgrade: websocket",
+    "Connection: Upgrade",
+    "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==",
+    "Sec-WebSocket-Version: 13",
+  ]);
+  expect(subpath).toMatch(/^HTTP\/1\.1 404 /);
+
   // An unknown path is still a 404, upgrade header or not.
   const unknown = await rawRequest(port, [
     "GET /nope HTTP/1.1",
@@ -185,14 +197,14 @@ test("/api refuses anything that is not a websocket handshake", async (_ctx) =>
   expect(unknown).toMatch(/^HTTP\/1\.1 404 /);
 });
 
-test("/__computerd/watermarks reports sync revisions over plain HTTP", async (_ctx) => {
+test("/api/watermarks reports sync revisions over plain HTTP", async (_ctx) => {
   // Samplers want three numbers on an interval. Opening an RPC session
   // per sample is the wrong shape for that.
   const port = await getAvailablePort();
   const mountPoint = await fs.mkdtemp(path.join(os.tmpdir(), "computerd-watermarks-"));
   await startComputerd({ port, mountPoint, env: { FUSE_MOUNT: "none" } });
 
-  const res = await fetch(`http://127.0.0.1:${port}/__computerd/watermarks`);
+  const res = await fetch(`http://127.0.0.1:${port}/api/watermarks`);
   expect(res.status).toBe(200);
   const body = await res.json();
   expect(body).toMatchObject({

packages/computerd/src/cli/computerd.ts

@@ -184,6 +184,35 @@ function createHTTPServer(
       return;
     }
 
+    // /api/watermarks — the same sync revisions the session serves,
+    // over plain HTTP, for samplers that want a few numbers on an
+    // interval rather than a session of their own. It reads through
+    // rpc.sync.watermarks(), so the two cannot drift. Part of the
+    // workspace API rather than daemon introspection, hence /api
+    // rather than /__computerd.
+    if (path === "/api/watermarks") {
+      if (request.method === "HEAD") {
+        send(response, 200, "", { "content-type": "application/json; charset=utf-8" });
+        return;
+      }
+      void rpc.sync
+        .watermarks()
+        .then((watermarks) => {
+          send(response, 200, JSON.stringify(watermarks), {
+            "content-type": "application/json; charset=utf-8",
+          });
+        })
+        .catch((error: unknown) => {
+          console.error("/api/watermarks failed:", error);
+          if (!response.headersSent) {
+            send(response, 500, "internal error\n", {
+              "content-type": "text/plain; charset=utf-8",
+            });
+          }
+        });
+      return;
+    }
+
     // /connect — POST { base, health, api } naming an endpoint the
     // host wants us to dial back into. We poll `base + health` until
     // it answers, then open a capnweb WebSocket session against
@@ -240,32 +269,6 @@ function createHTTPServer(
       return;
     }
 
-    // Sync revisions over plain HTTP, for samplers that want a few
-    // numbers on an interval rather than an RPC session. Reads through
-    // the same watermarks() the wire serves, so the two cannot drift.
-    if (path === "/__computerd/watermarks") {
-      if (request.method === "HEAD") {
-        send(response, 200, "", { "content-type": "application/json; charset=utf-8" });
-        return;
-      }
-      void rpc.sync
-        .watermarks()
-        .then((watermarks) => {
-          send(response, 200, JSON.stringify(watermarks), {
-            "content-type": "application/json; charset=utf-8",
-          });
-        })
-        .catch((error: unknown) => {
-          console.error("/__computerd/watermarks failed:", error);
-          if (!response.headersSent) {
-            send(response, 500, "internal error\n", {
-              "content-type": "text/plain; charset=utf-8",
-            });
-          }
-        });
-      return;
-    }
-
     if (path === "/__computerd/info") {
       const body = request.method === "HEAD" ? "" : JSON.stringify(info);
       send(response, 200, body, {

script/computerd-soak.mjs

@@ -183,7 +183,7 @@ async function dockerStats(cids) {
 // The daemon's revision numbers over plain HTTP. A sampler wanting
 // three integers on an interval does not need an RPC session.
 async function fetchWatermarks(url) {
-  const res = await fetch(`${url}/__computerd/watermarks`);
+  const res = await fetch(`${url}/api/watermarks`);
   if (!res.ok) throw new Error(`watermarks HTTP ${res.status}`);
   return await res.json();
 }