@prosody-events/prosody 0.5.1 → 0.6.0

package/lib/context.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The event context passed to handlers, and the demand that started it.
+ * @module lib/context
+ */
+
+import type { Message } from "./payload";
+import type {
+  DequeDefinition,
+  MapDefinition,
+  MessageDequeDefinition,
+  MessageMapDefinition,
+  MessageValueDefinition,
+  SetDefinition,
+  ValueDefinition,
+} from "./state/definitions";
+import type { DequeState } from "./state/deque";
+import type { MapState } from "./state/map";
+import type { SetState } from "./state/set";
+import type { ValueState } from "./state/value";
+
+/**
+ * The demand that started a handler invocation.
+ */
+export interface Demand {
+  /** `"normal"` for a first attempt, or `"failure"` for a retry. */
+  readonly kind: "normal" | "failure";
+  /**
+   * The retry count: 0 for normal demand and 1 on the first retry. It is
+   * an estimate. Keep an exact attempt count in keyed state if you need one.
+   */
+  readonly retry: number;
+}
+
+/**
+ * The event context that a handler receives. Each call propagates the active
+ * trace context.
+ *
+ * `state()` caches one handle per definition object, so repeated calls with
+ * the same definition return the same handle. It throws a
+ * {@link TransientStateError} for an object that no definition constructor
+ * made.
+ */
+export declare class Context {
+  private constructor();
+
+  /**
+   * The demand that started this handler invocation. The value is frozen.
+   */
+  get demand(): Demand;
+
+  /**
+   * Checks whether cancellation has been signaled.
+   * Cancellation includes message-level cancellation (e.g., timeout) and partition shutdown. During shutdown, cancellation is delayed until near the end of the shutdown timeout to allow in-flight work to complete.
+   *
+   * @returns True if cancellation was requested, otherwise false.
+   */
+  get shouldCancel(): boolean;
+
+  /**
+   * Waits for a cancellation signal.
+   * Cancellation includes message-level cancellation (e.g., timeout) and partition shutdown. During shutdown, cancellation is delayed until near the end of the shutdown timeout to allow in-flight work to complete.
+   *
+   * @returns A promise that resolves when cancellation is signaled.
+   */
+  onCancel(): Promise<void>;
+
+  /**
+   * Schedule a timer at the given time.
+   *
+   * @param time - The UTC timestamp to schedule.
+   * @returns A promise that resolves when the timer has been scheduled.
+   * @throws Error if time conversion or scheduling fails.
+   */
+  schedule(time: Date): Promise<void>;
+
+  /**
+   * Clear existing timers and schedule a new one at the given time.
+   *
+   * @param time - The UTC timestamp to schedule.
+   * @returns A promise that resolves when the timer has been scheduled.
+   * @throws Error if time conversion or scheduling fails.
+   */
+  clearAndSchedule(time: Date): Promise<void>;
+
+  /**
+   * Unschedules the timer for the specified time.
+   * @param time - The time to unschedule.
+   * @returns A promise that resolves when the timer has been unscheduled.
+   * @throws Error if unscheduling fails.
+   */
+  unschedule(time: Date): Promise<void>;
+
+  /**
+   * Clears all scheduled timers.
+   * @returns A promise that resolves when all timers have been cleared.
+   * @throws Error if clearing schedules fails.
+   */
+  clearScheduled(): Promise<void>;
+
+  /**
+   * Retrieves all scheduled times.
+   * @returns An array of scheduled times as Date objects.
+   * @throws Error if retrieval fails.
+   */
+  scheduled(): Promise<Array<Date>>;
+
+  /**
+   * Binds a registered message single-value collection, vending a handle whose
+   * item is the full `Message<P>`.
+   *
+   * The handle and any iterator it opens are valid only within this event
+   * attempt. Throws a {@link PermanentStateError} if the collection name is
+   * unregistered or its registered identity mismatches.
+   * @param definition - A definition from {@link messageValue}.
+   */
+  state<P>(definition: MessageValueDefinition<P>): ValueState<Message<P>>;
+  /**
+   * Binds a registered message ordered-map collection, vending a handle whose
+   * values are the full `Message<P>`. Valid only within this event attempt;
+   * throws {@link PermanentStateError} on an unregistered name or identity
+   * mismatch.
+   * @param definition - A definition from {@link messageMap}.
+   */
+  state<P>(definition: MessageMapDefinition<P>): MapState<Message<P>>;
+  /**
+   * Binds a registered message deque collection, vending a handle whose
+   * elements are the full `Message<P>`. Valid only within this event attempt;
+   * throws {@link PermanentStateError} on an unregistered name or identity
+   * mismatch.
+   * @param definition - A definition from {@link messageDeque}.
+   */
+  state<P>(definition: MessageDequeDefinition<P>): DequeState<Message<P>>;
+  /**
+   * Binds a registered single-value JSON collection. Valid only within this
+   * event attempt; throws {@link PermanentStateError} on an unregistered name
+   * or identity mismatch.
+   * @param definition - A definition from {@link value}.
+   */
+  state<T>(definition: ValueDefinition<T>): ValueState<T>;
+  /**
+   * Binds a registered ordered-map JSON collection (string keys). Valid only
+   * within this event attempt; throws {@link PermanentStateError} on an
+   * unregistered name or identity mismatch.
+   * @param definition - A definition from {@link map}.
+   */
+  state<V>(definition: MapDefinition<V>): MapState<V>;
+  /**
+   * Binds a registered set collection of string members. Valid only within
+   * this event attempt; throws {@link PermanentStateError} on an unregistered
+   * name or identity mismatch.
+   * @param definition - A definition from {@link set}.
+   */
+  state(definition: SetDefinition): SetState;
+  /**
+   * Binds a registered deque JSON collection. Valid only within this event
+   * attempt; throws {@link PermanentStateError} on an unregistered name or
+   * identity mismatch.
+   * @param definition - A definition from {@link deque}.
+   */
+  state<T>(definition: DequeDefinition<T>): DequeState<T>;
+}

