README: add documentation on adding mirrors

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).