@prosody-events/prosody 0.5.1 → 0.6.0

package/lib/state/bridge.js

@@ -0,0 +1,103 @@
+/**
+ * Calls into native code: trace carriers, error categories, value rendering,
+ * and the hidden native handle properties.
+ * @module lib/state/bridge
+ * @private
+ */
+
+const { types } = require("node:util");
+const { context: otelContext, propagation } = require("@opentelemetry/api");
+const { PermanentStateError, TransientStateError } = require("../errors");
+
+/**
+ * Injects the active OpenTelemetry context into a fresh carrier for one native
+ * operation. Native glue activates the carrier without recording a binding
+ * span, so the core semantic operation span joins the JavaScript trace directly.
+ * @returns {Record<string, string>} The populated carrier.
+ * @private
+ */
+function injectedCarrier() {
+  const carrier = {};
+  propagation.inject(otelContext.active(), carrier);
+  return carrier;
+}
+
+/**
+ * Converts a category-tagged native state error into the matching typed state
+ * error. The native layer sets the error's `cause` to an error whose message
+ * is exactly `"permanent"` or `"transient"`. The human message is never
+ * parsed. An untagged error, such as an argument conversion `TypeError`,
+ * passes through unchanged.
+ *
+ * The checks use `util.types.isNativeError`, which works across realms. A napi
+ * error comes from the addon's realm. Under a vm context, a worker thread, or a
+ * second module copy, `instanceof Error` is false for it.
+ * @param {unknown} error - The error thrown by the native layer.
+ * @returns {unknown} The typed state error, or the original error if untagged.
+ * @private
+ */
+function toStateError(error) {
+  if (!types.isNativeError(error)) return error;
+  const cause = error.cause;
+  const category = types.isNativeError(cause) ? cause.message : undefined;
+  if (category !== "permanent" && category !== "transient") return error;
+  const StateError =
+    category === "permanent" ? PermanentStateError : TransientStateError;
+  return new StateError(error.message, { cause: error });
+}
+
+/**
+ * Renders a value for a diagnostic message without ever throwing.
+ * `JSON.stringify` throws on a BigInt or a cycle, and a template literal throws
+ * on a Symbol. A raw `TypeError` from either would skip the state error
+ * classes. The function returns the value's `typeof` when it cannot serialize
+ * the value.
+ * @param {*} value - The value to describe.
+ * @returns {string} A safe, human-readable rendering.
+ * @private
+ */
+function describeValue(value) {
+  try {
+    const rendered = JSON.stringify(value);
+    return rendered === undefined ? typeof value : rendered;
+  } catch {
+    return typeof value;
+  }
+}
+
+/**
+ * Runs one async native state operation with a fresh carrier, translating a
+ * category-tagged failure into the matching typed state error.
+ * @param {(carrier: Record<string, string>) => Promise<*>} operation - The native call.
+ * @returns {Promise<*>} The operation's resolved value.
+ * @private
+ */
+async function stateOp(operation) {
+  try {
+    return await operation(injectedCarrier());
+  } catch (error) {
+    throw toStateError(error);
+  }
+}
+
+/**
+ * Stores internal fields on a wrapper as writable properties that do not
+ * enumerate, so `console.log` shows no internals. A data property also reads
+ * correctly when a getter or method runs with a Proxy as `this`.
+ * @param {object} object - The wrapper object.
+ * @param {Record<string, *>} fields - The internal fields and their values.
+ * @private
+ */
+function defineHidden(object, fields) {
+  for (const [name, value] of Object.entries(fields)) {
+    Object.defineProperty(object, name, { value, writable: true });
+  }
+}
+
+module.exports = {
+  defineHidden,
+  describeValue,
+  injectedCarrier,
+  stateOp,
+  toStateError,
+};

package/lib/state/codec.js