package/lib/context.js

@@ -0,0 +1,86 @@
+/**
+ * The event context passed to handlers: cancellation, timers, and state.
+ * @module lib/context
+ * @private
+ */
+
+const { TransientStateError } = require("./errors");
+const {
+  defineHidden,
+  injectedCarrier,
+  toStateError,
+} = require("./state/bridge");
+const { stateDefinitionAccess } = require("./state/definitions");
+
+// The frozen demand of each native context, read on first access. The key is
+// the native context, so the cache also works through a Proxy with a `set`
+// trap. An entry goes away with its native context.
+const demands = new WeakMap();
+
+/** The event context that handlers receive. Each call propagates the trace. */
+class Context {
+  constructor(nativeContext) {
+    // The vended state handles, cached by definition object, so repeated
+    // state(definition) calls within one event return the same handle.
+    defineHidden(this, { nativeContext, stateHandles: new Map() });
+  }
+
+  get shouldCancel() {
+    return this.nativeContext.shouldCancel;
+  }
+
+  get demand() {
+    let demand = demands.get(this.nativeContext);
+    if (demand === undefined) {
+      demand = Object.freeze({ ...this.nativeContext.demand });
+      demands.set(this.nativeContext, demand);
+    }
+    return demand;
+  }
+
+  async onCancel() {
+    return this.nativeContext.onCancel();
+  }
+
+  async schedule(time) {
+    return this.nativeContext.schedule(time, injectedCarrier());
+  }
+
+  async clearAndSchedule(time) {
+    return this.nativeContext.clearAndSchedule(time, injectedCarrier());
+  }
+
+  async unschedule(time) {
+    return this.nativeContext.unschedule(time, injectedCarrier());
+  }
+
+  async clearScheduled() {
+    return this.nativeContext.clearScheduled(injectedCarrier());
+  }
+
+  async scheduled() {
+    return this.nativeContext.scheduled(injectedCarrier());
+  }
+
+  state(definition) {
+    const access = stateDefinitionAccess.get(definition);
+    if (access === undefined) {
+      throw new TransientStateError(
+        "state: definition must come from a Prosody state definition constructor",
+      );
+    }
+    const cached = this.stateHandles.get(definition);
+    if (cached !== undefined) return cached;
+    try {
+      const handle = access.owned(this.nativeContext, definition.name);
+      this.stateHandles.set(definition, handle);
+      return handle;
+    } catch (error) {
+      throw toStateError(error);
+    }
+  }
+}
+
+module.exports = {
+  Context,
+};

