Repository navigation
Releases
v0.1.0
What's Changed
- Speed: parallel hash + hash cache + parallel uploads + 256 KiB chunks by @Urdemonlord in #1
- Security: refuse unverified --ip, add --tofu; sync --replace by @Urdemonlord in #2
- Release 0.1.0: distribution + version bump by @Urdemonlord in #3
New Contributors
- @Urdemonlord made their first contribution in #1
Full Changelog: v0.0.24...v0.1.0
v0.0.24 — the share page, after a browser looked at it
v0.0.24 — What four screenshots found
v0.0.23 shipped a share page. It passed 24 shell checks and looked finished in
curl output. Then it was opened in Chromium at 390 px and 1100 px, and four
things were wrong that no shell check could see.
1. The summary line was invisible, and the disk path was public
The file count and total size went into <title>, so a visitor saw a page with
a wordmark and no explanation. Worse, the <title> was built from the share
directory, so /var/tmp/acme/secret — the operator's path — was rendered into a
page served to whoever held the link.
- let summary = format!("{} file(s), {} — {}", …, root.display());
+ let summary = format!("{} file(s), {}", …); // no path, ever
+ &format!("<p>{summary}</p><table>{body}</table>") // visible, where a human reads2. 4 file(s)
file(s) is what you write when you cannot be bothered. Two branches, four
lines:
let summary = match rows.len() {
1 => format!("1 file, {}", crate::human_bytes(total)),
n => format!("{n} files, {}", crate::human_bytes(total)),
};3. A path was indistinguishable from a file name
A nested file kept its relative path — sub/catatan-rapat-produk.txt — inline,
same size, same colour except a dimmed prefix. On a phone that wrapped mid-name,
and it read as one filename that happens to contain a slash. Colour alone as the
only cue also fails WCAG 1.4.1.
The folder now gets its own line above the name, smaller and dimmer; the
structure carries the meaning, not the hue.
4. The download arrow slid around
↓ 1.1 MiB, ↓ 293.0 KiB, ↓ 14 B were one right-aligned run, so the arrow
sat at a different x in every row and the eye caught a ragged edge. Two fixed
slots — glyph, then a fixed-width right-aligned number — put all four arrows on
one axis.
What was checked
cargo build --releaseclean; 15 unit, 31 compat, 28 json, 25 pull-resume,
29 hosts, 19 pull, 17 resume, 52 fan-out, 25 sync, 24 page — 265 checks, all
green; daemon e2e run separately, no failures- the page was rendered by real Chromium (headless, in the sandbox — nothing
installed on the production host) at phone and desktop width, and re-read from
the resulting PNGs after every fix
What is not claimed
-
The page has not been exercised on a real Windows kernel. WinPE has no
curl.exe, so the HTML cannot be fetched from inside the VM. What is
checked is the shipped.exeitself, running under wine in the sandbox:$ zapsend.exe --version -> zapsend 0.0.24 $ GET / (no PIN) -> the PIN form $ GET /?pin=4242 -> <p>2 files, 4.0 KiB</p>, blob.bin, sub/ label $ leaked paths in the page -> 0 $ GET download link -> sha256 matches the source filewine is not Windows: this proves the binary and the HTML it serves, not the
kernel. -
No bulk "download all", no file-type icons, no desktop-specific layout. A
share page for a handful of files does not need them; the empty space on a
wide screen is honest about how little there is to show.
v0.0.23 — The page a human can open, and one flag for agents
v0.0.23 — The page a human can open, and one flag for agents
Two gaps this release closes were found by reading the competition, not by
guessing: lsq hands out a share link that opens in any browser, and lsend
has --json everywhere with an agent-shaped docs command. Both were real.
A share link a browser can actually open
$ zapsend receive --share ./photos --pin 424242
sharing ./photos (Download API on)
$ curl -k https://box:53317/
<!doctype html>… <table><tr><td><a href="/api/localsend/v2/download?…">report.txt</a></td>…
GET / now serves a plain page: every shared file, its size, and a link that
downloads it. Same port, same PIN, same listener — no extra port and no extra
surface. Without --share there is no page at all (still 404).
- no scripts, no fonts, no CDN: it has to work on a network with no internet
- file names are HTML-escaped, links are percent-encoded, so
evil <b>.txtis
a name, not markup - the PIN rides in the query string (
/?pin=…), because a browser cannot send a
header of our invention; wrong PIN gets a form, not a hint - the download links carry the same short-lived session id as the API, so a page
open for an hour is not an open file server
ZAPSEND_JSON=1
--json was already on every one-shot command, but an agent driving ten commands
had to remember ten flags. The environment variable sets it once:
export ZAPSEND_JSON=1
zapsend discover | jq -r '.devices[].alias'Auto-detecting a pipe, the way lsend does, was considered and rejected: it
would silently rewrite the output of every script that already reads ours.
Verified
test_page.sh: 22 checks — page only with--share, listing flat and
nested files, name escaping, real downloads with matching SHA-256,../and
dotfile requests refused, unknown session 403, PIN form / right PIN / wrong
PIN, env JSON on and off.- Full suite: 15 unit, 31 compat, 28 json, 25 pull-resume, 29 hosts, 19 pull,
17 resume, 52 fan-out, 25 sync, 22 page, 11 interop. - WinPE 10.0.26100.1742 (round 16):
--version0.0.23,send3,000,000 B
exit 0 against a share-enabled receiver. The page itself was not fetched
from that environment — WinPE ships neithercurlnor PowerShell — so browser
rendering is verified on Linux only.
v0.0.22 — Two bugs that only another implementation could find
v0.0.22 — Two bugs that only another implementation could find
Every test until now put zapsend on both ends. That proves the code agrees with
itself, which is not the same as speaking the protocol. So this release was
checked against lsq, a Rust LocalSend client written by someone else
(AlexDevFlow/lsq), in all three
directions. Two real bugs fell out on the first run.
1. The port you asked for was thrown away
zapsend send file.bin --ip 127.0.0.1:53320
# sending 2 file(s) to "lsq-recv" (127.0.0.1:53317) ← not the port given
# tcp connect error: Connection refusedAfter /info, the client copied the port the peer announced over the port it
had just successfully connected to. When those differ, the announced port is the
one thing not proven to work. It now keeps the address that answered; the
announced port is ignored. Same fix in pull and trust.
Our own receiver announces its real port, so nothing we wrote could ever have
caught this.
2. pull could not talk to a peer serving the Download API over HTTP
error: received corrupt message of type InvalidContentType
lsq share serves its downloads over plain HTTP. send already retried on the
other scheme when the TLS handshake failed; pull did not. It does now, and the
retry sticks for the downloads that follow.
pulling 2 file(s) from "lsq-share" into out-c
{"ok":true,"count":2,"transferred":2000014}
Interop is now a test, not a claim
tests/interop-lsq.sh downloads that binary and checks three directions with
SHA-256 on both ends — 11 checks:
| direction | who is on the other side |
|---|---|
zapsend send → lsq receive |
their receiver, our sender |
lsq send → zapsend receive |
their sender, our receiver |
zapsend pull ← lsq share |
their Download API, our client |
README told two lies, both fixed
- "Nobody filled that slot. Zapsend does." — false.
localsend-rs,lsq,
lsend-cliandlocalsndall exist. The README now names them, says to pick
one of them for a single transfer, and argues only for the fleet case. - "No resume yet: a dropped connection means starting over." — stale since
v0.0.14. Replaced with the limits that are true:synccannot replace a file,
andsyncneeds a zapsend receiver.
Verified
- Windows build on WinPE 10.0.26100.1742:
sendto a non-default port
10.0.2.2:53485(5,000,000 B, exit 0) andpullfrom it (2 files,
transferred:1000018, exit 0) — the exact shape of bug 1. - VPS → sandbox, 20 MB, over a real TCP hop (ssh tunnel; the sandbox is not
routable), SHA-256 identical on both machines. - Suites: 15 unit, 31 compat, 28 json, 25 pull-resume, 29 hosts, 19 pull, 17
resume, 52 fan-out, 25 sync, 11 interop.
v0.0.21 — Sync: send only what is missing
v0.0.21 — Sync: send only what is missing
The last of the three. daemon pushes whatever appears; sync pushes what the
other side does not already have, so running it again is cheap enough for cron.
zapsend sync ./out --to gpu-box # push the difference
zapsend sync ./out --to gpu-box --dry-run # say what would move
zapsend sync ./out --to gpu-box --json{"ok":true,"command":"sync","scanned":2,"sent":2,"skipped":0,"bytes":15,
"conflicts":[],"dryRun":false,"dir":"./out","peer":{...}}It has to ask, because LocalSend cannot answer
LocalSend has no "what do you hold?" call, so sync asks
GET /api/zapsend/v1/manifest — a zapsend-only endpoint on the receiver that
lists every file in its folder as path → {size, sha256}. Against a plain
LocalSend app that endpoint is simply not there, and sync says so:
zapsend does not answer /api/zapsend/v1/manifest — it is probably a plain
LocalSend app, which cannot say what it already has; use `zapsend send` instead
An unanswered question is not an empty answer. Assuming "empty" would re-send
the whole folder every night and call it a sync.
The manifest costs a read of the peer's folder (it hashes what it holds), which
is the honest price of not transferring everything. The receive side skips dot
entries and symlinks: .partial bookkeeping and a link out of the tree are not
content.
It will not overwrite, so it refuses instead
LocalSend's upload has no replace. A file that exists on the peer with different
bytes would arrive as report (1).csv, and the two sides would then disagree
forever — every later run would see "different" again and add another copy.
So that case is a conflict: nothing is sent, the path is named, and the run
exits 1.
! a.txt: different content on the peer — LocalSend cannot replace a file, resolve it by hand
Same size is not treated as "same file": the local SHA-256 is compared with the
peer's, because a build that rewrites a report with the same length is exactly
the change worth catching.
Verified
Windows build on WinPE 10.0.26100.1742 against a Linux receiver on this same
version, two runs in a row:
first {"scanned":2,"sent":2,"skipped":0,"bytes":15} exit=0
second {"scanned":2,"sent":0,"skipped":2,"bytes":0} exit=0
--- what the Linux receiver holds:
./a.txt
./sub/b.txt
The subfolder survived the trip. Linux suite: 25 sync checks — manifest
contents, PIN required, tree preserved, identical file not duplicated, second
run sends nothing, differing file becomes a conflict and leaves exactly one copy
on the peer, --dry-run writes nothing — plus 15 unit, 31 compat, 28 json, 25
pull-resume, 29 hosts, 19 pull, 17 resume, 52 fan-out, and the daemon
walkthrough.
The fleet story so far
| command | shape |
|---|---|
send --to a,b |
push a file or folder to several hosts now |
pull --to a,b |
collect from several hosts into dir/<name>/ |
daemon --to a,b |
watch a folder, push each new file to all of them |
sync --to a |
push only the difference, safe to re-run from cron |
Next candidates: sync --to a,b (the same list rule as everywhere else), a
doctor check for the Windows firewall, and running the sync from a systemd
timer on the box that produces the files.
v0.0.20 — Watch a folder, feed a fleet
v0.0.20 — Watch a folder, feed a fleet
daemon already watched a folder and pushed what appeared in it. It could only
push to one machine, which made it useless for the case it was written for: an
agent on one server producing output for three others.
zapsend daemon --dir ./outbox --to gpu-box,edge-1,edge-2
zapsend daemon --dir ./outbox --to all watching ./outbox (every 2s)
target gpu-box,edge-1,edge-2
after send move to ./outbox/.sent
✓ run-42.tar.zst (1 file(s), 1.2 MB) → gpu-box, edge-1, edge-2 → ./outbox/.sent/run-42.tar.zst
Only "done" when every target has it
A file moves to .sent when all targets acknowledged it. Until then it stays
in the folder, which is the queue: nothing is written anywhere else, and a
restart picks up exactly what is still missing.
The important part is what does not happen. Delivery progress is tracked per
file per target, so a file that reached two of three peers is only sent to
the third on the next tick. Re-sending to the two that already had it would
leave the receiver with report.csv and report (1).csv — duplicates are worse
than a late delivery, because nobody cleans them up.
! again.txt: ghost: connection refused — kept for the next tick
✓ hello.txt (1 file(s), 38 B) → g1, g2 → ./outbox/.sent/hello.txt
A target that fails is named once per file (not once per tick, so a dead peer
does not fill the log), the rest of the fleet still gets the file, and the error
is retried every tick. --pin overrides every target; without it each host uses
the PIN remembered by zapsend trust.
Verified
Windows build on WinPE 10.0.26100.1742 pushing to a Linux receiver on this same
version, two names in one list:
✓ watched.txt (1 file(s), 38 B) → w1, w2 → \\?\C:\out\.sent\watched.txt
--- what is left in the folder
.sent
watched.txt
Both hops landed on the Linux side with identical hashes
(2f0f881f… and 2f0f881f…), and the watched file was gone from the folder
root. Linux suite: 52 fan-out checks — including "one dead target keeps the
file queued, and does not duplicate it on the live one" — plus 15 unit, 31
compat, 28 json, 25 pull-resume, 29 hosts, 19 pull, 17 resume, and the original
single-target daemon walkthrough.
Next
sync DIR --to host is the last piece: send only what the other side does not
have, so re-running it is cheap and a nightly cron is enough.
v0.0.19 — Pull from the whole fleet
v0.0.19 — Pull from the whole fleet
The other half of v0.0.18. send could already fan out; pull could only ask one
machine at a time.
zapsend pull --to gpu-box,edge-1,edge-2 --dir ./collected --json
zapsend pull --to all --dir ./collected # every host in the hosts file{
"ok": true, "command": "pull", "count": 3, "failed": 0,
"files": 7, "bytes": 4194304, "transferred": 4194304,
"peers": [
{"name": "gpu-box", "ok": true, "dir": "./collected/gpu-box", "count": 4, ...},
{"name": "edge-1", "ok": true, "dir": "./collected/edge-1", "count": 2, ...},
{"name": "edge-2", "ok": true, "dir": "./collected/edge-2", "count": 1, ...}
]
}Each peer gets its own directory
--dir is a parent: every peer writes into --dir/<name>/. Two machines that
both have a report.csv must not overwrite each other, and a fleet pull that
silently drops one of them is data loss. --file still filters by name or id
inside each peer.
What it does when a peer cannot serve
--to all is the case that matters, because it sweeps in machines that are
trusted but not sharing anything:
→ a (10.0.2.2)
✗ a: "zapsend" does not offer the Download API — its receiver needs `--share DIR`
→ d (127.0.0.1)
✓ from-linux.txt (18 B)
{"ok":false,"failed":3,"files":2,...}
{"error":"3 of 5 peer(s) failed","ok":false}
Exit 1, the peers that could serve delivered their files, and each failure
carries its own reason. A name that was never trusted is reported as such and
does not stop the rest.
Shape of the JSON
- One target — unchanged:
{"command":"pull","peer":{...},"files":[...], "count":<files>,"bytes":...,"transferred":...}. Nothing that already parses
pull --jsonbreaks. - A list — adds
peers[], andcount/failedcount peers whilefiles
is a number. Per-peer file arrays are inpeers[].files. Exit0only when
every peer delivered every file it had.
Verified
Windows build on WinPE 10.0.26100.1742 pulling from a Linux peer running the same
version, two names into two directories:
pulling 1 file(s) from "zapsend" into C:\pulled\w1
pulling 1 file(s) from "zapsend" into C:\pulled\w2
{"ok":true,"count":2,"failed":0,"files":2,"bytes":36,"transferred":36,...}
exit=0
C:\pulled\w1\from-linux.txt
C:\pulled\w2\from-linux.txt
from-linux-on-019
Linux suite: 43 checks for fan-out (send list, pull list, all, dead peer,
untrusted name, both back-compat JSON shapes), plus 15 unit, 31 compat, 28 json,
25 pull-resume, 29 hosts, 19 pull, 17 resume.
Next
watch DIR --to a,b (push what appears) and sync DIR --to host (send only what
changed) are the two that make this useful without a human typing commands.
v0.0.18 — One command, a whole fleet
v0.0.18 — One command, a whole fleet
Until now send took one peer. Five machines meant five commands, five PINs to
remember, five logs to read, and no single answer to "did it work?".
zapsend send ./run-42.tar.zst --to gpu-box,edge-1,edge-2 --json{
"ok": true, "command": "send", "count": 3, "failed": 0,
"bytes": 1048576, "delivered": 3145728,
"peers": [
{"name": "gpu-box", "ok": true, "alias": "gpu-box", "ip": "100.64.0.7", "port": 53317, "bytes": 1048576},
{"name": "edge-1", "ok": true, ...},
{"name": "edge-2", "ok": true, ...}
]
}bytes is the file, delivered is what the fleet actually absorbed. Exit code
0 only when every name got the files.
What it does when something is wrong
A fleet push must not be all-or-nothing. One dead machine should not cost the
other four their delivery, and it must not be silent either:
sending 1 file(s), 19 B to 2 peer(s)
→ w1 (10.0.2.2:53485)
✓ w1
✗ nope: not in the hosts file — `zapsend trust nope --ip <addr>` first
{"ok":false,"failed":1,"delivered":19,...}
{"error":"1 of 2 peer(s) failed","ok":false}
Exit 1, the good delivery stands, the bad name is named. A peer that times out
or refuses is reported the same way, with its error attached to its own entry.
Decisions worth naming
- Names come from the hosts file, not from discovery. A scan answers "who is
nearby?" and a human picks one; that is the opposite of unattended.zapsend trustonce per machine, then a list works forever. - Sequential, not parallel. One uplink shared by three simultaneous uploads
is slower for everyone, and a fleet push is usually logs and artifacts. When
there is a real case for parallel, it becomes--parallel N, not the default. - Each host keeps its own remembered PIN.
--pinoverrides all of them for
the odd fleet that shares one. - A single name keeps the old JSON shape.
{"peer": {...}}with nopeers
array, so nothing that already parsessend --jsonbreaks.
Verified
Windows build, WinPE 10.0.26100.1742 under QEMU, two names pointing at one Linux
peer: both delivered, delivered 38 for two 19-byte files, exit 0; then
--to w1,nope → w1 delivered, nope reported, exit 1, and the files were
found on the Linux side.
Linux suite: 25 checks for fan-out (delivery to all names, dead peer, untrusted
name, single-name JSON shape), plus the rest unchanged — 15 unit, 31 compat, 28
json, 25 pull-resume, 29 hosts, 19 pull, 17 resume.
Still missing for a real fleet
pull --from all (the other half), watch (push what appears), and sync
(send only what changed). Fan-out is the first of those three because everything
else composes on top of it.
v0.0.17 — pull --json says what the transfer cost
v0.0.17 — pull --json says what the transfer cost
"bytes" in pull --json was the sum of the file sizes. That is the size of
what landed on disk, not what the transfer cost — and for the case this tool
exists for (an interrupted transfer that resumes), the two numbers differ by
exactly the interesting amount.
zapsend pull --to gpu-box --dir ./results --json | jq '{bytes, transferred}'{ "bytes": 300000000, "transferred": 280000000 }That is a 300 MB file whose first 20 MB were already on disk: it cost 280 MB of
traffic. A fresh pull of the same file reports transferred equal to bytes.
The counter is incremented per body chunk as it is read, so it includes work that
was later thrown away — a corrupt partial that had to be discarded, a retry after
a dropped connection, a resumed download that started over because the peer sent
the whole file. It is the honest number to bill, throttle or log against.
"bytes" is unchanged, so nothing that already parses pull --json breaks.
Verified
The Windows build in this release, on WinPE 10.0.26100.1742 under QEMU
(-cpu max), pulling 314,572,817 B from a Linux peer:
{"bytes":314572817, ..., "transferred":314572817}Resumed download on Linux, 300 MB file with a 20 MB partial already present:
bytes = 300000000
transferred = 280000000
sha256 = matches the source
Host suites: 15 unit, 31 compat, 28 json, 25 pull-resume (four new checks
cover this field), 29 hosts, 19 pull, 17 resume.
One process fix behind the numbers
The local test harness defaulted to a prebuilt binary in a scratch directory, and
that binary was three versions old — so a suite could pass while the change under
test was not in the binary at all. Each harness script now refuses to run when
the binary's --version does not match Cargo.toml.
v0.0.16 — Transfers that outlive the clock
v0.0.16 — Transfers that outlive the clock
One bug, found on real Windows, and one protocol answer that was lying.
The 30-second wall
The HTTP client bounded the whole request with .timeout(30s). Any transfer
that needed longer than half a minute died mid-flight — 300 MB at 5 MB/s over
Tailscale is a full minute, which is exactly the VPS-to-laptop case zapsend is
for.
What it looked like on the wire, from a 300 MB upload out of a WinPE guest:
upload failed for big.bin: operation timed out ← 217 MB already stored
↻ big.bin — receiver already has 217.1 MiB, resuming
! upload rejected for big.bin (500): incomplete: 227618816 of 314572800 bytes
stored — resume at offset 227618816
! big.bin changed since the last attempt — starting over
Three things were wrong in a row. The receiver kept draining the body after the
client gave up, so the offset it reported next time was ahead of the one the
client resumed from. That mismatch looked like a different file, so the client
restarted from zero — and hit the same wall again. A big file could never
finish.
connect_timeout(10s) still fails fast when a peer is down. read_timeout(60s)
is per-read inactivity: a peer that stops sending still fails, a slow one is
allowed to finish. There is no longer any limit on how long a transfer may take.
A short body is 409, not 500
A body that arrived short of its declared size used to be answered with 500 Internal Server Error. Any peer reads 500 as the server is broken, so it
retries from zero. The receiver was fine — the transfer simply was not finished.
It now answers 409 Conflict with the offset to continue from:
incomplete: 227618816 of 314572800 bytes stored — resume at offset 227618816
Clearer words when the kept partial is not this file
When the receiver holds bytes that are not a prefix of the file being sent, the
client throws them away and starts over (safe — splicing two files would be
worse). It used to say big.bin changed since the last attempt, which blames
the file. It now says what actually happened:
! big.bin — the partial the receiver kept is not this file, starting over
Verified
The exact artefacts in this release ran on a real Windows kernel — WinPE
10.0.26100.1742 under QEMU, -cpu max:
zapsend 0.0.16
trust wbox --ip 10.0.2.2:53485 --pin 4242 --json → fingerprint pinned
receive --dir C:\inbox --port 53486 --pin 4242 → → incoming: 1 file(s)
✓ saved C:\inbox\laporan akhir.txt
pull --to wbox --dir "C:\pulled dir" --json → {"ok":true,"bytes":314572817}
send "C:\pulled dir\big.bin" --to wbox --json → {"ok":true,"bytes":314572800}
The 300 MB file was pulled out of a Linux peer and pushed back, then compared on
the Linux side:
original 314572800 B sha e6ab3bb898cc0a49dbd7bf872659daf2711c54b968482e3039af0aae6a748c48
returned 314572800 B sha e6ab3bb898cc0a49dbd7bf872659daf2711c54b968482e3039af0aae6a748c48
Byte-for-byte identical, through the Windows build, in both directions.
Host suites unchanged: 15 unit, 31 compat, 28 json, 21 pull-resume, 29 hosts,
19 pull, 17 resume.
What this release does not prove
- A push into the WinPE guest from another machine. QEMU's slirp accepts
the host-side TCP connection, but the guest never answers, and WinPE cannot be
told to allow it:wpeutil DisableFirewallfails with0x8007007e,netsh
has noadvfirewallcontext, andsc.exeis absent. The receiving side
itself is proven by the loopback transfer above. On a normal Windows install
one command opens the port:
New-NetFirewallRule -DisplayName zapsend -Direction Inbound -Protocol TCP -LocalPort 53317 -Action Allow - The resume-upload path when the receiver's partial is not a prefix of the
file. There is no endpoint to drop a stale.part, so the client starts the
file over. Safe, but blunt. "bytes"inpull --jsonis the sum of the file sizes, not bytes on the wire.
Wire format is unchanged from v0.0.15; 409 and the incomplete: body are
zapsend extensions alongside /resume and /verify-download, and a peer that
does not know them just sees a failed request.