Initial Commit
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Drive Transport HTTPS — Spec Delta (drive-transport-https-port)
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### TRANSPORT-HTTPS-01 — DriveTransport contract
|
||||
|
||||
`httpsTransport(options)` MUST return an object satisfying the `DriveTransport` interface from `@suaveplan/drive-mesh`. `advertise` and `onAdvertisement` MUST be no-ops (HTTPS is unidirectional). `peers()` MUST return a single synthetic `PeerInfo` representing the server.
|
||||
|
||||
**Verified by:** `src/transport.spec-conformance.test.ts` (`TRANSPORT-HTTPS-01`).
|
||||
|
||||
### TRANSPORT-HTTPS-02 — Chunk fetch URL and body
|
||||
|
||||
`requestChunk(peerId, fileId, chunkId)` MUST issue `GET <baseUrl>/v1/chunks/<fileId-hex>/<chunkId>` via the injected `fetch` and yield the response body as `AsyncIterable<Uint8Array>`. Response body bytes MUST be passed through unmodified (the chunks plugin's sig-verify will validate them).
|
||||
|
||||
**Verified by:** `src/transport.spec-conformance.test.ts` (`TRANSPORT-HTTPS-02`).
|
||||
|
||||
### TRANSPORT-HTTPS-03 — Range requests for partial reads
|
||||
|
||||
When `requestChunk` is called with a byte range, the transport MUST issue an HTTP `Range: bytes=<start>-<end>` header. Responses with status `206 Partial Content` MUST be honoured.
|
||||
|
||||
**Verified by:** `src/transport.spec-conformance.test.ts` (`TRANSPORT-HTTPS-03`).
|
||||
|
||||
### TRANSPORT-HTTPS-04 — Error code mapping
|
||||
|
||||
HTTP `404` MUST surface as `MeshError(MESH.MANIFEST_FETCH_FAILED)` for manifest endpoints or `MeshError(MESH.NO_PEERS_AVAILABLE)` for chunk endpoints. `5xx` MUST surface as `MeshError(MESH.TRANSPORT_ERROR)`. `401`/`403` MUST surface as `MeshError(MESH.TRANSPORT_ERROR)` with code-string `auth-failed` in the cause.
|
||||
|
||||
**Verified by:** `src/transport.spec-conformance.test.ts` (`TRANSPORT-HTTPS-04`).
|
||||
@@ -0,0 +1,29 @@
|
||||
# Tasks: drive-transport-https-port
|
||||
|
||||
> Blocked on: `drive-mesh-port`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] 1.1 `packages/drive/drive-transport-https/` with `package.json` (`@suaveplan/drive-transport-https@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [ ] 1.2 Workspace deps: `@suaveplan/drive-mesh` (interface), `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@opentelemetry/api`, `zod`.
|
||||
|
||||
## 2. Transport impl
|
||||
|
||||
- [ ] 2.1 `src/transport.ts` — `httpsTransport(options)` factory, `requestChunk` returns `AsyncIterable<Uint8Array>` from the fetch response body.
|
||||
- [ ] 2.2 `src/range.ts` — Range header construction for partial chunk reads.
|
||||
- [ ] 2.3 `src/auth.ts` — Bearer token injection.
|
||||
- [ ] 2.4 `src/errors.ts` — HTTP-status → `MeshError` code mapping.
|
||||
|
||||
## 3. Spec
|
||||
|
||||
- [ ] 3.1 `openspec/specs/drive-transport-https/spec.md` — `TRANSPORT-HTTPS-01` … `-04` with `**Verified by:**` lines.
|
||||
|
||||
## 4. Conformance tests
|
||||
|
||||
- [ ] 4.1 `src/transport.spec-conformance.test.ts` — chunk fetch round-trip with injected fetch, Range request, error mapping, manifest fetch (`TRANSPORT-HTTPS-01` … `-04`).
|
||||
|
||||
## 5. Verify
|
||||
|
||||
- [ ] 5.1 `bunx turbo lint typecheck test --filter=@suaveplan/drive-transport-https` green.
|
||||
- [ ] 5.2 `bunx turbo test:coverage --filter=@suaveplan/drive-transport-https` 100/100/100/100.
|
||||
- [ ] 5.3 `bun scripts/openspec-conformance.ts @suaveplan/drive-transport-https` PASS.
|
||||
Reference in New Issue
Block a user