Sterister
e6fdf31b49
Some checks failed
Test / test (push) Has been cancelled
Cross-platform vectors / TypeScript vectors (bun) (push) Has been cancelled
Cross-platform vectors / Kotlin vectors (gradle) (push) Has been cancelled
Docker build and publish / docker (push) Has been cancelled
Publish / publish (push) Has been cancelled
V3.1 → V3.12 consolidated and tagged for the first GA release. Wire format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers byte-for-byte. The version bump is semantic: audit-cycle complete, opt-in surface fully exposed, threat model refreshed for every new surface. Highlights: - All 24 @shade/* packages bumped to 4.0.0 in lockstep. - CHANGELOG 4.0.0 section is the canonical manifest of what landed. - THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12 Web-Worker boundary) + residual-risks table refreshed. - OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox, bridge, observer, /metrics, /healthz, /ready. - MIGRATION 0.3.x → 4.0 documented + smoke-tested against shade migrate-storage on a real SQLite DB. - docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer. - scripts/soak.ts harness for the GA-stable 2-week soak window. - All V*.md plans archived under docs/archive/ with Status: Done. - Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen non-realtime stack. Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green. Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports version 4.0.0 on /health. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
128 lines
2.9 KiB
Markdown
128 lines
2.9 KiB
Markdown
# Shade V3.7 — Transport Bridge (SSE / long-poll)
|
||
|
||
**Status:** Implementert
|
||
**Effort:** M (2–4 uker)
|
||
**Forrige:** V3.6
|
||
**Adresserer:** V2.3 §3
|
||
**Leveranse:** `@shade/transport-bridge` 0.1.0 + `createBridgeRoutes` i
|
||
`@shade/inbox-server`. Brukerveiledning: [`docs/transport.md`](../transport.md).
|
||
|
||
---
|
||
|
||
## Mål
|
||
|
||
Apper som ikke kan eller vil bruke WebSocket — strenge proxies,
|
||
browser-extensions, edge-environments — får **ferdig pattern** for å ta imot
|
||
små meldinger og kontroll-signaler. SSE som primær fallback, long-poll som
|
||
sekundær.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### Inn
|
||
|
||
- `@shade/transport-bridge` — ny submodul i `@shade/transport` (eller egen
|
||
pakke).
|
||
- SSE-endpoint i `@shade/server` (kombineres med inbox fra V3.6 for "hent
|
||
fra inbox uten plaintext").
|
||
- Long-poll fallback med konfigurerbar timeout.
|
||
- Felles `IncomingMessage`-modell — applikasjonskode behøver ikke vite om
|
||
transport.
|
||
- Auto-fallback: WS → SSE → long-poll (samme mønster som transfer-transport).
|
||
|
||
### Ut
|
||
|
||
- HTTP/2 push.
|
||
- WebTransport — browser-støtte fortsatt umoden i 2026.
|
||
|
||
---
|
||
|
||
## Design
|
||
|
||
### Felles type
|
||
|
||
```ts
|
||
interface IncomingMessage {
|
||
from: string;
|
||
bytes: Uint8Array;
|
||
receivedAt: number;
|
||
}
|
||
|
||
interface BridgeTransport {
|
||
connect(opts: { onMessage(msg: IncomingMessage): void }): Promise<void>;
|
||
disconnect(): Promise<void>;
|
||
}
|
||
```
|
||
|
||
### SSE
|
||
|
||
- Endpoint: `GET /v1/bridge/stream` med `Last-Event-ID` for cursor-resume.
|
||
- Server-side: emitterer `envelope-ready`-event når inbox får ny.
|
||
- Klient åpner én EventSource; reconnect på drop.
|
||
|
||
### Long-poll
|
||
|
||
- Endpoint: `GET /v1/bridge/poll?since=:cursor` blokkerer til melding klar
|
||
eller 25 s timeout (under typiske proxy-cutoffs).
|
||
- Klient repeterer.
|
||
|
||
### Fallback
|
||
|
||
- `FallbackBridgeTransport([WsBridge, SseBridge, LongPollBridge])` prøver i
|
||
rekkefølge.
|
||
|
||
---
|
||
|
||
## Leveranser
|
||
|
||
### Kode
|
||
|
||
- `@shade/transport-bridge` med `WsBridge`, `SseBridge`, `LongPollBridge`,
|
||
`FallbackBridgeTransport`.
|
||
- Server: SSE og long-poll routes på `@shade/server` eller
|
||
`@shade/inbox-server`.
|
||
|
||
### Tester
|
||
|
||
- Unit: hver bridge åpner/lukker korrekt; reconnect på drop.
|
||
- Integration: WS down → faller til SSE; SSE 502 → long-poll.
|
||
- Same `IncomingMessage` shape ut fra alle tre.
|
||
|
||
### Dokumentasjon
|
||
|
||
- `docs/transport.md` utvidet med bridge-oversikt.
|
||
|
||
---
|
||
|
||
## Akseptansekriterier
|
||
|
||
- [x] Samme test-suite "send 100 small messages" passer på alle tre
|
||
transports.
|
||
- [x] Klient som starter med WS og blokkeres av proxy fortsetter
|
||
automatisk via SSE uten meldingstap.
|
||
- [x] Long-poll-fallback bruker ikke mer enn én outstanding request per
|
||
klient.
|
||
|
||
---
|
||
|
||
## Avhengigheter
|
||
|
||
- V3.6 — naturlig komplement; SSE-payload er typisk "envelope er klar i
|
||
inbox".
|
||
|
||
---
|
||
|
||
## Risiko
|
||
|
||
- **Reconnect-cykluser.** SSE som flapper kan tape meldinger. Mitiger med
|
||
Last-Event-ID + at server beholder kort buffer.
|
||
- **Long-poll keepalive.** Proxy-timeouts kan kutte før 30 s; juster
|
||
default til 25 s.
|
||
|
||
---
|
||
|
||
## Migrasjon
|
||
|
||
Additivt.
|