@percher/shared 0.1.9 → 1.0.0

package/dist/timeouts.d.ts

@@ -64,4 +64,89 @@ export declare const TIMEOUTS: {
     readonly mcpWaitDeployMax: number;
 };
 export type TimeoutKey = keyof typeof TIMEOUTS;
+/**
+ * Bun refuses a `Bun.serve({ idleTimeout })` above this and throws at boot
+ * ("Bun.serve expects idleTimeout to be 255 or less"). Measured on Bun 1.3.14,
+ * the version `packages/api/Dockerfile` and `packages/mcp/Dockerfile` both
+ * digest-pin, on linux and win32. It is a hard ceiling, not a guideline: an
+ * operation whose budget exceeds it can never be covered by a server-wide
+ * value and has to be exempted per route
+ * (`packages/api/src/http/scoped-idle-timeout.ts`) or made job-based.
+ */
+export declare const BUN_MAX_IDLE_TIMEOUT_SECONDS = 255;
+/**
+ * Transport-level idle timeout, in SECONDS, for each `Bun.serve` Percher runs.
+ * (Every other budget in this file is in milliseconds; Bun's option is
+ * seconds, so the unit is in the name.)
+ *
+ * Bun's default is 10 s, and leaving it there is how a healthy request dies of
+ * something unrelated to itself. 2026-09-08: a supervised admin POST to
+ * `/admin/migrate-networks` returned `curl: (52) Empty reply from server`
+ * while the same log window held `[watchdog] WARNING: disk usage 80% —
+ * triggering auto-prune` and `[Bun.serve]: request timed out after 10
+ * seconds`. Identical earlier runs answered in under 10 s; concurrent pruning
+ * was observed, but the log timing alone does not prove the cause of the delay.
+ * The client had budgeted 900 s.
+ *
+ * Two measurements shape these numbers. Both were taken with curl against a
+ * real `Bun.serve` on the pinned 1.3.14 linux image:
+ *
+ * - A request whose body is EMPTY (`GET`, or `curl -X POST` with no `-d`) is
+ *   reset at the idle timeout: 200 at 8 s, `curl: (52)` at ~12 s.
+ * - A request carrying a non-empty body survived the measured 30 s handler,
+ *   answering 200 under both the 10 s default and a 2 s override.
+ *
+ * That asymmetry is undocumented, so nothing may depend on it, but it does
+ * explain the shape of the incident report: the long-held bodied calls
+ * (`/build/nixpacks`, held for up to `workerBuildSubprocess`) never showed a
+ * symptom, while every bodyless operator `-X POST` and the watchdog's own
+ * non-aggressive `POST /docker/prune` were being cut at 10 s.
+ *
+ * Each value must outlive the longest SYNCHRONOUS request that surface
+ * legitimately serves. Anything longer than {@link BUN_MAX_IDLE_TIMEOUT_SECONDS}
+ * cannot be expressed here at all and stays on the per-route exemption list.
+ */
+export declare const HTTP_IDLE_TIMEOUT_SECONDS: {
+    /**
+     * `packages/api/src/server.ts`. Deliberately the most conservative of the
+     * three: this one `Bun.serve` also carries the anonymous lane and every
+     * signed-in user route, and the caps that bound that traffic (anon global
+     * 20, the per-network concurrency ceiling, the 25 MiB anon upload, the
+     * per-IP rate limits) all bound REQUESTS — a connection that sends nothing
+     * is bounded by this value and nothing else, so raising it is a real, if
+     * small, increase in what one idle socket can hold.
+     *
+     * 120 s is what the API's own downstream budgets ask for: a single
+     * `RemotePocketBaseManager.post()` is 90 s, `RemoteDeployer.post()` is 60 s,
+     * `waitHealthy` is its deadline + 10 s. Below those the transport, not the
+     * deadline, would decide the outcome — the misalignment the rest of this
+     * file exists to prevent. The operator routes that legitimately run longer
+     * (`/admin/backup/verify` at 10 min, `/admin/migrate-networks` at the
+     * runbook's 180 s and beyond) are on the exact-route exemption list, which
+     * is narrower than any process-wide number could be.
+     */
+    readonly api: 120;
+    /**
+     * `packages/api/bin/percher-worker.ts`. The internal control plane: reached
+     * over the private networks with the shared worker secret, never from the
+     * public internet. Its unexempted routes are the ones the API budgets 60–90 s
+     * for, and the prune ladder the 2026-09-08 window was running has no API-side
+     * budget at all — the watchdog's non-aggressive `POST /docker/prune` sends no
+     * body and no signal, so it was being reset at 10 s and reported as
+     * `auto-prune failed` while the worker kept pruning unobserved. 240 s covers
+     * those with room for the IO stalls this exists for, and leaves the ceiling
+     * visible rather than sitting on it.
+     */
+    readonly worker: 240;
+    /**
+     * `packages/mcp/bin/percher-mcp-http.ts`. Public through Caddy, so not the
+     * place for the ceiling either. Its longest legitimate single POST is
+     * `percher_wait_for_deploy`, whose hosted schema clamps `timeoutSeconds` to
+     * 120; 180 s covers that plus the internal API hop and JSON-RPC framing.
+     * Every hosted call carries a JSON-RPC body, so this is a guard rather than
+     * a fix for an observed failure.
+     */
+    readonly hostedMcp: 180;
+};
+export type HttpIdleTimeoutSurface = keyof typeof HTTP_IDLE_TIMEOUT_SECONDS;
 //# sourceMappingURL=timeouts.d.ts.map

