@owlmeans/server-api 0.1.18-rc.3 → 0.1.18-rc.31

package/README.md

@@ -1,80 +1,212 @@
 # @owlmeans/server-api
 
-Fastify-based HTTP/WebSocket server with handler wrappers for the OwlMeans module system.
-
-## Overview
-
-- `handleBody`, `handleParams`, `handleRequest` wrap business logic with context injection and error handling
-- Built on [Fastify](https://fastify.dev/) — registered modules become Fastify routes automatically
-- `createApiServer` / `appendApiServer` initialize the HTTP server in a context
-- Not typically used directly — import handlers from `@owlmeans/server-app`
+The Fastify HTTP server of an OwlMeans backend and the protocol-bound handler factories that serve
+it. An application imports `handlers<Context>()` in every HTTP handler module (often through the
+`@owlmeans/server-app` re-export) and `holdApiPort` for a guarded boot. The server itself —
+`appendApiServer` — is already added by `@owlmeans/server-app`'s `makeContext`; call it directly
+only when composing a context without that package. WebSocket routes belong to
+`@owlmeans/server-socket`, and calls to other services go through the `@owlmeans/api` client.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-api
+bun add @owlmeans/server-api@^0.1.18-rc.27
 ```
 
+## Concepts
+
+- **API server** — the `api-server` service (`context.getApiServer()`), holding a `FastifyInstance`
+  and `listen()`. At context init it builds its route table from the registered entrypoints: backend
+  routes of this `cfg.service` only, excluding socket and queue protocols.
+- **Request pipeline** — intermediates run first; then the protocol's guards (the first guard whose
+  `match` hits handles the request and sets `request.auth`, and the organization entity is attached);
+  then its gates (`gate.assert`); then the handler.
+- **Protocol-bound handler** — `handlers<Context>().body / .params / .request` infer the request
+  sections and the response type from the declaration. A returned value resolves the entrypoint with
+  `EntrypointOutcome.Ok` (HTTP 200); a thrown error rejects it.
+- **Validation** — the contract's schemas are compiled with AJV (`removeAdditional`, `useDefaults`,
+  `coerceTypes`), so a handler receives cleaned, coerced input.
+- **Error mapping** — `AuthForbidden` / `AccessError` answer 403, `AuthorizationError` /
+  `AuthFailedError` answer 401, anything else 500, with the marshalled `ResilientError` as the body.
+
 ## Usage
 
-Handler functions called via `elevate()` in modules:
+### Body, params and request handlers
 
-```typescript
-import { handleBody, handleParams, handleRequest } from '@owlmeans/server-app'
+```ts
+import { handlers } from '@owlmeans/server-api'
+import { bind } from '@owlmeans/server-entrypoint'
+import { requireEntityKey } from '@owlmeans/auth-common'
+import { projectProtocols } from 'my-app-common'
+import type { Context } from './context.js'
 
-// Body handler: receives parsed + validated body as first arg
-export const create = handleBody<CreateProject>(async (payload, context, req) => {
-  const ctx = context as Context
-  return await ctx.project().create({ ...payload, entityId: req.auth!.entityId })
-})
+const api = handlers<Context>()
 
-// Params handler: receives validated URL params as first arg
-export const get = handleParams<{ id: string }>(async (params, context, req) => {
-  return await (context as Context).project().get(params.id)
-})
+// body: the validated body first, then context and the full request
+const create = api.body(projectProtocols.create, async (payload, context, request) =>
+  context.project().create({ ...payload, entityId: requireEntityKey(request) }))
 
-// Request handler: receives the full AbstractRequest
-export const health = handleRequest(async (req, context) => {
-  return { status: 'ok' }
-})
+// params: the validated URL params first
+const get = api.params(projectProtocols.get, async ({ id }, context, request) =>
+  context.project().load({ id, entityId: requireEntityKey(request) }))
+
+// request: every typed section plus request metadata (auth, entity, headers)
+const search = api.request(projectProtocols.search, async (request, context) =>
+  context.project().list({ entityId: requireEntityKey(request), ...request.query }))
+
+export const serverBindings = [
+  bind(projectProtocols.base),
+  bind(projectProtocols.create, create),
+  bind(projectProtocols.get, get),
+  bind(projectProtocols.search, search),
+]
 ```
 
-## API
+### Refusing a request
+
+Guards and gates run before the handler; a handler still checks ownership and throws a typed error,
+which the server maps onto a status.
+
+```ts
+import { AuthForbidden } from '@owlmeans/auth'
 
-### `handleBody<T>(handler): RefedModuleHandler`
+// the protocol declares both `params` and `body`
+export const rename = api.body(projectProtocols.rename, async ({ name }, context, request) => {
+  const entityId = requireEntityKey(request)
+  const project = await context.project().load({ id: request.params.id, entityId })
+  if (project == null) {
+    throw new AuthForbidden('project') // 403
+  }
 
-Wraps a handler that receives the validated request body as the first argument.
-```typescript
-handler: (payload: T, ctx: Context, req: AbstractRequest) => Promise<any>
+  return context.project().update({ ...project, name })
+})
 ```
 
-### `handleParams<T>(handler): RefedModuleHandler`
+### File upload
+
+`uploadedFile(request)` is the only place a handler touches the Fastify multipart API. The protocol
+must declare a `body` section.
+
+```ts
+import { handlers, NoFileError, uploadedFile } from '@owlmeans/server-api'
 