package/lib/errors.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The handler error classes, the state error classes, and the error decorators.
+ * @module lib/errors
+ */
+
+/**
+ * Base class for event handler errors.
+ * Provides a common interface for determining if an error is permanent.
+ */
+export abstract class EventHandlerError extends Error {
+  /**
+   * @param message - The error message.
+   * @param options - The standard error options, such as `cause`.
+   */
+  constructor(message?: string, options?: ErrorOptions);
+
+  /**
+   * Indicates whether the error is permanent and should not be retried.
+   */
+  abstract get isPermanent(): boolean;
+}
+
+/**
+ * Represents a transient error that may be resolved by retrying.
+ * These errors are temporary and the operation should be retried.
+ */
+export class TransientError extends EventHandlerError {
+  /**
+   * @returns Always false, indicating the error is not permanent.
+   */
+  get isPermanent(): false;
+}
+
+/**
+ * Represents a permanent error that should not be retried.
+ * These errors indicate unrecoverable failures.
+ */
+export class PermanentError extends EventHandlerError {
+  /**
+   * @returns Always true, indicating the error is permanent.
+   */
+  get isPermanent(): true;
+}
+
+/**
+ * A keyed-state failure that a later attempt can resolve.
+ *
+ * A store timeout is transient. A caller mistake is transient too: an
+ * unrepresentable write, a wrong item type, or a bad index. The event then
+ * retries, so the mistake stays visible and no message is discarded. State
+ * handles and scan iterators throw it. It extends {@link TransientError}, so a
+ * handler that rethrows it retries the event.
+ */
+export class TransientStateError extends TransientError {}
+
+/**
+ * A keyed-state failure that no retry in this process can resolve.
+ *
+ * Examples are an unregistered collection name, a registered identity that
+ * does not match, a JSON `null` write, and a stored value that cannot be
+ * decoded. A caller mistake is a {@link TransientStateError} instead. A
+ * handler can also throw this error to mark its own failure permanent. It extends {@link PermanentError},
+ * so a handler that rethrows it does not retry the event.
+ */
+export class PermanentStateError extends PermanentError {}
+
+/**
+ * Checks whether a value is a keyed-state error of either category. It
+ * matches the error `name`, so it also recognizes an error from another realm.
+ *
+ * @param error - The value to test.
+ * @returns True when the value is a keyed-state error.
+ */
+export function isStateError(
+  error: unknown,
+): error is PermanentStateError | TransientStateError;
+
+/** Type alias for a constructor of an Error subclass. */
+type ErrorClass<T extends Error> = new (...args: never[]) => T;
+
+/** A decorator for a class method. */
+type DecoratorFunction = (
+  target: Function,
+  context: ClassMethodDecoratorContext,
+) => Function | void;
+
+/**
+ * Decorator factory for marking errors as transient.
+ * Apply it to a method. The wrapper keeps the original error as its `cause`.
+ * @param exceptionTypes The error types to be treated as transient.
+ */
+export declare function transient<E extends Error>(
+  ...exceptionTypes: ErrorClass<E>[]
+): DecoratorFunction;
+
+/**
+ * Decorator factory for marking errors as permanent.
+ * Apply it to a method. The wrapper keeps the original error as its `cause`.
+ * @param exceptionTypes The error types to be treated as permanent.
+ */
+export declare function permanent<E extends Error>(
+  ...exceptionTypes: ErrorClass<E>[]
+): DecoratorFunction;

package/lib/errors.js

