An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
zig-http CONTRIBUTING.md
7.1 kB · 172 lines
Markdown
at main

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:

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.