Contributing to zig-http #
What someone changing this library needs to know that the README does not already say. The README explains what the library is and how it is tested; this is about how to work on it.
Where to send things #
Issues and pull requests go to the Tangled mirror:
- Issues: https://tangled.org/jcollie.dev/zig-http/issues
- Pull requests: https://tangled.org/jcollie.dev/zig-http/pulls
The repository also lives on Forgejo and on Radicle (see Where this lives), and all three carry the same history, but Tangled is where reports and changes are read.
A bug report is most useful with the octets that caused it. Almost every layer of this library can be driven from a slice of memory, so a request, a response or a frame sequence pasted into the report usually becomes the regression test for its fix.
The development environment #
Everything comes from the flake, including the Zig it is built with:
$ nix develop
main builds with Zig 0.17.0. The zig-0.16 branch is the last release for
Zig 0.16.0 and takes critical fixes only.
Before sending a change #
These are what CI runs, and a change should pass all of them:
$ reuse lint
$ zig fmt --check --exclude zig-pkg --exclude interop/https-records/zig-pkg .
$ zig build test --summary all
$ zig build check
$ zig build fuzz-run -- --iterations 60000
$ (cd interop/https-records && zig build test --summary all)
zig build check compiles what no test builds — the fuzz driver, the
documentation server and the demonstration program — so that one of them
cannot quietly stop compiling. The interop/https-records project is separate
because it depends on zig-dns-client, which depends on this library; see
its build file.
nix flake check runs the NixOS virtual machine tests described in
The virtual machine tests. They need
KVM and take a while, so CI runs them on every push and running them by hand is
worth it when a change touches what a real peer sees on the wire.
Tests #
Unit tests live next to the code they test. The suites under tests/ drive
whole exchanges; the README's Building and testing
says which does what.
Every public function has a doctest. A doctest is a test named by the
function, test name { ... }, in the same container as the function, which is
what the generated documentation shows as its example. Write it the way a
caller would use the function, with std.testing.expect* assertions on what
comes back. A few things about them are easy to get wrong:
- A test inside a nested type is only compiled if that type is analyzed. If
the test count does not go up by the number of tests added, the container
needs a
test { std.testing.refAllDecls(@This()); }or a_ = Type;to reach it.-Dtest-filter=is the quick way to see whether a test runs. - A doctest name has to resolve unambiguously. Where it cannot — a method sharing a name with a function in an enclosing scope — write a string-named test instead and say why in a comment.
- A test that writes to stderr fails the build step even when its assertions pass, so take any debugging output out before committing.
A bug fix comes with a test that fails without the fix. Name such a test after
the rule it pins — test "RFC 9114 4.1.2: a response to HEAD carries its length and no content" — and check that it really does fail on the old code, since a
test that never failed proves nothing.
Tests that need a socket listen on .loopback(0) and connect to themselves.
The Io is std.testing.io; transport.memory and
transport.memory_session.Scripted stand in for a connection or a QUIC
session where a test does not need a real one.
The README states how many tests there are. Keep it right, counting from a
clean .zig-cache: a build that reuses cached results counts only the tests it
ran.
Fuzzing #
tests/fuzz.zig holds the targets, each a property rather than an example
(see Fuzzing). A new parser, or a new path through an
existing one that takes input from a peer, wants a target or a seed for one.
For a longer search than CI does:
$ zig build fuzz-run -- --seconds 600
A finding is saved as a file and reported with its path; anything else that goes wrong is the tooling rather than a finding.
Dependencies #
Zig dependencies are added and moved with the package manager:
$ zig fetch --save=<name> git+https://...#<commit>
pinned to a commit. The Nix build cannot fetch, so after any change to
build.zig.zon regenerate the expression it builds from, and commit both:
$ zon2nix --17 --nix=build.zig.zon.nix build.zig.zon
The tls pin has to be the one zig-quic uses, so that the two resolve to one
module and their types are the same types. Moving zig-quic means checking its
build.zig.zon and moving tls with it if it moved.
How the code is written #
The four layers and the
two modules are the design, and
a change should keep to them: http is the protocol and owns no file
descriptor, and every octet reaches it through a transport.Connection or a
transport.Session. Anything that needs a socket belongs in http_io.
Nothing a peer sends may make this library panic. Check a value before
narrowing it into a smaller integer, since @intCast of out-of-range input is
a panic rather than an error, and treat every length a peer declares as a
claim to be checked against a limit.
The doc comments carry most of the explanation in this library, and the
published API documentation is generated from
them. A change that alters what a function does updates its doc comment in the
same commit. Where a rule comes from a specification, cite the section —
§4.1.2 of RFC 9114 — and quote it when the wording matters. Use the terms
GLOSSARY.md defines, and American spelling.
Licensing #
The project is MIT licensed and follows REUSE. A new
file starts with the SPDX header the others have; a file that cannot hold one,
such as a generated file or test data, is covered in REUSE.toml instead.
reuse lint checks both.
Commit messages #
The subject is a sentence saying what the change does — "Reset an HTTP/2 stream whose body fell short of its declared length" — and the body says why: what was wrong, how it showed, and what the fix is. One logical change per commit.
Releases #
A release sets the version in build.zig.zon and package.nix, commits that,
and tags the commit with a signed, annotated vX.Y.Z tag whose message says in
a line what the release brings. Before 1.0.0 the minor version goes up when
public API is removed or changed incompatibly, and the patch version for
anything else.