@ixo/oracle-runtime-workers 0.37.1 → 0.38.0

package/src/do/flush-schedule.ts

@@ -9,7 +9,9 @@
  * dirty copy alone. Two exceptions upload right away: a copy about to be
  * evicted (the wipe must never drop unsaved turns) and a copy marked dirty
  * before the deadline existed (older objects; one upload, then the
- * debounce applies).
+ * debounce applies). A copy waiting for a delegation is not uploaded at
+ * all: without one the owner store refuses it, and the next delegation
+ * the object receives uploads it (`meta:flushWaitsForDelegation`).
  */
 export interface FlushScheduleInput {
   /** The object holds writes the owner store has not seen (and a database is open). */
@@ -19,10 +21,12 @@ export interface FlushScheduleInput {
   now: number;
   /** The idle-eviction path is about to wipe the working copy. */
   idle: boolean;
+  /** The last upload failed for want of a delegation; none has arrived since. */
+  waitingForDelegation?: boolean;
 }
 
 export type FlushScheduleDecision =
-  | { action: 'skip'; reason: 'clean' }
+  | { action: 'skip'; reason: 'clean' | 'waiting-for-delegation' }
   | { action: 'flush'; reason: 'due' | 'idle' | 'no-deadline' }
   | { action: 'wait'; at: number };
 
@@ -31,6 +35,8 @@ export const FLUSH_DUE_SLACK_MS = 1000;
 
 export function decideFlush(input: FlushScheduleInput): FlushScheduleDecision {
   if (!input.dirty) return { action: 'skip', reason: 'clean' };
+  if (input.waitingForDelegation)
+    return { action: 'skip', reason: 'waiting-for-delegation' };
   if (input.idle) return { action: 'flush', reason: 'idle' };
   if (typeof input.flushAt !== 'number' || !Number.isFinite(input.flushAt))
     return { action: 'flush', reason: 'no-deadline' };

package/src/do/room-mirror.ts

@@ -19,9 +19,20 @@ import {
  * - sends are serialised per session (parallel across sessions), so a reply
  *   being retried can never overtake the message it answers, and a later
  *   turn's mirrors queue behind an earlier turn's.
+ *
+ * The same chain carries the media events of a channel turn's files
+ * (`sendMedia`, built by `attachments/room-media.ts`): the owner object
+ * queues them in file order right after the person's text, so each is
+ * posted after that text and before the reply, whenever its upload ends.
  */
+import type { EncryptedFileInfo } from '@ixo/matrix-bot-workers-sdk';
+import { abortError, untilAborted } from '../attachments/download';
 import { matrixTxnId } from '../matrix/txn-id';
-import { retryGateway, type RetryGatewayOptions } from './gateway-retry';
+import {
+  isTransientGatewayError,
+  retryGateway,
+  type RetryGatewayOptions,
+} from './gateway-retry';
 
 export type MirrorAuthor = 'user' | 'oracle';
 
@@ -53,8 +64,43 @@ export interface MirrorSend {
   };
 }
 
+/** The `org.ixo.qi.origin` input of a channel mirror. */
+export type MirrorOrigin = NonNullable<MirrorSend['origin']>;
+
+/**
+ * The media part of an `m.room.message` file event (`m.image` / `m.video` /
+ * `m.audio` / `m.file`): what the room shows, without the thread relation
+ * and the channel origin, which `mediaEventContent` adds.
+ */
+export interface MediaMessage {
+  msgtype: 'm.image' | 'm.video' | 'm.audio' | 'm.file';
+  body: string;
+  filename: string;
+  info: { mimetype: string; size: number };
+  /**
+   * The encrypted attachment: its `mxc://` plus the `EncryptedFile` fields.
+   * Always encrypted: a file is only ever posted into a Megolm room.
+   */
+  file: { url: string } & EncryptedFileInfo;
+}
+
+export interface MediaMirrorSend {
+  roomId: string;
+  /** The session's marker event — the thread the file is posted under. */
+  threadId: string;
+  txnId: string;
+  origin?: MirrorOrigin;
+  media: MediaMessage;
+}
+
 export interface RoomMirrorDeps {
   sendText(send: MirrorSend): Promise<string>;
+  /**
+   * Send one file event (`content` JSON-encoded) with a pinned transaction
+   * id, at background priority (`MatrixGatewayObject.sendEvent`); returns
+   * its event id.
+   */
+  sendEvent(roomId: string, content: string, txnId: string): Promise<string>;
   /** Keeps the (un-awaited) send alive past the request that started it: `ctx.waitUntil`. */
   keepAlive(work: Promise<unknown>): void;
   log(message: string): void;
@@ -63,6 +109,16 @@ export interface RoomMirrorDeps {
   retry?: Pick<RetryGatewayOptions, 'delaysMs' | 'sleep' | 'isTransient'>;
 }
 
+/** The relation that posts an event in the thread of `threadId` (with the reply fallback for clients without threads). */
+function threadRelation(threadId: string) {
+  return {
+    rel_type: 'm.thread',
+    event_id: threadId,
+    is_falling_back: true,
+    'm.in_reply_to': { event_id: threadId },
+  };
+}
+
 export function mirrorEventContent(send: MirrorSend) {
   return {
     msgtype: 'm.text',
@@ -70,12 +126,7 @@ export function mirrorEventContent(send: MirrorSend) {
     ...(send.formattedBody
       ? { format: 'org.matrix.custom.html', formatted_body: send.formattedBody }
       : {}),
-    'm.relates_to': {
-      rel_type: 'm.thread',
-      event_id: send.threadId,
-      is_falling_back: true,
-      'm.in_reply_to': { event_id: send.threadId },
-    },
+    'm.relates_to': threadRelation(send.threadId),
     ...(send.origin
       ? {
           'org.ixo.qi.origin': channelOrigin(send.origin),
@@ -87,6 +138,19 @@ export function mirrorEventContent(send: MirrorSend) {
   };
 }
 
+/**
+ * A file event in the session thread: the media part, the thread relation
+ * of the text mirrors and their `org.ixo.qi.origin` (never the quote, which
+ * the text mirror of the same message carries).
+ */
+export function mediaEventContent(send: MediaMirrorSend) {
+  return {
+    ...send.media,
+    'm.relates_to': threadRelation(send.threadId),
+    ...(send.origin ? { 'org.ixo.qi.origin': channelOrigin(send.origin) } : {}),
+  };
+}
+
 const errorText = (err: unknown): string =>
   err instanceof Error ? err.message : String(err);
 
@@ -115,38 +179,98 @@ export class RoomMirror {
     label: string,
     required = false,
   ): Promise<void> {
-    const previous = this.chains.get(sessionId) ?? Promise.resolve();
-    // Starts once the previous mirror settled either way: a required mirror
-    // that failed (and rejected its own caller) must not skip this one.
-    const tracked: Promise<void> = previous
-      .catch(() => undefined)
-      .then(() => prepare())
-      .then((send) => (send ? this.send(send, label) : undefined))
-      .catch((err: unknown) => {
+    return this.chain(sessionId, async () => {
+      try {
+        const send = await prepare();
+        if (send)
+          await this.send(() => this.deps.sendText(send), send.threadId, label);
+      } catch (err) {
         if (required) throw err;
         this.deps.warn(
           `[user-do] Matrix replay (${label}) failed — session=${sessionId}: ${errorText(err)}`,
         );
-      })
+      }
+    });
+  }
+
+  /**
+   * Queue one file event behind the session's previous mirrors. When its
+   * turn in the chain comes, `prepare` builds the event (it waits for the
+   * file's upload; `null` = nothing to post) and the send follows with the
+   * transient retries; resolves with the event id, or null when nothing was
+   * posted. `signal` is honoured throughout: checked before `prepare` and
+   * before every send attempt, and it ends the wait on `prepare` — once it
+   * aborts no further attempt is made and the call rejects with its reason.
+   * A send that fails after the retries rejects.
+   */
+  sendMedia(
+    sessionId: string,
+    prepare: () => Promise<MediaMirrorSend | null>,
+    label: string,
+    signal?: AbortSignal,
+  ): Promise<string | null> {
+    return this.chain(sessionId, async () => {
+      if (signal?.aborted) throw abortError(signal);
+      const send = await (signal ? untilAborted(prepare(), signal) : prepare());
+      if (!send) return null;
+      const content = JSON.stringify(mediaEventContent(send));
+      return this.send(
+        () => {
+          if (signal?.aborted) return Promise.reject(abortError(signal));
+          return this.deps.sendEvent(send.roomId, content, send.txnId);
+        },
+        send.threadId,
+        label,
+        signal,
+      );
+    });
+  }
+
+  /**
+   * Run `work` once the session's previous mirrors have settled either way
+   * (a required mirror that failed, and rejected its own caller, must not
+   * skip the next one), keep it alive past the request, and drop the chain
+   * once it drains.
+   */
+  private chain<T>(sessionId: string, work: () => Promise<T>): Promise<T> {
+    const previous = this.chains.get(sessionId) ?? Promise.resolve();
+    // Settles (as `work` did) once the chain entry is gone, so a caller that
+    // awaited it sees the session's chain drained.
+    const done = previous
+      .catch(() => undefined)
+      .then(work)
       .finally(() => {
         if (this.chains.get(sessionId) === tracked)
           this.chains.delete(sessionId);
       });
+    const tracked: Promise<void> = done.then(
+      () => undefined,
+      () => undefined,
+    );
     this.chains.set(sessionId, tracked);
     this.deps.keepAlive(tracked);
-    return tracked;
+    return done;
   }
 
-  private async send(send: MirrorSend, label: string): Promise<void> {
-    const eventId = await retryGateway(() => this.deps.sendText(send), {
+  private async send(
+    post: () => Promise<string>,
+    threadId: string,
+    label: string,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    const isTransient = this.deps.retry?.isTransient ?? isTransientGatewayError;
+    const eventId = await retryGateway(post, {
       ...this.deps.retry,
+      // An abort is final: the transient check would otherwise retry it.
+      isTransient: (err) => !signal?.aborted && isTransient(err),
       onRetry: (err, attempt, delayMs) =>
         this.deps.warn(
           `[user-do] Matrix replay (${label}) send failed (attempt ${attempt}) — retrying in ${delayMs} ms with the same transaction id: ${errorText(err)}`,
         ),
     });
     this.deps.log(
-      `[user-do] Matrix replay (${label}) → ${eventId} in thread ${send.threadId}`,
+      `[user-do] Matrix replay (${label}) → ${eventId} in thread ${threadId}`,
     );
+    return eventId;
   }
 }

package/src/do/transcript.ts

@@ -111,7 +111,7 @@ export function contentToText(content: BaseMessage['content']): string {
         if (typeof part === 'string') return part;
         if (part && typeof part === 'object' && 'text' in part) {
           const text = (part as { text?: unknown }).text;
-          // The retention placeholder is model-facing only; the transcript
+          // The attachment placeholder is model-facing only; the transcript
           // keeps listing the attachment from its metadata.
           return typeof text === 'string' && !isAttachmentPlaceholderText(text)
             ? text

package/src/do/turn-attachments.ts

@@ -15,6 +15,7 @@ import {
   type ChannelMediaSource,
   type PreparedAttachments,
 } from '../attachments';
+import type { ChannelThreadFile } from '../attachments/room-media';
 import { parseChannelServiceDids } from '../channels/auth';
 import {
   channelAttachmentInputs,
@@ -58,26 +59,64 @@ export function channelTurnLinks(
   }));
 }
 
+/**
+ * A channel turn's files as `room-media.ts` posts them to the session
+ * thread: the first occurrence of each file (a file sent twice in one
+ * message is posted once), with its position in the message.
+ */
+export function channelThreadFiles(req: TurnFiles): ChannelThreadFile[] {
+  if (req.client !== 'channel' || !req.channel?.attachments?.length) return [];
+  const bindingId = req.channel.bindingId;
+  const seen = new Set<string>();
+  const files: ChannelThreadFile[] = [];
+  req.channel.attachments.forEach((file, index) => {
+    const ref = channelAttachmentRef(file.sha256);
+    if (seen.has(ref)) return;
+    seen.add(ref);
+    files.push({
+      ref,
+      index,
+      link: { url: file.url, sha256: file.sha256, bindingId },
+      filename: file.filename,
+      mimetype: file.mimetype,
+      size: file.size,
+      kind: file.kind,
+    });
+  });
+  return files;
+}
+
+/** The https origins channel files are fetched from: the gateways of `CHANNEL_SERVICE_DID`. */
+export function channelGatewayOrigins(
+  channelServiceDid: string | undefined,
+): string[] {
+  return channelMediaOrigins(parseChannelServiceDids(channelServiceDid));
+}
+
 /**
  * The channel source of a turn in `sessionId`: a reference resolves to the
  * turn's own files first, then to the links kept for the session; only the
- * gateways of `CHANNEL_SERVICE_DID` are fetched from.
+ * gateways of `CHANNEL_SERVICE_DID` are fetched from. The store also names
+ * the room copy of a file posted to the session thread, which serves it
+ * when its link fails or has expired (`loadAttachmentBytes`).
  */
 export function turnChannelMediaSource(input: {
   sessionId: string;
   turnLinks: ReadonlyArray<ChannelMediaLink & { ref: string }>;
-  store: Pick<ChannelAttachmentLinkStore, 'get'> | null;
+  store: Pick<ChannelAttachmentLinkStore, 'get' | 'eventIdOf'> | null;
   channelServiceDid: string | undefined;
 }): ChannelMediaSource {
+  const store = input.store;
   return createChannelMediaSource({
-    origins: channelMediaOrigins(
-      parseChannelServiceDids(input.channelServiceDid),
-    ),
+    origins: channelGatewayOrigins(input.channelServiceDid),
     resolve: async (ref) => {
       const own = input.turnLinks.find((link) => link.ref === ref);
       if (own) return own;
-      return input.store?.get(input.sessionId, ref);
+      return store?.get(input.sessionId, ref);
     },
+    ...(store
+      ? { roomEventOf: (ref: string) => store.eventIdOf(input.sessionId, ref) }
+      : {}),
   });
 }