Skip to content

Development

Project layout

  • main.go: Startup; reads the environment, validates upstreams, loads the rules, and coordinates application components.
  • internal/config: logging setup and Block Rule file loading.
  • internal/filter: the request handler for body reading, Searchable Content assembly, matching, and verdict routing.
  • internal/health: the reserved Liveness Endpoint handler that wraps the content filter.
  • internal/proxy: upstream proxies and the startup reachability check.
  • docker/: the Dockerfile and the s6-overlay service definitions for the published images.

Requirements

  • Go 1.25 or newer.
  • prek (hooks for formatting, static analysis, compile, and tests).

Getting started

go build ./...
prek install --hook-type pre-commit --hook-type commit-msg

Testing

go test ./...

Coverage can be generated with:

go test ./... -coverprofile=coverage.out

Commits

Commits must follow Conventional Commits (feat:, fix:, docs:, ...). The commit-msg hook enforces this, and the changelog is grouped by prefix.

For example: feat: add Docker build support (#1)

Docs site

The documentation site is built with Zensical from the public docs sources:

pip install "zensical==0.0.62"
zensical build --clean

The built site/ is what gets published to GitHub Pages; do not edit it by hand.

Terminology

The docs follow a two-tier convention for domain terms.

Multi-word terms keep their capitals in prose: Block Rule, Allow Upstream, Block Upstream, Searchable Content, Liveness Endpoint, Reserved Path, Dropped Path. Single-word state terms are lowercase except at the start of a sentence: term, match/matching, allowed, blocked, discarded.

The first mention of a term on a page is bold and links to its most useful destination: the term's dedicated page or section when it has one (Block Rules, upstreams, Searchable Content), otherwise its anchor in the Glossary. On the page that documents a term, the mention is bold but unlinked. Later mentions are plain.

Short labels, as found in table cells, diagram nodes and step headings, keep their capitals. CONTEXT.md uses full capitals throughout. It is the canonical glossary, not prose.

Releases

Releases are created using goreleaser: each v-prefixed Git tag triggers a build of Linux binaries (amd64 and arm64), a checksum file, and a changelog assembled from the conventional commits. Docker images are published separately. See Docker.