unikvs 0.0.12 → 0.0.13

package/src/_pipeline-graph.types.ts

@@ -0,0 +1,303 @@
+import type { IReadableStream } from "@unikvs/core";
+
+import type { VariablesStore } from "./_contexts.js";
+import type UniKvsMiddleware from "./_middleware.js";
+import type UniKvsStorage from "./_storage.js";
+
+/**
+ * パイプラインの葉となる宛先です。
+ */
+export type PipelineLeaf = {
+  /**
+   * データの永続化先です。
+   */
+  readonly storage: UniKvsStorage;
+
+  /**
+   * 宛先の登録順 (0 起点) です。
+   */
+  readonly index: number;
+
+  /**
+   * ストレージ名のキャッシュです。
+   */
+  readonly name: string;
+
+  /**
+   * 経路上に `AllowRepair` が存在するかどうかです。
+   */
+  readonly canRepair: boolean;
+
+  /**
+   * 葉 1 件分の凍結された名前空間です。
+   */
+  readonly nameNames: readonly string[];
+
+  /**
+   * 根直下から葉の直前までのノード列です。
+   * グラフ自身の走査と内部単体テスト専用です。
+   *
+   * @internal
+   */
+  readonly path: readonly PipelineNode[];
+};
+
+/**
+ * パイプラインの節となるミドルウェアです。
+ */
+export type PipelineNode = {
+  /**
+   * 節を構成するミドルウェアです。
+   */
+  readonly middleware: UniKvsMiddleware;
+
+  /**
+   * この節で終端する葉です。
+   * 登録順に保持します。
+   */
+  readonly leaves: readonly PipelineLeaf[];
+
+  /**
+   * 子の節です。
+   * 登録順に保持します。
+   */
+  readonly children: readonly PipelineNode[];
+
+  /**
+   * 直下の葉と節を登録順に列挙した静的な項目列です。
+   */
+  readonly entries: readonly PipelineEntry[];
+
+  /**
+   * 部分木の全葉です。
+   * 登録順に保持します。
+   */
+  readonly allLeaves: readonly PipelineLeaf[];
+
+  /**
+   * 部分木の全葉名です。
+   * 凍結されています。
+   */
+  readonly leafNames: readonly string[];
+};
+
+/**
+ * 節または葉を登録順に列挙するための項目です。
+ */
+export type PipelineEntry =
+  | {
+      /**
+       * 葉であることを示します。
+       */
+      readonly kind: "leaf";
+
+      /**
+       * 対象の葉です。
+       */
+      readonly leaf: PipelineLeaf;
+    }
+  | {
+      /**
+       * 節であることを示します。
+       */
+      readonly kind: "node";
+
+      /**
+       * 対象の節です。
+       */
+      readonly node: PipelineNode;
+    };
+
+/**
+ * コンパイル前の宛先定義です。
+ */
+export type PipelineDestination = {
+  /**
+   * データの永続化先です。
+   */
+  readonly storage: UniKvsStorage;
+
+  /**
+   * 適用順のミドルウェア列です。末尾未使用分は含みません。
+   */
+  readonly middlewares: readonly UniKvsMiddleware[];
+};
+
+/**
+ * 葉へ書き込むためのエンコード結果です。
+ */
+export type EncodeTarget = {
+  /**
+   * 対象の葉です。
+   */
+  readonly leaf: PipelineLeaf;
+
+  /**
+   * エンコード済みのデータです。
+   */
+  readonly data: unknown;
+
+  /**
+   * 写像済みのキーです。
+   */
+  readonly key: string;
+};
+
+/**
+ * 解決済みの葉です。
+ */
+export type ResolvedLeaf = {
+  /**
+   * 対象の葉です。
+   */
+  readonly leaf: PipelineLeaf;
+
+  /**
+   * 写像済みのキーです。
+   */
+  readonly key: string;
+};
+
+/**
+ * ストリームのエンコード先となる葉です。
+ */
+export type StreamEncodeTarget = {
+  /**
+   * 対象の葉です。
+   */
+  readonly leaf: PipelineLeaf;
+
+  /**
+   * 葉へ書き込むストリームです。
+   */
+  readonly stream: IReadableStream;
+
+  /**
+   * 写像済みのキーです。
+   */
+  readonly key: string;
+};
+
+/**
+ * 構築済みのストリームエンコード木です。
+ */
+export type StreamEncodeTree = {
+  /**
+   * 登録順の書き込み対象です。
+   */
+  readonly targets: StreamEncodeTarget[];
+
+  /**
+   * 読み取り側へ渡すストリームです。`splitRead` を指定したときだけ分岐後の読み取り側になります。
+   */
+  readonly readStream: IReadableStream;
+};
+
+/**
+ * 書き込み対象とする葉を判定する関数です。
+ */
+export interface IActiveLeafChecker {
+  /**
+   * 書き込み対象とする葉を判定します。
+   *
+   * @param leaf 対象の葉です。
+   *
+   * @returns 判定結果です。
+   */
+  (leaf: PipelineLeaf): boolean;
+}
+
+/**
+ * 節の `encodeStream` または `mapKey` が失敗したときの処理を行う関数です。
+ */
+export interface IEncodeNodeErrorHandler {
+  /**
+   * 節のセットアップ失敗時の処理です。
+   *
+   * `true` を返すと節の部分木をスキップします。
+   * 例外を投げた場合はそのまま伝播します。
+   *
+   * @param ex 節の取得または写像で発生した例外です。
+   * @param activeLeaves 節の配下で対象となる葉です。
+   *
+   * @returns 部分木をスキップする場合は `true` を返します。
+   */
+  (ex: unknown, activeLeaves: readonly PipelineLeaf[]): boolean;
+}
+
+/**
+ * ストリームエンコード木の構築オプションです。
+ */
+export type BuildEncodeTreeOptions = {
+  /**
+   * 書き込み対象とする葉を判定します。省略時は全葉が対象です。
+   */
+  readonly isActive?: IActiveLeafChecker | undefined;
+
+  /**
+   * 読み取り側と書き込み側を分岐するかどうかです。書き戻しで使用します。
+   */
+  readonly splitRead?: boolean | undefined;
+
+  /**
+   * 節のセットアップ失敗を分類します。省略時は生の例外として伝播します。
+   */
+  readonly onNodeError?: IEncodeNodeErrorHandler | undefined;
+};
+
+/**
+ * 操作共通の実行時情報です。
+ *
+ * `store` は操作内の全コンテキストで共有され、下流の `set` が上流の `get` に見えます。
+ */
+export type OperationScope = {
+  /**
+   * 操作対象の論理キーです。
+   */
+  readonly key: string;
+
+  /**
+   * 中断シグナルです。
+   */
+  readonly signal: AbortSignal;
+
+  /**
+   * 操作内で共有される変数ストアです。
+   */
+  readonly store: VariablesStore;
+};
+
+/**
+ * コンパイル中の節です。フィールドは finalize で確定します。
+ */
+export type MutableNode = {
+  /**
+   * 節を構成するミドルウェアです。
+   */
+  readonly middleware: UniKvsMiddleware;
+
+  /**
+   * この節で終端する葉です。登録順に保持します。
+   */
+  readonly leaves: PipelineLeaf[];
+
+  /**
+   * 子の節です。登録順に保持します。
+   */
+  readonly children: MutableNode[];
+
+  /**
+   * 直下の葉と節を登録順に列挙した項目列です。finalize で確定します。
+   */
+  entries: readonly PipelineEntry[];
+
+  /**
+   * 部分木の全葉です。登録順に保持します。finalize で確定します。
+   */
+  allLeaves: readonly PipelineLeaf[];
+
+  /**
+   * 部分木の全葉名です。finalize で確定します。
+   */
+  leafNames: readonly string[];
+};

