Transfer Lifecycle & Workflow Specification

Phase 1: Session Initialization

When a user initiates a transfer by selecting a file on the host machine:

1. File Metadata Extraction: The browser reads file properties (filename, size in bytes, MIME type) via the HTML5 File API. Filenames are sanitized locally to prevent path traversal or control character injection.
2. Room Code Generation: A cryptographically pseudorandom 6-digit alphanumeric room code is generated from a 32-character alphabet (excluding ambiguous letters like 'l', '1', 'o', '0').
3. Signaling Registration: The host registers the room state on the signaling relay with an initial status of waiting and a 15-minute time-to-live (TTL).
4. QR Code Rendering: A vector SVG QR code encoding the room URL (https://shareonline.net/room/[code]) is rendered on the host screen.

Phase 2: Signaling & Peer Pairing

When the receiving client joins:

1. Room Lookup: The receiver requests room metadata via POST /api/signal with action join-room.
2. SDP Offer/Answer: The host constructs a WebRTC SDP offer describing its transport capabilities. The receiver processes the offer and returns an SDP answer.
3. ICE Gathering: Both peers query configured STUN servers (stun:stun.l.google.com:19302) to discover public IP/port bindings and exchange candidates via signaling.
4. Direct Pathway Selection: WebRTC establishes the shortest direct network path (LAN or WAN UDP hole-punching).

Phase 3: Binary Stream Transmission

1. DataChannel Ready: The host confirms the RTCDataChannel state is open.
2. Slicing: The file is read in 32,768-byte (32 KB) chunks using FileReader.readAsArrayBuffer().
3. Backpressure Throttling: If dataChannel.bufferedAmount > 524,288 bytes, transmission halts until bufferedamountlow fires.
4. Chunk Delivery: Chunks flow directly over SCTP/DTLS to the receiver without server storage.

Phase 4: Finalization & Teardown

1. Completion Token: Upon reaching offset >= file.size, the host transmits a { type: 'complete' } signal.
2. Blob Compilation: The receiver packages accumulated ArrayBuffer[] chunks into a unified Blob matching the file MIME type.
3. Download Trigger: An object URL (URL.createObjectURL(blob)) is attached to a temporary anchor element and clicked programmatically.
4. Session Purge: Both peers close connections, garbage-collect in-memory buffers, and trigger signaling cleanup.