@prosody-events/prosody 0.5.0 → 0.6.0

package/lib/client.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The ProsodyClient class, the event handler it runs, and request outcomes.
+ * @module lib/client
+ */
+
+import type { Configuration, ConsumerState, Timer } from "../bindings";
+import type { Context } from "./context";
+import type {
+  ExciseMessage,
+  JsonCompatible,
+  JsonValue,
+  MaybePromise,
+  Message,
+} from "./payload";
+import type {
+  DequeDefinition,
+  MapDefinition,
+  SetDefinition,
+  ValueDefinition,
+} from "./state/definitions";
+import type {
+  PublishedDeque,
+  PublishedMap,
+  PublishedSet,
+  PublishedValue,
+} from "./state/published";
+
+/** The callbacks that a subscription runs for each message, excise, and timer. */
+export interface EventHandler<P = JsonValue, R = JsonValue> {
+  /** Handles an excise record. */
+  onExcise: (
+    context: Context,
+    message: ExciseMessage,
+    signal: AbortSignal,
+  ) => MaybePromise<R & JsonCompatible<R>>;
+  /**
+   * Callback function to handle incoming messages.
+   *
+   * @param context - The context of the message processing.
+   * @param message - The received Kafka message.
+   * @param signal - An AbortSignal that can be used to cancel the message processing.
+   * @returns A JSON response for subsystem requests. JSON null is valid.
+   */
+  onMessage: (
+    context: Context,
+    message: Message<P>,
+    signal: AbortSignal,
+  ) => MaybePromise<R & JsonCompatible<R>>;
+
+  /**
+   * Callback function to handle timers.
+   *
+   * @param context - The context of the message processing.
+   * @param timer - The triggered timer.
+   * @param signal - An AbortSignal that can be used to cancel the message processing.
+   * @returns No value.
+   */
+  onTimer: (
+    context: Context,
+    timer: Timer,
+    signal: AbortSignal,
+  ) => MaybePromise<void>;
+}
+
+/** One successful subsystem outcome. */
+export interface Success<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+/** One failed subsystem outcome. */
+export interface Failure {
+  readonly ok: false;
+  readonly error: ResponseError;
+}
+
+/** One subsystem outcome. */
+export type Outcome<T> = Success<T> | Failure;
+
+/** One subsystem failure. */
+export type ResponseError =
+  | { readonly kind: "handler"; readonly message: string }
+  | { readonly kind: "timeout"; readonly message: string }
+  | { readonly kind: "formatMismatch"; readonly message: string }
+  | { readonly kind: "malformedResponse"; readonly message: string };
+
+/** Request targets, deadline, and cancellation. */
+export interface RequestOptions {
+  /** The subsystems that must respond. */
+  readonly subsystems: readonly string[];
+  /** The response deadline in milliseconds. */
+  readonly timeoutMs: number;
+  /** Cancels the local wait. */
+  readonly signal?: AbortSignal;
+}
+
+/** The Prosody client: send, request, subscribe, and shut down. */
+export declare class ProsodyClient implements AsyncDisposable {
+  private constructor();
+
+  /**
+   * Creates a Prosody client without blocking the Node.js event loop.
+   *
+   * @param config - The configuration options for the client.
+   */
+  static create(config: Configuration): Promise<ProsodyClient>;
+
+  /**
+   * Gets the current state of the consumer.
+   *
+   * @returns The current state of the consumer.
+   * @throws Error if the operation fails.
+   */
+  consumerState(): Promise<ConsumerState>;
+
+  /**
+   * Gets the number of partitions assigned to the consumer.
+   *
+   * @returns The number of assigned partitions, or 0 if the consumer is not in the Running state.
+   * @throws Error if the operation fails.
+   */
+  assignedPartitionCount(): Promise<number>;
+
+  /**
+   * Checks if the consumer is stalled.
+   *
+   * @returns Whether the consumer is stalled, or false if the consumer is not in the Running state.
+   * @throws Error if the operation fails.
+   */
+  isStalled(): Promise<boolean>;
+
+  /** Opens a read-only view of a published JSON value collection. */
+  state<T>(
+    subsystem: string,
+    definition: ValueDefinition<T>,
+  ): Promise<PublishedValue<T>>;
+  /** Opens a read-only view of a published JSON map collection. */
+  state<V>(
+    subsystem: string,
+    definition: MapDefinition<V>,
+  ): Promise<PublishedMap<V>>;
+  /** Opens a read-only view of a published set collection. */
+  state(subsystem: string, definition: SetDefinition): Promise<PublishedSet>;
+  /** Opens a read-only view of a published JSON deque collection. */
+  state<T>(
+    subsystem: string,
+    definition: DequeDefinition<T>,
+  ): Promise<PublishedDeque<T>>;
+
+  /**
+   * Gets the source system identifier configured for the client.
+   *
+   * @returns The source system identifier.
+   */
+  get sourceSystem(): string;
+
+  /**
+   * Sends a message to a specified topic.
+   *
+   * @param topic - The name of the topic to send the message to.
+   * @param key - The key of the message.
+   * @param payload - The message payload (must be JSON-serializable).
+   * @param signal - An optional AbortSignal that can be used to cancel the send operation. When aborted, the promise will reject with the abort reason.
+   * @returns A promise that resolves when the message has been successfully sent.
+   * @throws Error if the send operation fails or is aborted.
+   */
+  send<P>(
+    topic: string,
+    key: string,
+    payload: P & JsonCompatible<P>,
+    signal?: AbortSignal,
+  ): Promise<void>;
+
+  /** Sends an excise record for a key. */
+  excise(topic: string, key: string, signal?: AbortSignal): Promise<void>;
+
+  /**
+   * Sends a request and returns one outcome for each subsystem.
+   *
+   * The map contains every selected subsystem. A missing response has a timeout outcome.
+   * `R` types the response. `P` types the payload and is inferred when you give no type arguments.
+   * @throws Error if the input is invalid, sending fails, shutdown starts, or the signal aborts.
+   */
+  request<R = JsonValue, P = JsonValue>(
+    topic: string,
+    key: string,
+    payload: P & JsonCompatible<P>,
+    options: RequestOptions,
+  ): Promise<ReadonlyMap<string, Outcome<R>>>;
+
+  /** Sends an excise request and returns one outcome for each subsystem. */
+  requestExcise<R = JsonValue>(
+    topic: string,
+    key: string,
+    options: RequestOptions,
+  ): Promise<ReadonlyMap<string, Outcome<R>>>;
+
+  /**
+   * Subscribes to receive messages using the provided event handler.
+   *
+   * @param eventHandler - The event handler to process received messages and timers.
+   * @returns A promise that resolves when the subscription is successfully established and the consumer is ready to receive messages.
+   * @throws TypeError if any required handler method is missing.
+   * @throws Error if the subscription fails to establish.
+   */
+  subscribe<P = JsonValue, R = JsonValue>(
+    eventHandler: EventHandler<P, R>,
+  ): Promise<void>;
+
+  /**
+   * Stops the consumer. You can subscribe again later.
+   *
+   * @returns A promise that resolves when the unsubscribe operation is complete.
+   * @throws Error if the unsubscribe operation fails.
+   */
+  unsubscribe(): Promise<void>;
+
+  /**
+   * Shuts down the client and all its services.
+   * Concurrent and repeated calls await the same shutdown operation.
+   *
+   * @returns A promise that resolves when shutdown is complete.
+   * @throws Error if shutdown fails.
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Shuts down the client when an `await using` block ends. It calls
+   * {@link ProsodyClient.shutdown}.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}

package/lib/client.js

@@ -0,0 +1,347 @@
+/**
+ * The ProsodyClient class: producing, requests, subscription, and shutdown.
+ * @module lib/client
+ * @private
+ */
+
+const {
+  context: otelContext,
+  propagation,
+  trace,
+  SpanStatusCode,
+} = require("@opentelemetry/api");
+const { NativeClient } = require("../bindings");
+const { Context } = require("./context");
+const { EventHandlerError, TransientError } = require("./errors");
+const { captureException, getCurrentLogger } = require("./logging");
+const {
+  defineHidden,
+  injectedCarrier,
+  toStateError,
+} = require("./state/bridge");
+const { eventMetadata, toJson, withParsedPayload } = require("./state/codec");
+const { stateDefinitionAccess } = require("./state/definitions");
+
+/** Proves that a constructor call comes from {@link wrapNative}. @private */
+const CONSTRUCT = Symbol("ProsodyClient");
+
+/** The Prosody client: send, request, subscribe, and shut down. */
+class ProsodyClient {
+  constructor(token, nativeClient) {
+    if (token !== CONSTRUCT) {
+      throw new TypeError("Use await ProsodyClient.create(config)");
+    }
+    // `shutdownPromise` is the one shutdown operation that every shutdown
+    // call awaits.
+    defineHidden(this, { nativeClient, shutdownPromise: undefined });
+  }
+
+  static async create(config) {
+    return wrapNative(await NativeClient.create(config));
+  }
+
+  get sourceSystem() {
+    return this.nativeClient.sourceSystem;
+  }
+
+  consumerState() {
+    return this.nativeClient.consumerState();
+  }
+
+  assignedPartitionCount() {
+    return this.nativeClient.assignedPartitionCount();
+  }
+
+  isStalled() {
+    return this.nativeClient.isStalled();
+  }
+
+  async state(subsystem, definition) {
+    const access = stateDefinitionAccess.get(definition);
+    if (access?.published === undefined) {
+      throw new TypeError(
+        "definition must be a JSON value, map, or deque definition, or a set definition",
+      );
+    }
+    try {
+      return await access.published(
+        this.nativeClient,
+        subsystem,
+        definition.name,
+        definition.readCache,
+      );
+    } catch (error) {
+      throw toStateError(error);
+    }
+  }
+
+  async send(topic, key, payload, signal) {
+    const carrier = injectedCarrier();
+    const json = toJson(payload, TransientError);
+
+    await withAbort(signal, (aborted) =>
+      this.nativeClient.send(
+        topic,
+        key,
+        json,
+        eventMetadata(payload),
+        carrier,
+        aborted,
+      ),
+    );
+  }
+
+  async excise(topic, key, signal) {
+    const carrier = injectedCarrier();
+    await withAbort(signal, (aborted) =>
+      this.nativeClient.excise(topic, key, carrier, aborted),
+    );
+  }
+
+  async request(topic, key, payload, options) {
+    const carrier = injectedCarrier();
+    const request = {
+      topic,
+      key,
+      payload: toJson(payload, TransientError),
+      metadata: eventMetadata(payload),
+      subsystems: options.subsystems,
+      timeoutMs: options.timeoutMs,
+    };
+    const results = await withAbort(options.signal, (aborted) =>
+      this.nativeClient.request(request, carrier, aborted),
+    );
+    return responseOutcomes(results);
+  }
+
+  async requestExcise(topic, key, options) {
+    const carrier = injectedCarrier();
+    const request = {
+      topic,
+      key,
+      subsystems: options.subsystems,
+      timeoutMs: options.timeoutMs,
+    };
+    const results = await withAbort(options.signal, (aborted) =>
+      this.nativeClient.requestExcise(request, carrier, aborted),
+    );
+    return responseOutcomes(results);
+  }
+
+  async subscribe(eventHandler) {
+    for (const name of ["onMessage", "onExcise", "onTimer"]) {
+      if (typeof eventHandler?.[name] !== "function") {
+        throw new TypeError(`EventHandler.${name} must be a function`);
+      }
+    }
+
+    const tracer = trace.getTracer("prosody");
+    const { onExcise, onMessage, onTimer } = eventHandler;
+    // Runs one handler call under its span. `run` returns the response text.
+    // `failure` is the logger text for a failed call.
+    const runHandler = (
+      nativeContext,
+      carrier,
+      spanName,
+      eventType,
+      failure,
+      captureContext,
+      run,
+    ) => {
+      const ctx = propagation.extract(otelContext.active(), carrier);
+      return otelContext.with(ctx, () =>
+        tracer.startActiveSpan(spanName, async (span) => {
+          const controller = new AbortController();
+          let completed = false;
+          nativeContext.onCancel().then(() => {
+            if (!completed) {
+              span.setAttribute("cancelled", true);
+              controller.abort(new Error(`${eventType} cancelled`));
+            }
+          });
+
+          try {
+            return await run(new Context(nativeContext), controller.signal);
+          } catch (error) {
+            const cause = error.cause ?? error;
+            getCurrentLogger().error(failure, cause);
+            span.recordException(cause);
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: cause.message,
+            });
+            captureException(error, eventType, captureContext);
+            throw error;
+          } finally {
+            completed = true;
+            span.end();
+          }
+        }),
+      );
+    };
+
+    // A result with no JSON form is a handler mistake. It is transient, so
+    // the event retries and the mistake stays visible.
+    const handleRecord = (
+      nativeContext,
+      message,
+      carrier,
+      handler,
+      spanName,
+      eventType,
+    ) =>
+      runHandler(
+        nativeContext,
+        carrier,
+        spanName,
+        eventType,
+        `${eventType} handler error`,
+        {
+          topic: message.topic,
+          partition: message.partition,
+          key: message.key,
+          offset: message.offset,
+        },
+        async (context, signal) =>
+          toJson(
+            (await handler(context, message, signal)) ?? null,
+            TransientError,
+          ),
+      );
+
+    await this.nativeClient.subscribe({
+      isPermanent: ([err]) => {
+        try {
+          return err instanceof EventHandlerError && err.isPermanent;
+        } catch {
+          return false;
+        }
+      },
+
+      onMessage: async (err, [nativeContext, message, carrier]) => {
+        if (err) throw err;
+        return handleRecord(
+          nativeContext,
+          withParsedPayload(message),
+          carrier,
+          onMessage,
+          "onMessage",
+          "message",
+        );
+      },
+
+      onExcise: async (err, [nativeContext, message, carrier]) => {
+        if (err) throw err;
+        return handleRecord(
+          nativeContext,
+          message,
+          carrier,
+          onExcise,
+          "onExcise",
+          "excise",
+        );
+      },
+
+      onTimer: async (err, [nativeContext, timer, carrier]) => {
+        if (err) throw err;
+        return runHandler(
+          nativeContext,
+          carrier,
+          "onTimer",
+          "timer",
+          "Timer handler error",
+          { key: timer.key, time: timer.time },
+          async (context, signal) => {
+            await onTimer(context, timer, signal);
+            return "null";
+          },
+        );
+      },
+    });
+  }
+
+  async unsubscribe() {
+    await this.nativeClient.unsubscribe();
+  }
+
+  async shutdown() {
+    this.shutdownPromise ??= this.nativeClient.shutdown();
+    await this.shutdownPromise;
+  }
+
+  [Symbol.asyncDispose]() {
+    return this.shutdown();
+  }
+}
+
+// napi-rs can only surface rejections whose value is an object, function, or
+// symbol — napi_create_reference fails on primitives and the rejection becomes
+// an opaque `InvalidArg: Create Error reference failed`. Coerce primitive
+// reasons into Error instances so the original reason is preserved across the
+// napi boundary.
+const toAbortError = (reason) =>
+  reason instanceof Error
+    ? reason
+    : new Error(reason === undefined ? "aborted" : String(reason));
+
+/**
+ * Runs a native call that stops when an optional abort signal fires.
+ *
+ * The call receives a promise that rejects with the abort reason. The abort
+ * listener is removed when the call settles, so one long-lived signal can
+ * serve any number of calls.
+ * @param {AbortSignal|undefined} signal - The abort signal to watch.
+ * @param {(aborted: Promise<never>|undefined) => Promise<*>} call - The
+ *   native call.
+ * @returns {Promise<*>} The result of the call.
+ * @private
+ */
+async function withAbort(signal, call) {
+  if (signal === undefined) return call(undefined);
+  let abort;
+  const aborted = new Promise((_, reject) => {
+    abort = () => reject(toAbortError(signal.reason));
+  });
+  if (signal.aborted) abort();
+  else signal.addEventListener("abort", abort, { once: true });
+  try {
+    return await call(aborted);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+}
+
+function responseOutcome(outcome) {
+  if (typeof outcome !== "string") return { ok: false, error: outcome };
+
+  try {
+    return { ok: true, value: JSON.parse(outcome) };
+  } catch (cause) {
+    return {
+      ok: false,
+      error: { kind: "malformedResponse", message: cause.message },
+    };
+  }
+}
+
+function responseOutcomes(results) {
+  const outcomes = new Map();
+  for (const { subsystem, outcome } of results)
+    outcomes.set(subsystem, responseOutcome(outcome));
+  return outcomes;
+}
+
+/**
+ * Wraps a native client. The unit tests wrap a stub through it.
+ * @param {object} native - The native client.
+ * @returns {ProsodyClient} The client.
+ * @private
+ */
+function wrapNative(native) {
+  return new ProsodyClient(CONSTRUCT, native);
+}
+
+module.exports = {
+  ProsodyClient,
+  wrapNative,
+};