OpenSpec Change: drive-transport-https-port

Change ID: drive-transport-https-port
Package: @suaveplan/drive-transport-https (new — NOT BUILT)
Status: RETIRED — subsumed by drive-mesh ServerFallback (archived 2026-05-12)
Date: 2026-04-28 (proposed); 2026-05-12 (retired)

Why retired

The shipped @suaveplan/drive-mesh package contains a built-in ServerFallback module (./server-fallback/server-fallback) that already provides every capability this proposal asked for:

HTTPS GET ${baseUrl}/${fileId}/${chunkId} chunk fetch.
Real verifyChunkSig(serverPubKey, …) gate against the drive-plugin-chunks signature verifier.
Equal-jitter exponential backoff with caller-configurable maxRetries / backoffBaseMs / backoffMaxMs.
Injectable fetchFn for tests (defaults to globalThis.fetch).
AbortSignal threading through every retry.
DriveMeshError(FALLBACK_FAILED) surface with underlying HTTP / fetch error preserved in cause.

Bearer-token (or arbitrary other) authentication is supplied by the consumer by wrapping the fetchFn rather than by adding transport-level auth plumbing — i.e. it's already pluggable without a new package.

Modelling HTTPS as a parallel DriveTransport plugin (with no-op advertise, onAdvertisement, and a single-server synthetic peers() list) was the originally-proposed surface; on review it adds no consumer capability beyond ServerFallback while doubling the scheduler's surface area. The decision to consolidate the HTTPS chunk-fetch path inside ServerFallback is recorded in the ## ADDED Requirements section of openspec/specs/drive-mesh/spec.md ("HTTPS chunk fetch via ServerFallback" / "No HTTPS DriveTransport plugin").

Summary

HTTPS implementation of the DriveTransport interface defined in @suaveplan/drive-mesh. Acts as the server-fallback transport for browser mesh sessions: when no peer can serve a chunk (or for cold-start manifest fetches in manifest-as-chunk mode where no peer has it yet), mesh fans out an HTTPS GET. Also serves as the canonical transport when running drive on a server-only setup with no peer mesh.

API surface

const transport = httpsTransport({
    baseUrl: "https://cdn.example.com",
    fetch: globalThis.fetch,           // injectable
    auth?: { bearer: string }          // optional
});
// Implements DriveTransport:
transport.requestChunk(peerId, fileId, chunkId): AsyncIterable<Uint8Array>;
transport.advertise(peerId, fileId, bitset);                   // no-op (HTTPS is unidirectional)
transport.onAdvertisement(handler);                            // no-op
transport.peers(): Iterable<PeerInfo>;                         // returns the single server "peer"

Wire protocol

Chunk fetch: GET /v1/chunks/<fileId-hex>/<chunkId> → response body is the raw 164+payloadLen byte chunk (Content-Type: application/octet-stream). Range requests supported for partial reads of in-flight downloads.
Manifest fetch: GET /v1/manifests/<fileId-hex> → response body is the canonical-encoded manifest (CBOR or JSON; Accept header negotiates).
Auth: optional Authorization: Bearer <token> from auth.bearer.
Errors: standard HTTP status codes; transport surfaces them as MeshError codes via the cause chain.

Dependencies

Consumes: @suaveplan/drive-mesh (interface only — DriveTransport), @suaveplan/error, @suaveplan/types, @suaveplan/retry, @opentelemetry/api, zod.
Blocked on: drive-mesh-port (for the interface).

Out of scope

HTTP/3 / QUIC — future optimisation.
Chunked transfer encoding for streaming push-from-server — covered by Range requests.

3.6 KiB Raw Blame History