1# Zig mirror
2
3The canonical artifact tree is `/srv/clover/Media/Software/Public/zig`.
4Copyparty publishes only `Software/Public` as anonymous read-only `/mirrors`;
5its existing authenticated `/media` and `/clover` mounts keep their permissions.
6The mirror container shares only the Zig subtree. Flat protocol URLs fetch
7missing files synchronously, then serve them locally; nested release/dev paths
8remain browsable through Copyparty.
9
10This is a personal IPv4 mirror at `https://file.paperclover.net/mirrors/zig/`.
11Clover explicitly chose to leave it unlisted and omit IPv6 publication.
12[Zig's public mirror contract](https://codeberg.org/ziglang/ziglang.org/src/branch/main/MIRRORS.md)
13requires both address families, so this deployment is not submitted to that list.
14No AAAA record or DDNS IPv6 change belongs to this rollout.
15
16The worker polls the official index every six hours and caches the latest stable
17release and current development build. A request for any uncached supported name
18checks its exact official URL immediately; a newly published release needs no
19manual trigger or wait for the poll. `refresh` runs the periodic operation on
20demand. Missing upstream files/timeouts return 504; saturated downloads return
21429. Downloads have four slots, a 2 GiB per-artifact ceiling, and a 16 GiB
22free-space reserve. Completed archives and signatures publish atomically after
23SHA-256 and/or Zig Minisign verification. Existing archive files need the
24one-time `verify` operation before first public exposure.
25
26## Release dates and navigation
27
28Indexed stable releases use the official download index's date at UTC midnight.
29The retracted 0.15.0 artifacts use authenticated signing time instead: the
30[official retraction](https://github.com/ziglang/www.ziglang.org/commit/1be0f80b15d256d42411a21f10e208f9b269a5e2)
31removed that release from the index. Other unknown stable releases fail closed.
32Development archives use the build timestamp from their Minisign trusted comment;
33its global Ed25519 signature is checked against Zig's pinned key before the date
34is accepted. The signature file receives the archive's date. Each visible folder,
35including the mirror root, uses its newest contained archive date. Empty folders,
36README files and hidden operational/history files do not contribute to that date.
37Every cache miss, periodic refresh and backfill uses this same publication path.
38
39Version folders contain an architecture/OS download table built only from present
40canonical artifacts and signatures. Released versions list Release Notes,
41Language Reference and Standard Library Documentation below their heading only
42when the official index publishes the corresponding `notes`, `docs` or `stdDocs`
43URL. No documentation URL is synthesized or probed per artifact. The index has
44one process-wide, lock-protected snapshot, expiring after an hour; periodic/manual
45refresh bypasses it, as does a cache miss for an unindexed stable version's date.
46Refresh also updates the current release/build navigation when archives are
47already cached, preserving artifact and folder dates.
48
49Released base versions show their artifacts without a development-build link; a
50base folder with only development builds says “this release only has development
51builds out.” Each development version links back to its index, whose heading
52leaves the native directory listing to show the builds. Complete existing
53relative-link tables are retained when their introduction matches the published
54links and navigation, removing the old standalone development-build link from
55released pages; incomplete or production-only links are replaced. The owner's
56root `preadme.md` and hidden history remain untouched.
57
58Existing verified archives need a one-time metadata reconciliation. It reads
59signature comments and file metadata, not archive bodies, and preserves atime,
60ownership and modes. Preview it first:
61
62```sh
63python3 /app/mirror.py reconcile > /alloc/metadata-proposal.json
64python3 /app/mirror.py reconcile --apply --journal /alloc/private-metadata-undo.jsonl
65python3 /app/mirror.py reconcile > /alloc/metadata-after.json
66```
67
68Retain proposal and undo files privately outside `/mirror`; never publish them
69through Copyparty. Apply fails closed on missing dates, unsafe paths or changed
70files. The journal is created exclusively with mode0600 and fsynced before any
71change. Its first record retains old metadata and replaced public README bytes;
72a second record captures completed inode/metadata states. A journal without the
73completion record requires recovery review. A guarded one-time undo must verify
74those completed identities and generated README bytes before restoring old
75metadata/docs; later writes must cause it to stop. Keep that recovery helper with
76the private deployment evidence, rather than adding an automatic rollback hook.
77
78The worker has only `FOWNER` beyond its normal capability set, allowing explicit
79historic dates on the existing UID3000-owned NAS folders without changing their
80ownership. Its root filesystem is read-only and its only writable external mount
81is the canonical Zig subtree. Download temporaries and locks stay beneath hidden
82`.mirror-locks`; they cannot change visible folder dates. Fresh worker previews
83start empty, disable polling and fetch public artifacts only when requested.
84
85## Production cutover
86
87The 2026-10-17 production inventory found 289,931,243,359 bytes / 10,063 files
88in `/srv/mirrors/zig`, on unencrypted `globe/mirrors`. The destination existed
89empty on encrypted `globe/clover/Media`, with more than 9 TiB available.
90These are different filesystems and encryption roots: neither atomic rename
91nor block cloning can perform the move. Both roots use group `chloe` (GID 3000).
92
93Confirm the host machine ID `691734bfb3c24b19ae66e5cacd17f5e2`, mounts, free
94space, and that no writer is changing the old tree. Copy without deleting the
95source:
96
97```sh
98findmnt -T /srv/mirrors/zig
99findmnt -T /srv/clover/Media/Software/Public/zig
100rsync -aHAX --numeric-ids --info=progress2 /srv/mirrors/zig/ /srv/clover/Media/Software/Public/zig/
101rsync -anHAXc --numeric-ids --itemize-changes --delete /srv/mirrors/zig/ /srv/clover/Media/Software/Public/zig/
102```
103
104The checksum dry run must report no differences. Preserve existing numeric
105ownership and ACLs; do not recursively chown the Media dataset. The destination
106root must retain group traversal/write access for the mirror's declared Clover
107group. Run the mirror image's `verify` command against the copied destination
108before publishing it. A disposable container can bind that exact subtree
109read-only. The checksum and authenticity passes may run concurrently with
110bounded CPU/I/O to reuse the filesystem cache. Both must finish successfully.
111Retain old `.hist` metadata privately; verify that public URLs cannot fetch it.
112
113Promote the reviewed configuration through `tools/deploy.py prod`. Do not replace
114containers by hand. Confirm anonymous GET/HEAD/Range on flat and nested URLs,
115anonymous upload/delete denial, authenticated existing shares, and that parent
116folders remain inaccessible. Only after copy verification and positive public
117checks, rename the original tree to `/srv/mirrors/zig-retired-<UTC>` and link
118`/srv/mirrors/zig` to the canonical NAS tree. Keep the retired tree as a recovery
119copy; this cutover never deletes it. The NAS tree is the only active mirror.
120
121## Backfill and manual refresh
122
123Inside the running mirror task, the same script exposes:
124
125```sh
126python3 /app/mirror.py verify
127python3 /app/mirror.py refresh
128python3 /app/mirror.py backfill
129python3 /app/mirror.py backfill --apply --budget-gib 32
130```
131
132Use the normal authenticated Nomad allocation exec path to run these. The
133no-`--apply` backfill lists missing artifact URLs without downloading them.
134The source is [Meghan's mirror](http://mirrors.nektro.net/zig/), which listed
135893 version directories on 2026-10-17. Stable files also check the official
136index hash; development files require Zig's signature. Invalid bytes never
137become public. The 32 GiB budget reserves the full per-artifact ceiling before
138each download and stops conservatively; rerun to resume, preserving cached
139files. Missing historical builds cannot be recovered from Zig once removed,
140so failed verification/downloads stop the batch for review.
141
142## Staging
143
144Both services use fresh previews. Copyparty mounts disposable directories instead
145of the live NAS and generates one clearly synthetic public archive. Mirror
146previews disable periodic downloads. A flat cache miss may fetch a public Zig
147artifact on demand for verification. The preview association lives in the
148Copyparty stage's `mirrorStage` metadata; an unpaired preview returns 503 for
149flat protocol URLs and never falls back to production.