-Wraps a handler that receives the validated URL params as the first argument.
-```typescript
-handler: (payload: T, ctx: Context, req: AbstractRequest) => Promise<any>
+export const upload = api.request(invoiceProtocols.attach, async (request, context) => {
+  const file = await uploadedFile(request)
+  if (file == null) {
+    throw new NoFileError()
+  }
+
+  const content = await file.toBuffer()
+
+  return context.attachment().create({
+    entityId: requireEntityKey(request),
+    name: file.filename,
+    mimetype: file.mimetype,
+    size: content.length,
+  })
+})
 ```
 
-### `handleRequest(handler): RefedModuleHandler`
+### Holding the port during boot
 
-Wraps a handler that receives the full request object.
-```typescript
-handler: (req: AbstractRequest, ctx: Context, res?: AbstractResponse) => Promise<any>
+```ts
+import { holdApiPort } from '@owlmeans/server-api'
+
+const hold = await holdApiPort(cfg, { okPath: '/healthz' }) // 200 on /healthz, 503 elsewhere
+await context.configure().init()
+await hold.release()
+await context.getApiServer().listen()
 ```
 
-### `handleIntermediate(handler): RefedModuleHandler`
+### A context without `@owlmeans/server-app`
 
-Wraps middleware-layer handlers that do not return a final response.
+```ts
+import { makeServerContext } from '@owlmeans/server-context'
+import { appendApiServer } from '@owlmeans/server-api'
 
-### `extractUploadedFile(req, fieldName): UploadedFile | null`
+const context = appendApiServer(makeServerContext(cfg))
+context.registerEntrypoints(serverBindings)
+await context.configure().init()
 
-Extract a multipart-uploaded file from the request.
+// the Fastify instance, for plugins the framework does not register
+context.getApiServer().server.addHook('onResponse', async (request, reply) => {
+  console.log(request.url, reply.statusCode)
+})
 
