@owlmeans/server-api 0.1.18-rc.1 → 0.1.18-rc.11

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-api",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.496Z",
+  "version": "0.1.18-rc.11",
+  "generatedAt": "2026-08-24T21:14:00.090Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-api/SKILL.md

@@ -8,13 +8,14 @@ user-invocable: false
 # @owlmeans/server-api
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-api": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/server-api": "^0.1.18-rc.11"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
 | `makeServer()` | Factory for the Fastify-based API server |
+| `holdApiPort(cfg, { okPath?, payload? })` | Own the app's port during boot; released by the real `listen()` |
 | `Server`, `ServerRequest`, `ServerResponse` types | Runtime shapes |
 | Errors | Typed transport errors |
 | Constants | Default ports, paths |
@@ -34,7 +35,56 @@ const server = makeServer({ port: 8080 })
 context.registerService(server)
 ```
 
+## Holding the port through the boot
+
+The server builds its route table from the entrypoints the context knows about, so it can only
+bind **after** `init()` resolves — and Fastify refuses new routes once it is listening. That
+leaves every way a boot can fail with nothing on the port: the edge answers a bare upstream
+connect error naming neither the app nor the reason.
+
+`holdApiPort` closes that window: a minimal Fastify instance binds the app's socket immediately —
+resolving port and host from the same `cfg.services[cfg.service]` declaration `listen()` uses —
+answers `okPath` with 200 and everything else with **503, not 404** (the real routes do not exist
+yet, and "no such route" would be a lie that outlives the boot), evaluating `payload()` per
+request so a changing boot phase is reported live.
+
+```typescript
+const hold = await holdApiPort(ctx.cfg, { okPath: '/healtz', payload: bootPayload })
+try { await initialize() } catch (e) { recordFailure(e); return }   // hold keeps answering
+await hold.release()          // awaited — listen() binds on the next line
+await ctx.getApiServer().listen()
+```
+
+Two rules the caller owns: a **bind failure is fatal and loud** — name it (EADDRINUSE above all)
+and `process.exit(1)`, because carrying on ends the boot with nothing listening and nothing
+holding the event loop, a clean exit 0 while a stale predecessor keeps serving; and a **failed
+init returns without exiting** — the hold keeps the loop open and is the only thing that can say
+why.
+
+## Error → HTTP status
+
+`handleError` (`./utils`) is the single mapping from a thrown error to a status. Handlers own no
+status table: they throw, and this decides. Two families reach it and both are recognised —
+`AccessError` / `AuthFailedError`, raised by this package's own request pipeline, and
+`AuthForbidden` / `AuthorizationError` from `@owlmeans/auth`, which is what guards and gates throw.
+
+| Thrown | Status | Meaning |
+|--------|--------|---------|
+| `AuthForbidden`, `AccessError` | `403` | An established identity that lacks the permission — re-authenticating changes nothing |
+| `AuthorizationError`, `AuthFailedError` | `401` | No usable credential: absent, expired, revoked, or naming a session this server does not hold |
+| anything else | `500` | |
+
+**Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch is tested first —
+otherwise every refusal of a permission is reported as a failure to authenticate. And an
+unrecognised refusal answering 500 reports a refused request as a crashed server: the client cannot
+tell "sign in again" from "the service is broken", and a consumer watching statuses concludes the
+application fell over.
+
+The body is always `ResilientError.marshal(ResilientError.ensure(error)).message`, and nothing is
+written when the reply was already sent.
+
 ## Depends On
 
 - `@owlmeans/context`, `@owlmeans/entrypoint`, `@owlmeans/route`
+- `@owlmeans/auth` (the error family the guards throw), `@owlmeans/error`, `@owlmeans/api` (status constants)
 - `fastify` (runtime)

package/build/hold.d.ts

@@ -0,0 +1,52 @@
+import type { ServerConfig } from '@owlmeans/server-context';
+export interface ApiPortHoldOptions {
+    /**
+     * The one path answered 200 while the hold is in place — the app's health endpoint, so
+     * whatever supervises the process keeps a conventional liveness answer through the boot.
+     * Everything else answers 503 with the same body. Absent, everything is 503.
+     */
+    okPath?: string;
+    /** Body of every answer, evaluated per request so a changing boot phase is reported live. */
+    payload?: () => unknown;
+}
+export interface ApiPortHold {
+    /**
+     * Free the port for the real server. Awaits the actual close — `listen()` follows immediately,
+     * and a predecessor still bound makes it throw — and force-closes keep-alive sockets, so a
+     * supervisor's own poller cannot hold the release open.
+     */
+    release: () => Promise<void>;
+}
+/**
+ * Own the app's port while the context initializes, and answer for the app until `listen()`
+ * takes over.
+ *
+ * The API server itself cannot do this: it builds its route table from the entrypoints the
+ * context knows about, so it can only bind AFTER `init()` resolves — and Fastify refuses new
+ * routes once it is listening. Without a hold, the whole boot window, and every way a boot can
+ * fail, leaves nothing on the port; the edge then answers a bare upstream connect error that
+ * names neither the app nor the reason, which is indistinguishable from a crashed pod or an app
+ * that was never installed.
+ *
+ * So the boot sequence an app wants is:
+ *
+ *     const hold = await holdApiPort(cfg, { okPath, payload })   // bind FIRST
+ *     try { ...initialize... } catch { record the failure; return }  // hold keeps answering
+ *     await hold.release()
+ *     await context.getApiServer().listen()
+ *
+ * Everything that is not the health path answers **503, not 404**: the routes the app really
+ * serves do not exist yet, and "no such route" would be a lie that outlives the boot.
+ *
+ * The port and host are resolved exactly as `listen()` resolves them — from the service's own
+ * declaration in `cfg.services[cfg.service]` — so the hold and the server can never disagree
+ * about which socket they are trading.
+ *
+ * A bind failure here (EADDRINUSE above all) throws to the caller and must be treated as fatal:
+ * a process that continues past it ends the boot with nothing listening and nothing holding the
+ * event loop, i.e. a clean exit 0 while a predecessor keeps serving stale code. Name the error
+ * and exit non-zero — that is what makes a supervisor reclaim the port instead of respawning
+ * into it.
+ */
+export declare const holdApiPort: (cfg: ServerConfig, opts?: ApiPortHoldOptions) => Promise<ApiPortHold>;
+//# sourceMappingURL=hold.d.ts.map

package/build/hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hold.d.ts","sourceRoot":"","sources":["../src/hold.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAG5D,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,WAAW,QACjB,YAAY,SAAQ,kBAAkB,KAC1C,OAAO,CAAC,WAAW,CA0BrB,CAAA"}

package/build/hold.js

@@ -0,0 +1,56 @@
+import Fastify from 'fastify';
+import { CLOSED_HOST, OPENED_HOST, PORT } from './consts.js';
+/**
+ * Own the app's port while the context initializes, and answer for the app until `listen()`
+ * takes over.
+ *
+ * The API server itself cannot do this: it builds its route table from the entrypoints the
+ * context knows about, so it can only bind AFTER `init()` resolves — and Fastify refuses new
+ * routes once it is listening. Without a hold, the whole boot window, and every way a boot can
+ * fail, leaves nothing on the port; the edge then answers a bare upstream connect error that
+ * names neither the app nor the reason, which is indistinguishable from a crashed pod or an app
+ * that was never installed.
+ *
+ * So the boot sequence an app wants is:
+ *
+ *     const hold = await holdApiPort(cfg, { okPath, payload })   // bind FIRST
+ *     try { ...initialize... } catch { record the failure; return }  // hold keeps answering
+ *     await hold.release()
+ *     await context.getApiServer().listen()
+ *
+ * Everything that is not the health path answers **503, not 404**: the routes the app really
+ * serves do not exist yet, and "no such route" would be a lie that outlives the boot.
+ *
+ * The port and host are resolved exactly as `listen()` resolves them — from the service's own
+ * declaration in `cfg.services[cfg.service]` — so the hold and the server can never disagree
+ * about which socket they are trading.
+ *
+ * A bind failure here (EADDRINUSE above all) throws to the caller and must be treated as fatal:
+ * a process that continues past it ends the boot with nothing listening and nothing holding the
+ * event loop, i.e. a clean exit 0 while a predecessor keeps serving stale code. Name the error
+ * and exit non-zero — that is what makes a supervisor reclaim the port instead of respawning
+ * into it.
+ */
+export const holdApiPort = async (cfg, opts = {}) => {
+    const config = cfg.services[cfg.service];
+    const port = config?.internalPort ?? config?.port ?? PORT;
+    const host = config?.opened === true ? OPENED_HOST : CLOSED_HOST;
+    const payload = opts.payload ?? (() => ({ status: 'OK' }));
+    // Quiet and disposable: no logger, no plugins, and connections are force-closed on release so
+    // the handover to the real server is bounded rather than waiting out a keep-alive.
+    const server = Fastify({ logger: false, forceCloseConnections: true });
+    if (opts.okPath != null) {
+        server.all(opts.okPath, async (_request, reply) => {
+            return await reply.code(200).send(payload());
+        });
+    }
+    server.setNotFoundHandler(async (_request, reply) => {
+        return await reply.code(503).send(payload());
+    });
+    await server.listen({ port, host });
+    console.log(`api-server: holding ${host}:${port} for the boot${opts.okPath != null ? ` (${opts.okPath})` : ''}`);
+    return {
+        release: async () => { await server.close(); },
+    };
+};
+//# sourceMappingURL=hold.js.map

package/build/hold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hold.js","sourceRoot":"","sources":["../src/hold.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAA;AAE7B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAsB5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,GAAiB,EAAE,IAAI,GAAuB,EAAE,EAC1B,EAAE;IACxB,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACxC,MAAM,IAAI,GAAG,MAAM,EAAE,YAAY,IAAI,MAAM,EAAE,IAAI,IAAI,IAAI,CAAA;IACzD,MAAM,IAAI,GAAG,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAA;IAEhE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IAE1D,8FAA8F;IAC9F,mFAAmF;IACnF,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;YAChD,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;QAC9C,CAAC,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAClD,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;IAC9C,CAAC,CAAC,CAAA;IAEF,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IACnC,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,IAAI,IAAI,gBAAgB,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAEhH,OAAO;QACL,OAAO,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA,CAAC,CAAC;KAC9C,CAAA;AACH,CAAC,CAAA"}

package/build/index.d.ts

@@ -3,4 +3,5 @@ export * from './server.js';
 export * from './consts.js';
 export * from './errors.js';
 export * from './helper.js';
+export * from './hold.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/build/index.js

@@ -2,4 +2,5 @@ export * from './server.js';
 export * from './consts.js';
 export * from './errors.js';
 export * from './helper.js';
+export * from './hold.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/build/utils/error.d.ts

@@ -1,3 +1,16 @@
 import type { FastifyReply } from 'fastify';
+/**
+ * Map a thrown error onto an HTTP status.
+ *
+ * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
+ * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
+ * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
+ * one answers 500, which reports a refused request as a crashed server: the client cannot tell
+ * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
+ * application fell over.
+ *
+ * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
+ * tested first or every refusal of a permission is reported as a failure to authenticate.
+ */
 export declare const handleError: (error: Error, reply: FastifyReply) => void;
 //# sourceMappingURL=error.d.ts.map

package/build/utils/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAI3C,eAAO,MAAM,WAAW,UAAW,KAAK,SAAS,YAAY,SAY5D,CAAA"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAK3C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,UAAW,KAAK,SAAS,YAAY,SAe5D,CAAA"}

package/build/utils/error.js

@@ -1,14 +1,31 @@
 import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api';
 import { AccessError, AuthFailedError } from '../errors.js';
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth';
 import { ResilientError } from '@owlmeans/error';
+/**
+ * Map a thrown error onto an HTTP status.
+ *
+ * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
+ * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
+ * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
+ * one answers 500, which reports a refused request as a crashed server: the client cannot tell
+ * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
+ * application fell over.
+ *
+ * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
+ * tested first or every refusal of a permission is reported as a failure to authenticate.
+ */
 export const handleError = (error, reply) => {
     let code = SERVER_ERROR;
-    if (error instanceof AuthFailedError) {
-        code = UNAUTHORIZED_ERROR;
-    }
-    else if (error instanceof AccessError) {
+    if (error instanceof AuthForbidden || error instanceof AccessError) {
+        // An established identity that lacks the permission. Re-authenticating changes nothing.
         code = FORBIDDEN_ERROR;
     }
+    else if (error instanceof AuthorizationError || error instanceof AuthFailedError) {
+        // No usable credential — absent, expired, revoked, or naming a session this server no longer
+        // holds. The caller is told to sign in, not that signing in would not help.
+        code = UNAUTHORIZED_ERROR;
+    }
     if (!reply.sent) {
         reply.code(code).send(ResilientError.marshal(ResilientError.ensure(error)).message);
     }

package/build/utils/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEjF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,KAAmB,EAAE,EAAE;IAC/D,IAAI,IAAI,GAAW,YAAY,CAAA;IAC/B,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACrC,IAAI,GAAG,kBAAkB,CAAA;IAC3B,CAAC;SAAM,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACxC,IAAI,GAAG,eAAe,CAAA;IACxB,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CACnB,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,KAAc,CAAC,CAAC,CAAC,OAAO,CACtE,CAAA;IACH,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEjF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,KAAmB,EAAE,EAAE;IAC/D,IAAI,IAAI,GAAW,YAAY,CAAA;IAC/B,IAAI,KAAK,YAAY,aAAa,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACnE,wFAAwF;QACxF,IAAI,GAAG,eAAe,CAAA;IACxB,CAAC;SAAM,IAAI,KAAK,YAAY,kBAAkB,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACnF,6FAA6F;QAC7F,4EAA4E;QAC5E,IAAI,GAAG,kBAAkB,CAAA;IAC3B,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CACnB,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,KAAc,CAAC,CAAC,CAAC,OAAO,CACtE,CAAA;IACH,CAAC;AACH,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.1",
+  "version": "0.1.18-rc.11",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -32,15 +32,15 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.1",
-    "@owlmeans/auth": "^0.1.18-rc.1",
-    "@owlmeans/auth-common": "^0.1.18-rc.1",
-    "@owlmeans/context": "^0.1.18-rc.1",
-    "@owlmeans/error": "^0.1.18-rc.1",
-    "@owlmeans/entrypoint": "^0.1.18-rc.1",
-    "@owlmeans/route": "^0.1.18-rc.1",
-    "@owlmeans/server-context": "^0.1.18-rc.1",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.1",
+    "@owlmeans/api": "^0.1.18-rc.7",
+    "@owlmeans/auth": "^0.1.18-rc.6",
+    "@owlmeans/auth-common": "^0.1.18-rc.7",
+    "@owlmeans/context": "^0.1.18-rc.6",
+    "@owlmeans/error": "^0.1.18-rc.6",
+    "@owlmeans/entrypoint": "^0.1.18-rc.7",
+    "@owlmeans/route": "^0.1.18-rc.6",
+    "@owlmeans/server-context": "^0.1.18-rc.7",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.7",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
     "fastify-raw-body": "^5.0.0",

package/src/hold.ts

@@ -0,0 +1,84 @@
+import Fastify from 'fastify'
+import type { ServerConfig } from '@owlmeans/server-context'
+import { CLOSED_HOST, OPENED_HOST, PORT } from './consts.js'
+
+export interface ApiPortHoldOptions {
+  /**
+   * The one path answered 200 while the hold is in place — the app's health endpoint, so
+   * whatever supervises the process keeps a conventional liveness answer through the boot.
+   * Everything else answers 503 with the same body. Absent, everything is 503.
+   */
+  okPath?: string
+  /** Body of every answer, evaluated per request so a changing boot phase is reported live. */
+  payload?: () => unknown
+}
+
+export interface ApiPortHold {
+  /**
+   * Free the port for the real server. Awaits the actual close — `listen()` follows immediately,
+   * and a predecessor still bound makes it throw — and force-closes keep-alive sockets, so a
+   * supervisor's own poller cannot hold the release open.
+   */
+  release: () => Promise<void>
+}
+
+/**
+ * Own the app's port while the context initializes, and answer for the app until `listen()`
+ * takes over.
+ *
+ * The API server itself cannot do this: it builds its route table from the entrypoints the
+ * context knows about, so it can only bind AFTER `init()` resolves — and Fastify refuses new
+ * routes once it is listening. Without a hold, the whole boot window, and every way a boot can
+ * fail, leaves nothing on the port; the edge then answers a bare upstream connect error that
+ * names neither the app nor the reason, which is indistinguishable from a crashed pod or an app
+ * that was never installed.
+ *
+ * So the boot sequence an app wants is:
+ *
+ *     const hold = await holdApiPort(cfg, { okPath, payload })   // bind FIRST
+ *     try { ...initialize... } catch { record the failure; return }  // hold keeps answering
+ *     await hold.release()
+ *     await context.getApiServer().listen()
+ *
+ * Everything that is not the health path answers **503, not 404**: the routes the app really
+ * serves do not exist yet, and "no such route" would be a lie that outlives the boot.
+ *
+ * The port and host are resolved exactly as `listen()` resolves them — from the service's own
+ * declaration in `cfg.services[cfg.service]` — so the hold and the server can never disagree
+ * about which socket they are trading.
+ *
+ * A bind failure here (EADDRINUSE above all) throws to the caller and must be treated as fatal:
+ * a process that continues past it ends the boot with nothing listening and nothing holding the
+ * event loop, i.e. a clean exit 0 while a predecessor keeps serving stale code. Name the error
+ * and exit non-zero — that is what makes a supervisor reclaim the port instead of respawning
+ * into it.
+ */
+export const holdApiPort = async (
+  cfg: ServerConfig, opts: ApiPortHoldOptions = {}
+): Promise<ApiPortHold> => {
+  const config = cfg.services[cfg.service]
+  const port = config?.internalPort ?? config?.port ?? PORT
+  const host = config?.opened === true ? OPENED_HOST : CLOSED_HOST
+
+  const payload = opts.payload ?? (() => ({ status: 'OK' }))
+
+  // Quiet and disposable: no logger, no plugins, and connections are force-closed on release so
+  // the handover to the real server is bounded rather than waiting out a keep-alive.
+  const server = Fastify({ logger: false, forceCloseConnections: true })
+
+  if (opts.okPath != null) {
+    server.all(opts.okPath, async (_request, reply) => {
+      return await reply.code(200).send(payload())
+    })
+  }
+  server.setNotFoundHandler(async (_request, reply) => {
+    return await reply.code(503).send(payload())
+  })
+
+  await server.listen({ port, host })
+  console.log(`api-server: holding ${host}:${port} for the boot${opts.okPath != null ? ` (${opts.okPath})` : ''}`)
+
+  return {
+    release: async () => { await server.close() },
+  }
+}

package/src/index.ts

@@ -4,3 +4,4 @@ export * from './server.js'
 export * from './consts.js'
 export * from './errors.js'
 export * from './helper.js'
+export * from './hold.js'

package/src/utils/error.ts

@@ -1,14 +1,31 @@
 import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api'
 import type { FastifyReply } from 'fastify'
 import { AccessError, AuthFailedError } from '../errors.js'
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
 import { ResilientError } from '@owlmeans/error'
 
+/**
+ * Map a thrown error onto an HTTP status.
+ *
+ * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
+ * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
+ * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
+ * one answers 500, which reports a refused request as a crashed server: the client cannot tell
+ * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
+ * application fell over.
+ *
+ * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
+ * tested first or every refusal of a permission is reported as a failure to authenticate.
+ */
 export const handleError = (error: Error, reply: FastifyReply) => {
   let code: number = SERVER_ERROR
-  if (error instanceof AuthFailedError) {
-    code = UNAUTHORIZED_ERROR
-  } else if (error instanceof AccessError) {
+  if (error instanceof AuthForbidden || error instanceof AccessError) {
+    // An established identity that lacks the permission. Re-authenticating changes nothing.
     code = FORBIDDEN_ERROR
+  } else if (error instanceof AuthorizationError || error instanceof AuthFailedError) {
+    // No usable credential — absent, expired, revoked, or naming a session this server no longer
+    // holds. The caller is told to sign in, not that signing in would not help.
+    code = UNAUTHORIZED_ERROR
   }
   if (!reply.sent) {
     reply.code(code).send(