From c651f4291f0467766c045a69a647f769229f5ce7 Mon Sep 17 00:00:00 2001 From: korya <148461+korya@users.noreply.github.com> Date: Fri, 7 Aug 2026 21:36:53 -0400 Subject: [PATCH 1/2] docs(godoc): Document the command in the package comment pkg.go.dev showed "There is no documentation for this package" for every version published so far, because main carried no doc comment. The README links to that page with a Go Reference badge, so the badge advertised documentation that did not exist. Covers what the tool is for, the shape of an invocation, the exit codes, and which options read the environment -- the four things somebody landing on pkg.go.dev from the badge is trying to find out. The exit codes are the part worth writing down. They are the tool's actual output, and the distinction between a failed assertion and a tool that could not run is what lets a pipeline tell a broken service from a broken invocation. Documentation only; no behaviour change. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_019EMMhgmTkbzAsmeNy97PrP --- main.go | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/main.go b/main.go index e4b3066..f9c4eb1 100644 --- a/main.go +++ b/main.go @@ -1,3 +1,40 @@ +// Command http-assert performs an HTTP request and asserts properties of the +// response, exiting non-zero when an assertion fails. +// +// It is built for the places where a failing exit code is the whole point: a +// pipeline step, a container healthcheck, a monitoring script. Assertions are +// declared as flags, and the request is made once and checked against all of +// them. +// +// http-assert --assert-ok https://example.com +// http-assert --assert-status 201 -X POST -d '{"n":1}' https://api.example.com/things +// http-assert --assert-header 'Content-Type: application/json' \ +// --assert-body '"ok":true' https://api.example.com/health +// +// # Exit codes +// +// The exit code is the result. Distinguishing a failed assertion from a tool +// that could not run is what lets a pipeline tell a broken service from a +// broken invocation. +// +// 0 every assertion passed +// 71 a flag or environment value failed to parse +// 91 the request could not be constructed from the method and URL +// 93 the request failed, or at least one assertion did +// 103 wrong argument count, or an unknown flag +// +// # Environment +// +// Six options also read the environment, as HTTP_ASSERT_ with dashes +// replaced by underscores: --verbose, --silent, --log-level, --insecure, +// --max-time and --maphost. The command line wins over the environment, which +// wins over the default. A value that does not parse is rejected rather than +// coerced, so a typo fails loudly instead of silently disabling the option it +// was meant to set. +// +// The remaining options are command-line only. Repeatable options split one +// variable on whitespace, which suits host mappings and would corrupt header +// values. package main import ( From 37c8f91a998447549a8070aac6c5abb8490456a8 Mon Sep 17 00:00:00 2001 From: korya <148461+korya@users.noreply.github.com> Date: Fri, 7 Aug 2026 21:36:53 -0400 Subject: [PATCH 2/2] docs(readme): Complete the exit code list Two of the five codes were missing. 71 has been returned since unparseable environment values started being rejected, and 91 for as long as a malformed method or URL has been possible -- neither was ever written down. The gap mattered more than a missing table row. A script that treats every non-zero code as "the service is down" reads a typo in HTTP_ASSERT_MAX_TIME as an outage, which is the opposite of what the tool is for. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_019EMMhgmTkbzAsmeNy97PrP --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ccfdbee..be0632b 100644 --- a/README.md +++ b/README.md @@ -264,8 +264,10 @@ Repeating `--maphost` on the command line accumulates as usual. ### Exit Codes - `0`: All assertions passed, or `--version`/`--help` was requested -- `93`: Failed to perform HTTP request or assertions failed -- `103`: Invalid command line arguments or other errors +- `71`: A flag or environment value failed to parse +- `91`: The request could not be constructed from the method and URL +- `93`: Failed to perform HTTP request, or at least one assertion failed +- `103`: Wrong argument count, or an unknown flag ## Use Cases