package/dist/timeouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../src/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;OAKG;aACH,qBAAqB;IAErB;;;;;;OAMG;aACH,qBAAqB;IAErB;;;;;OAKG;aACH,iBAAiB;IAEjB,2CAA2C;aAC3C,iBAAiB,EAAE,IAAK;IAExB,2CAA2C;aAC3C,YAAY,EAAE,KAAM;IAEpB,uEAAuE;aACvE,oBAAoB,EAAE,KAAM;IAE5B;;;;;;OAMG;aACH,gBAAgB;CACR,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,QAAQ,CAAC"}
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../src/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;OAKG;aACH,qBAAqB;IAErB;;;;;;OAMG;aACH,qBAAqB;IAErB;;;;;OAKG;aACH,iBAAiB;IAEjB,2CAA2C;aAC3C,iBAAiB,EAAE,IAAK;IAExB,2CAA2C;aAC3C,YAAY,EAAE,KAAM;IAEpB,uEAAuE;aACvE,oBAAoB,EAAE,KAAM;IAE5B;;;;;;OAMG;aACH,gBAAgB;CACR,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,QAAQ,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,yBAAyB;IACpC;;;;;;;;;;;;;;;;;OAiBG;aACH,GAAG,EAAE,GAAG;IACR;;;;;;;;;;OAUG;aACH,MAAM,EAAE,GAAG;IACX;;;;;;;OAOG;aACH,SAAS,EAAE,GAAG;CACN,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,yBAAyB,CAAC"}

package/dist/timeouts.js

@@ -63,4 +63,88 @@ export const TIMEOUTS = {
      */
     mcpWaitDeployMax: 12 * 60_000,
 };
+/**
+ * Bun refuses a `Bun.serve({ idleTimeout })` above this and throws at boot
+ * ("Bun.serve expects idleTimeout to be 255 or less"). Measured on Bun 1.3.14,
+ * the version `packages/api/Dockerfile` and `packages/mcp/Dockerfile` both
+ * digest-pin, on linux and win32. It is a hard ceiling, not a guideline: an
+ * operation whose budget exceeds it can never be covered by a server-wide
+ * value and has to be exempted per route
+ * (`packages/api/src/http/scoped-idle-timeout.ts`) or made job-based.
+ */
+export const BUN_MAX_IDLE_TIMEOUT_SECONDS = 255;
+/**
+ * Transport-level idle timeout, in SECONDS, for each `Bun.serve` Percher runs.
+ * (Every other budget in this file is in milliseconds; Bun's option is
+ * seconds, so the unit is in the name.)
+ *
+ * Bun's default is 10 s, and leaving it there is how a healthy request dies of
+ * something unrelated to itself. 2026-09-08: a supervised admin POST to
+ * `/admin/migrate-networks` returned `curl: (52) Empty reply from server`
+ * while the same log window held `[watchdog] WARNING: disk usage 80% —
+ * triggering auto-prune` and `[Bun.serve]: request timed out after 10
+ * seconds`. Identical earlier runs answered in under 10 s; concurrent pruning
+ * was observed, but the log timing alone does not prove the cause of the delay.
+ * The client had budgeted 900 s.
+ *
+ * Two measurements shape these numbers. Both were taken with curl against a
+ * real `Bun.serve` on the pinned 1.3.14 linux image:
+ *
+ * - A request whose body is EMPTY (`GET`, or `curl -X POST` with no `-d`) is
+ *   reset at the idle timeout: 200 at 8 s, `curl: (52)` at ~12 s.
+ * - A request carrying a non-empty body survived the measured 30 s handler,
+ *   answering 200 under both the 10 s default and a 2 s override.
+ *
+ * That asymmetry is undocumented, so nothing may depend on it, but it does
+ * explain the shape of the incident report: the long-held bodied calls
+ * (`/build/nixpacks`, held for up to `workerBuildSubprocess`) never showed a
+ * symptom, while every bodyless operator `-X POST` and the watchdog's own
+ * non-aggressive `POST /docker/prune` were being cut at 10 s.
+ *
+ * Each value must outlive the longest SYNCHRONOUS request that surface
+ * legitimately serves. Anything longer than {@link BUN_MAX_IDLE_TIMEOUT_SECONDS}
+ * cannot be expressed here at all and stays on the per-route exemption list.
+ */
+export const HTTP_IDLE_TIMEOUT_SECONDS = {
+    /**
+     * `packages/api/src/server.ts`. Deliberately the most conservative of the
+     * three: this one `Bun.serve` also carries the anonymous lane and every
+     * signed-in user route, and the caps that bound that traffic (anon global
+     * 20, the per-network concurrency ceiling, the 25 MiB anon upload, the
+     * per-IP rate limits) all bound REQUESTS — a connection that sends nothing
+     * is bounded by this value and nothing else, so raising it is a real, if
+     * small, increase in what one idle socket can hold.
+     *
+     * 120 s is what the API's own downstream budgets ask for: a single
+     * `RemotePocketBaseManager.post()` is 90 s, `RemoteDeployer.post()` is 60 s,
+     * `waitHealthy` is its deadline + 10 s. Below those the transport, not the
+     * deadline, would decide the outcome — the misalignment the rest of this
+     * file exists to prevent. The operator routes that legitimately run longer
+     * (`/admin/backup/verify` at 10 min, `/admin/migrate-networks` at the
+     * runbook's 180 s and beyond) are on the exact-route exemption list, which
+     * is narrower than any process-wide number could be.
+     */
+    api: 120,
+    /**
+     * `packages/api/bin/percher-worker.ts`. The internal control plane: reached
+     * over the private networks with the shared worker secret, never from the
+     * public internet. Its unexempted routes are the ones the API budgets 60–90 s
+     * for, and the prune ladder the 2026-09-08 window was running has no API-side
+     * budget at all — the watchdog's non-aggressive `POST /docker/prune` sends no
+     * body and no signal, so it was being reset at 10 s and reported as
+     * `auto-prune failed` while the worker kept pruning unobserved. 240 s covers
+     * those with room for the IO stalls this exists for, and leaves the ceiling
+     * visible rather than sitting on it.
+     */
+    worker: 240,
+    /**
+     * `packages/mcp/bin/percher-mcp-http.ts`. Public through Caddy, so not the
+     * place for the ceiling either. Its longest legitimate single POST is
+     * `percher_wait_for_deploy`, whose hosted schema clamps `timeoutSeconds` to
+     * 120; 180 s covers that plus the internal API hop and JSON-RPC framing.
+     * Every hosted call carries a JSON-RPC body, so this is a guard rather than
+     * a fix for an observed failure.
+     */
+    hostedMcp: 180,
+};
 //# sourceMappingURL=timeouts.js.map

