first commit

docs/persistence/storage/storage-uri-plugin-fallback/src/plugin/plugin.md

@@ -0,0 +1,77 @@
+# plugin
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `plugin` module hosts the `fallbackUriPlugin` factory — the public
+entry point of the package. The factory validates its options via Zod,
+binds the supplied `StorageUriResolver` for recursive dispatch, builds a
+streaming-extended adapter implementing every `StorageLike` method, and
+returns a frozen `UriPlugin` ready for registration alongside other
+scheme handlers. The plugin's adapter routes every operation through the
+walk + ops modules, threading a per-call `DepthContext` so nested
+`fallback://` URIs remain bounded.
+
+## Features
+
+- Boundary Zod validation of options + policy.
+- Frozen `UriPlugin` with explicit `parse` / `build` round-trip.
+- Full streaming-extended `StorageLike` adapter: `get`, `set`, `delete`,
+  `exists`, `list`, `clear`, `createReadStream`, `createWriteStream`,
+  `getMetadata`, plus `listUri` for raw `ListUriResult`.
+- Recursion-safe via `DepthContext` registered through the parsed
+  `__fbctx` query parameter.
+- Refuses `clear()` (heterogeneous-mirror semantics not well-defined).
+
+## Usage: Basic Example
+
+```ts
+import {
+    createStorageUriResolver,
+} from "@suaveplan/storage-uri";
+import { fallbackUriPlugin } from "@suaveplan/storage-uri-plugin-fallback/plugin";
+
+const resolver = createStorageUriResolver([
+    httpPlugin,
+    drivePlugin,
+    fallbackUriPlugin({
+        resolver: () => resolver, // late-bound via a proxy in real wiring
+    } as never),
+]);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fallbackUriPlugin } from "@suaveplan/storage-uri-plugin-fallback/plugin";
+
+const plugin = fallbackUriPlugin({
+    resolver,
+    policy: {
+        maxParallel: 2,
+        writeMode: "all",
+        listFailureMode: "partial",
+    },
+    events: bus,
+});
+console.log(plugin.scheme); // "fallback"
+```
+
+## API Reference
+
+- `fallbackUriPlugin(options: FallbackPluginOptions): UriPlugin`
+- `FallbackAdapter` — adapter shape attached to `plugin.adapter`.
+- `buildFallbackUri` / `parseFallbackUri` re-exports for caller
+  convenience.
+
+## Implementation Notes
+
+The plugin holds the resolver by reference, allowing late binding via a
+proxy when the resolver instance has not yet been constructed. Each
+operation parses the input URI to discover any embedded context id; when
+present, it rehydrates the parent `DepthContext` from the registry,
+otherwise it creates a fresh root context. The root context is cleaned
+up in the `finally` block to keep the registry leak-free.