@@ -0,0 +1,102 @@
+/**
+ * The handler error classes, the state error classes, and the error decorators.
+ * @module lib/errors
+ * @private
+ */
+
+const { types } = require("node:util");
+
+/** Base class for event handler errors. */
+class EventHandlerError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+
+  get isPermanent() {
+    throw new Error("Subclasses must implement isPermanent");
+  }
+}
+
+/** An event handler error that a retry can resolve. */
+class TransientError extends EventHandlerError {
+  get isPermanent() {
+    return false;
+  }
+}
+
+/** An event handler error that no retry can resolve. */
+class PermanentError extends EventHandlerError {
+  get isPermanent() {
+    return true;
+  }
+}
+
+/** A keyed-state failure that a later attempt can resolve. */
+class TransientStateError extends TransientError {}
+
+/** A keyed-state failure that no retry in this process can resolve. */
+class PermanentStateError extends PermanentError {}
+
+const STATE_ERROR_NAMES = new Set([
+  "PermanentStateError",
+  "TransientStateError",
+]);
+
+function isStateError(error) {
+  return types.isNativeError(error) && STATE_ERROR_NAMES.has(error.name);
+}
+
+/**
+ * Helper function to create error decorators.
+ * @param {Function} ErrorClass - The error class to wrap exceptions with.
+ * @returns {Function} A decorator function that wraps specified exceptions.
+ * @private
+ */
+function createErrorDecorator(ErrorClass) {
+  return function decorator(...exceptionTypes) {
+    return function (originalMethod, context) {
+      if (context.kind !== "method") {
+        throw new TypeError(`@${ErrorClass.name} can only decorate methods`);
+      }
+
+      function handleError(error) {
+        if (exceptionTypes.some((type) => error instanceof type)) {
+          return new ErrorClass(error.message, { cause: error });
+        }
+        return error;
+      }
+
+      // A method that returns a promise is classified the same way whether
+      // or not it is a native async function, because a transpiler can
+      // compile an async method into a plain function.
+      return function (...args) {
+        let result;
+        try {
+          result = originalMethod.apply(this, args);
+        } catch (error) {
+          throw handleError(error);
+        }
+        if (typeof result?.then !== "function") return result;
+        return result.then(undefined, (error) => {
+          throw handleError(error);
+        });
+      };
+    };
+  };
+}
+
+const transient = createErrorDecorator(TransientError);
+
+const permanent = createErrorDecorator(PermanentError);
+
+module.exports = {
+  EventHandlerError,
+  PermanentError,
+  PermanentStateError,
+  TransientError,
+  TransientStateError,
+  isStateError,
+  permanent,
+  transient,
+};

package/lib/logging.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The logger interface and the logger setters.
+ * @module lib/logging
+ */
+
+/**
+ * JavaScript logger interface for use with Prosody client.
+ *
+ * Each logging method receives a message string and optional metadata object.
+ */
+export interface Logger {
+  /** Logs error-level messages. */
+  error: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
+  /** Logs warning-level messages. */
+  warn: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
+  /** Logs info-level messages. */
+  info: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
+  /** Logs debug-level messages. */
+  debug: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
+  /** Logs trace-level messages. */
+  trace: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
+}
+
+/**
+ * Sets a new JavaScript logger for the Prosody client.
+ *
+ * This function configures the logging system to use the provided JavaScript logger
+ * for all log output. The logger must implement all required log levels.
+ *
+ * @param logger - The JavaScript logger object with error, warn, info, debug, and trace methods.
+ * @throws Error if creating the new JavaScript logger fails.
+ */
+export function setLogger(logger: Logger): void;
+
+/**
+ * Checks whether the application set a logger. The default console logger
+ * does not count.
+ *
+ * @returns True after a call to `setLogger` or a successful `setLoggerIfUnset`.
+ */
+export function loggerIsSet(): boolean;
+
+/**
+ * Sets a JavaScript logger only if the application has not set one.
+ *
+ * A library that embeds Prosody can use it to supply a logger without
+ * replacing the logger of the host application.
+ *
+ * @param logger - The JavaScript logger object with error, warn, info, debug, and trace methods.
+ * @returns True if the logger was set, false if the application already set one.
+ * @throws Error if creating the new JavaScript logger fails.
+ */
+export function setLoggerIfUnset(logger: Logger): boolean;
+
+/**
+ * Gets the current logger.
+ *
+ * @returns The logger that the application set, or the default console logger.
+ */
+export function getCurrentLogger(): Logger;

package/lib/logging.js