-## Related Packages
+await context.getApiServer().listen()
+```
+
+## API
 
-- [`@owlmeans/server-app`](../server-app) — re-exports all handlers; preferred import point
-- [`@owlmeans/server-module`](../server-module) — `elevate()` attaches handlers to modules
-- [`@owlmeans/server-socket`](../server-socket) — WebSocket `handleConnection` counterpart
+### Root export
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `handlers<Context>()` | function | Factories `body(protocol, fn)`, `params(protocol, fn)`, `request(protocol, fn)` returning `BoundEntrypointHandler<Protocol>` |
+| `uploadedFile(request)` | function | The multipart file of a request, or `undefined` |
+| `extractUploadedFile(req)` | function | Same boundary for an untyped `AbstractRequest`; returns `Promise<UploadedFile \| undefined>` |
+| `holdApiPort(cfg, opts?)` | function | Bind the service port before init; returns `ApiPortHold` with `release()` |
+| `createApiServer(alias)` | function | Create the Fastify API server service |
+| `appendApiServer(ctx, alias = DEFAULT_ALIAS)` | function | Register the API server and `context.getApiServer()` |
+| `handleBody`, `handleParams`, `handleRequest`, `handleIntermediate` | function | Unbound compatibility wrappers returning `RefedEntrypointHandler` |
+| `AuthFailedError`, `AccessError`, `NoFileError` | class | Registered `ResilientError` subclasses (401, 403, 500) |
+| `DEFAULT_ALIAS` | const | `'api-server'` |
+| `PORT` | const | `80`, used when the service route declares no port |
+| `CLOSED_HOST`, `OPENED_HOST` | const | `'127.0.0.1'` and `'0.0.0.0'`; a service with `opened: true` listens on the second |
+| `ApiServer`, `ApiServerAppend` | type | The server service and its context mixin |
+| `ApiPortHold`, `ApiPortHoldOptions` | type | `holdApiPort` result and options (`okPath?`, `payload?`) |
+| `Config`, `Context` | type | `ServerConfig` and `ServerContext & ApiServerAppend` |
+| `Request`, `Response` | type | Fastify request and reply |
+| `UploadedFile` | type | Fastify `MultipartFile` |
+
+### `./utils` subpath
+
+For transport packages (such as `@owlmeans/server-socket`) that reuse the HTTP pipeline; application
+code does not need it.
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `authorize(context, module, req, reply)` | function | Run guards, set `auth`, call `attachEntity` |
+| `createServerHandler(module, location)` | function | The Fastify handler: authorize, gates, handle, respond |
+| `canServeModule(context, module)` | function | Whether an entrypoint belongs on this HTTP server |
+| `provideRequest(alias, req, provision?)` | function | Build an `AbstractRequest` from a Fastify request |
+| `executeResponse(response, reply, throwOnError?)` | function | Send an `AbstractResponse` onto a reply |
+| `handleError(error, reply)` | function | Map an error onto 401 / 403 / 500 |
+| `fixFormatDates(schema)` | function | Rewrite `date-time` object schemas as strings |
+| `populateContext(req, context)`, `extractContext(req, ctx?, location?)` | function | Carry the request-scoped context on the raw request |
+
+## Common pitfalls
+
+- `.body` and `.params` exist only for a protocol that declares that section; for anything else use
+  `.request`.
+- Do not reach into `request.original` from application code — `uploadedFile(request)` is the
+  multipart boundary.
+- Prefer `handlers<Context>()` over the unbound `handle*` wrappers, and never hand-write a
+  `RefedEntrypointHandler` for an HTTP route.
+- A handler is wrapped by `handlers<Context>()` **exactly once**: wrap a plain function where it is
+  bound (`bind(p, api.body(p, create))`), or bind the already-bound export directly
+  (`const create = api.body(p, ...)` then `bind(p, create)`) — never both. `tsc` rejects a double
+  wrap (`TS2345 "BoundEntrypointHandler<…> is not assignable"`); at runtime a handler already bound
+  to the SAME protocol is returned unchanged with a one-time console warning, and anything else that
+  is not a plain function fails that one route with `HandlerMisconfiguredError` instead of the
+  opaque `TypeError: handler is not a function`.
+- A guard only authenticates. Gates authorize, and the handler keeps its organization check keyed on
+  `requireEntityKey(request)` — never an id read from the token.
+- `request.entity` is absent when no entity resolver is registered; `requireEntityKey` falls back to
+  the slug there, `requireEntity` throws.
+- A handler always answers 200 on success. The port comes from `cfg.services[cfg.service]`
+  (`internalPort ?? port ?? 80`).
+- A `holdApiPort` bind failure must end the process with a non-zero exit.
+- WebSocket routes use `connection(protocol, callback)` from `@owlmeans/server-socket`.
+
+## Related packages
+
+- [`@owlmeans/server-entrypoint`](../server-entrypoint) — `bind()` attaches handlers to protocols
+- [`@owlmeans/server-app`](../server-app) — application bootstrap and re-exports
+- [`@owlmeans/server-socket`](../server-socket) — the WebSocket counterpart of `handlers`
+- [`@owlmeans/entrypoint`](../entrypoint) — `contract`, `typed`, request/response types
+- [`@owlmeans/auth-common`](../auth-common) — `requireEntityKey`, `attachEntity`, guard aliases
+- [`@owlmeans/api`](../api) — the client that calls these endpoints from other services
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -84,7 +216,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.26
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

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.31",
+  "generatedAt": "2026-09-15T13:12:48.098Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,40 +1,63 @@
 ---
 name: server-api
-description: How to use @owlmeans/server-api — Fastify-based API server factory, request/response shapes, server middleware integration. Auto-invoked when importing server-api types or extending the server middleware stack.
+description: Implement HTTP entrypoint protocols with @owlmeans/server-api handlers<Context>().body(), params(), request(), and uploadedFile(). Load before writing an API handler.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # @owlmeans/server-api
 
-**Layer:** Server
-**Install:** `"@owlmeans/server-api": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.27`
 
-## Key Exports
+Make handlers from the protocol declaration so input and output types stay coupled to the shared
+contract:
 
-| Export | Description |
-|--------|-------------|
-| `makeServer()` | Factory for the Fastify-based API server |
-| `Server`, `ServerRequest`, `ServerResponse` types | Runtime shapes |
-| Errors | Typed transport errors |
-| Constants | Default ports, paths |
-| Helpers | Middleware composition |
+```ts
+const api = handlers<AppContext>()
 
