73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```ts
|
|
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.
|