@@ -0,0 +1,206 @@
+/**
+ * Encodes and decodes the items of JSON and message collections.
+ * @module lib/state/codec
+ * @private
+ */
+
+const { Message: NativeMessage } = require("../../bindings");
+const {
+  PermanentError,
+  PermanentStateError,
+  TransientStateError,
+} = require("../errors");
+
+/**
+ * The native `payload` getter, which answers the raw JSON text read from the
+ * wire. Captured before {@link withParsedPayload} shadows it per instance.
+ * @private
+ */
+const rawPayload = Object.getOwnPropertyDescriptor(
+  NativeMessage.prototype,
+  "payload",
+).get;
+
+/**
+ * Replaces a message's raw-text `payload` with the parsed document.
+ *
+ * Rust hands the payload across as the bytes it read from the wire, never
+ * parsing them; the parse happens here, on first read, and the result is kept.
+ * A handler that only inspects metadata therefore never pays for one.
+ *
+ * A payload that is not JSON raises a permanent error: no retry makes bytes
+ * parse. Reading `payload` is where that surfaces, since nothing before it
+ * looks at the document. That outcome is kept too, so a handler reading a bad
+ * payload twice re-raises rather than re-parsing.
+ * @param {object} message - The native message.
+ * @returns {object} The same message, with `payload` parsed on demand.
+ * @private
+ */
+function withParsedPayload(message) {
+  let document;
+  let failure;
+  let parsed = false;
+  // Not enumerable, matching the five native getters: none of a message's
+  // fields are own properties, so spread, `Object.keys`, and `JSON.stringify`
+  // see none of them. An enumerable own `payload` would make `JSON.stringify`
+  // of a message serialize the whole parsed document.
+  Object.defineProperty(message, "payload", {
+    configurable: true,
+    enumerable: false,
+    get() {
+      if (!parsed) {
+        // The native read fails for bytes that are not UTF-8, and JSON.parse
+        // fails for text that is not JSON. Both are the same permanent error.
+        try {
+          document = JSON.parse(rawPayload.call(this));
+        } catch (error) {
+          failure = new PermanentError(
+            `message payload is not JSON: ${error.message}`,
+            { cause: error },
+          );
+        }
+        parsed = true;
+      }
+      if (failure !== undefined) throw failure;
+      return document;
+    },
+  });
+  return message;
+}
+
+/**
+ * Serializes a JSON value.
+ *
+ * It returns `undefined` for a function, a symbol, or `undefined` itself. It
+ * throws for a BigInt or a cycle.
+ * @param {*} value - The value to serialize.
+ * @param {Function} ErrorClass - The error to raise on failure.
+ * @returns {string} The JSON text.
+ * @private
+ */
+function toJson(value, ErrorClass) {
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch (error) {
+    throw new ErrorClass(
+      `value is not representable as JSON: ${error.message}`,
+    );
+  }
+  if (json === undefined) {
+    throw new ErrorClass(
+      "value is not representable as JSON (functions, symbols, and " +
+        "`undefined` have no JSON form)",
+    );
+  }
+  return json;
+}
+
+/**
+ * Serializes a value for a JSON collection.
+ *
+ * A collection stores whatever JSON it is given, so the only rejections here
+ * are values with no JSON form at all. Both are caller mistakes and reject
+ * transient: the event retries and the mistake stays visible rather than
+ * discarding the message.
+ *
+ * Everything else follows `JSON.stringify`, which is now the serializer of
+ * record. Inside a container a function-valued property is dropped and an
+ * `undefined` element becomes `null`. `NaN` and the infinities become `null`
+ * anywhere they appear. A `toJSON` method decides what its value serializes to.
+ * The previous Rust-side conversion rejected each of those instead.
+ * @param {*} value - The value to store.
+ * @returns {string} The document's JSON text.
+ * @throws {TransientStateError} If the value has no JSON representation.
+ * @private
+ */
+function encodeJson(value) {
+  if (value instanceof NativeMessage) {
+    throw new TransientStateError(
+      "a Kafka message cannot be stored in a JSON collection; declare it with " +
+        "messageValue/messageMap/messageDeque instead",
+    );
+  }
+  return toJson(value, TransientStateError);
+}
+
+/**
+ * Reads the event metadata a payload carries.
+ *
+ * When the payload is an object with a string `id` or `type`, prosody uses
+ * them. Anything else carries no metadata. Each field is read once, so a getter
+ * that answers differently on a second read cannot make the metadata disagree
+ * with itself.
+ * @param {*} payload - The payload about to be sent.
+ * @returns {{eventId?: string, eventType?: string}} The metadata.
+ * @private
+ */
+function eventMetadata(payload) {
+  const id = payload?.id;
+  const type = payload?.type;
+  return {
+    eventId: typeof id === "string" ? id : undefined,
+    eventType: typeof type === "string" ? type : undefined,
+  };
+}
+
+/**
+ * Checks that a value for a message collection is a real Kafka message.
+ *
+ * A message collection stores the Kafka message itself, so it accepts only a
+ * `Message` — an object merely shaped like one is rejected. A message read back
+ * out of a collection is a `Message` and stores fine.
+ * What it stores is the message's own wire bytes, so assigning to a message's
+ * fields, or mutating its parsed `payload`, does not change what is written.
+ * @param {*} value - The value to store.
+ * @returns {object} The message.
+ * @throws {TransientStateError} If the value is not a Kafka message.
+ * @private
+ */
+function requireMessage(value) {
+  if (!(value instanceof NativeMessage)) {
+    throw new TransientStateError(
+      "expected a Kafka message; a JSON value cannot be stored in a message collection",
+    );
+  }
+  return value;
+}
+
+/**
+ * Builds the item codec for one collection payload type.
+ *
+ * The native handle has one payload type. `encode` prepares an item for a
+ * write and rejects an item of the other type.
+ * @param {(item: *) => *} encode - Prepares an item for a write.
+ * @param {(item: *) => *} decode - Turns a read item into what the caller asked for.
+ * @returns {Readonly<object>} The frozen codec.
+ * @private
+ */
+function itemCodec(encode, decode) {
+  return Object.freeze({
+    encode,
+    decode: (item) => (item === null ? null : decode(item)),
+  });
+}
+
+/** JSON documents cross as their text. @private */
+const jsonItems = itemCodec(encodeJson, (text) => {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new PermanentStateError(
+      `stored JSON document could not be parsed: ${error.message}`,
+    );
+  }
+});
+
+/** Kafka messages cross as the `Message` object itself. @private */
+const messageItems = itemCodec(requireMessage, withParsedPayload);
+
+module.exports = {
+  eventMetadata,
+  jsonItems,
+  messageItems,
+  toJson,
+  withParsedPayload,
+};

