unikvs 0.0.9 → 0.0.10

package/src/unikvs.ts

@@ -10,6 +10,7 @@ import UniKvsTransformer from "./_transformer.js";
 import * as v from "./_valibot.js";
 import type { ContextSource } from "./context.types.js";
 import {
+  type KeyNotFoundErrorArgs,
   KeyNotFoundError,
   UniKvsIsOpenError,
   PluginOperationAggregateError,
@@ -73,9 +74,11 @@ export type KeyofKeyValueMappingHasStreamValue<TKeyValueMapping extends KeyValue
 
 const ContextKeySchema = v.string();
 
+// 配列形式の context も正当な入力であるため、record スキーマより先に判定する必要があります。
+// record スキーマは配列にもマッチして数値キーのオブジェクトに変換してしまうため、配列形式を先に処理しないと mergeContext での配列としてのマージが行われません。
 const ContextSourceSchema = v.union([
-  v.record(v.any(), v.unknown()),
   v.array(v.tuple([ContextKeySchema, v.unknown()])),
+  v.record(v.any(), v.unknown()),
 ]);
 
 const OpenOptionsSchema = v.object({
@@ -347,12 +350,31 @@ export type ClearOptions = v.InferInput<typeof ClearOptionsSchema>;
 const ioLockRegistry =
   typeof FinalizationRegistry !== "function"
     ? null
-    : new FinalizationRegistry<AsyncmuxLock>((lock) => {
-        if (!lock.released) {
-          lock.release();
+    : new FinalizationRegistry<IoLockRegistryHeld>((held) => {
+        if (!held.lock.released) {
+          held.lock.release();
         }
+
+        // valueStream が読み取られないまま GC されたとき、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放するために破棄します。
+        // dispose は valueStream 自身を参照しないため、これを保持しても valueStream のガベージコレクションを妨げません。
+        // 失敗しても対処できないので無視します。
+        held.dispose().catch((ex) => {
+          logger.error`Failed to dispose value stream: ${ex}`;
+        });
       });
 
+type IoLockRegistryHeld = {
+  /**
+   * stream 操作で取得したキーの読み取りロックです。
+   */
+  readonly lock: AsyncmuxLock;
+
+  /**
+   * {@linkcode ValueStream.dispose} です。ソースストリームのキャンセルとロック解放を行います。
+   */
+  readonly dispose: () => Promise<void>;
+};
+
 /**
  * 接続状態を管理する内部オブジェクトです。
  */
@@ -542,9 +564,18 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
         }),
       );
       if (errors.length > 0) {
+        // 中断以外の失敗が混在しない場合は、abort 理由が集約エラーに埋もれないようにそのまま投げます。
+        if (signal.aborted && errors.every((error) => error.reason === signal.reason)) {
+          throw signal.reason;
+        }
+
         throw new PluginOperationAggregateError({ action: "open", errors });
       }
 
+      // すべてのプラグインのオープンが成功した後も、待機中に中断されていないか最終確認します。
+      // 中断済みのシグナルを持つ接続を作成すると、isOpen が true でありながら以降のすべての操作が即座に失敗する壊れた状態になります。
+      signal.throwIfAborted();
+
       this.#con = {
         ac,
         io: new Asyncmux(),
@@ -650,7 +681,8 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
         throw new UniKvsIsNotOpenError();
       }
 
-      const { ac } = this.#con;
+      const con = this.#con;
+      const { ac } = con;
       const acArr = [ac, ...this.#acSet];
       this.#acSet.clear();
       for (const ac of acArr) {
@@ -659,12 +691,38 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
         }
       }
 
-      return this.#close(context, signal, this.#con);
+      return this.#close(context, signal, con).catch(async (ex) => {
+        // #close が失敗した場合、コネクションの AbortController は既に abort 済みであり、以降の操作がすべて即座に失敗する壊れた状態になります。
+        // そこで接続を破棄して isOpen=false の一貫した状態にし、ベストエフォートでプラグインのクローズ処理を実行します。
+        if (this.#con === con) {
+          this.#con = null;
+
+          const disposeSignal = AbortSignal.timeout(10e3);
+          await Promise.all(
+            [...this.#destinations, ...this.#transformers].map(async (plugin) => {
+              try {
+                await plugin.close(context, disposeSignal);
+              } catch (reason) {
+                logger.error`Failed to close plugin after close failure: ${reason}`;
+              }
+            }),
+          );
+        }
+
+        throw ex;
+      });
     } catch (ex) {
       return Promise.reject(ex);
     }
   }
 
