9.8 KiB
RULES OF CONDUCT
This module (github.com/effective-security/porto) is a library of server
and client building blocks for Go services. There is no binary, service, or
generated mock tree. The packages are:
restserver(+authz,ready,telemetry): anhttprouter-based REST server with CORS, role-based path authorization, readiness, request logging and metrics.gserver(+credentials,roles): a combined gRPC, gRPC-Web and REST gateway server with identity extraction from JWT, DPoP, AWS STS caller identity and TLS/SPIFFE certificates.xhttp/*: HTTP helpers shared by both servers and by clients:correlation(request IDs),header(constants),httperror(structured errors mapped to and from gRPC codes),identity(caller identity incontext.Context),marshal(JSON and gzip response writing).pkg/*: infrastructure:retriable(HTTP client with retries and failover),rpcclient(gRPC client factory),redisclient,cache(memory and Redis providers),tasks(cron-like scheduler),tlsconfig(TLS config with file reloading),transport(TLS and keepalive listeners),appinit(application bootstrap),discovery(in-process service registry),crlcache,streamctx,location(client location from IP with a per-network cache).metricskey: metric descriptors shared by the servers.tests/*: helpers used only by tests.
Work in one package at a time unless you are changing a documented internal dependency.
Dependency direction is one way and is listed per package in
Documentation/codemap.md. The rules: xhttp/*
and pkg/* never import restserver or gserver; xhttp/header,
pkg/tlsconfig, pkg/tasks, pkg/discovery, pkg/streamctx and
metricskey import nothing else from this module; restserver imports only
restserver/* and xhttp/*; gserver may import restserver/*,
xhttp/*, pkg/transport, pkg/discovery and pkg/streamctx.
pkg/retriable and pkg/rpcclient import gserver/credentials for token
types only. Nothing outside tests/ imports tests/.
NAVIGATION
Do not start by grepping the tree.
- Open
Documentation/codemap.md. Use the concept index to find the owning file, then the package section for entry points and invariants. - Open that file (and its
_test.go) before searching elsewhere. - Grep or glob only if the concept is missing from the map. When you find it, add it to the map in the same change.
- For high-level purpose, config samples and install path, see
README.md.
CODING GUIDELINES
Style
- Target Go 1.27 (
go.mod). Use the standard library where it now covers a helper:slices.Contains,cmp.Or,maps.Copy,strings.SplitSeq,min/max, range-over-int,math/rand/v2,crypto/rand, and the standarduuidpackage (uuid.NewV7().String()). Do not add calls to functions markedDeprecatedin the stdlib, ingithub.com/effective-security/x, or in third-party modules;golangci-lint run(staticcheck SA1019) must stay clean. - Do not use long one-liners for map or struct population; split key-value pairs on new lines for readability.
- Do not use many hardcoded strings or integers; define
constat the top of the file or in the package. Header and metadata names live inxhttp/header; reuse them. - Memoize into variables; do not call functions with the same parameters more than once.
- Use
any, notinterface{}.
Errors
- Use
github.com/cockroachdb/errorsfor all error creation and wrapping. - Wrap external errors (filesystem, YAML/JSON, network, Redis, gRPC, AWS
SDK) using either:
errors.WithMessage(err, "unable to read file")for static context.errors.Wrapf(err, "failed to resolve file %s", path)when context includes dynamic values.
- Errors originated from internal sentinel types must also be wrapped so
the stack is preserved. For
var ErrNotFound = errors.New("not found")do not simplyreturn ErrNotFound. - Compare errors with
errors.Is/errors.As, never==or a type assertion. Errors returned to HTTP or gRPC callers go throughxhttp/httperrorso status codes and codes stay consistent. - Never ignore errors from serialization, filesystem, or network calls in
library paths that already return
error. Helpers that intentionally swallow errors must keep that behavior documented inDocumentation/codemap.md. - Keep error strings accurate after refactors. Do not leave stale package or function names in runtime errors.
- Library code does not panic on bad input or bad configuration; it
returns an error. The only intentional panics are
Must*constructors andinit()-time table construction. - Every outgoing HTTP call takes a
context.Contextand a client with a timeout (http.NewRequestWithContext; no barehttp.Get). - Credentials: bearer tokens, cookies, private keys and PINs are never
logged in full; token files are written with mode
0600; random values come fromcrypto/rand; use constant-time comparison for secrets. - Headers that carry caller identity (
X-Forwarded-For,X-Real-Ip,Authorization, DPoP) are untrusted input. Do not widen what the servers accept from them without aFINDINGS.mdorROADMAP.mdentry.
Tests
- Build tests using
assertandrequirefromgithub.com/stretchr/testify; suites usetestify/suite. - Assert exact behavior, including key absence versus empty values and
the real
errfrom the call being tested. - Do not assert on source line numbers or on exact compressed bytes; both
change with unrelated edits or Go releases. Derive expected line numbers
from
runtime.Callerand compare decompressed payloads. - Prefer table tests for conversion and formatting helpers.
- Use
package foo_testfor black-box tests andpackage fooonly when a test needs unexported seams. - External fixtures:
pkg/redisclientandpkg/cachestart a Redis container throughtestcontainers-go, so Docker must be running;pkg/tlsconfig,pkg/transport,restserverandgserveruse the PEM fixtures under theirtestdata/directories andtests/testutils. Do not hard-code other paths; reuse the constants the packages define. - Cover shared state with a test that actually races, and run
make test RACE=truebefore proposing a change to shared state (scheduler, TLS reloader, caches, identity maps, token storage). - This module has no gomock-generated interfaces; do not introduce mocks unless the package under test cannot be exercised directly.
- add
t.Parallel()for tests that can run in parallel.
Tools
make tools: install golangci-lint, cov-report, govulncheck, gomarkdocmake fmt: apply go fmt with the project rewritesmake test: test entire project (needs Docker for Redis-backed tests)make testshort: tests with-test.shortmake lint: gofmt, go vet, govulncheck, golangci-lintmake covtest: coverage run and console reportmake covtest coverage: coverage run and HTML reportmake docs: regenerate the gomarkdoc API reference underDocumentation/api/make all: clean, tools, generate, covtest
CI (.github/workflows/unittest.yml) runs make lint and
make build covtest, and its coverage status requires more than 90%
total coverage (MIN_TESTCOV). Keep every package with statements above
90% too. CI does not run the race detector; run it locally. Pushes to
main that change .VERSION create a tag <.VERSION>.<commit count>.
Documentation
- Every package has a
doc.gowith a package comment and, where the package has a non-obvious entry point, a short usage example. - Document all exported types, functions, interfaces, and interface methods. Say what a symbol is for, not just what it is named.
- Keep samples in
doc.go, the rootREADME.md,pkg/retriable/README.mdandDocumentation/accurate against the current API. A wrong sample is worse than no sample; compile a changed sample before committing it. - When you add a package, add it to the package table in the root
README.md, adddoc.go, and add a section plus concept-index rows inDocumentation/codemap.md. - When you find a defect you are not fixing in the same change, add it to
FINDINGS.mdwith the next free ID and reference the ID from a code comment. Larger API or contract changes go toROADMAP.md.
Keep Documentation/codemap.md current
Update the codemap in the same change when you add functionality or make a major change, including:
- New, removed, or renamed package, subpackage, or file that owns a concept.
- New, moved, or renamed exported entry-point type, func, or interface.
- Changed invariants: panic vs error, process-global state (loggers, registries, default clients), locking, config file format, header or metadata names, supported auth methods, goroutine/callback rules, or internal imports between packages.
- Changed test layout or fixture conventions.
The map must stay the navigation index: concept → file → entry points → invariants. If you had to grep to find something that belongs there, add the row.
REPOSITORY MAP
Start here instead of grepping the tree.
Documentation/codemap.md— concept index, per-package files and entry points, invariants, internal dependencies, test layout, build and CI.README.md— high-level overview, package table, configuration samples and quick-start code.FINDINGS.md— known defects, referenced by ID from code comments. Read it before "fixing" surprising behavior: it may already be recorded, with the compatibility decision still open.ROADMAP.md— larger planned work.pkg/retriable/README.md— retriable HTTP client usage.- Package
doc.goin each library package.