agl 1.0.17 → 21.0.2

package/ts_web/classes.sessiondraftsync.ts

@@ -0,0 +1,390 @@
+import type {
+  IControllerDraftAttachment,
+  IControllerRuntimeId,
+  IControllerSessionDraft,
+  IControllerSessionDraftUpdate,
+} from '../ts_interfaces/interfaces.js';
+
+const defaultDebounceMs = 150;
+const maximumConflictRetries = 4;
+
+export interface ISessionDraftSyncTransport {
+  getDraft(
+    projectIdArg: string,
+    sessionIdArg: IControllerRuntimeId,
+  ): Promise<IControllerSessionDraft>;
+  updateDraft(
+    projectIdArg: string,
+    sessionIdArg: IControllerRuntimeId,
+    expectedRevisionArg: number,
+    patchArg: { text?: string; attachments?: IControllerDraftAttachment[] },
+  ): Promise<IControllerSessionDraft>;
+  isConflict(errorArg: unknown): boolean;
+}
+
+export interface ISessionDraftSyncState extends IControllerSessionDraft {
+  projectId: string;
+  sessionId: IControllerRuntimeId;
+  loading: boolean;
+  saving: boolean;
+  error: string;
+}
+
+export interface ISessionDraftSyncOptions {
+  transport: ISessionDraftSyncTransport;
+  onState: (stateArg: ISessionDraftSyncState | undefined) => void;
+  onError?: (errorArg: unknown) => void;
+  debounceMs?: number;
+}
+
+interface IActiveDraft {
+  projectId: string;
+  sessionId: IControllerRuntimeId;
+  generation: number;
+  authoritative: IControllerSessionDraft;
+  desiredText: string;
+  desiredAttachments: IControllerDraftAttachment[];
+  dirtyText: boolean;
+  dirtyAttachments: boolean;
+  drainAfterDeactivate: boolean;
+  loading: boolean;
+  saving: boolean;
+  error: string;
+  debounceTimer?: ReturnType<typeof setTimeout>;
+  hydrateTask?: Promise<void>;
+  writeTask?: Promise<IControllerSessionDraft>;
+}
+
+const cloneAttachments = (
+  attachmentsArg: readonly IControllerDraftAttachment[],
+): IControllerDraftAttachment[] => attachmentsArg.map((attachment) => ({ ...attachment }));
+
+const cloneDraft = (draftArg: IControllerSessionDraft): IControllerSessionDraft => ({
+  text: draftArg.text,
+  attachments: cloneAttachments(draftArg.attachments),
+  revision: draftArg.revision,
+});
+
+const attachmentsEqual = (
+  leftArg: readonly IControllerDraftAttachment[],
+  rightArg: readonly IControllerDraftAttachment[],
+): boolean => leftArg.length === rightArg.length && leftArg.every((left, index) => {
+  const right = rightArg[index];
+  return right !== undefined
+    && left.id === right.id
+    && left.name === right.name
+    && left.mediaType === right.mediaType
+    && left.size === right.size
+    && left.kind === right.kind
+    && left.dataBase64 === right.dataBase64;
+});
+
+const runtimeIdsEqual = (leftArg: IControllerRuntimeId, rightArg: IControllerRuntimeId): boolean => (
+  leftArg.harnessId === rightArg.harnessId && leftArg.nativeId === rightArg.nativeId
+);
+
+export class SessionDraftSync {
+  private readonly debounceMs: number;
+  private generation = 0;
+  private active?: IActiveDraft;
+  private disposed = false;
+
+  constructor(private readonly options: ISessionDraftSyncOptions) {
+    this.debounceMs = options.debounceMs ?? defaultDebounceMs;
+  }
+
+  public get state(): ISessionDraftSyncState | undefined {
+    return this.active ? this.publicState(this.active) : undefined;
+  }
+
+  public async activate(
+    projectIdArg: string,
+    sessionIdArg: IControllerRuntimeId,
+  ): Promise<ISessionDraftSyncState | undefined> {
+    if (this.disposed) return undefined;
+    this.deactivate();
+    const generation = ++this.generation;
+    const active: IActiveDraft = {
+      projectId: projectIdArg,
+      sessionId: { ...sessionIdArg },
+      generation,
+      authoritative: { text: '', attachments: [], revision: 0 },
+      desiredText: '',
+      desiredAttachments: [],
+      dirtyText: false,
+      dirtyAttachments: false,
+      drainAfterDeactivate: false,
+      loading: true,
+      saving: false,
+      error: '',
+    };
+    this.active = active;
+    this.emit(active);
+    await this.hydrate(active);
+    return this.isCurrent(active) ? this.publicState(active) : undefined;
+  }
+
+  public deactivate(): void {
+    const active = this.active;
+    if (active?.debounceTimer) clearTimeout(active.debounceTimer);
+    if (
+      active
+      && !active.loading
+      && (active.dirtyText || active.dirtyAttachments)
+    ) {
+      active.drainAfterDeactivate = true;
+      if (!active.writeTask) {
+        const writeTask = this.flushActive(active);
+        active.writeTask = writeTask;
+        void writeTask
+          .catch((errorArg) => this.options.onError?.(errorArg))
+          .finally(() => {
+            if (active.writeTask === writeTask) active.writeTask = undefined;
+          });
+      }
+    }
+    this.generation += 1;
+    this.active = undefined;
+    this.options.onState(undefined);
+  }
+
+  public setText(textArg: string): void {
+    const active = this.active;
+    if (!active || active.loading) return;
+    active.desiredText = textArg;
+    active.dirtyText = active.desiredText !== active.authoritative.text;
+    active.error = '';
+    this.emit(active);
+    this.schedule(active);
+  }
+
+  public setAttachments(attachmentsArg: readonly IControllerDraftAttachment[]): void {
+    const active = this.active;
+    if (!active || active.loading) return;
+    active.desiredAttachments = cloneAttachments(attachmentsArg);
+    active.dirtyAttachments = !attachmentsEqual(
+      active.desiredAttachments,
+      active.authoritative.attachments,
+    );
+    active.error = '';
+    this.emit(active);
+    this.schedule(active);
+  }
+
+  public async flush(): Promise<IControllerSessionDraft> {
+    const active = this.active;
+    if (!active) throw new Error('No session draft is active.');
+    if (active.debounceTimer) {
+      clearTimeout(active.debounceTimer);
+      active.debounceTimer = undefined;
+    }
+    if (active.loading) await this.hydrate(active);
+    if (!this.isCurrent(active)) throw new Error('The session draft changed during synchronization.');
+    if (active.writeTask) return active.writeTask;
+    const writeTask = this.flushActive(active);
+    active.writeTask = writeTask;
+    try {
+      return await writeTask;
+    } finally {
+      if (active.writeTask === writeTask) active.writeTask = undefined;
+    }
+  }
+
+  public async refresh(): Promise<ISessionDraftSyncState | undefined> {
+    const active = this.active;
+    if (!active) return undefined;
+    await this.hydrate(active);
+    return this.isCurrent(active) ? this.publicState(active) : undefined;
+  }
+
+  public applyRemoteUpdate(
+    projectIdArg: string,
+    sessionIdArg: IControllerRuntimeId,
+    updateArg: IControllerSessionDraftUpdate,
+  ): boolean {
+    const active = this.active;
+    if (
+      !active
+      || active.projectId !== projectIdArg
+      || !runtimeIdsEqual(active.sessionId, sessionIdArg)
+      || updateArg.revision <= active.authoritative.revision
+    ) return false;
+    if (updateArg.revision !== active.authoritative.revision + 1) {
+      void this.hydrate(active).catch((errorArg) => this.options.onError?.(errorArg));
+      return true;
+    }
+    active.authoritative = {
+      text: updateArg.text ?? active.authoritative.text,
+      attachments: updateArg.attachments === undefined
+        ? active.authoritative.attachments
+        : cloneAttachments(updateArg.attachments),
+      revision: updateArg.revision,
+    };
+    if (!active.dirtyText && updateArg.text !== undefined) active.desiredText = updateArg.text;
+    if (!active.dirtyAttachments && updateArg.attachments !== undefined) {
+      active.desiredAttachments = cloneAttachments(updateArg.attachments);
+    }
+    active.dirtyText = active.desiredText !== active.authoritative.text;
+    active.dirtyAttachments = !attachmentsEqual(
+      active.desiredAttachments,
+      active.authoritative.attachments,
+    );
+    this.emit(active);
+    if (active.dirtyText || active.dirtyAttachments) this.schedule(active);
+    return true;
+  }
+
+  public dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.deactivate();
+  }
+
+  private async hydrate(activeArg: IActiveDraft): Promise<void> {
+    if (activeArg.hydrateTask) return activeArg.hydrateTask;
+    let hydrateTask!: Promise<void>;
+    hydrateTask = (async () => {
+      activeArg.loading = true;
+      this.emit(activeArg);
+      try {
+        const draft = await this.options.transport.getDraft(activeArg.projectId, activeArg.sessionId);
+        if (!this.canSynchronize(activeArg)) return;
+        activeArg.authoritative = cloneDraft(draft);
+        if (!activeArg.dirtyText) activeArg.desiredText = draft.text;
+        if (!activeArg.dirtyAttachments) {
+          activeArg.desiredAttachments = cloneAttachments(draft.attachments);
+        }
+        activeArg.dirtyText = activeArg.desiredText !== draft.text;
+        activeArg.dirtyAttachments = !attachmentsEqual(
+          activeArg.desiredAttachments,
+          draft.attachments,
+        );
+        activeArg.error = '';
+      } catch (errorArg) {
+        if (this.isCurrent(activeArg)) activeArg.error = this.errorMessage(errorArg);
+        throw errorArg;
+      } finally {
+        activeArg.loading = false;
+        this.emit(activeArg);
+      }
+    })();
+    activeArg.hydrateTask = hydrateTask;
+    try {
+      await hydrateTask;
+    } finally {
+      if (activeArg.hydrateTask === hydrateTask) activeArg.hydrateTask = undefined;
+    }
+  }
+
+  private async flushActive(activeArg: IActiveDraft): Promise<IControllerSessionDraft> {
+    activeArg.saving = true;
+    this.emit(activeArg);
+    let conflictAttempts = 0;
+    try {
+      while (
+        this.canSynchronize(activeArg)
+        && (activeArg.dirtyText || activeArg.dirtyAttachments)
+      ) {
+        const sentText = activeArg.desiredText;
+        const sentAttachments = cloneAttachments(activeArg.desiredAttachments);
+        const sentTextField = activeArg.dirtyText;
+        const sentAttachmentField = activeArg.dirtyAttachments;
+        const expectedRevision = activeArg.authoritative.revision;
+        let response: IControllerSessionDraft;
+        try {
+          response = await this.options.transport.updateDraft(
+            activeArg.projectId,
+            activeArg.sessionId,
+            expectedRevision,
+            {
+              ...(sentTextField ? { text: sentText } : {}),
+              ...(sentAttachmentField ? { attachments: sentAttachments } : {}),
+            },
+          );
+        } catch (errorArg) {
+          if (
+            this.options.transport.isConflict(errorArg)
+            && conflictAttempts < maximumConflictRetries
+          ) {
+            conflictAttempts += 1;
+            await this.hydrate(activeArg);
+            continue;
+          }
+          throw errorArg;
+        }
+        if (!this.canSynchronize(activeArg)) break;
+        conflictAttempts = 0;
+        if (response.revision >= activeArg.authoritative.revision) {
+          activeArg.authoritative = cloneDraft(response);
+          if (sentTextField && activeArg.desiredText === sentText) activeArg.dirtyText = false;
+          if (
+            sentAttachmentField
+            && attachmentsEqual(activeArg.desiredAttachments, sentAttachments)
+          ) activeArg.dirtyAttachments = false;
+        }
+        activeArg.dirtyText = activeArg.desiredText !== activeArg.authoritative.text;
+        activeArg.dirtyAttachments = !attachmentsEqual(
+          activeArg.desiredAttachments,
+          activeArg.authoritative.attachments,
+        );
+        activeArg.error = '';
+        this.emit(activeArg);
+      }
+      return {
+        text: activeArg.desiredText,
+        attachments: cloneAttachments(activeArg.desiredAttachments),
+        revision: activeArg.authoritative.revision,
+      };
+    } catch (errorArg) {
+      if (this.isCurrent(activeArg)) {
+        activeArg.error = this.errorMessage(errorArg);
+        this.emit(activeArg);
+      }
+      throw errorArg;
+    } finally {
+      activeArg.saving = false;
+      this.emit(activeArg);
+      activeArg.drainAfterDeactivate = false;
+    }
+  }
+
+  private schedule(activeArg: IActiveDraft): void {
+    if (!this.isCurrent(activeArg) || activeArg.loading) return;
+    if (activeArg.debounceTimer) clearTimeout(activeArg.debounceTimer);
+    activeArg.debounceTimer = setTimeout(() => {
+      activeArg.debounceTimer = undefined;
+      void this.flush().catch((errorArg) => this.options.onError?.(errorArg));
+    }, this.debounceMs);
+  }
+
+  private isCurrent(activeArg: IActiveDraft): boolean {
+    return !this.disposed
+      && this.active === activeArg
+      && this.generation === activeArg.generation;
+  }
+
+  private canSynchronize(activeArg: IActiveDraft): boolean {
+    return this.isCurrent(activeArg) || activeArg.drainAfterDeactivate;
+  }
+
+  private emit(activeArg: IActiveDraft): void {
+    if (this.isCurrent(activeArg)) this.options.onState(this.publicState(activeArg));
+  }
+
+  private publicState(activeArg: IActiveDraft): ISessionDraftSyncState {
+    return {
+      projectId: activeArg.projectId,
+      sessionId: { ...activeArg.sessionId },
+      text: activeArg.desiredText,
+      attachments: cloneAttachments(activeArg.desiredAttachments),
+      revision: activeArg.authoritative.revision,
+      loading: activeArg.loading,
+      saving: activeArg.saving,
+      error: activeArg.error,
+    };
+  }
+
+  private errorMessage(errorArg: unknown): string {
+    return errorArg instanceof Error ? errorArg.message : 'Draft synchronization failed.';
+  }
+}