@ably/ai-transport 0.0.1

package/src/core/codec/encoder.ts

@@ -0,0 +1,470 @@
+/**
+ * Encoder core — message append lifecycle machinery.
+ *
+ * Provides Ably primitives (publish, append, close, abort, flush) that
+ * domain-specific encoders wire their event types to.
+ *
+ * Domain encoders call `createEncoderCore(writer, options)` and use the
+ * returned core to map domain events to Ably operations without
+ * reimplementing the message append lifecycle.
+ */
+
+import * as Ably from 'ably';
+
+import { HEADER_MSG_ID, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID } from '../../constants.js';
+import { ErrorCode } from '../../errors.js';
+import type { Logger } from '../../logger.js';
+import { mergeHeaders } from '../../utils.js';
+import type { ChannelWriter, EncoderOptions, Extras, MessagePayload, StreamPayload, WriteOptions } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options for creating an encoder core. Extends {@link EncoderOptions} with a logger. */
+export interface EncoderCoreOptions extends EncoderOptions {
+  /** Logger instance for diagnostic output. */
+  logger?: Logger;
+}
+
+// ---------------------------------------------------------------------------
+// Stream tracker (internal)
+// ---------------------------------------------------------------------------
+
+interface StreamState {
+  serial: string;
+  name: string;
+  streamId: string;
+  accumulated: string;
+  persistentHeaders: Record<string, string>;
+  aborted: boolean;
+}
+
+interface PendingAppend {
+  promise: Promise<Ably.UpdateDeleteResult>;
+  streamId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Encoder core interface
+// ---------------------------------------------------------------------------
+
+/** The core encoder primitives that domain codec encoders delegate to. */
+export interface EncoderCore {
+  /** Publish a single discrete (non-streaming) message described by a payload. */
+  publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult>;
+
+  /** Publish multiple discrete messages atomically in a single channel publish. */
+  publishDiscreteBatch(payloads: MessagePayload[], opts?: WriteOptions): Promise<Ably.PublishResult>;
+
+  /** Start a streamed message with x-ably-status:streaming. */
+  startStream(streamId: string, payload: StreamPayload, opts?: WriteOptions): Promise<void>;
+
+  /**
+   * Append data to an in-flight streamed message. Fire-and-forget: errors are
+   * collected internally and surfaced by {@link closeStream} or {@link close}.
+   */
+  appendStream(streamId: string, data: string): void;
+
+  /**
+   * Close a streamed message with x-ably-status:finished. Flushes all pending
+   * appends for recovery before returning. Repeats persistent and payload headers.
+   */
+  closeStream(streamId: string, payload: StreamPayload): Promise<void>;
+
+  /**
+   * Abort a single in-progress stream (x-ably-status:aborted) and flush all
+   * pending appends for recovery before returning.
+   */
+  abortStream(streamId: string, opts?: WriteOptions): Promise<void>;
+
+  /**
+   * Abort all in-progress streams (x-ably-status:aborted) and flush all
+   * pending appends for recovery before returning.
+   */
+  abortAllStreams(opts?: WriteOptions): Promise<void>;
+
+  /** Flush + clear trackers. Idempotent. */
+  close(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Default implementation
+// ---------------------------------------------------------------------------
+
+// Spec: AIT-CD1
+class DefaultEncoderCore implements EncoderCore {
+  private readonly _writer: ChannelWriter;
+  private readonly _defaultClientId: string | undefined;
+  private readonly _defaultExtras: Extras | undefined;
+  private readonly _onMessageHook: (message: Ably.Message) => void;
+  private readonly _logger: Logger | undefined;
+  private readonly _trackers = new Map<string, StreamState>();
+  private _pending: PendingAppend[] = [];
+  private _flushPromise: Promise<void> | undefined;
+  private _closed = false;
+
+  constructor(writer: ChannelWriter, options: EncoderCoreOptions = {}) {
+    this._writer = writer;
+    this._defaultClientId = options.clientId;
+    this._defaultExtras = options.extras;
+    this._onMessageHook =
+      options.onMessage ??
+      (() => {
+        /* noop */
+      });
+    this._logger = options.logger?.withContext({ component: 'EncoderCore' });
+  }
+
+  // Spec: AIT-CD11
+  async publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult> {
+    this._assertNotClosed();
+    this._logger?.trace('DefaultEncoderCore.publishDiscrete();', { name: payload.name });
+    const msg = this._buildDiscreteMessage(payload, opts);
+    return this._writer.publish(msg);
+  }
+
+  // Spec: AIT-CD11a
+  async publishDiscreteBatch(payloads: MessagePayload[], opts?: WriteOptions): Promise<Ably.PublishResult> {
+    this._assertNotClosed();
+    this._logger?.trace('DefaultEncoderCore.publishDiscreteBatch();', { count: payloads.length });
+    const msgs = payloads.map((p) => this._buildDiscreteMessage(p, opts));
+    return this._writer.publish(msgs);
+  }
+
+  // Spec: AIT-CD2
+  async startStream(streamId: string, payload: StreamPayload, opts?: WriteOptions): Promise<void> {
+    this._assertNotClosed();
+    this._logger?.trace('DefaultEncoderCore.startStream();', { name: payload.name, streamId });
+
+    const allHeaders = this._buildHeaders(payload.headers ?? {}, opts);
+    allHeaders[HEADER_STREAM] = 'true';
+    allHeaders[HEADER_STATUS] = 'streaming';
+    allHeaders[HEADER_STREAM_ID] = streamId;
+
+    const clientId = this._resolveClientId(opts);
+    const msg: Ably.Message = {
+      name: payload.name,
+      data: payload.data,
+      extras: { headers: allHeaders },
+      ...(clientId ? { clientId } : {}),
+    };
+
+    this._invokeOnMessage(msg);
+    const result = await this._writer.publish(msg);
+    const serial = result.serials[0];
+
+    if (!serial) {
+      throw new Ably.ErrorInfo(
+        `unable to start stream; no serial returned for stream '${payload.name}' (streamId: ${streamId})`,
+        ErrorCode.BadRequest,
+        400,
+      );
+    }
+
+    this._trackers.set(streamId, {
+      serial,
+      name: payload.name,
+      streamId,
+      accumulated: payload.data,
+      persistentHeaders: allHeaders,
+      aborted: false,
+    });
+
+    this._logger?.debug('DefaultEncoderCore.startStream(); stream started', {
+      name: payload.name,
+      streamId,
+      serial,
+    });
+  }
+
+  // Spec: AIT-CD3
+  appendStream(streamId: string, data: string): void {
+    this._assertNotClosed();
+    const tracker = this._trackers.get(streamId);
+    if (!tracker) {
+      throw new Ably.ErrorInfo(
+        `unable to append to stream; no active stream for streamId '${streamId}'`,
+        ErrorCode.InvalidArgument,
+        400,
+      );
+    }
+
+    tracker.accumulated += data;
+
+    const appendMsg: Ably.Message = {
+      serial: tracker.serial,
+      data,
+      extras: { headers: { ...tracker.persistentHeaders } },
+    };
+
+    this._invokeOnMessage(appendMsg);
+    const p = this._writer.appendMessage(appendMsg);
+    this._pending.push({ promise: p, streamId });
+  }
+
+  // Spec: AIT-CD4, AIT-CD4a
+  async closeStream(streamId: string, payload: StreamPayload): Promise<void> {
+    this._assertNotClosed();
+    this._logger?.trace('DefaultEncoderCore.closeStream();', { streamId });
+
+    const tracker = this._trackers.get(streamId);
+    if (!tracker) {
+      throw new Ably.ErrorInfo(
+        `unable to close stream; no active stream for streamId '${streamId}'`,
+        ErrorCode.InvalidArgument,
+        400,
+      );
+    }
+
+    // Accumulate closing data so recovery has the full content
+    tracker.accumulated += payload.data;
+
+    const allHeaders = this._buildClosingHeaders(tracker, payload.headers ?? {});
+    allHeaders[HEADER_STATUS] = 'finished';
+
+    const msg: Ably.Message = {
+      serial: tracker.serial,
+      data: payload.data,
+      extras: { headers: allHeaders },
+    };
+
+    this._invokeOnMessage(msg);
+    const p = this._writer.appendMessage(msg);
+    this._pending.push({ promise: p, streamId });
+
+    await this._flushPending();
+
+    this._logger?.debug('DefaultEncoderCore.closeStream(); stream closed', { streamId });
+  }
+
+  // Spec: AIT-CD5, AIT-CD5b
+  async abortStream(streamId: string, opts?: WriteOptions): Promise<void> {
+    this._assertNotClosed();
+    this._logger?.trace('DefaultEncoderCore.abortStream();', { streamId });
+
+    const tracker = this._trackers.get(streamId);
+    if (!tracker) {
+      throw new Ably.ErrorInfo(
+        `unable to abort stream; no active stream for streamId '${streamId}'`,
+        ErrorCode.InvalidArgument,
+        400,
+      );
+    }
+
+    tracker.aborted = true;
+
+    const allHeaders = this._buildClosingHeaders(tracker, {}, opts);
+    allHeaders[HEADER_STATUS] = 'aborted';
+
+    const msg: Ably.Message = {
+      serial: tracker.serial,
+      data: '',
+      extras: { headers: allHeaders },
+    };
+
+    this._invokeOnMessage(msg);
+    const p = this._writer.appendMessage(msg);
+    this._pending.push({ promise: p, streamId });
+
+    await this._flushPending();
+
+    this._logger?.debug('DefaultEncoderCore.abortStream(); stream aborted', { streamId });
+  }
+
+  // Spec: AIT-CD5a
+  async abortAllStreams(opts?: WriteOptions): Promise<void> {
+    this._assertNotClosed();
+    this._logger?.trace('DefaultEncoderCore.abortAllStreams();', { streamCount: this._trackers.size });
+
+    for (const tracker of this._trackers.values()) {
+      tracker.aborted = true;
+
+      const allHeaders = this._buildClosingHeaders(tracker, {}, opts);
+      allHeaders[HEADER_STATUS] = 'aborted';
+
+      const msg: Ably.Message = {
+        serial: tracker.serial,
+        data: '',
+        extras: { headers: allHeaders },
+      };
+
+      this._invokeOnMessage(msg);
+      const p = this._writer.appendMessage(msg);
+      this._pending.push({ promise: p, streamId: tracker.streamId });
+    }
+
+    await this._flushPending();
+  }
+
+  // Spec: AIT-CD6
+  private async _flushPending(): Promise<void> {
+    // Re-entrancy guard: if a flush is already in progress, await it instead of starting a new one.
+    if (this._flushPromise) {
+      return this._flushPromise;
+    }
+
+    const snapshot = this._pending;
+    this._pending = [];
+
+    if (snapshot.length === 0) return;
+
+    this._logger?.trace('DefaultEncoderCore._flushPending();', { count: snapshot.length });
+
+    this._flushPromise = this._doFlush(snapshot);
+    try {
+      await this._flushPromise;
+    } finally {
+      this._flushPromise = undefined;
+    }
+  }
+
+  private async _doFlush(snapshot: PendingAppend[]): Promise<void> {
+    const results = await Promise.allSettled(snapshot.map(async (p) => p.promise));
+    const failures = new Set<string>();
+
+    for (const [i, result] of results.entries()) {
+      const entry = snapshot[i];
+      if (entry && result.status === 'rejected') {
+        failures.add(entry.streamId);
+      }
+    }
+
+    if (failures.size === 0) {
+      this._logger?.debug('DefaultEncoderCore._flushPending(); all appends succeeded');
+      return;
+    }
+
+    this._logger?.warn('DefaultEncoderCore._flushPending(); recovering failed appends', {
+      failedStreams: [...failures],
+    });
+
+    const recoveryErrors: { streamId: string; error: unknown }[] = [];
+
+    for (const streamId of failures) {
+      const tracker = this._trackers.get(streamId);
+      if (!tracker) continue;
+
+      const recoveryStatus = tracker.aborted ? 'aborted' : 'finished';
+      const msg: Ably.Message = {
+        serial: tracker.serial,
+        data: tracker.accumulated,
+        extras: { headers: { ...tracker.persistentHeaders, [HEADER_STATUS]: recoveryStatus } },
+      };
+
+      try {
+        await this._writer.updateMessage(msg);
+      } catch (error) {
+        recoveryErrors.push({ streamId, error });
+      }
+    }
+
+    if (recoveryErrors.length > 0) {
+      const ids = recoveryErrors.map((e) => e.streamId).join(', ');
+      this._logger?.error('DefaultEncoderCore._flushPending(); recovery failed', { failedStreams: ids });
+      throw new Ably.ErrorInfo(
+        `unable to flush pending appends; recovery failed for stream(s): ${ids}`,
+        ErrorCode.EncoderRecoveryFailed,
+        500,
+      );
+    }
+  }
+
+  // Spec: AIT-CD12
+  async close(): Promise<void> {
+    if (this._closed) return;
+    this._logger?.trace('DefaultEncoderCore.close();');
+    this._closed = true;
+    try {
+      await this._flushPending();
+    } finally {
+      this._trackers.clear();
+    }
+    this._logger?.debug('DefaultEncoderCore.close(); encoder closed');
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  // Spec: AIT-CD14
+  private _invokeOnMessage(msg: Ably.Message): void {
+    try {
+      this._onMessageHook(msg);
+    } catch (error) {
+      this._logger?.error('DefaultEncoderCore._invokeOnMessage(); hook threw', { error });
+    }
+  }
+
+  private _assertNotClosed(): void {
+    if (this._closed) {
+      throw new Ably.ErrorInfo('unable to write to encoder; encoder has been closed', ErrorCode.InvalidArgument, 400);
+    }
+  }
+
+  private _resolveClientId(opts?: WriteOptions): string | undefined {
+    return opts?.clientId ?? this._defaultClientId;
+  }
+
+  private _buildHeaders(codecHeaders: Record<string, string>, opts?: WriteOptions): Record<string, string> {
+    const callerHeaders = mergeHeaders(this._defaultExtras?.headers, opts?.extras?.headers);
+    const merged = { ...callerHeaders, ...codecHeaders };
+    if (opts?.messageId !== undefined) {
+      merged[HEADER_MSG_ID] = opts.messageId;
+    }
+    return merged;
+  }
+
+  private _buildDiscreteMessage(payload: MessagePayload, opts?: WriteOptions): Ably.Message {
+    const headers = this._buildHeaders(payload.headers ?? {}, opts);
+    headers[HEADER_STREAM] = 'false';
+    const clientId = this._resolveClientId(opts);
+
+    const msg: Ably.Message = {
+      name: payload.name,
+      data: payload.data,
+      extras: {
+        headers,
+        ...(payload.ephemeral ? { ephemeral: true } : {}),
+      },
+      ...(clientId ? { clientId } : {}),
+    };
+
+    this._invokeOnMessage(msg);
+    return msg;
+  }
+
+  /**
+   * Build headers for a closing append. Closing appends must repeat ALL
+   * persistent headers (Ably replaces the entire extras object on append).
+   * Then layer caller and codec overrides.
+   * @param tracker - The stream tracker with persistent headers.
+   * @param codecHeaders - Codec-layer headers to merge.
+   * @param opts - Optional per-write overrides.
+   * @returns Merged headers for the closing append.
+   */
+  private _buildClosingHeaders(
+    tracker: StreamState,
+    codecHeaders: Record<string, string>,
+    opts?: WriteOptions,
+  ): Record<string, string> {
+    const h = { ...tracker.persistentHeaders };
+    const callerHeaders = mergeHeaders(this._defaultExtras?.headers, opts?.extras?.headers);
+    Object.assign(h, callerHeaders);
+    Object.assign(h, codecHeaders);
+    return h;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an encoder core bound to the given channel writer.
+ * @param writer - The channel writer to publish messages through.
+ * @param options - Encoder configuration (clientId, extras, hooks, logger).
+ * @returns A new {@link EncoderCore} instance.
+ */
+export const createEncoderCore = (writer: ChannelWriter, options: EncoderCoreOptions = {}): EncoderCore =>
+  new DefaultEncoderCore(writer, options);

package/src/core/codec/index.ts

@@ -0,0 +1,28 @@
+export { eventOutput } from './decoder.js';
+export type {
+  ChannelWriter,
+  Codec,
+  DecoderOutput,
+  DiscreteEncoder,
+  EncoderOptions,
+  Extras,
+  MessageAccumulator,
+  MessagePayload,
+  StreamDecoder,
+  StreamEncoder,
+  StreamPayload,
+  StreamTrackerState,
+  WriteOptions,
+} from './types.js';
+
+// Encoder core
+export type { EncoderCore, EncoderCoreOptions } from './encoder.js';
+export { createEncoderCore } from './encoder.js';
+
+// Decoder core
+export type { DecoderCore, DecoderCoreHooks, DecoderCoreOptions } from './decoder.js';
+export { createDecoderCore } from './decoder.js';
+
+// Lifecycle tracker
+export type { LifecycleTracker, PhaseConfig } from './lifecycle-tracker.js';
+export { createLifecycleTracker } from './lifecycle-tracker.js';

package/src/core/codec/lifecycle-tracker.ts

@@ -0,0 +1,140 @@
+/**
+ * Generic lifecycle tracker for codec decoders.
+ *
+ * Manages per-scope (typically per-turn) tracking of lifecycle phases that
+ * must be emitted before content events. When a phase has not been emitted
+ * (e.g. mid-stream join), the tracker synthesizes the missing events using
+ * codec-provided build functions.
+ *
+ * Codecs configure the tracker with an ordered list of phases, then compose
+ * it into their decoder hooks. The tracker is independent of any specific
+ * codec or event type.
+ */
+
+// ---------------------------------------------------------------------------
+// Phase configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for a single lifecycle phase that may need to be
+ * synthesized when missing from the wire stream.
+ */
+export interface PhaseConfig<TEvent> {
+  /** Unique key identifying this phase (e.g. "start", "start-step"). */
+  key: string;
+  /**
+   * Build the synthetic event(s) for this phase. Called with a context
+   * record that codecs populate at the call site — the tracker passes
+   * it through without interpreting it.
+   * @param context - Key-value pairs from the call site (e.g. headers).
+   * @returns One or more synthetic events to emit for this phase.
+   */
+  build(context: Record<string, string | undefined>): TEvent[];
+}
+
+// ---------------------------------------------------------------------------
+// Tracker interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-scope lifecycle tracker that ensures required phases are emitted
+ * before content events, synthesizing missing ones for mid-stream joins.
+ *
+ * Scoped by an arbitrary string key (typically a turn ID). Each scope
+ * tracks independently which phases have been emitted.
+ */
+export interface LifecycleTracker<TEvent> {
+  /**
+   * Ensure all configured phases have been emitted for the given scope.
+   * Returns synthetic events for any phases not yet marked as emitted,
+   * then marks them. Returns an empty array if all phases are current.
+   * @param scopeId - The scope to check (e.g. turn ID).
+   * @param context - Key-value pairs passed through to phase build functions.
+   * @returns Synthetic events for missing phases, in configuration order.
+   */
+  ensurePhases(scopeId: string, context: Record<string, string | undefined>): TEvent[];
+
+  /**
+   * Mark a phase as emitted from the wire (not synthetic). Call this
+   * when the real event arrives so the tracker does not re-synthesize it.
+   * @param scopeId - The scope (e.g. turn ID).
+   * @param phaseKey - The phase key to mark.
+   */
+  markEmitted(scopeId: string, phaseKey: string): void;
+
+  /**
+   * Reset a phase so it will be re-synthesized on the next
+   * {@link ensurePhases} call. Used for repeating phases (e.g. "start-step"
+   * resets after "finish-step").
+   * @param scopeId - The scope (e.g. turn ID).
+   * @param phaseKey - The phase key to reset.
+   */
+  resetPhase(scopeId: string, phaseKey: string): void;
+
+  /**
+   * Remove all tracking state for a scope. Call on turn completion
+   * (finish, abort) to free memory.
+   * @param scopeId - The scope to clear.
+   */
+  clearScope(scopeId: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Default implementation
+// ---------------------------------------------------------------------------
+
+// Spec: AIT-CD13
+class DefaultLifecycleTracker<TEvent> implements LifecycleTracker<TEvent> {
+  private readonly _phases: PhaseConfig<TEvent>[];
+  private readonly _emitted = new Map<string, Set<string>>();
+
+  constructor(phases: PhaseConfig<TEvent>[]) {
+    this._phases = phases;
+  }
+
+  ensurePhases(scopeId: string, context: Record<string, string | undefined>): TEvent[] {
+    const emitted = this._getOrCreate(scopeId);
+    const events: TEvent[] = [];
+    for (const phase of this._phases) {
+      if (!emitted.has(phase.key)) {
+        emitted.add(phase.key);
+        events.push(...phase.build(context));
+      }
+    }
+    return events;
+  }
+
+  markEmitted(scopeId: string, phaseKey: string): void {
+    this._getOrCreate(scopeId).add(phaseKey);
+  }
+
+  resetPhase(scopeId: string, phaseKey: string): void {
+    this._emitted.get(scopeId)?.delete(phaseKey);
+  }
+
+  clearScope(scopeId: string): void {
+    this._emitted.delete(scopeId);
+  }
+
+  private _getOrCreate(scopeId: string): Set<string> {
+    let set = this._emitted.get(scopeId);
+    if (!set) {
+      set = new Set();
+      this._emitted.set(scopeId, set);
+    }
+    return set;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a lifecycle tracker configured with the given phases.
+ * Phases are checked and synthesized in array order.
+ * @param phases - Ordered phase configurations.
+ * @returns A new {@link LifecycleTracker} instance.
+ */
+export const createLifecycleTracker = <TEvent>(phases: PhaseConfig<TEvent>[]): LifecycleTracker<TEvent> =>
+  new DefaultLifecycleTracker(phases);