first commit

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

@@ -0,0 +1,75 @@
+# parse-fallback-uri
+
+## Purpose
+
+The `parse-fallback-uri` module owns the canonical grammar for the
+`fallback://` URI scheme. It parses input strings into ordered candidate
+URI lists, rejects malformed inputs with structured `FALLBACK_URI.*`
+errors, builds canonical URIs from candidate arrays, and exposes helpers
+to attach or strip the internal recursion-context query parameter used
+for cycle detection across resolver re-entries.
+
+## Features
+
+- `parseFallbackUri(uri, maxCandidates?)` — split into candidates +
+  canonical re-serialisation; throws `NO_CANDIDATES` / `INVALID_URI`.
+- `buildFallbackUri(uris, maxCandidates?)` — construct a canonical URI
+  using stdlib `URLSearchParams`; rejects empty / oversized inputs.
+- `stripContext(uri)` / `withContextId(uri, id)` — manipulate the
+  internal `__fbctx=<id>` recursion-context marker.
+- Hard ceilings (`MAX_URI_LEN` 4096, `MAX_CANDIDATES_HARD` 64) enforced
+  even when a more permissive policy value is supplied.
+
+## Usage: Basic Example
+
+```ts
+import {
+    buildFallbackUri,
+    parseFallbackUri,
+} from "@suaveplan/storage-uri-plugin-fallback/parse-uri";
+
+const uri = buildFallbackUri([
+    "https://cdn.example.com/foo",
+    "drive://primary/foo",
+]);
+const { candidates } = parseFallbackUri(uri);
+console.log(candidates);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    parseFallbackUri,
+    withContextId,
+    stripContext,
+} from "@suaveplan/storage-uri-plugin-fallback/parse-uri";
+
+const decorated = withContextId(uri, "ctx-42");
+const parsed = parseFallbackUri(decorated);
+if (parsed.contextId === "ctx-42") {
+    const canonical = stripContext(decorated);
+    console.log("recursion key:", canonical);
+}
+```
+
+## API Reference
+
+- `parseFallbackUri(uri: string, maxCandidates?: number): ParsedFallbackUri`
+- `buildFallbackUri(uris: readonly string[], maxCandidates?: number): string`
+- `stripContext(uri: string): string`
+- `withContextId(uri: string, contextId: string): string`
+- `FB_CTX_PARAM` — `"__fbctx"` marker name.
+- `MAX_URI_LEN` — 4096.
+- `MAX_CANDIDATES_HARD` — 64.
+
+## Implementation Notes
+
+Parsing is delegated entirely to the Web-standard `URL` and
+`URLSearchParams` constructors, eliminating every custom regex outside
+syntactic guards. Candidate ordering is preserved because
+`URLSearchParams.getAll` is ordered. Round-trip safety is verified by a
+fast-check property test in the sibling `.test.ts` file. The
+`__fbctx` parameter is stripped from the canonicalised visited-set key so
+nested re-entries cannot defeat cycle detection by carrying different
+context ids.