-## Subpath Exports
+const create = api.body(projectProtocols.create, async (body, context, request) =>
+  context.projects.create(body, request.auth)
+)
 
-- `./utils` — server utility functions
+const get = api.params(projectProtocols.get, async ({ id }, context) =>
+  context.projects.get(id)
+)
 
-## Usage
+const search = api.request(projectProtocols.search, async (request, context) =>
+  context.projects.search(request.query)
+)
 
-The server is normally constructed transparently by `@owlmeans/server-app#main()`. Use `server-api` directly only when you need to register raw Fastify plugins or customize transport:
+export const serverBindings = [
+  bind(projectProtocols.create, create),
+  bind(projectProtocols.get, get),
+  bind(projectProtocols.search, search),
+]
+```
+
+`body` and `params` are available only for a protocol declaring that section. `request` works for
+any protocol and receives all its typed sections plus request metadata. A successful callback
+return resolves the entrypoint with `EntrypointOutcome.Ok`; a thrown error rejects it.
+
+## Wrap exactly once
 
-```typescript
-import { makeServer } from '@owlmeans/server-api'
-const server = makeServer({ port: 8080 })
-context.registerService(server)
+A handler is wrapped by `handlers<Context>()` exactly once — either shape above (create the bound
+handler and bind it directly) is correct on its own. Never combine them: a handler module that
+already exports a bound handler must be bound directly, not wrapped again where it is bound.
+
+```ts
+// WRONG — bound once in the handler module, wrapped a second time here
+export const create = api.body(projectProtocols.create, async (body, context) => ...)
+bind(projectProtocols.create, api.body(projectProtocols.create, create))
 ```
 
-## Depends On
+`tsc` rejects the double wrap (`TS2345 "Argument of type 'BoundEntrypointHandler<…>' is not
+assignable"`). At runtime, `body`/`params`/`request` return an already-bound handler for the SAME
+protocol unchanged, with a one-time warning; anything else that is not a plain function fails only
+that one route with `HandlerMisconfiguredError`, instead of the opaque
+`TypeError: handler is not a function`.
+
+`uploadedFile(request)` is the Fastify multipart boundary. Keep raw Fastify access there rather
+than reaching through `request.original` in application code.
 
-- `@owlmeans/context`, `@owlmeans/entrypoint`, `@owlmeans/route`
-- `fastify` (runtime)
+Do not use unbound compatibility handler wrappers. For a WebSocket route use
+`@owlmeans/server-socket`'s `connection(protocol, callback)`.

package/build/errors.d.ts

@@ -11,4 +11,16 @@ export declare class NoFileError extends ApiError {
     static typeName: string;
     constructor();
 }
