@owlmeans/server-api 0.1.18-rc.5 → 0.1.18-rc.51

package/build/utils/payload.js

@@ -1,64 +1,48 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint';
-import { ACCEPTED, CREATED, OK, SERVER_ERROR } from '@owlmeans/api';
-export const provideRequest = (alias, req, provision) => {
-    provision = provision ?? false;
-    return {
-        alias,
-        auth: req._auth ?? undefined,
-        params: req.params,
-        body: req.body,
-        headers: req.headers,
-        query: req.query,
-        path: req.url,
-        original: provision ? req : undefined
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api';
+import { httpErrorHelper } from './error.js';
+export const createPayloadHelper = () => {
+    const provideRequest = (alias, req, provision) => {
+        provision = provision ?? false;
+        return {
+            alias,
+            auth: req._auth ?? undefined,
+            // Resolved once by `authorize` and carried by reference, exactly like `_auth`, so a handler
+            // reached through any path sees the same entity the guard admitted.
+            entity: req._entity ?? undefined,
+            params: req.params,
+            body: req.body,
+            headers: req.headers,
+            query: req.query,
+            path: req.url,
+            original: provision ? req : undefined
+        };
     };
-};
-/**
- * Emits the response onto the fastify reply if the handler produced an
- * error or an outcome. Returns `true` when something was actually sent so
- * callers don't rely on `reply.sent`, which in fastify v5 only flips once
- * the raw socket finishes writing (asynchronously) and therefore reads
- * `false` synchronously right after `reply.send()`.
- *
- * @throws {Error}
- */
-export const executeResponse = (response, reply, throwOnError) => {
-    if (response.error != null) {
-        if (throwOnError ?? false) {
-            throw response.error;
-        }
-        reply.code(SERVER_ERROR).send(response.error.message);
-        return true;
-    }
-    else if (response.outcome != null) {
-        switch (response.outcome) {
-            case EntrypointOutcome.Accepted:
-                reply.code(ACCEPTED).send(response.value);
-                break;
-            case EntrypointOutcome.Created:
-                reply.code(CREATED).send(response.value);
-                break;
-            case EntrypointOutcome.Ok:
-            default:
-                reply.code(OK).send(response.value);
-        }
-        return true;
-    }
-    return false;
-};
-export const fixFormatDates = (schema) => {
-    if (schema.type === 'object') {
-        if (schema.format === 'date-time') {
-            schema.type = 'string';
-            schema.format = 'date-time';
-            if (schema.required != null) {
-                delete schema.required;
+    const executeResponse = (response, reply, throwOnError) => {
+        if (response.error != null) {
+            if (throwOnError ?? false) {
+                throw response.error;
             }
+            httpErrorHelper.handleError(response.error, reply);
+            return true;
         }
-        else if (schema.properties != null) {
-            schema.properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, fixFormatDates(value)]));
+        else if (response.outcome != null) {
+            switch (response.outcome) {
+                case EntrypointOutcome.Accepted:
+                    reply.code(ACCEPTED).send(response.value);
+                    break;
+                case EntrypointOutcome.Created:
+                    reply.code(CREATED).send(response.value);
+                    break;
+                case EntrypointOutcome.Ok:
+                default:
+                    reply.code(OK).send(response.value);
+            }
+            return true;
         }
-    }
-    return schema;
+        return false;
+    };
+    return { provideRequest, executeResponse };
 };
+export const payloadHelper = createPayloadHelper();
 //# sourceMappingURL=payload.js.map

package/build/utils/payload.js.map

@@ -1 +1 @@
-{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAGxD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAGnE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,GAAY,EAAE,SAAmB,EAAmB,EAAE;IAClG,SAAS,GAAG,SAAS,IAAI,KAAK,CAAA;IAC9B,OAAO;QACL,KAAK;QACL,IAAI,EAAG,GAAW,CAAC,KAAK,IAAI,SAAS;QACrC,MAAM,EAAE,GAAG,CAAC,MAA4D;QACxE,IAAI,EAAE,GAAG,CAAC,IAA2B;QACrC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAA2D;QACtE,IAAI,EAAE,GAAG,CAAC,GAAG;QACb,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;KACtC,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAI,QAA6B,EAAE,KAAe,EAAE,YAAsB,EAAW,EAAE;IACpH,IAAI,QAAQ,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QAC3B,IAAI,YAAY,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,QAAQ,CAAC,KAAK,CAAA;QACtB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACrD,OAAO,IAAI,CAAA;IACb,CAAC;SAAM,IAAI,QAAQ,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;QACpC,QAAQ,QAAQ,CAAC,OAAO,EAAE,CAAC;YACzB,KAAK,iBAAiB,CAAC,QAAQ;gBAC7B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;gBACzC,MAAK;YACP,KAAK,iBAAiB,CAAC,OAAO;gBAC5B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;gBACxC,MAAK;YACP,KAAK,iBAAiB,CAAC,EAAE,CAAC;YAC1B;gBACE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QACvC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAGD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAuB,EAAE,EAAE;IACxD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,GAAG,QAAQ,CAAA;YACtB,MAAM,CAAC,MAAM,GAAG,WAAW,CAAA;YAC3B,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;gBAC5B,OAAO,MAAM,CAAC,QAAQ,CAAA;YACxB,CAAC;QACH,CAAC;aAAM,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;YACrC,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,WAAW,CACpC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,cAAc,CAAC,KAAwB,CAAC,CAAC,CAAC,CACzG,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAGxD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAG5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAkB,EAAE;IACrD,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,GAAY,EAAE,SAAmB,EAAmB,EAAE;QAC3F,SAAS,GAAG,SAAS,IAAI,KAAK,CAAA;QAC9B,OAAO;YACL,KAAK;YACL,IAAI,EAAG,GAAW,CAAC,KAAK,IAAI,SAAS;YACrC,4FAA4F;YAC5F,oEAAoE;YACpE,MAAM,EAAG,GAAW,CAAC,OAAO,IAAI,SAAS;YACzC,MAAM,EAAE,GAAG,CAAC,MAA4D;YACxE,IAAI,EAAE,GAAG,CAAC,IAA2B;YACrC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG,CAAC,KAA2D;YACtE,IAAI,EAAE,GAAG,CAAC,GAAG;YACb,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;SACtC,CAAA;IACH,CAAC,CAAA;IAED,MAAM,eAAe,GAAG,CAAI,QAA6B,EAAE,KAAe,EAAE,YAAsB,EAAW,EAAE;QAC7G,IAAI,QAAQ,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;YAC3B,IAAI,YAAY,IAAI,KAAK,EAAE,CAAC;gBAC1B,MAAM,QAAQ,CAAC,KAAK,CAAA;YACtB,CAAC;YACD,eAAe,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;YAClD,OAAO,IAAI,CAAA;QACb,CAAC;aAAM,IAAI,QAAQ,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;YACpC,QAAQ,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACzB,KAAK,iBAAiB,CAAC,QAAQ;oBAC7B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;oBACzC,MAAK;gBACP,KAAK,iBAAiB,CAAC,OAAO;oBAC5B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;oBACxC,MAAK;gBACP,KAAK,iBAAiB,CAAC,EAAE,CAAC;gBAC1B;oBACE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA;AAC5C,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAA"}

package/build/utils/schema.d.ts

@@ -0,0 +1,7 @@
+import type { AnySchemaObject } from 'ajv';
+/**
+ * A request schema Fastify can serve: a `date-time` object becomes a `date-time` string (and loses
+ * its `required` list), recursively through object properties. Mutates and returns `schema`.
+ */
+export declare const fixFormatDates: (schema: AnySchemaObject) => AnySchemaObject;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAA;AAE1C;;;GAGG;AACH,eAAO,MAAM,cAAc,WAAY,eAAe,KAAG,eAgBxD,CAAA"}

package/build/utils/schema.js

@@ -0,0 +1,20 @@
+/**
+ * A request schema Fastify can serve: a `date-time` object becomes a `date-time` string (and loses
+ * its `required` list), recursively through object properties. Mutates and returns `schema`.
+ */
+export const fixFormatDates = (schema) => {
+    if (schema.type === 'object') {
+        if (schema.format === 'date-time') {
+            schema.type = 'string';
+            schema.format = 'date-time';
+            if (schema.required != null) {
+                delete schema.required;
+            }
+        }
+        else if (schema.properties != null) {
+            schema.properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, fixFormatDates(value)]));
+        }
+    }
+    return schema;
+};
+//# sourceMappingURL=schema.js.map

