@prosody-events/prosody 0.3.1 → 0.4.0

package/bindings.d.ts

@@ -71,7 +71,7 @@ export declare class NativeClient {
    * timers @returns A promise that resolves when the subscription is
    * established @throws Error if the subscription fails
    */
-  subscribe(eventHandler: { onMessage: (err: null | Error, args: [Context, Message, Record<string, string>]) => Promise<void>; onTimer: (err: null | Error, args: [Context, Timer, Record<string, string>]) => Promise<void>; isPermanent: (args: [Error]) => boolean }): Promise<void>
+  subscribe(eventHandler: { onMessage: (err: null | Error, args: [NativeContext, Message, Record<string, string>]) => Promise<void>; onTimer: (err: null | Error, args: [NativeContext, Timer, Record<string, string>]) => Promise<void>; isPermanent: (args: [Error]) => boolean }): Promise<void>
   /**
    * Gets the number of partitions assigned to the consumer.
    *
@@ -159,6 +159,409 @@ export declare class NativeContext {
    * @throws Error if retrieval fails.
    */
   scheduled(otelContext: Record<string, string>): Promise<Array<Date>>
+  /**
+   * Vends the state handle for the named JSON value collection.
+   *
+   * Vending verifies the collection's registration (core-side); no span is
+   * opened here — vended handles outlive the call, and every operation opens
+   * its own span.
+   *
+   * @param name The registered collection name.
+   * @returns The value-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  valueState(name: string): NativeValueState
+  /**
+   * Vends the state handle for the named JSON map collection.
+   *
+   * Vending verifies the collection's registration (core-side); no span is
+   * opened here — vended handles outlive the call, and every operation opens
+   * its own span.
+   *
+   * @param name The registered collection name.
+   * @returns The map-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  mapState(name: string): NativeMapState
+  /**
+   * Vends the state handle for the named JSON deque collection.
+   *
+   * Vending verifies the collection's registration (core-side); no span is
+   * opened here — vended handles outlive the call, and every operation opens
+   * its own span.
+   *
+   * @param name The registered collection name.
+   * @returns The deque-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  dequeState(name: string): NativeDequeState
+  /**
+   * Vends the state handle for the named Kafka-message value collection.
+   *
+   * Items are the full `Message` the handler received, loader-resolved on
+   * read. Vending verifies registration (core-side); no span is opened here.
+   *
+   * @param name The registered collection name.
+   * @returns The message value-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  messageValueState(name: string): NativeValueState
+  /**
+   * Vends the state handle for the named Kafka-message map collection.
+   *
+   * Items are the full `Message` the handler received, loader-resolved on
+   * read. Vending verifies registration (core-side); no span is opened here.
+   *
+   * @param name The registered collection name.
+   * @returns The message map-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  messageMapState(name: string): NativeMapState
+  /**
+   * Vends the state handle for the named Kafka-message deque collection.
+   *
+   * Items are the full `Message` the handler received, loader-resolved on
+   * read. Vending verifies registration (core-side); no span is opened here.
+   *
+   * @param name The registered collection name.
+   * @returns The message deque-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  messageDequeState(name: string): NativeDequeState
+}
+
+/** Erased deque state handle, vended per event. */
+export declare class NativeDequeState {
+  /**
+   * The number of live elements.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The element count.
+   * @throws Error carrying the category on `cause` if the read fails, or if
+   *   the count exceeds the `u32` range.
+   */
+  len(otelContext: Record<string, string>): Promise<number>
+  /**
+   * Whether the deque holds no live elements.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns True when the deque is empty.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  isEmpty(otelContext: Record<string, string>): Promise<boolean>
+  /**
+   * Reads the element at front-relative position `index`.
+   *
+   * @param index The zero-based position from the front.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The element, or null past the end.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  get(index: number, otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Reads the front endpoint SLOT without a length round trip — exactly
+   * `get(0)`.
+   *
+   * Decodes and resolves the returned element (unlike eviction). An empty
+   * deque, or a front endpoint slot expired under a TTL, yields null even
+   * when live interior elements exist — a peek never searches inward.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The front element, or null when the endpoint slot is empty.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  peekFront(otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Reads the back endpoint SLOT without a length round trip — exactly
+   * `get(len − 1)`.
+   *
+   * Decodes and resolves the returned element (unlike eviction). An empty
+   * deque, or a back endpoint slot expired under a TTL, yields null even
+   * when live interior elements exist — a peek never searches inward.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The back element, or null when the endpoint slot is empty.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  peekBack(otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Appends an element at the back.
+   *
+   * JSON null is not a storable element and is rejected with a transient
+   * error. An item-shape mismatch is a caller mistake and is likewise
+   * transient (it retries and stays visible, never discarded).
+   *
+   * @param item The value (JSON) or message to append.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the write fails.
+   */
+  pushBack(item: any, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Prepends an element at the front.
+   *
+   * JSON null is not a storable element and is rejected with a transient
+   * error. An item-shape mismatch is a caller mistake and is likewise
+   * transient (it retries and stays visible, never discarded).
+   *
+   * @param item The value (JSON) or message to prepend.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the write fails.
+   */
+  pushFront(item: any, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Removes and returns the front element.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The removed front element, or null when empty.
+   * @throws Error carrying the category on `cause` if the operation fails.
+   */
+  popFront(otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Removes and returns the back element.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The removed back element, or null when empty.
+   * @throws Error carrying the category on `cause` if the operation fails.
+   */
+  popBack(otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Removes every element.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the clear fails.
+   */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Opens a demand-driven cursor over the live elements in index order.
+   *
+   * Synchronous — it performs no I/O. The extracted JavaScript context is
+   * active while core constructs its semantic stream span; chunk pulls do
+   * not create binding spans.
+   *
+   * @param direction The scan direction (`"forward"` or `"backward"`).
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns A cursor over the deque elements.
+   * @throws Error if the direction token is invalid.
+   */
+  scan(direction: string, otelContext: Record<string, string>): NativeStateCursor
+  /**
+   * Durably commits the buffered operations mid-handler.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the commit fails.
+   */
+  commit(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Discards the buffered uncommitted operations.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   */
+  rollback(otelContext: Record<string, string>): Promise<void>
+}
+
+/** Erased ordered-map state handle, keyed by `String`, vended per event. */
+export declare class NativeMapState {
+  /**
+   * Reads the value for `key`.
+   *
+   * @param key The map key.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The value, or null when the key is absent.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  get(key: string, otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Reads several keys in a single call.
+   *
+   * Returns one entry per key, in the same order requested: the entry at
+   * index `i` is the value for `keys[i]`. A key that isn't there reads as
+   * null, and a key listed more than once is answered at each of its spots.
+   * The whole read happens as one step, so no other change to this event's
+   * state can slip in partway through.
+   *
+   * @param keys The keys to read, in order.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns One result per input key; null for a key that is absent.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  getMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<any | Message | undefined | null>>
+  /**
+   * Reports whether a stored cell exists for `key`.
+   *
+   * Reads the event's dirty overlay (read-your-writes) and answers presence
+   * WITHOUT decoding the value or running the resolver — a message-backed
+   * map answers with zero Kafka fetches and can report `true` for a
+   * message that can no longer be fetched. This is NOT "no I/O": a cache
+   * miss can still reach Cassandra, so it is async and fallible exactly
+   * like `get`.
+   *
+   * @param key The map key.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns True when a stored cell exists for `key`.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  contains(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /**
+   * Inserts or overwrites `key`.
+   *
+   * JSON null is rejected with a transient error naming `delete` as the way
+   * to remove an entry. An item-shape mismatch is a caller mistake and is
+   * likewise transient (it retries and stays visible, never discarded).
+   *
+   * @param key The map key.
+   * @param item The value (JSON) or message to store.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the write fails.
+   */
+  set(key: string, item: any, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Removes `key`.
+   *
+   * @param key The map key.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the removal fails.
+   */
+  remove(key: string, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Removes every entry.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the clear fails.
+   */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Opens a demand-driven cursor over the live entries in key order.
+   *
+   * Synchronous — it performs no I/O. The extracted JavaScript context is
+   * active while core constructs its semantic stream span; chunk pulls do
+   * not create binding spans. Entries are yielded as `(key, value)` pairs.
+   *
+   * @param direction The scan direction (`"forward"` or `"backward"`).
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns A cursor over the map entries.
+   * @throws Error if the direction token is invalid.
+   */
+  scan(direction: string, otelContext: Record<string, string>): NativeStateCursor
+  /**
+   * Opens a demand-driven cursor over the live KEYS in key order.
+   *
+   * Skips the value codec and the resolver (no value decode, no Kafka
+   * fetch), so a message-backed map enumerates keys with zero Kafka
+   * fetches — but it still reads presence, so it is not zero-I/O.
+   * Synchronous like `scan`: the extracted JavaScript context is active
+   * while core constructs its semantic stream span. Yields bare keys.
+   *
+   * @param direction The scan direction (`"forward"` or `"backward"`).
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns A cursor over the map keys.
+   * @throws Error if the direction token is invalid.
+   */
+  keys(direction: string, otelContext: Record<string, string>): NativeStateCursor
+  /**
+   * Durably commits the buffered operations mid-handler.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the commit fails.
+   */
+  commit(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Discards the buffered uncommitted operations.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   */
+  rollback(otelContext: Record<string, string>): Promise<void>
+}
+
+/**
+ * Demand-driven scan cursor over a map or deque collection.
+ *
+ * Pulling is lazy: each `next_chunk()` restores the JavaScript context without
+ * creating a binding span, awaits one stream item, and asks core to drain only
+ * the immediately-ready tail. Chunking,
+ * exhaustion, error ordering, serialization, close-idempotence, and
+ * use-after-close behavior are core-owned; this layer only transports.
+ */
+export declare class NativeStateCursor {
+  /**
+   * Pulls the next immediately-ready chunk of scanned items.
+   *
+   * Awaits the first item, then drains up to 255 more items only while they
+   * are immediately ready. This amortizes N-API overhead without waiting to
+   * fill a chunk.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The next non-empty vector of items, or null when exhausted.
+   * @throws Error carrying the category on `cause` if the pull fails or the
+   *   cursor was closed.
+   */
+  nextChunk(otelContext: Record<string, string>): Promise<Array<any | [string, any] | Message | [string, Message]> | null>
+  /**
+   * Closes the cursor, releasing the underlying stream.
+   *
+   * Idempotent; a subsequent `next_chunk()` errors. No span — pure teardown.
+   *
+   * @returns A promise that resolves when the cursor is closed.
+   */
+  close(): Promise<void>
+}
+
+/**
+ * Erased single-value state handle, vended per event.
+ *
+ * Wraps the boxed erased value handle plus the propagator used to open each
+ * operation's span. Values cross as JSON; message collections cross as the
+ * `Message` object.
+ */
+export declare class NativeValueState {
+  /**
+   * Reads the current value.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The current value, or null when absent/cleared.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  get(otelContext: Record<string, string>): Promise<any | Message | null>
+  /**
+   * Buffers a write of the value.
+   *
+   * JSON null is rejected with a transient error naming `clear` as the way
+   * to delete. A message-shaped payload cannot be stored in a JSON
+   * collection (and vice versa); such a mismatch is a caller mistake and is
+   * likewise transient (it retries and stays visible, never discarded).
+   *
+   * @param item The value (JSON) or message to write.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the write fails.
+   */
+  set(item: any, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Buffers a clear of the value.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the clear fails.
+   */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Durably commits the buffered operations mid-handler.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the commit fails.
+   */
+  commit(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Discards the buffered uncommitted operations.
+   *
+   * Infallible: rolling back a terminated session is a no-op.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   */
+  rollback(otelContext: Record<string, string>): Promise<void>
 }
 
 /** Configuration options for the Prosody client. */
@@ -173,7 +576,7 @@ export interface Configuration {
   groupId?: string
   /**
    * Global shared cache capacity across all partitions for deduplicating
-   * messages. Set to 0 to disable deduplication entirely.
+   * messages. Must be greater than 0.
    */
   idempotenceCacheSize?: number
   /**
@@ -313,8 +716,8 @@ export interface Configuration {
   /** Sliding window duration (in milliseconds) for failure rate tracking. */
   deferFailureWindowMs?: number
   /**
-   * Cache size for defer middleware.
-   * Controls capacity for store cache and loader cache.
+   * Cache size for the deferred-retry message loader.
+   * Controls capacity for the loader cache.
    */
   deferCacheSize?: number
   /**
@@ -354,6 +757,37 @@ export interface Configuration {
    * or `"follows_from"`. Default: `"follows_from"`.
    */
   timerSpans?: string
+  /**
+   * Keyed-state collections to register before subscribe.
+   *
+   * Each entry declares one collection by name, kind, and payload. Duplicate
+   * names within this set are rejected.
+   */
+  stateCollections?: Array<StateCollectionConfig>
+  /**
+   * Disk workspace for the local keyed-state cache.
+   *
+   * Each live client needs its own directory because it is locked
+   * exclusively. Falls back to the `PROSODY_STATE_CACHE_DIR` environment
+   * variable, then a per-client temporary directory. Must not be an
+   * empty string when set.
+   */
+  stateCacheDir?: string
+  /**
+   * Capacity of the in-memory keyed-state cache, in bytes. Falls back to
+   * `PROSODY_STATE_CACHE_SIZE_BYTES`,
+   * then to the storage-engine default. Must be a positive safe integer.
+   */
+  stateCacheSizeBytes?: number
+  /**
+   * Delay in whole seconds between staging a provisional cell and the
+   * keyed-state recovery sweep. Every registered TTL must strictly exceed
+   * this. Falls back to the `PROSODY_STATE_RECOVERY_DELAY` environment
+   * variable (a duration string such as `30s`), then to 30 seconds. Must be
+   * a whole number of seconds >= 1 when set (fractional, negative, and
+   * non-finite values are rejected).
+   */
+  stateRecoveryDelaySeconds?: number
 }
 
 /**
@@ -510,6 +944,48 @@ export declare function setLogger(logger: Logger): void
  */
 export declare function setLoggerIfUnset(logger: Logger): boolean
 
+/** Declares one keyed-state collection to register before subscribe. */
+export interface StateCollectionConfig {
+  /**
+   * The collection name. Must be non-empty and unique within the client's
+   * definition set.
+   */
+  name: string
+  /** The collection kind: `"value"`, `"map"`, or `"deque"`. */
+  kind: string
+  /**
+   * The item payload: `"json"` (JSON values) or `"message"` (the full Kafka
+   * message the handler received).
+   */
+  payload: string
+  /**
+   * Optional per-write TTL in whole seconds. Must be a whole number >= 1
+   * (fractional, negative, and non-finite values are rejected) and must
+   * exceed the recovery delay (the latter checked at consumer build).
+   */
+  ttlSeconds?: number
+  /**
+   * Optional opt-out of transactional staging (read-uncommitted, at-least
+   * once). Defaults to transactional.
+   */
+  readUncommitted?: boolean
+  /**
+   * Optional map-only keyset bound (`0..=4096`; default 128 core-side; `0`
+   * disables ordered-scan tracking). Must be a whole number in that range
+   * (fractional, negative, and non-finite values are rejected). Invalid on
+   * value or deque collections.
+   */
+  keysetLimit?: number
+  /**
+   * Optional deque-only capacity (bounded backlog). Must be a whole number
+   * >= 1 (fractional, zero, negative, and non-finite values are rejected).
+   * Runtime configuration only — not persisted, not part of collection
+   * identity, and freely changeable across deploys; enforced lazily on push.
+   * Invalid on value or map collections.
+   */
+  capacity?: number
+}
+
 /**
  * Represents a timer event.
  *