Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Code Style

jetwarp follows standard Go idioms with a few explicit conventions.

Formatting

  • gofmt: all code must be gofmt-clean. The release gate checks this.
  • golangci-lint: run bash tools/lint-all.sh before opening a PR.

Error handling

No panics on bad input

Registration methods (Handle, Scope, Use, Group, With) must never panic. Bad input becomes a returned error. This is a compatibility contract enforced by the suite.

Sentinel errors

All errors wrap jetwarp.ErrJetwarp so errors.Is(err, jetwarp.ErrJetwarp) is always true. Concrete sentinels live in errors.go:

var ErrNilDriver = fmt.Errorf("%w: nil driver", ErrJetwarp)

Use %w wrapping, not string concatenation. This keeps errors.Is / errors.As working regardless of how many layers the error travels through.

Error codes vs message text

For OpenAPI diagnostics: DiagCode is stable (part of the public API). Message text is not stable and may change between minor versions. Code accordingly.

Package conventions

Driver packages

  • Implement drv.Drv in a file named <routername>.go.
  • Add var _ drv.Drv = (*Driver)(nil) as the first line after imports.
  • Keep safeRegister-style panic recovery in every registration path.
  • Tests go in a <pkgname>_test (black-box) package.

Adapter wrappers

Adapter packages are one-liners:

func New() core.Adapter { return core.New(driver.New()) }

Do not add business logic to adapter wrappers. If you need custom construction logic, add it to the driver.

Naming

  • Capabilities: Cap<FeatureName> (e.g. CapParams, CapAnyMethod).
  • Error sentinels: Err<Condition> (e.g. ErrNilDriver, ErrInvalidPattern).
  • Driver kinds: Kind<Framework> (e.g. KindChi, KindGin).
  • Suite entry points: Run<Thing> (e.g. RunDriver, RunAdapter, RunDriverSmoke).

Comments

  • Public API: full Godoc with contract semantics (not just “what it does” but “what it guarantees”).
  • Handle, Scope, Caps in driver implementations: comment the capability claim with the reason.
  • Any //nolint: directive must have a trailing comment explaining why.

Tests

  • Suite tests live in tests/suite/. They are the portability spec.
  • Driver-specific behavior (things not covered by the suite) belongs in <n>_regression_test.go.
  • Use t.Helper() in test helpers.
  • Test packages are black-box (package foo_test, not package foo).

Multi-module hygiene

  • Do not add replace directives in committed go.mod files. Replace directives are for local hacks; the workspace (go.work) is the contributor convenience.
  • go mod tidy must pass per module before a PR is merged.
  • All modules must declare go 1.26.0.