Initial Commit

packages/networking/drive/drive-plugin-chunks/src/manifest/source.md

@@ -0,0 +1,44 @@
+# source
+
+## Purpose
+
+Validates the `manifestSource` configuration before the plugin starts wiring its read middleware. The function is small but load-bearing: it short-circuits the `"server-only"` branch when no `manifestServerUrl` is supplied so the rest of the plugin can assume the source is well-formed by the time it runs.
+
+## Features
+
+- `resolveManifestSource(source, manifestServerUrl?): { source, url }` — returns the normalised configuration tuple.
+- Eager validation — throws synchronously instead of failing inside the read pipeline.
+- Pure function — no I/O, no global state, deterministic for fixed inputs.
+- Unaware of `getChunk` / `fetch` — those concerns live in `load.ts`.
+
+## Usage: Basic Example
+
+```ts
+import { resolveManifestSource } from "@suaveplan/drive-plugin-chunks";
+
+const cfg = resolveManifestSource("manifest-as-chunk");
+```
+
+## Usage: Advanced Example
+
+```ts
+import { resolveManifestSource } from "@suaveplan/drive-plugin-chunks";
+
+const cfg = resolveManifestSource("server-only", "https://manifests.example.com");
+console.log(cfg.url); // "https://manifests.example.com"
+
+try {
+    resolveManifestSource("server-only");
+} catch (err) {
+    console.error("missing manifestServerUrl");
+}
+```
+
+## API Reference
+
+- `resolveManifestSource(source: ManifestSource, manifestServerUrl?: string): { source: ManifestSource; url: string | undefined }`.
+- Throws a plain `Error` (not `ChunksError`) when `source === "server-only"` and `manifestServerUrl` is missing, because this is a programmer error in plugin construction, not a runtime fault that consumers should branch on.
+
+## Implementation Notes
+
+The two valid `ManifestSource` values are intentionally narrow: `"manifest-as-chunk"` reuses the chunk-storage substrate as the manifest store, while `"server-only"` keeps manifests out-of-band on a separate HTTPS endpoint. Future sources (e.g. a libp2p PubSub channel) would slot in by extending the union type and the dispatcher in `load.ts`. The plain `Error` is surfaced as soon as the plugin object is constructed so misconfigurations show up at boot, not during the first `read`.