go-loose/docs/coding-standards.md

Coding standards

Go

• Use the standard library unless a dependency clearly reduces security or protocol risk.
• Keep public APIs small, documented, and backward compatible.
• Pass context.Context through I/O boundaries and always bound network calls with timeouts.
• Wrap errors with the operation; never log secrets, cookies, authorization headers, or full API keys.
• Return explicit errors. Runtime authorization must fail closed.
• Keep SQL tenant-aware: management queries must join through membership, and writes must enforce role in the query or transaction.
• Derive authorization from the matrix in internal/role instead of hardcoding role names. Pass role.Grants(...) into SQL, use role.Allows in handlers, and render controls from the capability lists the server returns.
• Use cryptographically secure randomness for credentials and constant-time comparison for signatures.
• Format with gofmt; run go test -race ./..., go vet ./..., and go build ./....

HTTP API

• Routes are versioned under /api/v1; health and authentication routes are infrastructure exceptions.
• JSON handlers reject unknown fields, extra JSON values, and oversized bodies.
• Errors use {"error":"human-readable message"} without internal implementation details.
• Use 401 for absent/unusable authentication, 403 for authenticated credentials outside policy, 404 when existence must not disclose access, and 422 for semantically invalid contracts.
• Any management mutation requires a valid user session and same-origin browser request.
• Update web/openapi.json whenever endpoint behavior changes.

Database

• Use UUID primary keys for tenant data and UTC timestamptz timestamps.
• Foreign keys declare deletion behavior; frequently queried authorization fields get explicit indexes.
• Applied migrations are immutable and forward-compatible.
• Multi-step writes use transactions. Do not add application-side checks that can race when a database constraint can enforce the invariant.

Frontend

• Preserve keyboard access, semantic elements, visible focus, responsive layout, and sufficient contrast in every theme.
• Escape all server-provided strings before assigning HTML. Prefer textContent for new dynamic surfaces.
• Store only visual preferences in local storage; authentication remains in HTTP-only cookies.
• Keep the console dependency-free unless complexity justifies a reviewed build tool decision.

Tests and reviews

• New domain behavior needs table-driven unit tests and negative cases.
• Security boundaries need explicit tests for missing, malformed, expired, cross-tenant, and unauthorized inputs.
• Integration tests that need PostgreSQL should use a disposable database and never shared developer data.
• Reviews prioritize tenant isolation, fail-closed behavior, migration compatibility, secret handling, and error visibility.

Commit style

Use focused commits with imperative subjects, for example Add scoped API key authorization. Do not mix unrelated refactors with behavior changes. Explain migration and security implications in the commit body.