@lakutata/nats 2.3.0 → 3.0.0-beta.1

package/dist/cjs/components/NATS.d.ts

@@ -0,0 +1,376 @@
+import { Application, Component, ComponentOptionsBuilder } from '@lakutata/core';
+import { type Codec, Subscription, type ObjectStoreStatus } from 'nats';
+import { SubscribeOptions } from '../types/SubscribeOptions.js';
+import { NatsClientOptions } from '../interfaces/NatsClientOptions.js';
+/**
+ * Build the component options of a {@link NATS} component, to register it in the `components` of an application (or a
+ * module) under the name of your choice. The options are validated when the component is created, not here.
+ * @param options The connection options: the servers, the codec, the authentication, the reconnection and the bulk
+ * channel of the large payloads.
+ * @returns The component options (`{class: NATS, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, type NATS} from '@lakutata/nats'
+ *
+ * Application
+ *     .run({
+ *         id: 'notifier.app',
+ *         name: 'Notifier',
+ *         components: {
+ *             nats: buildNatsClientOptions({
+ *                 servers: ['nats://10.0.0.1:4222', 'nats://10.0.0.2:4222'],
+ *                 user: 'notifier',
+ *                 pass: 'secret',
+ *                 name: 'notifier',
+ *                 //Never give up reconnecting
+ *                 maxReconnectAttempts: -1
+ *             })
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const nats: NATS = await app.getObject('nats')
+ *         nats.publish('notification.sent', {to: 'ada@example.com'})
+ *     })
+ * ```
+ */
+export declare const buildNatsClientOptions: ComponentOptionsBuilder<NatsClientOptions>;
+/**
+ * The NATS component: a connection to a NATS server (or cluster) to publish messages, subscribe to subjects, send
+ * requests and answer them, and emit and receive the service events. Register it in the `components` of an application
+ * with {@link buildNatsClientOptions} (or `{class: NATS, ...options}`) and get it with `getObject()` or `@Inject`; it is
+ * a singleton. The service entrypoint ({@link natsServiceEntrypoint}) and the service proxies ({@link ServiceProxy})
+ * use it by its component name.
+ *
+ * It connects when it is created: a server which cannot be reached within the `timeout` option fails its creation, and
+ * so the application's start. A lost connection is reestablished in the background (see the `reconnect` and
+ * `maxReconnectAttempts` options); once the reconnection is given up, an `'error'` event is emitted and the calls fail
+ * with the NATS client error `CONNECTION_CLOSED`. When it is destroyed, it drains its connections: the subscriptions stop receiving, the messages
+ * in progress are handled and the outgoing ones flushed before the connections close.
+ *
+ * Every payload is encoded with the codec ({@link messagePackCodec} by default). A payload larger than the server's
+ * `max_payload` (1 MiB by default) cannot be sent as a message: a request or a response of 90% of it or more is relayed
+ * through a JetStream object store when both sides enabled the bulk channel (the `bulk` option, on by default, which
+ * needs JetStream on the server), as a reference the receiving side reads transparently. The published messages and the
+ * events are never relayed: over `max_payload`, publishing them throws.
+ *
+ * It emits an `'error'` event, only when it has listeners, for the failures nobody else can report: a subscription
+ * callback or an event listener which threw, a message which could not be decoded, a subscription error (a permissions
+ * violation).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, type NATS} from '@lakutata/nats'
+ *
+ * Application
+ *     .run({
+ *         id: 'pricing.app',
+ *         name: 'Pricing',
+ *         components: {
+ *             nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222', name: 'pricing'})
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const nats: NATS = await app.getObject('nats')
+ *         nats.on('error', (error: Error): void => console.error('NATS message handling failed', error))
+ *         //Answer the requests, shared between the instances of the application: the value returned is the response
+ *         nats.subscribe('price.get', async (input: {sku: string}): Promise<number> => input.sku.length * 10, {queue: 'pricing'})
+ *         //The messages of every region: the subject tells which one
+ *         nats.subscribe('price.changed.*', (price: number, subject: string): void => console.log(subject, price))
+ *         nats.publish('price.changed.eu', 42)
+ *         console.log(await nats.request('price.get', {sku: 'ABC'}, 5000)) //30
+ *         //The service events of this application, received by the applications listening to them
+ *         nats.emitServiceEvent('priceChanged', 'ABC', 30)
+ *         nats.onServiceEvent('stock.service', 'stockChanged', (sku: string, quantity: number): void => console.log(sku, quantity))
+ *     })
+ * ```
+ */
+export declare class NATS extends Component {
+    #private;
+    /**
+     * The application the component belongs to; its id names the service events it emits.
+     */
+    protected readonly app: Application;
+    /**
+     * The NATS server, or the servers of a cluster: `host:port` or a URL (`nats://user:pass@host:4222`).
+     */
+    protected readonly servers: string | string[];
+    /**
+     * The codec encoding and decoding every payload.
+     * @default messagePackCodec()
+     */
+    protected readonly codec: Codec<unknown>;
+    /**
+     * The time to wait for the connection to a server to be established, in milliseconds.
+     * @default 20000
+     */
+    protected readonly timeout?: number;
+    /**
+     * The token of the server's token authentication.
+     */
+    protected readonly token?: string;
+    /**
+     * The user name of the server's user/password authentication.
+     */
+    protected readonly user?: string;
+    /**
+     * The password of the server's user/password authentication.
+     */
+    protected readonly pass?: string;
+    /**
+     * Whether the client prints the protocol messages it sends and receives.
+     * @default false
+     */
+    protected readonly debug?: boolean;
+    /**
+     * The number of pings left unanswered after which the connection is considered stale and the client reconnects.
+     * @default 2
+     */
+    protected readonly maxPingOut?: number;
+    /**
+     * The number of reconnection attempts to each server before giving up, `-1` never giving up.
+     * @default 10
+     */
+    protected readonly maxReconnectAttempts?: number;
+    /**
+     * The client name shown by the server's monitoring; it also names the default bucket of the bulk channel.
+     */
+    protected readonly name?: string;
+    /**
+     * Whether the messages this client publishes are never delivered to its own subscriptions.
+     * @default false
+     */
+    protected readonly noEcho?: boolean;
+    /**
+     * Whether the servers are tried in the order given, instead of a random order.
+     * @default false
+     */
+    protected readonly noRandomize?: boolean;
+    /**
+     * The interval between the pings the client sends to check the connection, in milliseconds.
+     * @default 120000
+     */
+    protected readonly pingInterval?: number;
+    /**
+     * Whether the client reconnects after losing its connection.
+     * @default true
+     */
+    protected readonly reconnect?: boolean;
+    /**
+     * Whether the bulk channel, relaying the large payloads through a JetStream object store over a second connection,
+     * is prepared when the component starts.
+     * @default true
+     */
+    protected readonly bulk?: boolean;
+    /**
+     * The object store bucket of the bulk channel.
+     * @default `lkt-bulk-{name}`, `lkt-bulk-default` without `name`
+     */
+    protected readonly bulkBucket?: string;
+    /**
+     * The time to live of the objects of the bulk channel, in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    protected readonly bulkTTL?: number;
+    /**
+     * The number of replicas of the bulk bucket, sent to the server only when set.
+     * @default none: the server's default (one replica)
+     */
+    protected readonly bulkReplicas?: number;
+    /**
+     * The subscriptions of the service event listeners, by event subject, then by listener.
+     */
+    protected readonly serviceEventSubscriptionMap: Map<string, Map<(...args: any[]) => void, Subscription>>;
+    /**
+     * Connect to the server, then prepare the bulk channel when it is enabled (a failure of the bulk channel only
+     * disables it, with a warning).
+     * @throws {Error} The NATS client error when no server can be reached.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Drain the connections: stop receiving, finish the messages in progress and flush the outgoing ones, then close.
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Graceful shutdown: drain stops receiving, finishes the messages in progress and flushes the outgoing ones before closing,
+     * so the requests in progress survive a rolling update; a failed drain closes the connection
+     * @param conn
+     * @private
+     */
+    private drainConnection;
+    /**
+     * Publish a message: every subscription to the subject receives it (one per queue group). It is not answered, and is
+     * lost when nobody listens.
+     * @param subject The subject, without wildcards (`order.created`).
+     * @param payload The data, encoded with the codec.
+     * @throws {Error} The NATS client error `MAX_PAYLOAD_EXCEEDED` when the encoded payload is larger than the server's
+     * `max_payload` (the published messages are never relayed through the bulk channel), `CONNECTION_CLOSED` once the
+     * connection is closed, `BAD_SUBJECT` for an empty subject; the codec's error when the payload cannot be encoded.
+     */
+    publish(subject: string, payload: any): void;
+    /**
+     * Send a request and wait for its first response. A subscription answers it with its callback's return value (see
+     * {@link NATS.subscribe}); when nobody listens on the subject, it fails at once.
+     *
+     * A payload of 90% of the server's `max_payload` or more is relayed through the bulk channel when the subject's
+     * responders support it: learned from a previous response on the subject, else asked once by a probe of the subject
+     * (answered by the responders of this version with the bulk channel on; the older ones do not answer it). Otherwise it
+     * is sent as a message, and fails over `max_payload`. A large response is relayed the same way and read
+     * transparently.
+     * @param subject The subject of the responders.
+     * @param payload The data, encoded with the codec.
+     * @param timeout The time to wait for the response, in milliseconds; `0` or no value waits 600000 (10 minutes).
+     * @returns The response, decoded.
+     * @throws {NatsNoRespondersAvailableException} When nobody listens on the subject.
+     * @throws {NatsRequestTimeoutException} When no response arrives in time (the request may have been processed).
+     * @throws {NatsBulkException} When a large request cannot be stored, or a large response cannot be read.
+     * @throws {Error} The NATS client error `MAX_PAYLOAD_EXCEEDED` when a payload too large is not relayed,
+     * `CONNECTION_CLOSED` once the connection is closed; the codec's error when the payload or the response cannot be
+     * encoded or decoded.
+     */
+    request(subject: string, payload?: any, timeout?: number): Promise<any>;
+    /**
+     * Subscribe to a subject and handle its messages with a callback. The payloads are decoded (and read from the bulk
+     * channel when they are references) before the callback runs. A request (a message with a reply subject, sent by
+     * {@link NATS.request}) is answered with the callback's return value, awaited and encoded, relayed through the bulk
+     * channel when it is large and the requester supports it; the return value of a published message is ignored.
+     *
+     * When the callback throws (or a payload cannot be decoded, or a response cannot be sent), the error is emitted as an
+     * `'error'` event, and a request is answered with `subscribeOptions.errorResponse`, or not answered at all (the
+     * requester waits for its timeout).
+     * @param subject The subject, possibly with wildcards: `*` matches one token (`order.*`), `>` the remaining tokens
+     * (`order.>`).
+     * @param callback The handler: receives the decoded payload and the subject the message arrived on (useful with the
+     * wildcards), and returns the response to a request.
+     * @param subscribeOptions The queue group, the number of messages, the sequential handling and the error response.
+     * @returns The NATS subscription: `unsubscribe()` stops it at once, `drain()` once the messages received are handled.
+     * @throws {Error} The NATS client error `CONNECTION_CLOSED` once the connection is closed, `BAD_SUBJECT` for an invalid
+     * subject.
+     */
+    subscribe(subject: string, callback: (data: any, subject: string) => any | Promise<any>, subscribeOptions?: SubscribeOptions): Subscription;
+    /**
+     * Subscribe to a subject, as {@link NATS.subscribe}; the subscriptions of the events do not answer the capability
+     * probes of the requesters (nobody requests them).
+     * @param subject The subject, wildcards allowed.
+     * @param callback Called with each message's data and subject; its result answers a request.
+     * @param subscribeOptions The queue group, the number of messages, the iteration and the error responses.
+     * @param answerProbes Whether the subscription answers the capability probes of the large requests to its subject.
+     * @returns The NATS subscription.
+     * @protected
+     */
+    protected subscribeTo(subject: string, callback: (data: any, subject: string) => any | Promise<any>, subscribeOptions: SubscribeOptions | undefined, answerProbes: boolean): Subscription;
+    /**
+     * Emit an `'error'` event when the component has listeners, and do nothing otherwise (an `'error'` event
+     * without listener would throw).
+     * @param error The error to report.
+     */
+    protected emitError(error: any): void;
+    /**
+     * Whether the bulk channel is ready: enabled by the `bulk` option and started (its connection and object store
+     * prepared).
+     */
+    get bulkEnabled(): boolean;
+    /**
+     * The encoded size from which a payload is relayed through the bulk channel, in bytes: 90% of the current server's
+     * `max_payload` (1 MiB when unknown).
+     */
+    get bulkThreshold(): number;
+    /**
+     * Whether the current server supports the message headers, which the bulk channel needs to mark its references.
+     */
+    get headersSupported(): boolean;
+    /**
+     * Store bytes in the bulk channel's object store, for its time to live (`bulkTTL`).
+     * @param bytes The bytes to store.
+     * @returns The id of the object (a random UUID), to read it with {@link NATS.getBulk}.
+     * @throws {NatsBulkException} When the bulk channel is not enabled, or the object store rejects the write.
+     */
+    putBulk(bytes: Uint8Array): Promise<string>;
+    /**
+     * Read an object from the bulk channel's object store. The object is not deleted.
+     * @param objId The id returned by {@link NATS.putBulk}.
+     * @returns The bytes stored.
+     * @throws {NatsBulkException} When the bulk channel is not enabled, the object store rejects the read, or the object
+     * does not exist (never stored, expired, or deleted).
+     */
+    getBulk(objId: string): Promise<Uint8Array>;
+    /**
+     * Delete an object from the bulk channel's object store; nothing happens when the bulk channel is not enabled.
+     * @param objId The id returned by {@link NATS.putBulk}.
+     * @throws {Error} The object store's error when the deletion fails.
+     */
+    deleteBulk(objId: string): Promise<void>;
+    /**
+     * Read the status of the bulk channel's object store: its bucket, time to live, replicas, storage and size.
+     * @returns The status, or `undefined` when the bulk channel is not enabled.
+     */
+    bulkStatus(): Promise<ObjectStoreStatus | undefined>;
+    /**
+     * Ask the responders of a subject whether they support the bulk references, before the first large request to it:
+     * the responders supporting them answer on the probe subject, the others (an older version, the bulk channel off)
+     * have no subscription there (no responders, or no answer in time). The answer is kept for the subject.
+     * @param subject The subject of the request.
+     * @returns Whether its responders support the bulk references.
+     * @private
+     */
+    private probeBulk;
+    /**
+     * Pack a payload to send: encoded, then stored in the object store and sent as a small reference when it is large and the peer supports it
+     * @param payload
+     * @param peerSupportsBulk whether the peer supports the references (the payload itself is sent otherwise)
+     * @private
+     */
+    private packPayload;
+    /**
+     * Unpack received bytes: a reference is read from the object store then decoded (deleted once read, its time to live covers a failure)
+     * @param bytes
+     * @param isRef
+     * @private
+     */
+    private unpackPayload;
+    /**
+     * Emit a service event of this application: the listeners registered for it with the application's id (with
+     * {@link NATS.onServiceEvent} or `ServiceProxy.on()`) receive the arguments. The event is published at most once: the
+     * applications not listening, or disconnected, miss it.
+     * @param eventName The event name.
+     * @param args The arguments given to the listeners, encoded with the codec (as one array).
+     * @returns The component, for chaining.
+     * @throws {Error} The NATS client error `MAX_PAYLOAD_EXCEEDED` when the encoded arguments are larger than the server's
+     * `max_payload` (the events are never relayed through the bulk channel), `CONNECTION_CLOSED` once the connection is
+     * closed; the codec's error when the arguments cannot be encoded.
+     */
+    emitServiceEvent(eventName: string, ...args: any[]): this;
+    /**
+     * Listen to a service event of an application. A listener registered again for the same event (by this method or
+     * {@link NATS.onceServiceEvent}) is ignored. A listener which throws is reported as an `'error'` event; the rejection of
+     * an asynchronous listener is not caught.
+     * @param serviceId The id of the application emitting the event (its `id` option).
+     * @param eventName The event name.
+     * @param listener The listener, receiving the event's arguments.
+     * @param onlySingleClientReceived Whether each event goes to one of the listeners registered with `true` for it, across
+     * all the applications (a queue group), instead of to each of them; the listeners registered with `false` still receive
+     * every event.
+     * @returns The component, for chaining.
+     * @throws {Error} The NATS client error `CONNECTION_CLOSED` once the connection is closed.
+     */
+    onServiceEvent(serviceId: string, eventName: string, listener: (...args: any[]) => void, onlySingleClientReceived?: boolean): this;
+    /**
+     * Listen to the next occurrence of a service event of an application only: the listener is removed once called. A
+     * listener already registered for the event is ignored.
+     * @param serviceId The id of the application emitting the event (its `id` option).
+     * @param eventName The event name.
+     * @param listener The listener, receiving the event's arguments.
+     * @returns The component, for chaining.
+     * @throws {Error} The NATS client error `CONNECTION_CLOSED` once the connection is closed.
+     */
+    onceServiceEvent(serviceId: string, eventName: string, listener: (...args: any[]) => void): this;
+    /**
+     * Stop listening to a service event of an application.
+     * @param serviceId The id of the application emitting the event.
+     * @param eventName The event name.
+     * @param listener The listener to remove; without it, every listener registered on this component for the event is
+     * removed (those of the service proxies using the component included).
+     * @returns The component, for chaining.
+     */
+    offServiceEvent(serviceId: string, eventName: string, listener?: (...args: any[]) => void): this;
+}