package/lib/state/definitions.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The keyed-state definition types, their options, and their constructors.
+ * @module lib/state/definitions
+ */
+
+import type { JsonValue } from "../payload";
+import type { ReadCacheOptions } from "./published";
+
+/** Options accepted by every keyed-state definition constructor. */
+export interface StateDefinitionOptions {
+  /**
+   * Optional per-write TTL in whole seconds. Must be at least 1 and must
+   * stay within the Cassandra TTL limit.
+   */
+  ttlSeconds?: number;
+  /**
+   * Opt out of transactional staging (read-uncommitted, at-least-once).
+   * Defaults to transactional.
+   */
+  readUncommitted?: boolean;
+}
+
+/** Options accepted by JSON collections that may be published. */
+export interface PublishedStateDefinitionOptions extends StateDefinitionOptions {
+  /** Allow read-only access from other consumer groups. */
+  published?: boolean;
+  /** Override caching when this descriptor opens a published reader. */
+  readCache?: ReadCacheOptions | false;
+}
+
+/** The keyset option of map and set collections. */
+interface KeysetOptions {
+  /**
+   * Keyset bound for ordered scans (`0..=4096`; default 128 core-side; `0`
+   * disables ordered-scan tracking). Map and set collections only.
+   */
+  keysetLimit?: number;
+}
+
+/** The capacity option of deque collections. */
+interface CapacityOptions {
+  /**
+   * Optional maximum value count, at least 1. Prosody does not store it and it
+   * is not part of the collection identity, so a deploy can change it. A push
+   * past the bound removes values from the opposite end. A deque above a new,
+   * smaller bound keeps its length until the next push trims it.
+   */
+  capacity?: number;
+}
+
+/** Options accepted by the map definition constructors. */
+export interface MapDefinitionOptions
+  extends PublishedStateDefinitionOptions, KeysetOptions {}
+
+/** Options accepted by the set definition constructor. */
+export type SetDefinitionOptions = MapDefinitionOptions;
+
+/** Options accepted by the deque definition constructors. */
+export interface DequeDefinitionOptions
+  extends PublishedStateDefinitionOptions, CapacityOptions {}
+
+/** Options accepted by message-map definitions, which cannot be published. */
+export interface MessageMapDefinitionOptions
+  extends StateDefinitionOptions, KeysetOptions {}
+
+/** Options accepted by message-deque definitions, which cannot be published. */
+export interface MessageDequeDefinitionOptions
+  extends StateDefinitionOptions, CapacityOptions {}
+
+/**
+ * Phantom brand carrying a definition's item type. Never present at runtime —
+ * it exists only so the item type survives on the frozen definition object and
+ * flows into the vended handle.
+ */
+declare const StateItem: unique symbol;
+declare const StateDescriptor: unique symbol;
+
+interface DefinitionBrand {
+  readonly [StateDescriptor]: true;
+}
+
+/** A frozen single-value JSON collection definition. */
+export interface ValueDefinition<T = JsonValue>
+  extends DefinitionBrand, Readonly<PublishedStateDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "value";
+  readonly payload: "json";
+  readonly [StateItem]?: T;
+}
+
+/** A frozen ordered-map JSON collection definition (string keys). */
+export interface MapDefinition<V = JsonValue>
+  extends DefinitionBrand, Readonly<MapDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "map";
+  readonly payload: "json";
+  readonly [StateItem]?: V;
+}
+
+/** A frozen set collection definition. A set stores string members only. */
+export interface SetDefinition
+  extends DefinitionBrand, Readonly<SetDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "set";
+}
+
+/** A frozen deque JSON collection definition. */
+export interface DequeDefinition<T = JsonValue>
+  extends DefinitionBrand, Readonly<DequeDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "deque";
+  readonly payload: "json";
+  readonly [StateItem]?: T;
+}
+
+/** A frozen single-value message collection definition (items are `Message<P>`). */
+export interface MessageValueDefinition<P = JsonValue>
+  extends DefinitionBrand, Readonly<StateDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "value";
+  readonly payload: "message";
+  readonly [StateItem]?: P;
+}
+
+/** A frozen ordered-map message collection definition (values are `Message<P>`). */
+export interface MessageMapDefinition<P = JsonValue>
+  extends DefinitionBrand, Readonly<MessageMapDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "map";
+  readonly payload: "message";
+  readonly [StateItem]?: P;
+}
+
+/** A frozen deque message collection definition (elements are `Message<P>`). */
+export interface MessageDequeDefinition<P = JsonValue>
+  extends DefinitionBrand, Readonly<MessageDequeDefinitionOptions> {
+  readonly name: string;
+  readonly kind: "deque";
+  readonly payload: "message";
+  readonly [StateItem]?: P;
+}
+
+/**
+ * Declares a single-value JSON collection. The returned frozen definition is
+ * the single source of typing: place it in `Configuration.stateCollections` to
+ * register the collection, and pass it to `Context.state()` to vend a typed
+ * handle. The type parameter annotates the stored value and is compile-time
+ * only — payloads cross as plain JSON with no runtime validation.
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, and read-cache
+ *   settings.
+ */
+export function value<T = JsonValue>(
+  name: string,
+  options?: PublishedStateDefinitionOptions,
+): ValueDefinition<T>;
+
+/**
+ * Declares an ordered-map JSON collection. Map keys are always `string`. The
+ * returned frozen definition is used both in `Configuration.stateCollections`
+ * and with `Context.state()`. The type parameter annotates the stored value
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `keysetLimit` settings.
+ */
+export function map<V = JsonValue>(
+  name: string,
+  options?: MapDefinitionOptions,
+): MapDefinition<V>;
+
+/**
+ * Declares a presence-only ordered set of string members. The returned frozen
+ * definition is used both in `Configuration.stateCollections` and with
+ * `Context.state()`. A set has no payload.
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `keysetLimit` settings.
+ */
+export function set(
+  name: string,
+  options?: SetDefinitionOptions,
+): SetDefinition;
+
+/**
+ * Declares a double-ended-queue JSON collection. The returned frozen definition
+ * is used both in `Configuration.stateCollections` and with `Context.state()`.
+ * The type parameter annotates the stored element (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `capacity` settings.
+ */
+export function deque<T = JsonValue>(
+  name: string,
+  options?: DequeDefinitionOptions,
+): DequeDefinition<T>;
+
+/**
+ * Declares a single-value message collection: each stored item is the full
+ * Kafka `Message<P>` the handler received. The type parameter annotates the
+ * message payload (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds) and `readUncommitted`.
+ */
+export function messageValue<P = JsonValue>(
+  name: string,
+  options?: StateDefinitionOptions,
+): MessageValueDefinition<P>;
+
+/**
+ * Declares an ordered-map message collection (string keys; values are the full
+ * Kafka `Message<P>`). The type parameter annotates the message payload
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds`, `readUncommitted`, and `keysetLimit`.
+ */
+export function messageMap<P = JsonValue>(
+  name: string,
+  options?: MessageMapDefinitionOptions,
+): MessageMapDefinition<P>;
+
+/**
+ * Declares a double-ended-queue message collection: each stored element is the
+ * full Kafka `Message<P>`. The type parameter annotates the message payload
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds), `readUncommitted`, and
+ *   `capacity` (bounded backlog; enforced lazily on push).
+ */
+export function messageDeque<P = JsonValue>(
+  name: string,
+  options?: MessageDequeDefinitionOptions,
+): MessageDequeDefinition<P>;

