# 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.