@lakutata/entrypoint 3.0.0 → 3.1.0

package/dist/cjs/adapter/fastify/FastifyHTTPEntrypoint.js

@@ -12,6 +12,7 @@ const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
 const Result_js_1 = require("../../lib/Result.js");
 const RouteNotFoundException_js_1 = require("../../exceptions/RouteNotFoundException.js");
 const Connections_js_1 = require("../../lib/Connections.js");
+const ExplicitStatus_js_1 = require("../../lib/ExplicitStatus.js");
 const Responders_js_1 = require("./Responders.js");
 /**
  * The content types of the common file extensions
@@ -127,7 +128,8 @@ function isFastifyInstance(value) {
  *                 }
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */
@@ -222,6 +224,7 @@ function fastifyHTTPEntrypoint(options = {}) {
             return await sendFile(result, request, reply);
         if (result instanceof Result_js_1.StatusResult) {
             reply.code(result.status).headers(result.headers);
+            (0, ExplicitStatus_js_1.markExplicitStatus)(reply.raw);
             return respond.success(reply, result.data, request);
         }
         respond.success(reply, result, request);

package/dist/cjs/adapter/fastify/Responders.d.ts

@@ -99,7 +99,8 @@ export type FastifyJSONEnvelopeOptions = {
  *                 })
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/fastify/Responders.js

@@ -4,6 +4,7 @@ exports.FastifyJSONResponder = void 0;
 exports.fastifyJSONEnvelope = fastifyJSONEnvelope;
 const HTTPErrors_js_1 = require("../../lib/HTTPErrors.js");
 const Envelope_js_1 = require("../../lib/Envelope.js");