package/lib/state/definitions.js

@@ -0,0 +1,151 @@
+/**
+ * The keyed-state definition constructors and the handle and reader factories they carry.
+ * @module lib/state/definitions
+ * @private
+ */
+
+const { jsonItems, messageItems } = require("./codec");
+const { DequeState } = require("./deque");
+const { MapState } = require("./map");
+const {
+  PublishedDeque,
+  PublishedMap,
+  PublishedSet,
+  PublishedValue,
+} = require("./published");
+const { SetState } = require("./set");
+const { ValueState } = require("./value");
+
+/**
+ * Maps each frozen definition to the factories that open its owned handle and
+ * its published reader. Only the definition constructors add entries.
+ * @private
+ */
+const stateDefinitionAccess = new WeakMap();
+const VALUE_ACCESS = Object.freeze({
+  owned: (context, collection) =>
+    new ValueState(context.valueState(collection), jsonItems),
+  published: async (client, subsystem, collection, readCache) =>
+    new PublishedValue(
+      await client.publishedValue(subsystem, collection, readCache),
+    ),
+});
+const MAP_ACCESS = Object.freeze({
+  owned: (context, collection) =>
+    new MapState(context.mapState(collection), jsonItems),
+  published: async (client, subsystem, collection, readCache) =>
+    new PublishedMap(
+      await client.publishedMap(subsystem, collection, readCache),
+    ),
+});
+const SET_ACCESS = Object.freeze({
+  owned: (context, collection) => new SetState(context.setState(collection)),
+  published: async (client, subsystem, collection, readCache) =>
+    new PublishedSet(
+      await client.publishedSet(subsystem, collection, readCache),
+    ),
+});
+const DEQUE_ACCESS = Object.freeze({
+  owned: (context, collection) =>
+    new DequeState(context.dequeState(collection), jsonItems),
+  published: async (client, subsystem, collection, readCache) =>
+    new PublishedDeque(
+      await client.publishedDeque(subsystem, collection, readCache),
+    ),
+});
+const MESSAGE_VALUE_ACCESS = Object.freeze({
+  owned: (context, collection) =>
+    new ValueState(context.messageValueState(collection), messageItems),
+});
+const MESSAGE_MAP_ACCESS = Object.freeze({
+  owned: (context, collection) =>
+    new MapState(context.messageMapState(collection), messageItems),
+});
+const MESSAGE_DEQUE_ACCESS = Object.freeze({
+  owned: (context, collection) =>
+    new DequeState(context.messageDequeState(collection), messageItems),
+});
+
+/**
+ * Builds a frozen state-collection definition. The definition is the single
+ * source of typing: the same frozen object is placed in
+ * `Configuration.stateCollections` (so the collection is registered once) and
+ * passed to `Context.state()` to vend a typed handle. Validation (name/ttl/
+ * keyset rules, duplicate names) is core-owned and happens at client
+ * construction and registration — this layer only shapes and freezes.
+ * @param {string} name - The collection name.
+ * @param {string} kind - `"value"`, `"map"`, `"set"`, or `"deque"`.
+ * @param {string|undefined} payload - `"json"` or `"message"`; a set has none.
+ * @param {Readonly<object>} access - The factories that open the owned handle
+ *   and, for a JSON or set collection, the published reader.
+ * @param {object} [options] - The definition options of the kind.
+ * @returns {Readonly<object>} The frozen definition.
+ * @private
+ */
+function stateDefinition(name, kind, payload, access, options = {}) {
+  const definition = { name, kind };
+  if (payload !== undefined) definition.payload = payload;
+  if (options.ttlSeconds !== undefined)
+    definition.ttlSeconds = options.ttlSeconds;
+  if (options.readUncommitted !== undefined)
+    definition.readUncommitted = options.readUncommitted;
+  if (options.published !== undefined) definition.published = options.published;
+  if (options.readCache !== undefined) definition.readCache = options.readCache;
+  if (options.keysetLimit !== undefined)
+    definition.keysetLimit = options.keysetLimit;
+  if (options.capacity !== undefined) definition.capacity = options.capacity;
+  const frozen = Object.freeze(definition);
+  stateDefinitionAccess.set(frozen, access);
+  return frozen;
+}
+
+function value(name, options) {
+  return stateDefinition(name, "value", "json", VALUE_ACCESS, options);
+}
+
+function map(name, options) {
+  return stateDefinition(name, "map", "json", MAP_ACCESS, options);
+}
+
+function set(name, options) {
+  return stateDefinition(name, "set", undefined, SET_ACCESS, options);
+}
+
+function deque(name, options) {
+  return stateDefinition(name, "deque", "json", DEQUE_ACCESS, options);
+}
+
+function messageValue(name, options) {
+  return stateDefinition(
+    name,
+    "value",
+    "message",
+    MESSAGE_VALUE_ACCESS,
+    options,
+  );
+}
+
+function messageMap(name, options) {
+  return stateDefinition(name, "map", "message", MESSAGE_MAP_ACCESS, options);
+}
+
+function messageDeque(name, options) {
+  return stateDefinition(
+    name,
+    "deque",
+    "message",
+    MESSAGE_DEQUE_ACCESS,
+    options,
+  );
+}
+
+module.exports = {
+  deque,
+  map,
+  messageDeque,
+  messageMap,
+  messageValue,
+  set,
+  stateDefinitionAccess,
+  value,
+};