@@ -0,0 +1,99 @@
+/**
+ * The JavaScript logger bridge and the optional Sentry reporter.
+ * @module lib/logging
+ * @private
+ */
+
+const { initialize, setLogger: setLoggerInternal } = require("../bindings");
+
+let _sentry = undefined;
+function getSentry() {
+  if (_sentry !== undefined) return _sentry;
+  _sentry = null;
+  if (!process.env.SENTRY_DSN) return null;
+  try {
+    const Sentry = require("@sentry/node");
+    if (!Sentry.isInitialized()) {
+      Sentry.init({ dsn: process.env.SENTRY_DSN });
+    }
+    _sentry = Sentry;
+    return Sentry;
+  } catch (err) {
+    const isMissing =
+      err?.code === "MODULE_NOT_FOUND" && err.message?.includes("@sentry/node");
+    if (isMissing) {
+      getCurrentLogger().error(
+        "SENTRY_DSN is set but @sentry/node is not installed. Run: npm install @sentry/node",
+      );
+    } else {
+      getCurrentLogger().warn("Unexpected error loading @sentry/node", err);
+    }
+    return null;
+  }
+}
+
+function captureException(error, eventType, context) {
+  const Sentry = getSentry();
+  if (!Sentry) return;
+  Sentry.withScope((scope) => {
+    scope.setTag("prosody.event_type", eventType);
+    scope.setContext("prosody", context);
+    Sentry.captureException(error.cause ?? error);
+  });
+}
+
+// Passes the metadata to the console only when the caller gives it.
+const write = (log) => (message, metadata) =>
+  metadata === undefined ? log(message) : log(message, metadata);
+
+const defaultLogger = {
+  error: write(console.error),
+  warn: write(console.warn),
+  info: write(console.info),
+  debug: write(console.debug),
+  trace: write(console.debug),
+};
+
+// The logger that handlers use. It is the default console logger until the
+// application sets one.
+let currentLogger = defaultLogger;
+
+function transformLogger(logger) {
+  return {
+    info: ([msg, meta]) => logger.info(msg, meta),
+    error: ([msg, meta]) => logger.error(msg, meta),
+    debug: ([msg, meta]) => logger.debug(msg, meta),
+    warn: ([msg, meta]) => logger.warn(msg, meta),
+    trace: ([msg, meta]) => logger.trace(msg, meta),
+  };
+}
+
+function getCurrentLogger() {
+  return currentLogger;
+}
+
+initialize();
+setLoggerInternal(transformLogger(defaultLogger));
+
+function setLogger(logger) {
+  currentLogger = logger;
+  setLoggerInternal(transformLogger(logger));
+}
+
+function loggerIsSet() {
+  return currentLogger !== defaultLogger;
+}
+
+function setLoggerIfUnset(logger) {
+  if (loggerIsSet()) return false;
+  setLogger(logger);
+  return true;
+}
+
+module.exports = {
+  captureException,
+  getCurrentLogger,
+  loggerIsSet,
+  setLogger,
+  setLoggerIfUnset,
+};

package/lib/payload.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JSON payload types and the message types that carry them.
+ * @module lib/payload
+ */
+
+import type {
+  ExciseMessage as NativeExciseMessage,
+  Message as NativeMessage,
+} from "../bindings";
+
+/** A primitive value representable in JSON. */
+export type JsonPrimitive = null | boolean | number | string;
+
+/**
+ * Any value representable in JSON.
+ *
+ * This is a compile-time contract. Prosody serializes payloads at runtime but
+ * does not validate them against a more specific application payload type.
+ */
+export type JsonValue =
+  JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+
+/**
+ * Maps an application type to its JSON-compatible shape. This lets APIs
+ * accept ordinary interfaces and type aliases without requiring an index
+ * signature, while rejecting non-JSON members wherever they are nested.
+ */
+export type JsonCompatible<T> = T extends JsonPrimitive
+  ? T
+  : T extends bigint | symbol | undefined | ((...args: never[]) => unknown)
+    ? never
+    : T extends readonly (infer Item)[]
+      ? readonly JsonCompatible<Item>[]
+      : T extends object
+        ? { readonly [Key in keyof T]: JsonCompatible<T[Key]> }
+        : never;
+
+/** A value that a handler can return now or through a promise. */
+export type MaybePromise<T> = T | PromiseLike<T>;
+
+/**
+ * Represents a message consumed from a Kafka topic.
+ *
+ * The optional payload type parameter is annotation-level only: the runtime
+ * payload is unchanged. An unparameterized `Message` uses {@link JsonValue};
+ * provide an application payload type for precise field-level checking.
+ * Message-backed keyed-state collections vend their items as `Message<P>`.
+ *
+ * A message can be stored into a message collection, whether it arrived from the
+ * topic or was read back out of a collection. What is stored is the message
+ * itself, so mutating its parsed `payload` does not change what is written.
+ */
+export interface Message<P = JsonValue> extends Omit<NativeMessage, "payload"> {
+  /** The message payload as a JSON-serializable value. */
+  payload: P;
+}
+
+/** An excise record with Kafka metadata and no payload. */
+export type ExciseMessage = NativeExciseMessage;