package/src/_pipeline-leaf-resolver.ts

@@ -0,0 +1,70 @@
+import { applyMapKey } from "./_pipeline-graph.helpers.js";
+import type {
+  PipelineLeaf,
+  PipelineNode,
+  ResolvedLeaf,
+  OperationScope,
+} from "./_pipeline-graph.types.js";
+
+/**
+ * 単一操作のスコープで葉の写像キーを解決します。
+ *
+ * 新 `mapKey` は同期的であり、中断シグナルも受け付けないため、共有節の写像は操作内で 1 回だけ実行され、結果を使い回します。
+ * 並行解決でも `Map` キャッシュにより重複しません (`resolve` 自体が同期的であるため、競合しません)。
+ */
+export class LeafResolver {
+  /**
+   * 根のキーです。
+   */
+  readonly #rootKey: string;
+
+  /**
+   * 操作共通の実行時情報です (共有ストアを含みます)。
+   */
+  readonly #scope: OperationScope;
+
+  /**
+   * 節ごとの解決結果のキャッシュです。
+   */
+  readonly #nodeCache: Map<PipelineNode, string>;
+
+  /**
+   * 通常は `PipelineGraph.createResolver` から生成します。
+   *
+   * @param scope 操作共通の実行時情報です。
+   */
+  public constructor(scope: OperationScope) {
+    this.#rootKey = scope.key;
+    this.#scope = scope;
+    this.#nodeCache = new Map();
+  }
+
+  /**
+   * 葉の写像キーを解決します。
+   *
+   * @param leaf 解決する葉です。
+   *
+   * @returns 解決済みの葉を返します。
+   */
+  public resolve(leaf: PipelineLeaf): ResolvedLeaf {
+    let key = this.#rootKey;
+
+    for (const node of leaf.path) {
+      const cached = this.#nodeCache.get(node);
+
+      if (cached !== undefined) {
+        key = cached;
+        continue;
+      }
+
+      const mapped = applyMapKey(node.middleware, key, this.#scope);
+      this.#nodeCache.set(node, mapped);
+      key = mapped;
+    }
+
+    return {
+      key,
+      leaf,
+    };
+  }
+}

package/src/_plugin-lifecycle.ts

@@ -0,0 +1,201 @@
+import type { MaybePromise } from "maypromise";
+
+/**
+ * 参照カウントで管理するプラグインの操作対象です。
+ *
+ * @template TOpenContext オープンコンテキストの型です。
+ * @template TCloseContext クローズコンテキストの型です。
+ */
+interface IPlugin<TOpenContext, TCloseContext> {
+  /**
+   * プラグインが開かれているかどうかです。
+   */
+  get isOpen(): boolean;
+
+  /**
+   * プラグインを開く関数です。未定義のときは `open` を持たないものとして扱います。
+   */
+  open?(c: TOpenContext): MaybePromise<void>;
+
+  /**
+   * プラグインを閉じる関数です。未定義のときは `close` を持たないものとして扱います。
+   */
+  close?(c: TCloseContext): MaybePromise<void>;
+}
+
+/**
+ * 共有プラグインの参照カウントと実 `close` の再試行を管理します。
+ *
+ * 同じプラグインを共有する利用者のうち、最初の `open` だけが実際に開き、最後の `close` だけが実際に閉じます。
+ * 実 `close` に失敗したときは所有権を残し、次の `close` で再試行できるようにします。
+ *
+ * @template TOpenContext オープンコンテキストの型です。
+ * @template TCloseContext クローズコンテキストの型です。
+ */
+export class PluginLifecycle<TOpenContext, TCloseContext> {
+  /**
+   * 参照カウントの対象です。
+   */
+  readonly #plugin: IPlugin<TOpenContext, TCloseContext>;
+
+  /**
+   * `open` した利用者の数です。最初の `open` だけが実際に開き、最後の `close` だけが実際に閉じます。
+   * `close` を持たないプラグインは閉じられないため数えません。
+   */
+  #references: number;
+
+  /**
+   * 実 `close` に失敗したまま利用者の数が 0 になったかどうかです。
+   *
+   * このフラグが立っている間は、外部で開かれたプラグインではなく、閉じきれていない所有権が残っています。
+   * 次の `open` が所有権を引き継ぎ、次の `close` が実 `close` を再試行します。
+   */
+  #closeFailed: boolean;
+
+  public constructor(plugin: IPlugin<TOpenContext, TCloseContext>) {
+    this.#plugin = plugin;
+    this.#references = 0;
+    this.#closeFailed = false;
+  }
+
+  /**
+   * プラグインを開きます。
+   *
+   * 同じプラグインを共有する利用者のうち、最初の 1 回だけ実際の `open` を呼びます。
+   * この管理対象外で既に開かれているプラグインは open/close の対象外にします。
+   * 参照が残っていても実体が閉じられているときは、既存の参照を失わずに実 open へフォールバックします。
+   * `close` を持たないプラグインは閉じられないため、参照を数えません。
+   *
+   * @param c オープンコンテキストです。
+   */
+  public async open(c: TOpenContext): Promise<void> {
+    if (this.#plugin.open === undefined) {
+      return;
+    }
+
+    // `close` を持たないプラグインは開いたままにしかできないため、参照を数えず、未 open のときだけ実 open します。
+    if (this.#plugin.close === undefined) {
+      if (this.#plugin.isOpen) {
+        return;
+      }
+
+      await this.#plugin.open(c);
+
+      return;
+    }
+
+    // この管理対象外の外部 open は対象外です。
+    // 直前の close に失敗した所有権 (#closeFailed) がある間は、外部 open とみなしません。
+    if (this.#plugin.isOpen && this.#references === 0 && !this.#closeFailed) {
+      return;
+    }
+
+    if (this.#references > 0 || this.#closeFailed) {
+      if (this.#plugin.isOpen) {
+        // 既存の参照を失わずに加算します。close 失敗分の所有権もここで引き継ぎます。
+        this.#references += 1;
+        this.#closeFailed = false;
+
+        return;
+      }
+
+      // 参照があるのに実体が閉じられているときは、実 open にフォールバックし、既存の参照を失わずに加算します。
+      await this.#plugin.open(c);
+      this.#references += 1;
+      this.#closeFailed = false;
+
+      return;
+    }
+
+    await this.#plugin.open(c);
+    this.#references += 1;
+  }
+
+  /**
+   * プラグインを閉じます。
+   *
+   * 同じプラグインを共有する利用者のうち、最後の 1 回だけ実際の `close` を呼びます。
+   * 各呼び出しで参照を 1 つ減らし、実 `close` は全参照が解放されたときにだけ呼びます。
+   * 実 `close` に失敗したときは所有権を残し、次の `close` で再試行できるようにします。
+   * `close` を持たないプラグインは open で参照を数えないため、ここでは何もしません。
+   * 実 `close` へ渡すコンテキストは最後に閉じる利用者のものであり、最初に開いた利用者の vars/signal は保持しません。
+   *
+   * @param c クローズコンテキストです。
+   */
+  public async close(c: TCloseContext): Promise<void> {
+    if (this.#plugin.close === undefined) {
+      return;
+    }
+
+    if (this.#references === 0 && !this.#closeFailed) {
+      // この管理対象外のプラグインは閉じません。
+      return;
+    }
+
+    if (this.#references > 0) {
+      this.#references -= 1;
+    }
+
+    if (this.#references > 0) {
+      // まだ利用者が残っているため、実体は閉じません。
+      return;
+    }
+
+    if (!this.#plugin.isOpen) {
+      // 既に外部で閉じられているため、未解放の所有権を解消します。
+      this.#closeFailed = false;
+
+      return;
+    }
+
+    await this.#closeReal(c);
+  }
+
+  /**
+   * 失敗した実 `close` だけを再試行します。
+   *
+   * 通常の `close` と違い参照を減らしません。close 失敗後に新しい `open` が所有権を引き継いでいる場合は何もしません。
+   * 実体が既に閉じられているときは失敗状態だけを解消します。
+   *
+   * @param c クローズコンテキストです。
+   */
+  public async retryClose(c: TCloseContext): Promise<void> {
+    if (this.#plugin.close === undefined) {
+      return;
+    }
+
+    // 新しい open が所有権を引き継いでいる場合は、その参照を解放しないよう何もしません。
+    if (!this.#closeFailed || this.#references > 0) {
+      return;
+    }
+
+    if (!this.#plugin.isOpen) {
+      // 既に外部で閉じられているため、未解放の所有権を解消します。
+      this.#closeFailed = false;
+
+      return;
+    }
+
+    await this.#closeReal(c);
+  }
+
+  /**
+   * 実 `close` を実行し、失敗したかどうかを記録します。
+   *
+   * @param c クローズコンテキストです。
+   */
+  async #closeReal(c: TCloseContext): Promise<void> {
+    if (this.#plugin.close === undefined) {
+      return;
+    }
+
+    try {
+      await this.#plugin.close(c);
+      this.#closeFailed = false;
+    } catch (ex) {
+      // 閉じるのに失敗したときは未解放として記録し、次の close で再試行できるようにします。
+      this.#closeFailed = true;
+      throw ex;
+    }
+  }
+}