@stigmer/server 3.14.0-dev.20260910084630

package/dist/transport/server.js

@@ -0,0 +1,137 @@
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { createServer as createHttp1Server } from "node:http";
+import { createServer as createHttp2Server } from "node:http2";
+import { KEEPALIVE_PING_INTERVAL_MS, KEEPALIVE_PING_TIMEOUT_MS, MAX_MESSAGE_BYTES, MODEL_REGISTRY_PATH, SHUTDOWN_DRAIN_TIMEOUT_MS, SKILL_ARTIFACTS_PATH_PREFIX, TASK_KIND_REGISTRY_PATH, } from "./constants.js";
+import { consoleLaneEligible } from "./console/handler.js";
+import { applyRpcCorsHeaders, handleRpcPreflight, isRpcPreflight, } from "./cors.js";
+import { createProtocolDemuxServer } from "./demux.js";
+export function createUnifiedPortServer(options) {
+    const rpcHandler = connectNodeAdapter({
+        routes: options.routes,
+        interceptors: options.interceptors,
+        readMaxBytes: MAX_MESSAGE_BYTES,
+        writeMaxBytes: MAX_MESSAGE_BYTES,
+    });
+    const laneRouter = (request, response) => {
+        const path = (request.url ?? "").split("?", 1)[0] ?? "";
+        if (path === TASK_KIND_REGISTRY_PATH) {
+            options.taskKindRegistryLane(request, response);
+            return;
+        }
+        if (path === MODEL_REGISTRY_PATH) {
+            options.modelRegistryLane(request, response);
+            return;
+        }
+        if (options.skillTransferLane !== undefined &&
+            path.startsWith(SKILL_ARTIFACTS_PATH_PREFIX)) {
+            options.skillTransferLane(request, response);
+            return;
+        }
+        if (options.consoleLane !== undefined && consoleLaneEligible(request)) {
+            options.consoleLane(request, response);
+            return;
+        }
+        if (isRpcPreflight(request)) {
+            // Go answers preflights for ALL endpoints, registered or not
+            // (WithCorsForRegisteredEndpointsOnly(false), server.go:777-784).
+            handleRpcPreflight(request, response);
+            return;
+        }
+        applyRpcCorsHeaders(request, response);
+        rpcHandler(request, response);
+    };
+    const http1 = createHttp1Server(laneRouter);
+    const http2 = createHttp2Server(laneRouter);
+    const liveSessions = new Set();
+    http2.on("session", (session) => {
+        liveSessions.add(session);
+        session.on("close", () => liveSessions.delete(session));
+        armKeepalivePings(session, options.logger);
+    });
+    // Protocol-level session failures (bad frames, resets) are a client's
+    // problem, not a server crash; Go's h2c stack likewise swallows them.
+    http2.on("sessionError", (error) => {
+        options.logger.debug("http2 session error", { error: String(error) });
+    });
+    const demux = createProtocolDemuxServer({ http1, http2 });
+    const liveSockets = new Set();
+    demux.on("connection", (socket) => {
+        liveSockets.add(socket);
+        socket.on("close", () => liveSockets.delete(socket));
+    });
+    return {
+        listen(port, host = "0.0.0.0") {
+            return new Promise((resolve, reject) => {
+                demux.once("error", reject);
+                demux.listen(port, host, () => {
+                    const address = demux.address();
+                    if (address === null || typeof address === "string") {
+                        reject(new Error("unified port bound without a TCP address"));
+                        return;
+                    }
+                    resolve(address.port);
+                });
+            });
+        },
+        async shutdown() {
+            // Go's Shutdown closes idle connections immediately and waits only
+            // for active work. Node needs that spelled out: GOAWAY every h2
+            // session (in-flight streams finish, idle sessions close now) and
+            // drop idle http1 keep-alives; then the drain race below only ever
+            // waits on genuinely active requests.
+            const closed = new Promise((resolve) => demux.close(() => resolve()));
+            http1.close();
+            http1.closeIdleConnections();
+            http2.close();
+            for (const session of liveSessions) {
+                session.close();
+            }
+            const drained = await Promise.race([
+                closed.then(() => true),
+                new Promise((resolve) => setTimeout(() => resolve(false), SHUTDOWN_DRAIN_TIMEOUT_MS).unref()),
+            ]);
+            if (!drained) {
+                options.logger.warn("shutdown drain budget exhausted; destroying remaining connections", {
+                    remaining: liveSockets.size,
+                });
+            }
+            for (const socket of liveSockets) {
+                socket.destroy();
+            }
+            await closed;
+        },
+    };
+}
+/**
+ * Server-initiated keepalive pings (constants.ts carries the values and the
+ * MinTime-enforcement caveat). One interval per session; an unacked ping
+ * past the timeout destroys the session — the same liveness contract Go's
+ * keepalive.ServerParameters provides.
+ */
+function armKeepalivePings(session, logger) {
+    const interval = setInterval(() => {
+        let acked = false;
+        const deadline = setTimeout(() => {
+            if (!acked && !session.destroyed) {
+                logger.debug("closing http2 session: keepalive ping unacknowledged");
+                session.destroy();
+            }
+        }, KEEPALIVE_PING_TIMEOUT_MS);
+        deadline.unref();
+        try {
+            session.ping(() => {
+                acked = true;
+                clearTimeout(deadline);
+            });
+        }
+        catch {
+            clearTimeout(deadline);
+            if (!session.destroyed) {
+                session.destroy();
+            }
+        }
+    }, KEEPALIVE_PING_INTERVAL_MS);
+    interval.unref();
+    session.on("close", () => clearInterval(interval));
+}
+//# sourceMappingURL=server.js.map