package/dist/timeouts.js.map

@@ -1 +1 @@
-{"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../src/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB;;;;;OAKG;IACH,qBAAqB,EAAE,EAAE,GAAG,MAAM;IAElC;;;;;;OAMG;IACH,qBAAqB,EAAE,EAAE,GAAG,MAAM;IAElC;;;;;OAKG;IACH,iBAAiB,EAAE,EAAE,GAAG,MAAM;IAE9B,2CAA2C;IAC3C,iBAAiB,EAAE,KAAK;IAExB,2CAA2C;IAC3C,YAAY,EAAE,MAAM;IAEpB,uEAAuE;IACvE,oBAAoB,EAAE,MAAM;IAE5B;;;;;;OAMG;IACH,gBAAgB,EAAE,EAAE,GAAG,MAAM;CACrB,CAAC"}
+{"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../src/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB;;;;;OAKG;IACH,qBAAqB,EAAE,EAAE,GAAG,MAAM;IAElC;;;;;;OAMG;IACH,qBAAqB,EAAE,EAAE,GAAG,MAAM;IAElC;;;;;OAKG;IACH,iBAAiB,EAAE,EAAE,GAAG,MAAM;IAE9B,2CAA2C;IAC3C,iBAAiB,EAAE,KAAK;IAExB,2CAA2C;IAC3C,YAAY,EAAE,MAAM;IAEpB,uEAAuE;IACvE,oBAAoB,EAAE,MAAM;IAE5B;;;;;;OAMG;IACH,gBAAgB,EAAE,EAAE,GAAG,MAAM;CACrB,CAAC;AAIX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC;;;;;;;;;;;;;;;;;OAiBG;IACH,GAAG,EAAE,GAAG;IACR;;;;;;;;;;OAUG;IACH,MAAM,EAAE,GAAG;IACX;;;;;;;OAOG;IACH,SAAS,EAAE,GAAG;CACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percher/shared",
-  "version": "0.1.9",
+  "version": "1.0.0",
   "description": "Shared constants and contracts (timeouts, etc.) used across the Percher CLI, API, MCP, and worker. Internal — values change in lockstep across packages.",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./brand": {
+      "types": "./dist/brand.d.ts",
+      "import": "./dist/brand.js",
+      "default": "./dist/brand.js"
+    },
     "./timeouts": {
       "types": "./dist/timeouts.d.ts",
       "import": "./dist/timeouts.js",
@@ -30,6 +35,11 @@
       "types": "./dist/pow.d.ts",
       "import": "./dist/pow.js",
       "default": "./dist/pow.js"
+    },
+    "./signup-invite-hash": {
+      "types": "./dist/signup-invite-hash.d.ts",
+      "import": "./dist/signup-invite-hash.js",
+      "default": "./dist/signup-invite-hash.js"
     }
   },
   "files": [
@@ -44,7 +54,7 @@
     "bun-types": "^1.1.0",
     "tsc-alias": "^1.8.17"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-MIT",
   "author": "Mattias Malmborg",
   "repository": {
     "type": "git",