+const ExplicitStatus_js_1 = require("../../lib/ExplicitStatus.js");
 /**
  * Send JSON
  * @param reply
@@ -20,7 +21,7 @@ function sendJSON(reply, data) {
 exports.FastifyJSONResponder = {
     success: (reply, data) => {
         if (data === undefined) {
-            reply.code(reply.statusCode === 200 ? 204 : reply.statusCode).send();
+            reply.code(reply.statusCode === 200 && !(0, ExplicitStatus_js_1.hasExplicitStatus)(reply.raw) ? 204 : reply.statusCode).send();
             return;
         }
         sendJSON(reply, data);
@@ -70,7 +71,8 @@ exports.FastifyJSONResponder = {
  *                 })
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/http/HTTPServiceEntrypoint.d.ts

@@ -66,8 +66,8 @@ export declare function httpRequestOfContext(context: ServiceContext): IncomingM
  * A request is a `POST` to the path whose JSON body holds the action's pattern and input (`{"cmd": "echo", "text":
  * "hi"}`). The response is always 200 with the body `{success, error, payload}` (see `ServiceResponseCodec`): `payload`
  * is the result, or `error` the whole error object when the action failed (no matching action, validation…). A body that
- * is not JSON or exceeds `limit` is answered with 400 and an error body; any other method or path with 404. The CORS
- * headers allow any origin.
+ * is not JSON is answered with 400 and an error body, a body over `limit` with 413; any other method or path with 404.
+ * The CORS headers allow any origin, and the headers a preflight asks for (`Authorization`…).
  *
  * The events pushed to the clients (`Entrypoint.notify`, `Entrypoint.broadcast`) are streamed as Server-Sent Events by
  * `GET <path>/events`: each event's name is the SSE event, its arguments the JSON array of its data. A client gives its
@@ -102,7 +102,8 @@ export declare function httpRequestOfContext(context: ServiceContext): IncomingM
  *             controllers: [EchoController],
  *             service: httpServiceEntrypoint({port: 3000, path: '/rpc'})
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  *
  * //A client: the response is {"success": true, "error": null, "payload": "hi"}

package/dist/cjs/adapter/http/HTTPServiceEntrypoint.js

@@ -9,6 +9,8 @@ const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
 const ServiceResponseCodec_js_1 = require("../../lib/ServiceResponseCodec.js");
 const EntrypointStoppedException_js_1 = require("../../exceptions/EntrypointStoppedException.js");
 const Connections_js_1 = require("../../lib/Connections.js");
+const ReadBody_js_1 = require("../../lib/ReadBody.js");
+const Preflight_js_1 = require("../../lib/Preflight.js");
 /**
  * Get the HTTP request carrying a service action's request, when {@link httpServiceEntrypoint} serves it (to read its
  * headers, its remote address…).
@@ -31,7 +33,8 @@ function httpRequestOfContext(context) {
     return context.request;
 }
 /**
- * The headers of the responses: the tools of the browsers may call the adapter (the development of the applications)
+ * The headers of the responses: the tools of the browsers may call the adapter (the development of the applications);
+ * a preflight is allowed the headers it asks for
  */
 const CORS_HEADERS = {
     'Access-Control-Allow-Origin': '*',
@@ -59,22 +62,6 @@ function reply(response, status, body) {
         return;
     response.writeHead(status, { ...CORS_HEADERS, 'Content-Type': 'application/json; charset=utf-8' }).end(JSON.stringify(body));
 }
-/**
- * The body of a request, up to a limit
- * @param request
- * @param limit
- */
-async function readBody(request, limit) {
-    const chunks = [];
-    let size = 0;
-    for await (const chunk of request) {
-        size += chunk.length;
-        if (size > limit)
-            throw Object.assign(new Error(`The body of the request is larger than ${limit} bytes`), { statusCode: 413 });
-        chunks.push(chunk);
-    }
-    return Buffer.concat(chunks).toString('utf8');
-}
 /**
  * Create a service adapter of an entrypoint served over plain HTTP, handy to call the service actions from tools such
  * as curl or Postman during development. It needs no optional dependency.
@@ -82,8 +69,8 @@ async function readBody(request, limit) {
  * A request is a `POST` to the path whose JSON body holds the action's pattern and input (`{"cmd": "echo", "text":
  * "hi"}`). The response is always 200 with the body `{success, error, payload}` (see `ServiceResponseCodec`): `payload`
  * is the result, or `error` the whole error object when the action failed (no matching action, validation…). A body that
- * is not JSON or exceeds `limit` is answered with 400 and an error body; any other method or path with 404. The CORS
- * headers allow any origin.
+ * is not JSON is answered with 400 and an error body, a body over `limit` with 413; any other method or path with 404.
+ * The CORS headers allow any origin, and the headers a preflight asks for (`Authorization`…).
  *
  * The events pushed to the clients (`Entrypoint.notify`, `Entrypoint.broadcast`) are streamed as Server-Sent Events by
  * `GET <path>/events`: each event's name is the SSE event, its arguments the JSON array of its data. A client gives its
@@ -118,7 +105,8 @@ async function readBody(request, limit) {
  *             controllers: [EchoController],
  *             service: httpServiceEntrypoint({port: 3000, path: '/rpc'})
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  *
  * //A client: the response is {"success": true, "error": null, "payload": "hi"}
@@ -189,7 +177,7 @@ function httpServiceEntrypoint(options = {}) {
         });
         let data;
         try {
-            const body = await readBody(request, limit);
+            const body = await (0, ReadBody_js_1.readBody)(request, limit);
             data = body ? JSON.parse(body) : {};
         }
         catch (error) {
@@ -215,7 +203,7 @@ function httpServiceEntrypoint(options = {}) {
             server = (0, node_http_1.createServer)((request, response) => {
                 const url = new URL(request.url ?? '/', 'http://localhost');
                 if (request.method === 'OPTIONS')
-                    return void response.writeHead(204, CORS_HEADERS).end();
+                    return void response.writeHead(204, (0, Preflight_js_1.preflightHeaders)(request, CORS_HEADERS)).end();
                 if (request.method === 'GET' && url.pathname === eventsPath)
                     return listen(request, response, url);
                 if (request.method === 'POST' && url.pathname === requestPath)

package/dist/cjs/adapter/http/HTTPServiceProxy.d.ts

@@ -0,0 +1,190 @@
+import { type ActionPattern, Component, type ComponentOptionsBuilder } from '@lakutata/core';
+/**
+ * The options of an {@link HTTPServiceProxy}, given to {@link buildHTTPServiceProxy}.
+ */
+export type BuildHTTPServiceProxyOptions = {
+    /**
+     * The address of the service: the URL of its `httpServiceEntrypoint`, with the adapter's `path`
+     * (`http://inventory:3000/`, `https://orders.internal/rpc`).
+     */
+    readonly url: string;
+    /**
+     * The headers sent with each call and with the event stream, such as `{Authorization: 'Bearer <token>'}`.
+     */
+    readonly headers?: Record<string, string>;
+    /**
+     * The client's id, sent as the `id` header of the calls and the `id` query parameter of the event stream: the
+     * service's `ServiceContext.clientId`, which `Entrypoint.notify()` pushes events to. Give a stable one to receive
+     * the events across restarts. At most 200 characters.
+     * @default a random UUID
+     */
+    readonly clientId?: string;
+    /**
+     * The delay, in milliseconds, before the event stream is opened again once it ended or failed (the service
+     * restarted, unreachable). A non-negative integer.
+     * @default 1000
+     */
+    readonly reconnectDelay?: number;
+};
+/**
+ * Build the component options of an {@link HTTPServiceProxy}, to register it in the `components` of an application.
+ * @param options The service's address, and the headers, client id and reconnection delay.
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildHTTPServiceProxy, type HTTPServiceProxy} from 'lakutata/com/entrypoint'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             inventory: buildHTTPServiceProxy({url: 'http://inventory.internal:3000/'}),
+ *             //With a token, and a stable client id to receive the events of the service
+ *             orders: buildHTTPServiceProxy({
+ *                 url: 'https://orders.internal/rpc',
+ *                 headers: {Authorization: `Bearer ${process.env.ORDERS_TOKEN}`},
+ *                 clientId: 'shop-1'
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const inventory: HTTPServiceProxy = await app.getObject<HTTPServiceProxy>('inventory')
+ *         console.log(await inventory.invoke({cmd: 'stock.get', product: 'lamp'}))
+ *     })
+ * ```
+ */
+export declare const buildHTTPServiceProxy: ComponentOptionsBuilder<BuildHTTPServiceProxyOptions>;
+/**
+ * The client of a lakutata service served over HTTP by `httpServiceEntrypoint`: it invokes the service's actions by
+ * their patterns and listens to the events the service pushes to it. It is a component (a singleton), registered with
+ * {@link buildHTTPServiceProxy}; it needs no package (it uses the `fetch()` of Node.js), and its event stream is opened
+ * when the first listener is added.
+ *
+ * The failures of the remote actions are thrown as `ServiceInvokeException`, with the remote error's message and
+ * properties (`errno`, `statusCode`…) and the address as its `service`; a service that gives no response (unreachable,
+ * too slow, or an answer that is not a service response) as a `ServiceUnavailableException`.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {type HTTPServiceProxy, ServiceInvokeException, ServiceUnavailableException} from 'lakutata/com/entrypoint'
+ * import {Inject} from 'lakutata/decorator/di'
+ *
+ * class StockWatcher extends Component {
+ *     //Registered as inventory: buildHTTPServiceProxy({url: 'http://inventory.internal:3000/'})
+ *     @Inject('inventory')
+ *     protected readonly inventory: HTTPServiceProxy
+ *
+ *     protected async init(): Promise<void> {
+ *         //The events the inventory pushes with Entrypoint.notify(clientId, 'lowStock', product, quantity)
+ *         this.inventory.on('lowStock', (product: string, quantity: number): void => {
+ *             console.log(`${product}: ${quantity} left`)
+ *         })
+ *     }
+ *
+ *     public async quantity(product: string): Promise<number | undefined> {
+ *         try {
+ *             //5 seconds at most; the inventory aborts the action's signal when the call gives up
+ *             return await this.inventory.invoke({cmd: 'stock.get', product: product}, 5000)
+ *         } catch (error) {
+ *             //The action failed: its error
+ *             if (error instanceof ServiceInvokeException && error.errno === 'E_PRODUCT_NOT_FOUND') return undefined
+ *             //The inventory gave no response
+ *             if (error instanceof ServiceUnavailableException) return undefined
+ *             throw error
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export declare class HTTPServiceProxy extends Component {
+    #private;
+    /**
+     * The service's address, as configured (see {@link BuildHTTPServiceProxyOptions.url}); required.
+     */
+    protected readonly url: string;
+    /**
+     * The headers sent with each call and with the event stream; none by default.
+     */
+    protected readonly headers?: Record<string, string>;
+    /**
+     * The configured client id; a random UUID is used without it (see {@link HTTPServiceProxy.id}).
+     */
+    protected readonly clientId?: string;
+    /**
+     * The delay, in milliseconds, before the event stream is opened again.
+     * @default 1000
+     */
+    protected readonly reconnectDelay: number;
+    /**
+     * Create the client id and the address of the event stream (`<url>/events?id=<id>`); nothing connects before the
+     * first call.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Close the event stream and remove the listeners (the calls in progress complete).
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The client's id: the configured `clientId`, or a random UUID. It is sent as the `id` header of the calls, and is
+     * the `ServiceContext.clientId` of the service's actions.
+     */
+    get id(): string;
+    /**
+     * Invoke an action of the service, matched by its pattern.
+     * @param input The action's pattern and its input in one object (`{cmd: 'order.get', id: 1}`), sent as JSON: the
+     * values JSON cannot hold (functions, `undefined`, class instances) are lost or turned into plain objects.
+     * @param timeout The longest wait for the response, in milliseconds; 600000 (10 minutes) by default. The request is
+     * abandoned after it, and the service aborts the action's signal.
+     * @returns The action's result, decoded from JSON: `undefined` when the action returned nothing.
+     * @throws {ServiceInvokeException} When the action fails (no action matches the pattern, an invalid input, an error
+     * thrown, the service stopping), or the service refuses the request (another path, a body over its limit): the
+     * remote error's message and properties (`errno`…), the address as its `service`.
+     * @throws {ServiceUnavailableException} When the service gives no response: unreachable, no response within the
+     * timeout, or an answer that is not a service response. Its `cause` is the error of the request.
+     */
+    invoke<T extends Record<string, any>>(input: ActionPattern<T>, timeout?: number): Promise<any>;
+    /**
+     * Listen to an event the service pushes to this client (`Entrypoint.notify()`, `broadcast()`); the first listener
+     * opens the event stream. The listeners' errors are ignored. The `client` event, received when the stream opens,
+     * carries the client's id.
+     * @param eventName The event's name.
+     * @param listener Called with the event's arguments, decoded from JSON.
+     * @returns The proxy, to chain the calls.
+     */
+    on(eventName: string, listener: (...args: any[]) => void): this;
+    /**
+     * Listen to an event the service pushes to this client, once: the listener is removed before it is called.
+     * @param eventName The event's name.
+     * @param listener Called with the event's arguments, decoded from JSON.
+     * @returns The proxy, to chain the calls.
+     */
+    once(eventName: string, listener: (...args: any[]) => void): this;
+    /**
+     * Stop listening to an event; removing the last listener of all the events closes the event stream.
+     * @param eventName The event's name.
+     * @param listener The listener to remove; without it, all the event's listeners are removed.
+     * @returns The proxy, to chain the calls.
+     */
+    off(eventName: string, listener?: (...args: any[]) => void): this;
+    /**
+     * Add a listener, and open the event stream when it is not open.
+     * @param eventName The event's name.
+     * @param listener The listener.
+     * @param once Whether the listener is removed after its first call.
+     * @returns The proxy.
+     * @protected
+     */
+    protected add(eventName: string, listener: (...args: any[]) => void, once: boolean): this;
+    /**
+     * Read the event stream and call the listeners; the stream is opened again after `reconnectDelay` milliseconds
+     * when it ends or fails, while there are listeners. It stops once no listener is left (removed by
+     * {@link HTTPServiceProxy.off}, or the last `once()` listener called) or the proxy is destroyed.
+     * @returns A promise resolved once the reading stops.
+     * @protected
+     */
+    protected stream(): Promise<void>;
+}