From b31aa542738f8c7eb7a9c43c4e2b7bbac969b1a8 Mon Sep 17 00:00:00 2001 From: mlugg Date: Fri, 13 Sep 2024 12:28:01 +0100 Subject: [PATCH] README: add documentation on adding mirrors --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/README.md b/README.md index d88a858..16b4f66 100644 --- a/README.md +++ b/README.md @@ -59,3 +59,68 @@ verified to ensure binaries have not been tampered with. The tarball is cached b The global Zig cache directory (`~/.cache/zig` on Linux) is automatically cached between runs, and all local caches are redirected to the global cache directory to make optimal use of this cross-run caching. + +## Adding a mirror + +Anyone is welcome to host a Zig download mirror; thanks to the tarball signatures, the mirror provider need +not be trusted. Naturally, if a mirror is found to be a bad actor, it will be removed, and likewise if a +mirror repeatedly encounters reliability problems. + +The rules for adding a mirror are listed below. Note that I (@mlugg) reserve the right to, for any or no +reason, exclude mirrors which obey these rules, or include mirrors which violate them. + +> [!NOTE] +> While there are a lot of rules listed here, most of them should be obvious. They are stated explicitly here +> to ensure complete clarity on what is expected of a mirror. Please do read these requirements through before +> attempting to add a mirror. + +* A mirror provides a single base URL, which we will call `X`. +* `X` **may** include a path component, but is not required to. For instance, `https://foo.bar/zig/` is okay, + as is `https://zig.baz.qux/`. +* The mirror **must** have working HTTPS support. `X` **must** start with `https://`. +* The mirror **must** cache tarballs locally. For instance, it may not simply forward all requests to another + mirror. +* The mirror **may** routinely evict its local tarball caches based on any reasonable factor, such as age, + access frequency, or the existence of newer versions. This does not affect whether the mirror may return 404 + for requests to these files (see below). +* The mirror **must** download its tarballs from either `https://ziglang.org/`, or another mirror which + follows these rules. +* Tarballs **must** be accessible by sending GET requests for files under `X`, where the filename matches that + of the files provided by `https://ziglang.org/`, not including the directory part. For instance, + `X/zig-linux-x86_64-0.13.0.tar.xz` is a valid access, and should return the same file as + `https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz`. +* Files provided by the mirror **must** be bit-for-bit identical to their `https://ziglang.org/` counterparts. +* If a file is accessed whose Zig version is a master branch build (i.e. a `-dev` version), and the version is + ordered before the latest major release of Zig, the mirror **may** respond with 404 Not Found, but is not + required to. For instance, at the time of writing, `0.13.0` is the latest major release of Zig, so a mirror + may respond with 404 for `0.13.0-dev...` builds, but *not* for `0.14.0-dev...` builds. +* If a file is accessed whose Zig version is `0.5.0` or below, the mirror **may** respond with 404 Not Found, + but is not required to. +* If a file is acccessed which represents a *source* tarball, such as `X/zig-0.13.0.tar.xz`, the mirror + **may** respond with 404 Not Found, but is not required to. The same applies to "bootstrap source tarballs", + such as `X/zig-bootstrap-0.13.0.tar.xz`. +* For all other accesses of valid Zig tarballs, the mirror **must** respond with status code 200 OK and the + file in question. If the mirror has not yet cached the file locally, it should immediately download it from + a permitted source (as covered above), and respond with the downloaded file. +* If a tarball `X/foo.ext` is available by the above rules, requesting the minisign signature file + `X/foo.ext.minisig` **must** also respond with status code 200 OK and the signature file in question, like + the tarball itself. +* The mirror **may** rate-limit accesses. If an access failed due to rate-limiting, the mirror **should** + return HTTP status code 429 Too Many Requests. +* The mirror **may** undergo maintenance, upgrades, and other scheduled downtime. If an access fails for this + reason, where possible, the mirror **should** return HTTP status code 503 Unavailable. The mirror **should** + try to minimize such downtime. +* The mirror **may** undergo occasional unintended and unscheduled downtime. The mirror **must** go to all + efforts to minimize such outages, and **must** resolve such outages within a reasonable time upon being + notified of them. +* The mirror **may** observe the `?source=github-actions` query parameter to track how many requests originate + from this Action. This Action will provide this query parameter to all mirror requests. + +The easiest way to set up a mirror right now is using Mach's [Wrench][wrench]. For instructions, please see +[the relevant section of their README][setup-wrench]. + +[wrench]: https://github.com/hexops/wrench +[setup-wrench]: https://github.com/hexops/wrench?tab=readme-ov-file#run-your-own-ziglangorgdownload-mirror + +After setting up a mirror, you can add it to this GitHub Action by opening a PR which adds it to the list in +[mirrors.json](https://github.com/mlugg/setup-zig/blob/main/mirrors.json).