package/build/utils/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAuB,EAAmB,EAAE;IACzE,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,GAAG,QAAQ,CAAA;YACtB,MAAM,CAAC,MAAM,GAAG,WAAW,CAAA;YAC3B,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;gBAC5B,OAAO,MAAM,CAAC,QAAQ,CAAA;YACxB,CAAC;QACH,CAAC;aAAM,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;YACrC,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,WAAW,CACpC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,cAAc,CAAC,KAAwB,CAAC,CAAC,CAAC,CACzG,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/build/utils/server.d.ts

@@ -1,10 +1,7 @@
 import type { FastifyReply, FastifyRequest } from 'fastify';
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint';
-import type { CommonEntrypoint } from '@owlmeans/entrypoint';
-import type { ServerContext, ServerConfig } from '@owlmeans/server-context';
-type Config = ServerConfig;
-type Context = ServerContext<Config>;
-export declare const canServeModule: (context: Context, module: CommonEntrypoint) => module is ServerEntrypoint<unknown>;
+import { type CommonEntrypoint } from '@owlmeans/entrypoint';
+import type { ServerContext2 } from './types.local.js';
+export declare const canServeModule: (context: ServerContext2, module: CommonEntrypoint) => module is ServerEntrypoint<unknown>;
 export declare const createServerHandler: (module: ServerEntrypoint<FastifyRequest>, location: string) => (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-export {};
 //# sourceMappingURL=server.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/utils/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG5D,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAQ3E,KAAK,MAAM,GAAG,YAAY,CAAA;AAC1B,KAAK,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;AAEpC,eAAO,MAAM,cAAc,YAAa,OAAO,UAAU,gBAAgB,KAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAY7G,CAAA;AAED,eAAO,MAAM,mBAAmB,WAAY,gBAAgB,CAAC,cAAc,CAAC,YAAY,MAAM,WAChF,cAAc,SAAS,YAAY,kBA0C9C,CAAA"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/utils/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC3D,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACjF,OAAO,EAAE,KAAK,gBAAgB,EAAqC,MAAM,sBAAsB,CAAA;AAQ/F,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGrE,eAAO,MAAM,cAAc,YAAa,cAAc,UAAU,gBAAgB,KAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAcpH,CAAA;AAED,eAAO,MAAM,mBAAmB,WAAY,gBAAgB,CAAC,cAAc,CAAC,YAAY,MAAM,WAChF,cAAc,SAAS,YAAY,kBAuC9C,CAAA"}

package/build/utils/server.js

@@ -1,10 +1,10 @@
-import { AppType } from '@owlmeans/context';
-import { assertContext } from '@owlmeans/context';
+import { AppType, assertContext } from '@owlmeans/context';
 import { provideResponse } from '@owlmeans/entrypoint';
 import { ResilientError } from '@owlmeans/error';
 import { OK } from '@owlmeans/api';
-import { handleError } from './error.js';
-import { executeResponse, provideRequest } from './payload.js';
+import { logger } from '@owlmeans/log';
+import { httpErrorHelper } from './error.js';
+import { payloadHelper } from './payload.js';
 import { authorize } from './guards.js';
 import { RouteProtocols } from '@owlmeans/route';
 export const canServeModule = (context, module) => {
@@ -14,7 +14,9 @@ export const canServeModule = (context, module) => {
     if (module.route.route.service != null && module.route.route.service !== context.cfg.service) {
         return false;
     }
-    if (module.route.route.protocol === RouteProtocols.SOCKET) {
+    // HTTP serves only its own protocol. Custom transports are handled by their owning packages.
+    if (module.route.route.protocol != null
+        && module.route.route.protocol !== RouteProtocols.WEB) {
         return false;
     }
     return 'isIntermediate' in module.route;
@@ -27,12 +29,12 @@ export const createServerHandler = (module, location) => async (req, reply) => {
         context = authorized[0];
         module = authorized[1];
         const response = provideResponse(reply);
-        const request = provideRequest(module.alias, req, true);
+        const request = payloadHelper.provideRequest(module.alias, req, true);
         const gates = module.getGates();
         for (const [srv, params] of gates) {
             const gate = context.service(srv);
             await gate.assert(request, response, params);
-            executeResponse(response, reply, true);
+            payloadHelper.executeResponse(response, reply, true);
         }
         await module.handle(request, response);
         // Don't rely on `reply.sent` here: in fastify v5 it is backed by
@@ -41,22 +43,19 @@ export const createServerHandler = (module, location) => async (req, reply) => {
         // synchronously right after `reply.send()`. Track the emitted state
         // explicitly instead, and only fall back to a default response when
         // neither `executeResponse` nor the handler itself (hijack) replied.
-        const responded = executeResponse(response, reply, true);
+        const responded = payloadHelper.executeResponse(response, reply, true);
         if (!responded && !reply.sent) {
-            console.warn(`SENDS DEFAULT RESPONSE: ${module.alias}`);
+            logger('http').warn(`SENDS DEFAULT RESPONSE: ${module.alias}`);
             reply.code(OK).send(response.value);
         }
     }
     catch (error) {
-        console.error(`Error in ${module.alias} (${location})`);
-        console.error(JSON.stringify(error, null, 2));
-        console.error(error);
         if (module.fixer != null) {
             const fixer = context.service(module.fixer);
             fixer.handle(reply, ResilientError.ensure(error));
             return;
         }
-        handleError(error, reply);
+        httpErrorHelper.handleError(error, reply, httpErrorHelper.errorExposure(context.cfg));
     }
 };
 //# sourceMappingURL=server.js.map

package/build/utils/server.js.map

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

package/build/utils/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What an error class may declare about the HTTP status it is answered with.
+ *
+ * Structural on purpose: the classes that declare it live in packages that must not depend on an
+ * HTTP server (`@owlmeans/payment`, a product's contract package), so they write a plain
+ * `public static httpStatus = 409` and nothing imports this type.
+ */
+export interface HttpStatusDeclaration {
+    httpStatus?: unknown;
+    /** Explicit opt-in for a declared 5xx response. Client-error declarations need no opt-in. */
+    allowServerErrorStatus?: unknown;
+}
+export interface SerializedHttpError {
+    status: number;
+    body: string;
+    incidentId: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,6FAA6F;IAC7F,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB"}

package/build/utils/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":""}

package/build/utils/types.local.d.ts

@@ -0,0 +1,9 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context';
+import type { Config as ApiConfig } from '../types.js';
+export type Config = ServerConfig;
+export interface Context<C extends Config = Config> extends ServerContext<C> {
+}
+export type Severity = 'debug' | 'info' | 'warn' | 'error';
+export type ServerConfig2 = ApiConfig;
+export type ServerContext2 = ServerContext<ServerConfig2>;
+//# sourceMappingURL=types.local.d.ts.map

package/build/utils/types.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../../src/utils/types.local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC3E,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,aAAa,CAAA;AAEtD,MAAM,MAAM,MAAM,GAAG,YAAY,CAAA;AAEjC,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI;AAEhF,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D,MAAM,MAAM,aAAa,GAAG,SAAS,CAAA;AAErC,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC,aAAa,CAAC,CAAA"}

package/build/utils/types.local.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.local.js.map

package/build/utils/types.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.js","sourceRoot":"","sources":["../../src/utils/types.local.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.5",
+  "version": "0.1.18-rc.51",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 264 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -29,22 +30,23 @@
   },
   "dependencies": {
     "@fastify/cors": "^11.3.0",
-    "@fastify/helmet": "^13.1.0",
-    "@fastify/middie": "^9.0.2",
-    "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.5",
-    "@owlmeans/auth": "^0.1.18-rc.5",
-    "@owlmeans/auth-common": "^0.1.18-rc.5",
-    "@owlmeans/context": "^0.1.18-rc.5",
-    "@owlmeans/error": "^0.1.18-rc.5",
-    "@owlmeans/entrypoint": "^0.1.18-rc.5",
-    "@owlmeans/route": "^0.1.18-rc.5",
-    "@owlmeans/server-context": "^0.1.18-rc.5",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.5",
+    "@fastify/helmet": "^13.1.1",
+    "@fastify/middie": "^9.3.4",
+    "@fastify/multipart": "^10.1.2",
+    "@owlmeans/api": "^0.1.18-rc.47",
+    "@owlmeans/auth": "^0.1.18-rc.40",
+    "@owlmeans/auth-common": "^0.1.18-rc.47",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/log": "^0.1.18-rc.2",
+    "@owlmeans/route": "^0.1.18-rc.35",
+    "@owlmeans/server-context": "^0.1.18-rc.43",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.40",
     "ajv-errors": "^3.0.0",
-    "fastify": "^5.0.0",
-    "fastify-raw-body": "^5.0.0",
-    "pino-pretty": "^13.0.0"
+    "fastify": "^5.12.5",
+    "fastify-raw-body": "^6.0.1",
+    "pino-pretty": "^13.2.0"
   },
   "peerDependencies": {
     "ajv": "*",
@@ -52,7 +54,9 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^26.1.0",
+    "@owlmeans/resource": "^0.1.18-rc.40",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.local.ts

@@ -0,0 +1 @@
+export const bodyLimit = 1024 * 1024 * 20

package/src/errors.ts

@@ -29,7 +29,25 @@ export class NoFileError extends ApiError {
   }
 }
 
+/**
+ * `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 {
+  public static override typeName = 'HandlerMisconfiguredError'
+
+  constructor(message: string = 'error') {
+    super(`handler:misconfigured:${message}`)
+    this.type = HandlerMisconfiguredError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(AuthFailedError)
 ResilientError.registerErrorClass(AccessError)
 ResilientError.registerErrorClass(NoFileError)
+ResilientError.registerErrorClass(HandlerMisconfiguredError)
 

package/src/helper.ts

@@ -1,15 +1,21 @@
 
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { assertContext } from '@owlmeans/context'
-import { EntrypointOutcome } from '@owlmeans/entrypoint'
-import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
+import { type BasicConfig, type BasicContext, assertContext } from '@owlmeans/context'
+import { EntrypointOutcome, type AbstractRequest, type AbstractResponse } from '@owlmeans/entrypoint'
 import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
-import type { Config, Context } from './types.js'
+import type { Config, Context, UploadedFile } from './types.js'
 import type { FastifyRequest } from 'fastify'
-import type { MultipartFile } from '@fastify/multipart'
 
+/**
+ * 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 = <C extends BasicConfig, T extends BasicContext<C> = BasicContext<C>>(req: AbstractRequest, def: T): T => {
-  return req.original._ctx ?? def
+  return req.original?._ctx ?? def
 }
 
 export const handleBody: <T>(
@@ -86,4 +92,3 @@ export const extractUploadedFile = async <T extends {} = {}>(req: AbstractReques
   return request.file()
 }
 
-export interface UploadedFile extends MultipartFile { }

package/src/hold.ts

@@ -0,0 +1,66 @@
+import Fastify from 'fastify'
+import { logger } from '@owlmeans/log'
+import type { ServerConfig } from '@owlmeans/server-context'
+import { CLOSED_HOST, OPENED_HOST, PORT } from './consts.js'
+import type { ApiPortHold, ApiPortHoldOptions } from './types.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: 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 })
+  logger('server').info(`api-server: holding ${host}:${port} for the boot${opts.okPath != null ? ` (${opts.okPath})` : ''}`, undefined, { event: 'server.hold' })
+
+  return {
+    release: async () => { await server.close() },
+  }
+}

package/src/index.ts

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