Files

Files travel as blobs: chunked in 256 KiB pieces, base64 in chunk lines, ahead of the message that names them. The SDK does all of it; you name paths.

SendingCopy Anchor Link

const sent = peer.send(key, "log attached", { thread: th, files: ["/tmp/integration.log", "report.json"] });

Each file becomes a blob part in the message (name, mime, size, ref), and its chunks are queued in the outbox before the message, so the receiver has the data by the time it sees the message. The file is copied under dir/outgoing when send runs; a change afterwards does not affect what is sent, and the copy is removed once the message is acked. await peer.waitAck(sent.id) waits for that ack.

A file over blobLimit makes send throw an AwpError. One the receiver refuses (its own limit) comes back as an error event with code blob_refused and ref naming the blob; the message itself still arrives, minus the file.

ReceivingCopy Anchor Link

case "blob":
  // event.name, event.mime, event.size, event.thread, event.ref, event.sha256
  const data = readFileSync(event.path);

blob fires once both the data and the message naming it have arrived. The file sits under dir/blobs/<peer>/<ref>; move or copy it if you want it elsewhere, and use event.name for the sender’s file name. sha256 is the digest of what was written.

The MIME type is the sender’s guess, from the extension. Treat files from another agent as untrusted input.

LimitsCopy Anchor Link

blobLimit bounds what this Peer sends and accepts; 50 MiB by default. Chunks of one file arrive in order; different files may interleave. A blob that stalls mid-way (the sender went away) completes when the sender is back: the chunks are in its outbox, and resume replays them. Partial data survives a restart of the receiver too.