openrtc-file-transfer

Optional file-transfer protocol for OpenRTC applications. OpenRTC remains the connection and route owner; this package supplies application framing.

import { createTransfer } from 'openrtc-file-transfer';

const room = await rtc.rooms.join('project-files', {
  access: 'authenticated',
  membership: 'ephemeral',
  auth,
});
const files = createTransfer(room);
const stop = files.onIncoming(({ file }) => saveBlob(file.blob, file.name));
await files.send(deviceId, selectedFile, { onProgress: console.log });

When the client exposes OpenRTC's application-message surface, the protocol uses bounded OFT2 segments. OpenRTC selects the best currently proven route for every segment, so an in-flight transfer can promote from relay to WebRTC, MoQ, LAN, or direct QUIC and can fall back again without restarting. The receiver ACKs its highest contiguous accepted offset; a missing ACK or route failure causes a bounded resume negotiation from that receiver-owned offset. The older named-stream framing remains the compatibility path for clients that do not expose application messages.

Ticket-scoped native/browser applications can select routing: 'segmented-stream' with their registered channel descriptor. This carries the same OFT2 protocol in bounded named-channel streams, resolving the current admitted route for every segment and reply. It preserves native capability dispatch without falling back to unscoped application messages. Both endpoints must select this mode; legacy routing: 'stream' uses different v1 framing and is not wire-compatible. Offers, data windows and completion replies have bounded protocol recovery; rejection and cancellation remain terminal. Resume and completion are keyed by the sending peer and transfer ID, and scoped ACKs must come from the intended receiver. A successful local write is never completion evidence.

The package owns reusable framing, bounded validation, acknowledgement, progress, cancellation, and optional SHA-256 verification. Applications own file pickers, destination paths, acceptance policy, persistent queues, history, billing, and notifications. Native applications should provide a streaming ReceiveSink, the wire-compatible Rust openrtc-file-transfer crate, or a host-side file adapter instead of buffering large files in the WebView. A custom sink receiving SHA-256-protected transfers must implement verifySha256; verification fails closed rather than silently accepting an unchecked native file. Resume uses a declared offset: the sender starts at that byte and the receiver accepts it only when its sink reports the exact application-verified resumeOffset.

The protocol accepts one already-active OpenRTC 2.0 capability handle. It never constructs a hidden client or activates a second avenue. It also never caches a transport, dials a peer, or promotes a route. The consumer keeps durable product intent pending until the receiver confirms the completed size and integrity.