package/dist/transport/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/transport/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@stigmer/server",
+  "version": "3.14.0-dev.20260910084630",
+  "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "stigmerPublish": {
+    "consumerCheck": {
+      "singleCopy": [
+        "@temporalio/proto",
+        "@bufbuild/protobuf",
+        "@opentelemetry/api"
+      ],
+      "boot": [
+        "scripts/verify-boot.mjs",
+        "--require-workers"
+      ],
+      "typecheckConsumer": "test/extension-consumer"
+    }
+  },
+  "engines": {
+    "node": ">=22.13.0 <23 || >=24"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build:slim": "npm run build && node scripts/bundle-slim.mjs",
+    "verify:dist": "node scripts/verify-boot.mjs dist/main.js",
+    "verify:slim": "node scripts/verify-boot.mjs dist-slim/main.js",
+    "verify:slim-artifact": "node scripts/verify-slim-artifact.mjs",
+    "verify:consumer": "node ../../../scripts/verify-consumer-install.mjs",
+    "start": "tsx src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist dist-slim"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stigmer/stigmer.git",
+    "directory": "backend/services/stigmer-server"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1116.0",
+    "@aws-sdk/s3-request-presigner": "3.1116.0",
+    "@bufbuild/protobuf": "2.12.0",
+    "@bufbuild/protovalidate": "^1.1.1",
+    "@connectrpc/connect": "^2.0.0",
+    "@connectrpc/connect-node": "^2.0.0",
+    "@kubernetes/client-node": "2.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@stigmer/protos": "3.14.0-dev.20260910084630",
+    "@stigmer/temporal-codecs": "3.14.0-dev.20260910084630",
+    "@stigmer/zip-structure": "3.14.0-dev.20260910084630",
+    "@temporalio/activity": "1.16.2",
+    "@temporalio/client": "1.16.2",
+    "@temporalio/common": "1.16.2",
+    "@temporalio/proto": "1.16.2",
+    "@temporalio/worker": "1.16.2",
+    "@temporalio/workflow": "1.16.2",
+    "fflate": "^0.8.3",
+    "jose": "6.2.10",
+    "js-yaml": "^4.3.1",
+    "pg": "8.23.0",
+    "ulidx": "2.4.1"
+  },
+  "devDependencies": {
+    "@connectrpc/connect-web": "^2.0.0",
+    "@opentelemetry/sdk-metrics": "^2.0.0",
+    "@temporalio/testing": "1.16.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "22.20.1",
+    "@types/pg": "8.23.1",
+    "esbuild": "^0.28.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  }
+}

