Transfer Lanes

Control Plane, Many Data Lanes

Every lane creates normal Ultra shares with the same policy, grant, delete-token, expiration, and lifecycle semantics. The data lane changes how bytes move.

Control plane:
  Share, Policy, Grant, Manifest, Auth, Telemetry, Lifecycle

Data lanes:
  Live Pipe
  Hybrid Live
  Turbo Multipart
  TUS Compatibility
  Import from URL

The checked Phase 2 lane audit lives at docs/phase-2-transfer-lane-audit.json. Regenerate it with npm run validate:phase2-transfer-lane-audit from workers/ after any lane threshold or flag-gate change. The audit is local-only and spends no transfer bandwidth.

Routing Rule

Live Pipe

Live Pipe is for small human-to-human sessions where both sides are likely present. PipeDO keeps a bounded hot buffer so connected receivers can read fresh chunks directly while R2 remains the replay and durability layer.

Hybrid Live

Hybrid Live keeps the live product feel for 256 MiB to 20 GiB transfers: the live link exists immediately, bytes move through progressive Direct-R2 chunks, and receiver progress follows the manifest's contiguous downloadable prefix before upload completion.

Completed progressive transfers continue to serve through the chunk manifest, exposed as servingMode: chunk-manifest, so upload completion does not stitch a large object through the Worker request path.

Optional finalized-object copies are a future background maintenance option only. They would require a separate rollout flag such as ULTRA_ENABLE_PROGRESSIVE_FINALIZED_COPY, must not run during upload completion or receiver download, must not be mobile-triggered, and must preserve policy, grant, max-use, delete-token, webhook, audit, encryption, and cleanup semantics. Candidate use is completed >20 GiB objects or repeated completed-object downloads where /api/dl compatibility or CDN behavior justifies the extra storage.

Encrypted progressive receives prefer the Service Worker stream at /sw-progressive-dl/..., which fetches and decrypts authorized chunks into the browser download stream without page-level whole-file assembly.

localStorage.ultra_enable_progressive_sw_download=1 explicitly enables the Service Worker receiver path; dev/local validation defaults it on, and 0 disables it as the rollback switch.

localStorage.ultra_progressive_batch_commit=1 explicitly enables sender-side progressive batch manifest publication; dev/local validation defaults it on, 0 disables it, and chunk 1 still commits immediately so receivers can start from the first contiguous prefix.

The browser product route is gated by localStorage.ultra_enable_hybrid_live=1 while it is validated. Worker-proxied multipart remains a compatibility fallback, and Live Pipe stays reserved for smaller true-live transfers where immediacy or storage avoidance beats maximum throughput.

The current locked 1..10 GiB sender policy is progressive-r2 over direct-r2: 32 MiB chunks, four workers on Chromium-class desktop hardware, 5 plaintext plus 5 ciphertext queue caps for 10 in-flight uploads, batch commits of 32 chunks, one early committed chunk, direct-R2 authorization batches of 32, and a 64-chunk authorization-ahead window. Old adaptive local telemetry and queue overrides do not change this band.

localStorage.ultra_hybrid_throughput_mode=max is a dev/local-only max-throughput Hybrid experiment for desktop Chromium-class browsers. It keeps the same progressive-r2 / direct-r2 lane, uses at least 32 MiB chunks, raises dev-only queue caps to 8 plaintext plus 8 ciphertext, and records throughputMode, saturatingPolicy, and targetInFlightBytes. It is not a production default or rollout candidate until a budget-approved product row beats the locked policy without retry, timeout, fallback, memory, or cleanup regressions; the first 2026-07-03 proof row was reliable but did not beat the locked policy on wall-clock upload or effective throughput.

Turbo Multipart

Turbo is Ultra's native high-throughput lane for larger files. It maps directly to R2 multipart upload and avoids putting Durable Objects in the hot byte path.

POST /api/upload/multipart/init
POST /api/upload/multipart/part
POST /api/upload/multipart/complete
POST /api/upload/multipart/abort
GET  /api/upload/multipart/status

TUS Compatibility

TUS is a compatibility adapter over multipart manifests for clients that already speak resumable TUS. Ultra-native multipart remains the fastest first-party lane.

OPTIONS /api/tus
POST    /api/tus
HEAD    /api/tus/{id}
PATCH   /api/tus/{id}
DELETE  /api/tus/{id}

P2P Experiment

P2P/WebRTC remains a dev-only experiment after the Direct-R2 and Hybrid Live backbone. ULTRA_ENABLE_P2P_EXPERIMENT enables short-lived tokenized signaling rooms on ultra-dev.egomonk.com and local dev only.

/api/p2p/rooms creates a room whose token stays in the URL fragment and is sent as X-Ultra-P2P-Room-Token. /api/p2p/rooms/{roomId}/signals stores bounded SDP, ICE, stats, and control messages in SESSIONS.

P2P Experiment opens an ultra-p2p-probe data channel, runs synthetic throughput probes, classifies selected ICE candidates as direct or relay-backed, records mobile lifecycle/network events, and can post dev evidence through the browser-result handoff. It moves no Ultra file bytes over P2P, and promotion still requires direct peer success rate, TURN relay fallback rate, mobile backgrounding, and 1 GiB/5 GiB throughput comparison against progressive Direct-R2.

Import From URL

Import-from-URL is for bytes that already live at an HTTP(S) URL. Ultra revalidates redirects, blocks private and internal targets, enforces byte and timeout caps, then stores the result as a normal file share.

Folder/Bulk

Folder state lives in FolderDO, files use the folder multipart lane, and ready files can be downloaded through GET /api/folder/{folderId}/zip as a Worker-streamed ZIP archive.

Opt-in folder E2EE keeps the key in the URL fragment, encrypts upload chunks in the browser, and decrypts individual file downloads in the browser. Encrypted folders do not use server-side plaintext ZIP because the Worker never receives the key; the ZIP endpoint returns 409 before consuming a folder share use.

Mobile Safety

Large mobile receive paths must be explicit and memory-safe. Ultra blocks unsafe iOS fallback behavior instead of silently assembling multi-GB decrypted chunks in JavaScript memory.

Mobile Safari Validation records receiver lifecycle, network, Service Worker, fallback, and completion checkpoints through mobile_validation_run_id. Promotion requires stored physical iPhone Safari rows with no unsafe page-level progressive assembly.