File Transfer

Relevant source files

The following files were used as context for generating this wiki page:

• core/src/transfer/file.ts
• core/src/transfer/file.test.ts
• V1_PRODUCTION_IMPLEMENTATION_PLAN.md
• tests/e2e/file-transfer.e2e.test.ts
• IMPLEMENTATION_SUMMARY.md
• android/IMPLEMENTATION_SUMMARY.md

The File Transfer system is a core component of the Sovereign Communications platform, enabling users to send files over the decentralized mesh network. The system is designed to be robust and efficient, handling large files by breaking them into smaller chunks for transmission. It includes features for progress tracking, transfer management, and resume capabilities to ensure reliable delivery even in challenging network conditions.

The implementation spans the core logic, platform-specific UI components, and end-to-end testing. It uses dedicated message types, FILE_METADATA and FILE_CHUNK, for coordinating transfers. The system is managed primarily by the FileTransferManager class in the @sc/core library.

Sources: core/src/transfer/file.ts, IMPLEMENTATION_SUMMARY.md:25

Architecture Overview

The file transfer process involves a sender and a receiver coordinating through a series of specialized messages. The sender first creates and sends file metadata. The file is then broken into chunks, which are sent individually. The receiver collects these chunks, requests any that are missing, and reassembles the file upon completion.

The following diagram illustrates the high-level data flow for a file transfer.

Core Logic: FileTransferManager

The FileTransferManager class is the central component responsible for orchestrating file transfers. It manages active transfers, handles file chunking and reassembly, tracks progress, and cleans up stale or failed transfers.

Sources: core/src/transfer/file.ts:46-302

Class Diagram

This diagram shows the structure of FileTransferManager and its relationship with key data structures.

Data Structures

The file transfer process relies on several key data structures to manage state and data.

FileMetadata

This structure contains all the necessary information about a file to be transferred. It is sent as the first message to initiate a transfer.

Field	Type	Description
fileId	string	A unique UUID for the file transfer.
fileName	string	The original name of the file.
fileSize	number	Total size of the file in bytes.
mimeType	string	The MIME type of the file.
chunkSize	number	The size of each chunk in bytes (default 16KB).
totalChunks	number	The total number of chunks for the file.
checksum	Uint8Array	A SHA-256 hash of the entire file for integrity verification.
timestamp	number	The time the metadata was created.

Sources: core/src/transfer/file.ts:15-24

FileChunk

A FileChunk represents a single piece of the file being transferred.

Field	Type	Description
fileId	string	The ID of the file this chunk belongs to.
chunkIndex	number	The zero-based index of this chunk.
data	Uint8Array	The binary data of the chunk.
checksum	Uint8Array	A SHA-256 hash of the chunk's data for integrity.

Sources: core/src/transfer/file.ts:32-37

TransferState

This structure tracks the real-time status of an ongoing transfer.

Field	Type	Description
fileId	string	The unique ID of the transfer.
metadata	FileMetadata	The metadata for the file being transferred.
progress	number	The transfer progress from 0 to 100.
bytesTransferred	number	The total number of bytes transferred so far.
status	'pending' | 'active' | 'paused' | 'completed' | 'failed' | 'cancelled'	The current status of the transfer.
error	string	An optional error message if the transfer failed.

Sources: core/src/transfer/file.ts:40-45

Key Processes

1. Transfer Initiation and Chunking

A transfer begins when createFileMetadata is called with a File. This function calculates the file's size, total chunks, and a SHA-256 checksum. The default chunk size is 16KB. The file is then split into an array of FileChunk objects by splitFileIntoChunks, with each chunk also having its own checksum.

Sources: core/src/transfer/file.ts:47, 54-72, 75-92, core/src/transfer/file.test.ts:13-48

2. Chunk Processing and Reassembly

On the receiver's side, processChunk is called for each incoming FileChunk. It performs the following steps:

1. Validates that the transfer (fileId) is known.
2. Verifies the chunk's checksum against its data.
3. Stores the valid chunk in the PartialFile map.
4. Updates the overall transfer progress.

Once isTransferComplete returns true, reassembleFile can be called to construct the final file from the ordered chunks and verify it against the original file checksum from the metadata.

Sources: core/src/transfer/file.ts:111-128, 161-193

3. Transfer Management and Resumption

The FileTransferManager manages concurrency and state:

• Queueing: It limits concurrent transfers to MAX_CONCURRENT_TRANSFERS (5) and queues additional requests.
• State Tracking: It maintains a TransferState for each transfer, which can be pending, active, paused, completed, failed, or cancelled.
• Resumption: The getMissingChunks method allows a receiver to identify which chunks have not been received, enabling a transfer to resume after an interruption.
• Cleanup: cleanupStaleTransfers automatically fails transfers that have been inactive for a specified timeout (TRANSFER_TIMEOUT, 5 minutes).

Sources: core/src/transfer/file.ts:48-50, 134-148, 209-245

The following sequence diagram shows the chunk exchange and reassembly process.

File Validation

Before a file transfer is initiated, the file is validated against a set of rules to enhance security and manage resources.

Limit	Value	Description
MAX_SIZE	100 MB	Maximum allowed file size.
MAX_FILES_PER_MESSAGE	10	Maximum number of files that can be attached to a single message.
ALLOWED_TYPES	string[]	A list of allowed MIME types (images, videos, audio, documents, archives).
BLOCKED_EXTENSIONS	string[]	A list of disallowed file extensions (e.g., .exe, .js, .bat).

Additionally, filenames are sanitized to remove path traversal characters (../) and other special characters.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md:121-171

User Interface and E2E Flow (Web)

The end-to-end tests for the web platform provide insight into the user-facing flow for sending a file.

1. The user clicks an "attach file" button ([data-testid="attach-file-btn"]).
2. A native file chooser dialog appears.
3. The user selects a file.
4. The file is validated.
5. The user clicks the "send message" button ([data-testid="send-message-btn"]).
6. For large files, an upload progress bar (.upload-progress) is displayed in the UI.
7. Once sent, the file appears as a message in the chat view (.message-content.file-message).

Sources: tests/e2e/file-transfer.e2e.test.ts

This sequence diagram illustrates the E2E test flow.

Android Platform Considerations

On Android, the file transfer system is complemented by a suite of media capabilities to provide a rich user experience.

• Image Compression: Images can be compressed to one of three quality levels, reducing file size by up to 70%.
• Voice Recording: Audio is recorded and encoded into AAC format.
• File Management: A file cache with a 100MB limit and 7-day expiry is used to manage storage.
• Thumbnail Generation: Thumbnails are created for image and video files to display in the UI.

Sources: android/IMPLEMENTATION_SUMMARY.md:109-123

Conclusion

The file transfer system in Sovereign Communications is a well-architected feature designed for reliability and security in a decentralized environment. By using chunking with checksums, it ensures data integrity. The FileTransferManager provides robust control over the transfer lifecycle, including queuing, concurrency limits, and timeout handling, while the resume capability makes it resilient to network interruptions. Strict validation rules at the entry point prevent the transmission of malicious or overly large files, protecting both the user and the network. The system is fully integrated into the user experience on both web and mobile platforms.