package/src/artifactstorage/__tests__/artifact-storage.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Ports storage/local_storage_test.go + disposition_test.go case-for-case:
+ * the containment guard (every escaping key refused on every operation,
+ * contained dot-segment keys allowed), the #285 no-implicit-segment
+ * layout contract, the local signed-URL shape, and the
+ * Content-Disposition builder. Adds the factory's r2/unknown refusals
+ * (Go's are boot asserted; here they're the disclosed deferral), and the
+ * O5 widened surface: size, the typed not-found, presigned-PUT over the
+ * skill-transfer-lane mechanism, and registered-driver factory selection.
+ */
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { UPLOADS_SEGMENT } from "../../domain/skill/constants.js";
+import { UploadSlots } from "../../domain/skill/transfer/slots.js";
+import { uploadUrl } from "../../domain/skill/transfer/handler.js";
+import { SKILL_ARTIFACTS_PATH_PREFIX } from "../../transport/constants.js";
+import {
+  ArtifactStorageNotFoundError,
+  LocalArtifactStorage,
+  contentDispositionAttachment,
+  newArtifactStorage,
+} from "../artifact-storage.js";
+import type { ArtifactStorage } from "../artifact-storage.js";
+
+// Keys that, once cleaned, resolve outside the artifact root — the
+// containment guard must refuse every one of them.
+const escapingKeys = [
+  "../evil.txt",
+  "../../evil.txt",
+  "attachments/x/../../../../evil.txt",
+  "attachments/../../evil.txt",
+  "a/b/../../../escape",
+];
+
+// Keys that clean to a location still inside the root — the guard
+// rejects escapes, not the mere presence of a `..` segment.
+const containedKeys = [
+  "attachments/01ABC/plan.md",
+  "artifacts/exec-1/out.txt",
+  "attachments/x/../y/file.txt",
+  "name.with.dots.txt",
+];
+
+describe("LocalArtifactStorage", () => {
+  let parent: string;
+  let base: string;
+  let storage: LocalArtifactStorage;
+
+  beforeEach(() => {
+    parent = mkdtempSync(path.join(tmpdir(), "artifact-test-"));
+    base = path.join(parent, "store");
+    storage = new LocalArtifactStorage(base, "http://localhost:7235");
+  });
+
+  afterEach(() => {
+    rmSync(parent, { recursive: true, force: true });
+  });
+
+  function assertNoEscape(name: string): void {
+    expect(
+      existsSync(path.join(parent, name)),
+      `file escaped the artifact root to ${path.join(parent, name)}`,
+    ).toBe(false);
+  }
+
+  describe("upload rejects path traversal", () => {
+    for (const key of escapingKeys) {
+      it(key, async () => {
+        await expect(
+          storage.upload(key, Buffer.from("owned"), "text/plain"),
+        ).rejects.toThrow("resolves outside the artifact storage root");
+        assertNoEscape("evil.txt");
+        assertNoEscape("escape");
+      });
+    }
+  });
+
+  describe("download rejects path traversal", () => {
+    for (const key of escapingKeys) {
+      it(key, async () => {
+        // Plant a file just outside the root that a traversal key would
+        // otherwise reach.
+        writeFileSync(path.join(parent, "secret.txt"), "top secret");
+        await expect(storage.download(key)).rejects.toThrow(
+          "resolves outside the artifact storage root",
+        );
+      });
+    }
+  });
+
+  describe("exists and delete reject path traversal", () => {
+    for (const key of escapingKeys) {
+      it(`exists/${key}`, async () => {
+        await expect(storage.exists(key)).rejects.toThrow(
+          "resolves outside the artifact storage root",
+        );
+      });
+      it(`delete/${key}`, async () => {
+        await expect(storage.delete(key)).rejects.toThrow(
+          "resolves outside the artifact storage root",
+        );
+      });
+    }
+  });
+
+  // Pins the layout contract after unification (#285): the configured
+  // base path IS the artifact root, so a key K lands at <base>/<K> with
+  // no implicit "artifacts" segment — what lets the runner, whose
+  // LOCAL_ARTIFACT_PATH points at the same directory, read back exactly
+  // what the server wrote.
+  it("stores key at root without implicit segment", async () => {
+    const key = "attachments/01ABC/plan.md";
+    await storage.upload(key, Buffer.from("the plan"), "text/markdown");
+    expect(existsSync(path.join(base, key))).toBe(true);
+    expect(existsSync(path.join(base, "artifacts", key))).toBe(false);
+  });
+
+  describe("allows contained keys with dot segments", () => {
+    for (const key of containedKeys) {
+      it(key, async () => {
+        await storage.upload(key, Buffer.from("ok"), "text/plain");
+        const data = await storage.download(key);
+        expect(Buffer.from(data).toString()).toBe("ok");
+      });
+    }
+  });
+
+  it("signed URL: inline has no query, download carries url-encoded filename", async () => {
+    const key = "artifacts/aex_1/plan.md";
+    const inline = await storage.getSignedUrl(key, 3600_000, "");
+    expect(inline).toBe(`http://localhost:7235/${key}`);
+
+    const download = await storage.getSignedUrl(
+      key,
+      3600_000,
+      "my plan.plan.md",
+    );
+    // Space encodes as '+' (Go url.Values.Encode).
+    expect(download).toBe(
+      `http://localhost:7235/${key}?download=my+plan.plan.md`,
+    );
+
+    // Go url.QueryEscape byte-exactness on the two characters where
+    // URLSearchParams disagrees: '~' stays bare, '*' percent-encodes.
+    const exotic = await storage.getSignedUrl(key, 3600_000, "a~b*c.md");
+    expect(exotic).toBe(`http://localhost:7235/${key}?download=a~b%2Ac.md`);
+  });
+
+  it("delete removes the artifact and prunes empty parents, never the root", async () => {
+    const key = "attachments/01DEL/file.txt";
+    await storage.upload(key, Buffer.from("x"), "text/plain");
+    await storage.delete(key);
+    expect(existsSync(path.join(base, key))).toBe(false);
+    expect(existsSync(path.join(base, "attachments", "01DEL"))).toBe(false);
+    expect(existsSync(base)).toBe(true);
+  });
+
+  it("health probes the root writable", async () => {
+    await expect(storage.health()).resolves.toBeUndefined();
+    expect(existsSync(path.join(base, ".health_check"))).toBe(false);
+  });
+
+  describe("O5 widened surface", () => {
+    it("size stats the stored byte count without loading", async () => {
+      await storage.upload("attachments/01S/f.bin", Buffer.from("12345"), "");
+      expect(await storage.size("attachments/01S/f.bin")).toBe(5);
+    });
+
+    it("download and size answer the typed not-found with the historical copy", async () => {
+      for (const op of [
+        () => storage.download("attachments/absent.bin"),
+        () => storage.size("attachments/absent.bin"),
+      ]) {
+        const error = await op().catch((e: unknown) => e);
+        expect(error).toBeInstanceOf(ArtifactStorageNotFoundError);
+        expect((error as Error).message).toBe(
+          "artifact not found: attachments/absent.bin",
+        );
+      }
+    });
+
+    it("presignPut without a wired lane is the explicit not-configured throw, never a silent no-op", async () => {
+      await expect(storage.presignPut(16, 60_000)).rejects.toThrow(
+        "local presigned uploads not configured",
+      );
+    });
+  });
+});
+
+// The local presigned-PUT arm over the REAL skill-transfer-lane slot
+// mechanism (§6b, the Q1 ruling: one upload surface, no new lane) — the
+// adapter below mirrors boot/compose.ts's wiring exactly.
+describe("LocalArtifactStorage presignPut over the transfer-lane slots", () => {
+  const BASE_URL = "http://localhost:8080";
+  let root: string;
+  let slots: UploadSlots;
+  let driver: ArtifactStorage;
+
+  beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), "artifact-presign-"));
+    slots = new UploadSlots(
+      path.join(root, "skills-staging"),
+      60_000,
+      1024 * 1024,
+    );
+    driver = new LocalArtifactStorage(root, "", {
+      mint: (declaredSizeBytes) => slots.mint(declaredSizeBytes),
+      uploadUrl: (ref) => uploadUrl(BASE_URL, ref),
+      stagedKey: (ref) => `skills-staging/${slots.stagedFileName(ref)}`,
+    });
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("mint → PUT (lane receive) → download(stagingKey) round-trips the bytes", async () => {
+    const bytes = Buffer.from("staged artifact bytes");
+    const upload = await driver.presignPut(bytes.length, 999_999_999);
+
+    // The URL is the lane's wire shape and the ref is its last segment —
+    // exactly how the lane handler dispatches a PUT.
+    expect(
+      upload.url.startsWith(
+        `${BASE_URL}${SKILL_ARTIFACTS_PATH_PREFIX}${UPLOADS_SEGMENT}`,
+      ),
+    ).toBe(true);
+    // The lane's slot TTL governs, not the caller's larger ask.
+    expect(upload.ttlMs).toBe(60_000);
+
+    const ref = upload.url.slice(upload.url.lastIndexOf("/") + 1);
+    await slots.receive(ref, Readable.from(bytes));
+
+    expect(Buffer.from(await driver.download(upload.stagingKey))).toEqual(
+      bytes,
+    );
+    expect(await driver.size(upload.stagingKey)).toBe(bytes.length);
+  });
+
+  it("the staged key never resolves outside the driver root", async () => {
+    const upload = await driver.presignPut(4, 60_000);
+    expect(upload.stagingKey.startsWith("skills-staging/")).toBe(true);
+    // Unreceived slot: the key is honest about absence.
+    await expect(driver.download(upload.stagingKey)).rejects.toThrow(
+      ArtifactStorageNotFoundError,
+    );
+  });
+});
+
+const NO_R2 = {
+  r2Bucket: "",
+  r2Endpoint: "",
+  r2AccessKeyId: "",
+  r2SecretAccessKey: "",
+  r2Region: "",
+} as const;
+
+describe("newArtifactStorage factory", () => {
+  it("empty type defaults to local", () => {
+    const parent = mkdtempSync(path.join(tmpdir(), "artifact-factory-"));
+    try {
+      const s = newArtifactStorage({
+        type: "",
+        localBasePath: path.join(parent, "store"),
+        localServeUrl: "http://localhost:7235",
+        ...NO_R2,
+      });
+      expect(s).toBeInstanceOf(LocalArtifactStorage);
+    } finally {
+      rmSync(parent, { recursive: true, force: true });
+    }
+  });
+
+  it("r2 constructs the R2 backend (validation pins live in r2-storage tests)", () => {
+    // The former boot-fail deferral test: the r2 arm now constructs, and
+    // an incomplete config fails with Go NewR2Storage's copy.
+    expect(() =>
+      newArtifactStorage({ type: "r2", localBasePath: "", localServeUrl: "", ...NO_R2 }),
+    ).toThrow("R2 bucket name is required");
+  });
+
+  it("unknown type refuses", () => {
+    expect(() =>
+      newArtifactStorage({ type: "s3", localBasePath: "", localServeUrl: "", ...NO_R2 }),
+    ).toThrow("unknown storage type: s3 (must be 'local' or 'r2')");
+  });
+
+  it("selects a registered driver by name — and only constructs the selected one (O5)", () => {
+    let constructed = 0;
+    let neverConstructed = 0;
+    const fake = { health: () => Promise.resolve() } as unknown as ReturnType<
+      typeof newArtifactStorage
+    >;
+    const registered = new Map([
+      [
+        "cloud-r2",
+        () => {
+          constructed += 1;
+          return fake;
+        },
+      ],
+      [
+        "unused",
+        () => {
+          neverConstructed += 1;
+          return fake;
+        },
+      ],
+    ]);
+    const s = newArtifactStorage(
+      { type: "cloud-r2", localBasePath: "", localServeUrl: "", ...NO_R2 },
+      registered,
+    );
+    expect(s).toBe(fake);
+    expect(constructed).toBe(1);
+    expect(neverConstructed, "unselected drivers must construct nothing").toBe(0);
+  });
+
+  it("unknown type names the registered drivers in its refusal (O5)", () => {
+    expect(() =>
+      newArtifactStorage(
+        { type: "s3", localBasePath: "", localServeUrl: "", ...NO_R2 },
+        new Map([["cloud-r2", () => ({}) as never]]),
+      ),
+    ).toThrow("unknown storage type: s3 (must be 'local' or 'r2' or 'cloud-r2')");
+  });
+});
+
+describe("contentDispositionAttachment", () => {
+  const cases = [
+    {
+      name: "plain ascii filename",
+      filename: "plan_card_ux_cleanup.plan.md",
+      want: 'attachment; filename="plan_card_ux_cleanup.plan.md"',
+    },
+    {
+      name: "embedded quote is escaped, not broken out of",
+      filename: 'evil".md',
+      want: 'attachment; filename="evil\\".md"',
+    },
+    {
+      name: "non-ascii adds an RFC 5987 filename* fallback",
+      filename: "café.md",
+      want: "attachment; filename=\"caf_.md\"; filename*=UTF-8''caf%C3%A9.md",
+    },
+  ];
+  for (const tt of cases) {
+    it(tt.name, () => {
+      expect(contentDispositionAttachment(tt.filename)).toBe(tt.want);
+    });
+  }
+});