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

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

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

```ts
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:

```ts
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.