118 lines
3.0 KiB
Markdown
118 lines
3.0 KiB
Markdown
|
# Shade V3.8 — Web Workers Crypto
|
|||
|
|
|
|||
|
|
**Status:** Done
|
|||
|
|
**Effort:** M-L (3–6 uker)
|
|||
|
|
**Forrige:** V3.1
|
|||
|
|
**Adresserer:** V2.2 §4
|
|||
|
|
**Levert:** `0.4.0`
|
|||
|
|
**Konsumentdokumentasjon:** [`docs/web-workers.md`](../web-workers.md)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Mål
|
|||
|
|
|
|||
|
|
Store filer i nettleseren skal kunne krypteres / dekrypteres uten å blokkere
|
|||
|
|
hovedtråden eller sprenge RAM. Dedikert Worker kjører `@shade/crypto-web` +
|
|||
|
|
`@shade/streams`, koblet til `@shade/transfer` via `ReadableStream` /
|
|||
|
|
`WritableStream`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Scope
|
|||
|
|
|
|||
|
|
### Inn
|
|||
|
|
|
|||
|
|
- Ny entry: `@shade/crypto-web/worker` — dedikert Web Worker med
|
|||
|
|
`WorkerCryptoProvider`.
|
|||
|
|
- Hovedtråd-proxy: `MainThreadCryptoProvider` som forwarder kall til Worker.
|
|||
|
|
- Stream-pipeline: `ReadableStream<Uint8Array>` → Worker (transferable
|
|||
|
|
buffers) → `@shade/transfer`-chunk-PUTs.
|
|||
|
|
- Lifecycle: spawn-on-demand, idle-timeout, terminate-on-rotate.
|
|||
|
|
- Safari-aware chunk-sizing (Safari har lavere `postMessage`-kapasitet).
|
|||
|
|
|
|||
|
|
### Ut
|
|||
|
|
|
|||
|
|
- Service Workers (background sync) — egen vurdering.
|
|||
|
|
- SharedArrayBuffer (krever COOP/COEP-headers; valgfritt opt-in).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Design
|
|||
|
|
|
|||
|
|
### Provider-API (uendret for konsumenter)
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
const crypto = await createWorkerCryptoProvider({
|
|||
|
|
workerUrl: '/shade-crypto.worker.js',
|
|||
|
|
});
|
|||
|
|
const shade = await createShade({ crypto, ... });
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`WorkerCryptoProvider` implementerer samme `CryptoProvider`-interface som
|
|||
|
|
`SubtleCryptoProvider`. Kall serialiseres med transferable `ArrayBuffer` så
|
|||
|
|
minne ikke kopieres.
|
|||
|
|
|
|||
|
|
### Stream-pipeline
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
file.stream()
|
|||
|
|
.pipeThrough(shade.encryptStream(peer)) // worker
|
|||
|
|
.pipeThrough(shade.transfer.outboundChunks()) // main → http
|
|||
|
|
.pipeTo(transferSink());
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Worker-siden av `encryptStream` bruker `MultiLaneSender`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Leveranser
|
|||
|
|
|
|||
|
|
### Kode
|
|||
|
|
|
|||
|
|
- `@shade/crypto-web` — ny `worker.ts` entrypoint.
|
|||
|
|
- `@shade/sdk` — `shade.encryptStream` / `decryptStream`.
|
|||
|
|
- Bundler-eksempel for Vite, Webpack og Rollup.
|
|||
|
|
|
|||
|
|
### Tester
|
|||
|
|
|
|||
|
|
- Unit: postMessage roundtrip med transferable buffer.
|
|||
|
|
- Integration: 100 MB fil i nettleser uten frame-drop > 16 ms (P99).
|
|||
|
|
- Safari: chunked `postMessage`-workaround.
|
|||
|
|
|
|||
|
|
### Dokumentasjon
|
|||
|
|
|
|||
|
|
- `docs/web-workers.md` — setup, bundler-kvirks, Safari-notater, COOP/COEP
|
|||
|
|
for SharedArrayBuffer-modus.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Akseptansekriterier
|
|||
|
|
|
|||
|
|
- [x] 100 MB upload i Chrome uten å blokkere main thread > 16 ms i P99
|
|||
|
|
(Performance Observer-måling — verifiseringsoppskrift i
|
|||
|
|
[`docs/web-workers.md`](../web-workers.md#verifying-main-thread-budget)).
|
|||
|
|
- [x] Safari fungerer med default chunk-size (256 KiB postMessage budget,
|
|||
|
|
langt under Safari's transferable-grense).
|
|||
|
|
- [x] Worker termineres innen 30 s etter siste bruk
|
|||
|
|
(`idleTimeoutMs`, default `30_000`).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Avhengigheter
|
|||
|
|
|
|||
|
|
Ingen direkte. Kan kjøres parallelt med V3.2 / V3.4.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Risiko
|
|||
|
|
|
|||
|
|
- **Bundler-helvete.** Vite, Webpack og Rollup behandler Workers ulikt.
|
|||
|
|
Mitiger ved publisert recipe + integration-tester per bundler.
|
|||
|
|
- **Safari postMessage-grenser.** Test tidlig.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Migrasjon
|
|||
|
|
|
|||
|
|
Opt-in. Default forblir `SubtleCryptoProvider`.
|