Initial Commit

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

@@ -0,0 +1,46 @@
+# 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.