suaveplan/openspec/archive/2026-05-11-drive-transport-https-v1/proposal.md

drive-transport-https-v1

Why

@suaveplan/drive-mesh-protocol defines the wire format for chunk discovery / request / delivery envelopes. To put those envelopes on the wire, drive-mesh consumers need a TransportLike<MessageEnvelope> implementation. This change ships the first one — an HTTPS-relay backed transport that works in browsers, sits behind any TLS proxy, and only requires the relay to host an HTTP server.

The HTTPS path is the lowest-friction connectivity tier in the drive stack: every browser, every server, every CI runner can speak it. WebRTC and WebSocket transports follow.

What Changes

• New package @suaveplan/drive-transport-https at packages/drive/drive-transport-https/ with full Vite + Vitest + Biome scaffolding.
• HttpsTransport class implementing TransportLike<MessageEnvelope> from @suaveplan/types/transport with explicit start() / stop() lifecycle.
• Long-poll receive loop (GET /recv?for=...&since=cursor&timeoutMs=...) with exponential backoff, equal jitter, AbortSignal cancellation, and a lastAuthError diagnostic getter for credential-refresh flows.
• Stateless send (POST /send with { to, envelope } body) with Zod-validated request and response shapes.
• Nine frozen HTTPS_TRANSPORT_CODES (NOT_CONNECTED / CLOSED / SEND_FAILED / RECV_FAILED / AUTH_FAILED / RELAY_UNAVAILABLE / MALFORMED_RESPONSE / ABORTED / PEER_UNKNOWN).
• Auth-failure short-circuit: a 401/403 from /recv stops the loop instead of looping forever — back-pressure belongs to the consumer.
• 58 tests across 6 files at 100/100/100/100 coverage; 5/5 docs coverage.

Impact

• New public package. No consumers yet — drive-mesh wiring will follow.
• Browser-friendly: no Node-only imports. Works against any HTTP relay that implements the documented /send and /recv endpoints.