Crate thincan_file_transfer

Expand description

File-transfer protocol helpers for thincan.

This crate provides Cap’n Proto message types and helpers for building a simple file transfer protocol on top of thincan.

§Integration steps

Define FileReq / FileChunk / FileAck in your bus atlas using schema owned types.
Implement Atlas for your atlas marker type.
Include FileTransferBundle in a thincan::maplet! bundle list.
Build maplet::Bundles::new(&iface) and call methods on the singleton bundle instance:
- sender: bundles.file_transfer.send_file(...) / send_file_with_id(...)
- receiver (alloc): bundles.file_transfer.recv_file(...)
- receiver (heapless): bundles.file_transfer.recv_file_no_alloc(...)

§Backpressure / throttling

Sender flow is ack-driven and windowed. Receiver flow only sends progress/completion acks after storage writes complete, so slow storage naturally throttles transfer rate.

§Runtime note

These methods rely on your external demux pump to feed incoming frames into the bus mailbox via BusHandle::ingest.

With --features heapless you can encode Cap’n Proto bodies without allocation:

let used = ft::encode_file_ack_into(
    &mut scratch,
    transfer_id,
    kind,
    next_offset,
    chunk_size,
    error,
    &mut out,
)?;
// Send `&out[..used]` as the body of your bus's `FileAck` message.

This crate is async-first and is designed for runtimes like embassy where storage I/O must not block the executor.

Re-exports§

pub use file_transfer_capnp as schema;

Modules§

file_transfer_capnp

Structs§

FileAckValue: Value type used to encode a FileAck message.
FileChunkValue: Value type used to encode a FileChunk message for a specific atlas marker type A.
FileOfferValue: Value type used to encode a FileReq message including metadata and chunk negotiation.
FileReqValue: Value type used to encode a FileReq message for a specific atlas marker type A.
FileTransferBundle: Bundle type for file-transfer protocol operations.
PendingAck: Ack message that the receiver side would like to emit.
ReceiverConfig: Receiver-side configuration.

Enums§

Error: Errors produced by the file-transfer state machine.

Constants§

DEFAULT_CHUNK_SIZE: Default chunk size (bytes) used by senders.
FILE_TRANSFER_MESSAGE_COUNT: Number of message types required by FileTransferBundle.

Traits§

AsyncFileStore: Async dependency required by the file-transfer bundle: a byte-addressable file store.
Atlas: Atlas contract for file-transfer message types.

Functions§

capnp_padded_len: Cap’n Proto “word padding” (Cap’n Proto Data blobs are padded to a word boundary).
capnp_scratch_words_for_bytes: Convert a byte count to a conservative Cap’n Proto scratch requirement (words).
file_ack_accept
file_ack_max_encoded_len: Upper bound for an encoded FileAck body (bytes).
file_ack_progress
file_ack_reject
file_chunk: Convenience constructor for FileChunkValue.
file_chunk_max_encoded_len: Upper bound for an encoded FileChunk body (bytes).
file_offer: Convenience constructor for FileOfferValue.
file_offer_max_encoded_len: Upper bound for an encoded FileReq body (bytes) with metadata.
file_req: Convenience constructor for FileReqValue.
file_req_max_encoded_len: Upper bound for an encoded FileReq body (bytes) without metadata.