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