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