Command Line Interface

Two binaries are provided: zyncmake publishes a file, and zync fetches it.

Install them with Zoi:

zoi install @zillowe/zync

Or from Crates.io:

cargo install --locked zync-cli

Or from source:

cargo build --release -p zync-cli

zyncmakeCopy Anchor Link

Writes a .zsync control file describing a file, and with --delta a .zdelta sidecar for the regions a base file differs in.

./zyncmake <FILE> [OPTIONS]

Options:

• -o <FILE>, --output <FILE>: Write the control file here. Defaults to FILE.zsync beside the input.
• -u <URL>, --url <URL>: Record where clients should fetch from. Defaults to the file's own name. Repeat for mirrors, which a client tries in the order given.
• -b <BYTES>, --blocksize <BYTES>: Block size, a non-zero power of two. Defaults to 2048, or 4096 for a gigabyte or more.
• -m, --mtime: Record the file's modification time. Purely informational.
• --delta <BASE>: Also write a sidecar, differenced against this base file. Repeat for more than one base.
• --delta-output <FILE>: Write the sidecar here. Defaults to the control file's path with its extension replaced.
• --max-region <BYTES>: Refuse to carry a sidecar region larger than this. Defaults to 64 MiB.
• -d, --dry-run: Report what would be written without writing it.

An empty input is refused: a control file cannot describe zero blocks.

./zyncmake image.bin -u https://example.com/image.bin --delta image.bin.old

zyncCopy Anchor Link

Reconstructs a file from a control file and whatever local copies hold.

./zync <CONTROL> [OPTIONS]

CONTROL is a URL or a path to a control file on disk.

Options:

• -o <FILE>, --output <FILE>: Write the result here. Defaults to the name the control file advertises, or the last segment of its URL.
• -i <FILE>, --input <FILE>: Reuse blocks from this local file. Repeat for several; every block any of them holds is kept.
• --delta <URL>: Rebuild missing regions from this sidecar. Defaults to the control file's URL with its extension replaced.
• --no-delta: Ignore the sidecar and fetch every missing block.
• --range-gap <BYTES>: Bridge two missing ranges separated by no more than this. Defaults to 262144.
• --attempts <N>: Retry a range whose blocks fail verification at most this many times. Defaults to 3.
• -d, --dry-run: Report what would be fetched without fetching it.
• -v, --verbose: Report each block as it is recovered.

./zync https://example.com/image.zsync -i image.bin.old -o image.bin

What a server needsCopy Anchor Link

Only the target file, and working range requests. Nothing about .zsync files. A server that ignores the range header and answers with the whole file is handled: the client discards the bytes before the requested offset.

A server that cannot answer ranges at all is not handled, and the transfer fails rather than silently assembling the wrong bytes.

Reading the outputCopy Anchor Link

recovered 877 blocks from image.bin.old (877/977)
target: image.bin (2000000 blocks, 977) — 1792000 of 2000000 bytes held
to fetch: 204800 bytes across 100 blocks
fetched 0 bytes in 0 requests; 204800 bytes rebuilt from the sidecar

The last line is where the sidecar shows up: nothing was transferred, because the regions were rebuilt from patches instead.

Exit statusCopy Anchor Link

0 on success, 1 on a usage, transport, control file, sidecar, or verification error. A failed transfer leaves no output file behind.