mlugg/setup-zig
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README: add documentation on adding mirrors

Browse Source
This commit is contained in:
mlugg
2024-09-13 12:50:35 +01:00
parent b92374239f
commit b31aa54273
1 changed files with 65 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+65
View File
@@ -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).