+  /**
+   * UniKvs が開いている場合にクローズします。
+   *
+   * `await using` 構文による自動クローズに使用されます。
+   *
+   * @returns 完了を通知する Promise です。
+   */
   async [Symbol.asyncDispose](): Promise<void> {
     if (!this.isOpen) {
       return;
@@ -728,25 +786,48 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
       if (value instanceof ReadableStream) {
         // 各トランスフォーマーを通してデータをエンコードストリームへ変換します。
         let data = value;
-        for (const transformer of this.#transformers) {
-          const e = await transformer.getEncodable(context, signal);
-          data = data.pipeThrough(e);
+        try {
+          for (const transformer of this.#transformers) {
+            const e = await transformer.getEncodable(context, signal);
+            data = data.pipeThrough(e);
+          }
+        } catch (ex) {
+          // チェーンの構築中に失敗した場合、パイプが保持するソースストリームのリソースを解放するためにキャンセルします。
+          // キャンセルしないとソースストリームはロックされたままリークします。
+          try {
+            await data.cancel(ex);
+          } catch {
+            // キャンセルに失敗しても元の例外の伝播を優先します。
+          }
+
+          throw ex;
         }
 
         const lock = await io.lock({ key, signal });
         try {
           await Promise.all(
             this.#destinations.map(async (storage, i) => {
+              // tee ブランチはキャンセルされるまで健康なブランチの読み取り分のチャンクを保持し続けるため、失敗時に放棄したブランチを確実にキャンセルできるよう参照を保持します。
+              let branch: ReadableStream | null = null;
               try {
                 // 複数のストレージがある場合は、tee メソッドを使用してストリームを分岐させます。
                 let r = data;
                 if (i !== this.#destinations.length - 1) {
                   [r, data] = data.tee();
                 }
+                branch = r;
 
                 const w = await storage.getWritable(context, signal, key);
                 await r.pipeTo(w, { signal });
               } catch (reason) {
+                if (branch !== null) {
+                  try {
+                    await branch.cancel(reason);
+                  } catch {
+                    // キャンセルに失敗してもエラー集約を優先します。
+                  }
+                }
+
                 errors.push({ reason });
                 errorStorageSet.add(storage);
               }
@@ -861,14 +942,25 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
 
       const NONE = {};
       let data: any = NONE;
+      const errors: { reason: unknown }[] = [];
 
       const lock = await io.rLock({ key, signal });
       try {
         // 各ストレージを巡回し、最初に見つかったデータを取得します。
+        // あるストレージの読み取りに失敗しても、他のストレージからデータを取得できるようにフォールバックします。
         for (const storage of this.#destinations) {
-          if (await storage.exists(context, signal, key)) {
+          try {
+            if (!(await storage.exists(context, signal, key))) {
+              continue;
+            }
             data = await storage.read(context, signal, key);
             break;
+          } catch (ex) {
+            if (signal.aborted) {
+              throw ex;
+            }
+            errors.push({ reason: ex });
+            logger.error`Failed to read from a storage: ${ex}`;
           }
         }
       } finally {
@@ -876,7 +968,22 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
       }
 
       if (data === NONE) {
-        throw new KeyNotFoundError({ key });
+        const args: KeyNotFoundErrorArgs = { key };
+        switch (errors.length) {
+          case 0:
+            break;
+          case 1:
+            args.cause = errors[0]!.reason;
+            break;
+          default:
+            args.cause = new PluginOperationAggregateError({
+              plugin: "storage",
+              action: "read",
+              errors,
+            });
+        }
+
+        throw new KeyNotFoundError(args);
       }
 
       // トランスフォーマーを逆順に適用してデータをデコードします。
@@ -931,7 +1038,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     context["unikvs:action"] = "stream";
     context["unikvs:key"] = key;
 
-    const lock = await asyncmux(this, signal);
+    const lock = await asyncmux.readonly(this, signal);
     try {
       // ロック待機中に接続状態が変更されていないか再確認します。
       if (this.#con === null) {
@@ -940,34 +1047,57 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
 
       const NONE: any = {};
       let r: IReadableStream = NONE;
+      const errors: { reason: unknown }[] = [];
 
       const lock = await io.rLock({ key, signal });
       try {
         // 各ストレージを巡回し、最初に見つかったデータを取得します。
+        // あるストレージの読み取りに失敗しても、他のストレージからデータを取得できるようにフォールバックします。
         for (const storage of this.#destinations) {
-          if (await storage.exists(context, signal, key)) {
+          try {
+            if (!(await storage.exists(context, signal, key))) {
+              continue;
+            }
+
             r = await storage.getReadable(context, signal, key);
             break;
+          } catch (ex) {
+            if (signal.aborted) {
+              throw ex;
+            }
+
+            errors.push({ reason: ex });
+            logger.error`Failed to read from a storage: ${ex}`;
           }
         }
 
         if (r === NONE) {
-          throw new KeyNotFoundError({ key });
+          const args: KeyNotFoundErrorArgs = { key };
+          switch (errors.length) {
+            case 0:
+              break;
+            case 1:
+              args.cause = errors[0]!.reason;
+              break;
+            default:
+              args.cause = new PluginOperationAggregateError({
+                plugin: "storage",
+                action: "read",
+                errors,
+              });
+          }
+
+          throw new KeyNotFoundError(args);
         }
 
         // トランスフォーマーを逆順に適用し、デコード用トランスフォームを連結します。
-        if (this.#transformers.length > 0) {
-          for (const transformer of this.#transformers.toReversed()) {
-            const d = await transformer.getDecodable(context, signal);
-            r = r.pipeThrough(d);
-          }
+        for (const transformer of this.#transformers.toReversed()) {
+          const d = await transformer.getDecodable(context, signal);
+          r = r.pipeThrough(d);
         }
 
         if (!ioLockRegistry) {
           return toValueStream(r, async () => {
-            try {
-              await r.cancel();
-            } catch {}
             try {
               lock.release();
             } catch {}
@@ -979,19 +1109,30 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
           try {
             ioLockRegistry.unregister(unregisterToken);
           } catch {}
-          try {
-            await r.cancel();
-          } catch {}
           try {
             lock.release();
           } catch {}
         });
 
-        // valueStream が GC されるタイミングでストリームが終了していなければロックを自動解放します。
-        ioLockRegistry.register(valueStream, lock, unregisterToken);
+        // valueStream が GC されるタイミングでストリームが終了していなければロックを自動解放するとともに、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放できるように dispose を記録します。
+        ioLockRegistry.register(
+          valueStream,
+          {
+            lock,
+            dispose: valueStream.dispose,
+          },
+          unregisterToken,
+        );
 
         return valueStream;
       } catch (ex) {
+        if (r !== NONE) {
+          // getReadable 成功後のセットアップ中に失敗した場合、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放するためにキャンセルします。
+          try {
+            await r.cancel(ex);
+          } catch {}
+        }
+
         lock.release();
         throw ex;
       }
@@ -1035,7 +1176,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     context["unikvs:action"] = "has";
     context["unikvs:key"] = key;
 
-    const lock = await asyncmux(this, signal);
+    const lock = await asyncmux.readonly(this, signal);
     try {
       // ロック待機中に接続状態が変更されていないか再確認します。
       if (this.#con === null) {
@@ -1045,12 +1186,40 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
       const lock = await io.rLock({ key, signal });
       try {
         // いずれかのストレージに存在すれば true を返します。
+        // あるストレージの存在確認に失敗しても、他のストレージで存在を確認できるようにフォールバックします。
+        const errors: { reason: unknown }[] = [];
         for (const storage of this.#destinations) {
-          if (await storage.exists(context, signal, key)) {
-            return true;
+          try {
+            if (await storage.exists(context, signal, key)) {
+              return true;
+            }
+          } catch (ex) {
+            if (signal.aborted) {
+              throw ex;
+            }
+            errors.push({ reason: ex });
+            logger.error`Failed to check existence in a storage: ${ex}`;
           }
         }
 
+        // すべてのストレージで存在を確認できなかった場合は結果が不明のため、get() と同様にエラーとして報告します。
+        if (errors.length > 0) {
+          const args: KeyNotFoundErrorArgs = { key };
+          switch (errors.length) {
+            case 1:
+              args.cause = errors[0]!.reason;
+              break;
+            default:
+              args.cause = new PluginOperationAggregateError({
+                plugin: "storage",
+                action: "read",
+                errors,
+              });
+          }
+
+          throw new KeyNotFoundError(args);
+        }
+
         return false;
       } finally {
         lock.release();

package/src/value-stream.types.ts

@@ -10,5 +10,10 @@ export interface ValueStream<T = any>
     Omit<ReadableStream, keyof AsyncDisposable | keyof AsyncIterable<unknown>>,
     AsyncDisposable,
     AsyncIterable<T, void, unknown> {
-  dispose(): Promise<void>;
+  /**
+   * ストリームを閉じ、関連するリソースを解放します。
+   *
+   * @returns リソースの解放が完了したときに解決される Promise です。
+   */
+  dispose: (this: void) => Promise<void>;
 }