`@suaveplan/drive-uri/plugins/drive-mesh`

(no submodules)

Purpose

driveMeshUriPlugin(options) is a factory returning a UriPlugin registered against the drive+mesh:// scheme. It parses drive+mesh://<swarmId>/<path> URIs, captures swarmId for instrumentation, and forwards path to the consumer-supplied mesh-configured Drive. The plugin does NOT use swarmId to choose a Drive or transport — peer routing remains entirely the responsibility of the Drive's installed transports (drive-transport-https, drive-webrtc) and its PeerRegistry.

The captured swarmId surfaces on every emitted span via the drive.uri.swarm_id attribute. When a span is active at the time of parse(uri), the attribute is written there (alongside drive.uri.scheme and the redacted drive.uri); otherwise the parse step is silent.

Features

parse(uri) enforces scheme === "drive+mesh", a non-empty authority, and a non-empty path. All other URI hygiene (whitespace, NUL, scheme regex, 4096-char limit) is delegated to parseUri from @suaveplan/storage-uri.
build(key, meta?) round-trips the URI back to its source shape, defaulting the swarmId to options.defaultSwarmId (or "default") when no meta is supplied.
Adapter inherits InstrumentedDriveAdapter so reads, writes, and errors are recorded under the drive+mesh scheme attribute.

Usage: Basic

import { Drive } from "@suaveplan/drive";
import { chunksPlugin } from "@suaveplan/drive-plugin-chunks";
import { createStorageUriResolver } from "@suaveplan/storage-uri";
import { driveMeshUriPlugin } from "@suaveplan/drive-uri/plugins/drive-mesh";

const meshDrive = new Drive(localStorage);
await meshDrive.initialize();
await meshDrive.usePlugin(chunksPlugin({ /* ... */ }));

const resolver = createStorageUriResolver([
    driveMeshUriPlugin({ drive: meshDrive }),
]);

const bytes = await resolver.read("drive+mesh://swarmA/raw/clip.mov");

Usage: Advanced

Mixing mesh and template plugins on the same mesh-configured Drive so a single resolver dispatches both shapes through one drive instance:

import {
    driveMeshUriPlugin,
    driveTemplateUriPlugin,
} from "@suaveplan/drive-uri";

const resolver = createStorageUriResolver([
    driveMeshUriPlugin({ drive: meshDrive, defaultSwarmId: "primary" }),
    driveTemplateUriPlugin({ drive: meshDrive, templateProvider }),
]);

await resolver.read("drive+mesh://primary/folder/a.bin");
await resolver.read("drive+template://templA/folder/a.bin");

The two plugins share the same Drive, so a hydration triggered by the template plugin populates the file-location index that the mesh plugin then uses to fetch chunks. This is the canonical composition.

API Reference

driveMeshUriPlugin(options: DriveMeshUriPluginOptions): UriPlugin — options.drive is required; options.defaultSwarmId is optional and defaults to "default" for build output.

Implementation Notes

The plugin's parse(uri) attaches the swarmId to the active span via trace.getActiveSpan(). When no span is active (e.g. plugin used outside the resolver, in unit tests parsing URIs directly), the attribute write is silently skipped — never throws.
The drive.uri attribute is passed through redactUri so query strings carrying peer hints or seeds are stripped before reaching span backends.
Like driveUriPlugin, writes are rejected with DRIVE_URI.WRITE_UNSUPPORTED per the per-release scope.

3.5 KiB Raw Permalink Blame History

@suaveplan/drive-uri/plugins/drive-mesh