+/**
+ * `handlers().body/params/request` was handed something it cannot serve — not a plain callback,
+ * and not a `BoundEntrypointHandler` bound to the SAME protocol it is being wrapped for. Thrown
+ * from inside the bound handler's own request path, so the module still loads and every OTHER
+ * route on it still answers; only the misconfigured one reports why, as a 500 rather than the
+ * opaque `TypeError: handler is not a function` a double wrap used to fail with. See
+ * `handlers()` in `protocol.ts` for what does and does not reach here.
+ */
+export declare class HandlerMisconfiguredError extends ApiError {
+    static typeName: string;
+    constructor(message?: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,OAAuB,QAAQ,SAAoB;IAEnD,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAgB;IAE/C,cAGC;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,OAAuB,QAAQ,SAAoB;IAEnD,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAgB;IAE/C,cAGC;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,QAAQ;IACrD,OAAuB,QAAQ,SAA8B;IAE7D,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF"}

package/build/errors.js

@@ -21,7 +21,23 @@ export class NoFileError extends ApiError {
         this.type = NoFileError.typeName;
     }
 }
+/**
+ * `handlers().body/params/request` was handed something it cannot serve — not a plain callback,
+ * and not a `BoundEntrypointHandler` bound to the SAME protocol it is being wrapped for. Thrown
+ * from inside the bound handler's own request path, so the module still loads and every OTHER
+ * route on it still answers; only the misconfigured one reports why, as a 500 rather than the
+ * opaque `TypeError: handler is not a function` a double wrap used to fail with. See
+ * `handlers()` in `protocol.ts` for what does and does not reach here.
+ */
+export class HandlerMisconfiguredError extends ApiError {
+    static typeName = 'HandlerMisconfiguredError';
+    constructor(message = 'error') {
+        super(`handler:misconfigured:${message}`);
+        this.type = HandlerMisconfiguredError.typeName;
+    }
+}
 ResilientError.registerErrorClass(AuthFailedError);
 ResilientError.registerErrorClass(AccessError);
 ResilientError.registerErrorClass(NoFileError);
+ResilientError.registerErrorClass(HandlerMisconfiguredError);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IACpC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,CAAA;IAEnD,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,SAAS,eAAe,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,aAAa,CAAA;IAE/C;QACE,KAAK,CAAC,SAAS,CAAC,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA;AAClD,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAC9C,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IACpC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,CAAA;IAEnD,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,SAAS,eAAe,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,aAAa,CAAA;IAE/C;QACE,KAAK,CAAC,SAAS,CAAC,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,QAAQ;IAC9C,MAAM,CAAU,QAAQ,GAAG,2BAA2B,CAAA;IAE7D,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAA;QACzC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC,QAAQ,CAAA;IAChD,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA;AAClD,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAC9C,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAC9C,cAAc,CAAC,kBAAkB,CAAC,yBAAyB,CAAC,CAAA"}

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGlE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAMvD,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,CAAC,KACxF,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAahD,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,CAAC,KAExF,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAahD,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,CAC1B,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,KAC7G,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAWhD,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,CAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,KAC7G,sBAAsB,CAAC,gBAAgB,CAAC,OAAO,GAAG,IAAI,CAAC,CAc3D,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAU,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,eAAe,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAItH,CAAA;AAED,MAAM,WAAW,YAAa,SAAQ,aAAa;CAAI"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGlE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAevD,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,CAAC,KACxF,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAahD,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,CAAC,KAExF,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAahD,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,CAC1B,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,KAC7G,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAWhD,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,CAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,KAC7G,sBAAsB,CAAC,gBAAgB,CAAC,OAAO,GAAG,IAAI,CAAC,CAc3D,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAU,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,eAAe,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAItH,CAAA;AAED,MAAM,WAAW,YAAa,SAAQ,aAAa;CAAI"}

package/build/helper.js

@@ -1,7 +1,16 @@
 import { assertContext } from '@owlmeans/context';
 import { EntrypointOutcome } from '@owlmeans/entrypoint';
+/**
+ * The context a handler runs against.
+ *
+ * The HTTP boundary hangs the request-scoped context on the raw Fastify request, so a handler
+ * reached that way gets it from there. A request that did not come from Fastify has no `original`
+ * at all — a queued call is rebuilt from an envelope, and a socket frame carries its own — so this
+ * has to fall back rather than dereference: these handlers are the same functions on every
+ * transport, and only the way they were reached differs.
+ */
 const _castContextFromOriginal = (req, def) => {
-    return req.original._ctx ?? def;
+    return req.original?._ctx ?? def;
 };
 export const handleBody = handler => ref => async (req, res) => {
     const ctx = assertContext(ref.ref?.ctx);

package/build/helper.js.map

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

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,6 @@ export * from './server.js';
 export * from './consts.js';
 export * from './errors.js';
 export * from './helper.js';
+export * from './hold.js';
+export * from './protocol.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;AACzB,cAAc,eAAe,CAAA"}

package/build/index.js

@@ -2,4 +2,6 @@ export * from './server.js';
 export * from './consts.js';
 export * from './errors.js';
 export * from './helper.js';
+export * from './hold.js';
+export * from './protocol.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;AACzB,cAAc,eAAe,CAAA"}