gokit

package module
v1.101.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

README

gokit

See CLAUDE.md for detailed documentation.

Build Status

Documentation

Overview

Package gokit provides a shared Go application framework for CLI bootstrap, configuration loading, structured logging, metrics, and OpenTelemetry tracing.

Index

Constants

View Source
const DefaultHealthCheckName = "service"

DefaultHealthCheckName is the name SetHealthCheck registers under.

Variables

This section is empty.

Functions

func ApplyGOMemLimit

func ApplyGOMemLimit(ctx context.Context, tracer trace.Tracer, lookupEnv EnvLookup)

ApplyGOMemLimit reads the container's cgroup memory limit and applies memLimitRatio of it as the Go runtime's soft memory limit via debug.SetMemoryLimit, so a Go process that never calls this itself still gets OOM-killed less often than one ignoring its container's mem_limit entirely.

It does nothing when:

  • GOMEMLIMIT is already set (lookupEnv reports ok, operator override wins)
  • neither cgroup v2 (/sys/fs/cgroup/memory.max) nor cgroup v1 (/sys/fs/cgroup/memory/memory.limit_in_bytes) is readable
  • the cgroup reports no limit ("max", or a v1 value near the unlimited sentinel)

ctx should carry the gokit/bootstrap span, so the child span this starts joins the same trace as the rest of startup. tracer is used to start that child span.

func LoadConfig

func LoadConfig[T any](viperInst *viper.Viper, requiredKeys []string, envVarNames map[string]string) (*T, error)

LoadConfig decodes viper's settings into T, checks required keys, and validates the struct. It is used by command builders in this package and the serve subpackage.

func RegisterFlags

func RegisterFlags[T any](viperInst *viper.Viper, flags *pflag.FlagSet) ([]string, map[string]string, error)

RegisterFlags reflects on type T, registers cobra flags for each field with an `envconfig` tag, binds env vars and pflags to v, and returns the list of viper keys that had required:"true" in their struct tag, plus a map of viper keys to env var names. It recurses into struct fields with the envconfig tag value ",squash".

func Run

func Run(app App)

Run starts the application with signal handling. If app has zero commands, Run calls startupFatal and exits. If app has exactly one command, that command IS the root — it executes directly without requiring the user to type a subcommand name. If app has more than one command, all commands are added as subcommands of the root cobra command.

func SetDefaultConfigFile

func SetDefaultConfigFile(v *viper.Viper, appName string)

SetDefaultConfigFile points viper at /etc/<appName>.yaml if it exists. If the file is absent, viper falls back to its empty-config path (ReadInConfig returns ConfigFileNotFoundError, which LoadConfig ignores).

func SpanSetAttributes

func SpanSetAttributes(span trace.Span, attrs ...Attributer)

SpanSetAttributes adds attributes from one or more Attributers to span. Nil Attributers are silently skipped.

func StartRuntimeMetrics

func StartRuntimeMetrics(provider metric.MeterProvider) error

StartRuntimeMetrics registers the Go runtime instruments on provider.

Every app gets memory, goroutine, garbage-collection and scheduler metrics without writing a line: they are the first thing anyone asks for when a service goes slow, and no app can be expected to hand-roll them.

It is exported because the metric provider is installed in more than one place — the CLI bootstrap and testkit — and both have to register the same instruments for a test to be able to prove they exist.

Types

type App

type App struct {
	Name     string
	Short    string
	Commands []Command
}

App defines a multi-command CLI application.

type AppContextResult

type AppContextResult[T any] struct {
	// Ctx is the application context with typed config and tracer.
	Ctx *Context[T]
	// Shutdown flushes and closes all telemetry providers.
	Shutdown func(context.Context) error
}

AppContextResult holds the built context and shutdown function for use by subpackages and tests.

func BuildContext

func BuildContext[T any](
	ctx context.Context,
	serviceName string,
	viperInst *viper.Viper,
	requiredKeys []string,
) (*AppContextResult[T], error)

BuildContext creates a Context[T] by loading config and initializing telemetry. The traces and metrics endpoints are read from the viper instance (bound from OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT env vars via RegisterFlags when T contains those fields, e.g. Configuration[App]). It is used by subpackages (e.g. gokit/serve) and tests.

func InitApp

func InitApp[T any](
	ctx context.Context,
	serviceName string,
	viperInst *viper.Viper,
	requiredKeys []string,
	envVarNames map[string]string,
) (*AppContextResult[T], error)

InitApp loads configuration, initializes telemetry, and emits a "gokit/bootstrap" startup span reporting the service name, the active trace/metric exporters, and the resolved config file. Command builders in this package and the serve subpackage use it so every command emits a consistent bootstrap span.

The returned AppContextResult carries a Context[T] whose standard context holds the bootstrap span, so every span started from it — "command/run" and everything the application starts beneath that — joins the same trace instead of becoming a disconnected root span.

type Attributer

type Attributer interface {
	Attributes() []attribute.KeyValue
}

Attributer is implemented by domain types that can describe themselves as a set of OpenTelemetry span attributes. Implement this on any struct that is commonly passed to spans for traceability.

type Command

type Command struct {
	// contains filtered or unexported fields
}

Command is a concrete type holding a factory function that builds a cobra subcommand. Use NewCommand, NewCommandWithArgs, or gokit/serve package constructors to create values. External packages may call BuildCommand to construct a Command directly.

func BuildCommand

func BuildCommand(fn func() *cobra.Command) Command

BuildCommand creates a Command from a cobra factory function. This is the only way to construct a Command outside the gokit package; subpackages (e.g. gokit/serve) use this to integrate their own cobra commands.

func NewCommand

func NewCommand[T any](use, short string, fn func(ctx *Context[T]) error, long ...string) Command

NewCommand creates a Command with typed config T for use in a multi-command App. An optional long description can be passed as the last argument.

func NewCommandWithArgs

func NewCommandWithArgs[T any](use, short string, fn func(ctx *Context[T], args []string) error) Command

NewCommandWithArgs creates a Command that passes positional args to the handler.

type Configuration

type Configuration[T any] struct {
	// Traces is the OTLP traces endpoint URL.
	Traces string `envconfig:"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"`
	// Metrics is the OTLP metrics endpoint URL.
	Metrics string `envconfig:"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"`
	// Profiles is the Pyroscope server URL that continuous profiles are
	// pushed to. Empty disables profiling entirely, which is the default for
	// every consumer that does not set it. On this fleet the value is supplied
	// by the compose environment anchor and differs per host, since Pyroscope
	// runs on ds-dev-01: services there use http://pyroscope:4040, services on
	// ds-dev-02 use the LAN address http://192.168.3.31:4040.
	Profiles string `envconfig:"PYROSCOPE_ENDPOINT"`
	// Verbose shows all traces when true; when false, only error traces are shown (only when OTLP is not configured).
	// InitApp also binds PLUGIN_DEBUG as an alias for this same value, so a
	// Woodpecker plugin's settings.debug controls it with no extra plugin code.
	Verbose bool `envconfig:"VERBOSE" default:"false"`
	// App holds the application-specific configuration.
	App T `envconfig:",squash"`
}

Configuration is a generic wrapper that adds standard gokit settings (OTLP endpoints, HTTP port) to any app-specific config T. Consumers embed their own config in App T via mapstructure squash:

type AppConfig struct {
    Whatever string `envconfig:"WHATEVER" required:"true"`
}

gokit.Run(gokit.App{
    Name: "myapp", Short: "desc",
    Commands: []gokit.Command{gokit.NewCommand[gokit.Configuration[AppConfig]]("run", "desc", run)},
})

Within the handler, access app-specific settings via ctx.Config.App.Whatever.

type Context

type Context[T any] struct {
	context.Context
	Config *T
	Tracer trace.Tracer
	// contains filtered or unexported fields
}

Context is passed to every command handler. T is the command's config type.

func (*Context[T]) AddHealthCheck

func (c *Context[T]) AddHealthCheck(name string, check HealthCheck)

AddHealthCheck registers a named dependency probe backing serve.New's GET /health endpoint. Call it from the routes-building function passed to serve.New, once whatever the check depends on (a database pool, for instance) has been built — that dependency exists only inside that function.

Registering the same name twice replaces the earlier entry; the last registration wins. A nil check removes the entry. With no entry registered at all (the default) GET /health always answers 200.

serve.New runs every registered check on every request, concurrently, each in its own span, and reports them individually in the response body.

func (*Context[T]) Drain

func (c *Context[T]) Drain() DrainFunc

Drain returns the registered application shutdown hook, or nil when the application registered none.

func (*Context[T]) HealthCheck

func (c *Context[T]) HealthCheck() HealthCheck

HealthCheck returns the check registered under DefaultHealthCheckName, or nil when none was registered under that name.

func (*Context[T]) HealthChecks

func (c *Context[T]) HealthChecks() []HealthCheckEntry

HealthChecks returns the registered probes in registration order. The returned slice is a copy: appending to it does not register anything.

func (*Context[T]) SetDrain

func (c *Context[T]) SetDrain(drain DrainFunc)

SetDrain registers an application shutdown hook. The serve command calls it after the HTTP server has stopped and before returning. Calling SetDrain more than once replaces the previous hook; the last registration wins.

func (*Context[T]) SetHealthCheck

func (c *Context[T]) SetHealthCheck(check HealthCheck)

SetHealthCheck registers check under DefaultHealthCheckName. It is shorthand for AddHealthCheck(DefaultHealthCheckName, check) and exists for services with a single, unnamed dependency. A nil check removes the entry.

Prefer AddHealthCheck: a service that depends on Postgres and MinIO should report which of the two is down, not a single opaque verdict.

func (*Context[T]) WithContext

func (c *Context[T]) WithContext(inner context.Context) *Context[T]

WithContext returns a copy of c carrying inner as its standard context, keeping the same config, tracer, and health registry. The registry is SHARED, not copied: an application that rebinds its context mid-boot (`ctx = ctx.WithContext(spanCtx)`) or hands a derived context to a helper still has every check it registers reach GET /health. Command builders use it to hand the handler a context that carries the "command/run" span, so spans the application starts become children of it instead of new root spans.

type DrainFunc

type DrainFunc func(ctx context.Context) error

DrainFunc is an optional application shutdown hook. A command that starts a background loop registers one with Context.SetDrain, and the serve command calls it after the HTTP server has stopped accepting requests and before the process exits, so the loop can finish in-flight work and persist its state.

It is never called concurrently with itself, and it is not called at all when no application registered one.

type EnvLookup

type EnvLookup func(name string) (value string, ok bool)

EnvLookup reports whether name is set, and its value. ApplyGOMemLimit takes this as a seam rather than calling os.LookupEnv itself, so the operator-override check goes through the same config layer (viper, already bound to the environment via AutomaticEnv) as every other setting instead of reading the process environment directly.

type HealthCheck

type HealthCheck func(ctx context.Context) error

HealthCheck reports whether a service is ready to serve traffic. A non-nil error marks the service unhealthy. serve.New runs it, when registered via (*Context[T]).SetHealthCheck, on every GET /health request.

type HealthCheckEntry

type HealthCheckEntry struct {
	// Name identifies the dependency in the /health response body, e.g.
	// "postgres", "minio", "gitea". It is also the span name suffix.
	Name string

	// Check is the probe itself.
	Check HealthCheck
}

HealthCheckEntry is one named dependency probe backing GET /health.

type TelemetryResult

type TelemetryResult struct {
	// Shutdown flushes and closes all telemetry providers.
	Shutdown func(context.Context) error
	// Tracer is the OpenTelemetry tracer initialized with the service name.
	Tracer trace.Tracer
}

TelemetryResult holds the shutdown function and tracer returned by InitTelemetry.

func InitTelemetry

func InitTelemetry(
	ctx context.Context,
	serviceName, tracesEndpoint, metricsEndpoint, profilesEndpoint string,
	verbose bool,
) (*TelemetryResult, error)

InitTelemetry initialises the OpenTelemetry trace and metric providers and, when profilesEndpoint is non-empty, the Pyroscope continuous profiler. An empty profilesEndpoint leaves profiling off. It is called by command builders in this package and the serve subpackage.

Directories

Path Synopsis
Package archive moves old rows out of PostgreSQL into MinIO as gzipped YAML.
Package archive moves old rows out of PostgreSQL into MinIO as gzipped YAML.
Package csrf provides opt-in CSRF protection for gokit HTTP apps: a token minted per browser session, carried to the page through webui's forms, and verified by Middleware on unsafe requests.
Package csrf provides opt-in CSRF protection for gokit HTTP apps: a token minted per browser session, carried to the page through webui's forms, and verified by Middleware on unsafe requests.
Package dockerupgrade resolves newer container image tags and rewrites the files that pin them.
Package dockerupgrade resolves newer container image tags and rewrites the files that pin them.
examples
mcp-server command
Package main is an example MCP server that demonstrates gokit's mcp.NewCommand integration.
Package main is an example MCP server that demonstrates gokit's mcp.NewCommand integration.
server command
Package main is an example HTTP server that demonstrates all OTel signal types using gokit.
Package main is an example HTTP server that demonstrates all OTel signal types using gokit.
webui command
Package main runs the gokit/webui showcase: a browsable gallery of every component the toolkit ships, served from an in-memory seed with no external dependency.
Package main runs the gokit/webui showcase: a browsable gallery of every component the toolkit ships, served from an in-memory seed with no external dependency.
webui/views
templ: version: v0.3.1020
templ: version: v0.3.1020
worker command
Package main is an example worker that demonstrates all OTel signal types using gokit.
Package main is an example worker that demonstrates all OTel signal types using gokit.
Package formsink writes form submissions to an object store as a durable archive, and wraps nothing beyond building the payload and the object key.
Package formsink writes form submissions to an object store as a durable archive, and wraps nothing beyond building the payload and the object key.
Package giteapolicy enforces the fleet's Gitea repository policy: merge style, tag protection, default-branch protection and the CI webhook.
Package giteapolicy enforces the fleet's Gitea repository policy: merge style, tag protection, default-branch protection and the CI webhook.
Package health provides ready-made GET /health probes for the dependencies a service talks to.
Package health provides ready-made GET /health probes for the dependencies a service talks to.
Package llm is one client for an OpenAI-compatible chat/completions endpoint, normally the fleet's models-router.
Package llm is one client for an OpenAI-compatible chat/completions endpoint, normally the fleet's models-router.
Package mcp provides an HTTP handler that wraps an MCP server with OTel integration.
Package mcp provides an HTTP handler that wraps an MCP server with OTel integration.
Package notify is the client for the notify service.
Package notify is the client for the notify service.
Package objectstore connects to a MinIO/S3 bucket and hands back the SDK client.
Package objectstore connects to a MinIO/S3 bucket and hands back the SDK client.
Package oidcauth provides a reusable OIDC authorization code flow handler with JWT session cookies for Go HTTP applications.
Package oidcauth provides a reusable OIDC authorization code flow handler with JWT session cookies for Go HTTP applications.
otel
metrics
Package metrics provides a small, strongly typed client for the Prometheus HTTP query API, as implemented by VictoriaMetrics.
Package metrics provides a small, strongly typed client for the Prometheus HTTP query API, as implemented by VictoriaMetrics.
traces
Package traces provides a strongly typed client for Grafana Tempo's HTTP API.
Package traces provides a strongly typed client for Grafana Tempo's HTTP API.
traces/projection
Package projection converts full Tempo responses into compact, field-selected objects so MCP tool results stay small and cheap for an LLM to consume.
Package projection converts full Tempo responses into compact, field-selected objects so MCP tool results stay small and cheap for an LLM to consume.
traces/summary
Package summary reduces a full Tempo trace down to the handful of facts an LLM actually needs, so callers never have to ship every span back to the model.
Package summary reduces a full Tempo trace down to the handful of facts an LLM actually needs, so callers never have to ship every span back to the model.
traces/traceql
Package traceql provides a fluent builder and a best-effort explainer for Grafana Tempo's TraceQL query language.
Package traceql provides a fluent builder and a best-effort explainer for Grafana Tempo's TraceQL query language.
Package postgres connects a pgx pool and runs embedded SQL migrations.
Package postgres connects a pgx pool and runs embedded SQL migrations.
Package serve provides HTTP server commands for gokit applications.
Package serve provides HTTP server commands for gokit applications.
Package testkit provides test helpers for code instrumented with gokit.
Package testkit provides test helpers for code instrumented with gokit.
Package version holds the application version injected at build time.
Package version holds the application version injected at build time.
templ: version: v0.3.1020
templ: version: v0.3.1020
chat
Package chat is the fleet's conversation surface, with a pluggable backend.
Package chat is the fleet's conversation surface, with a pluggable backend.
chat/chattest
Package chattest holds an in-memory chat.Backend.
Package chattest holds an in-memory chat.Backend.
chat/client
Package client is the browser half of a voice call: the call controls, the one module script that joins a LiveKit room, the header that lets the page use a microphone, and the answer the voice route gives the browser.
Package client is the browser half of a voice call: the call controls, the one module script that joins a LiveKit room, the header that lets the page use a microphone, and the answer the voice route gives the browser.
chat/server
Package server is the server half of a voice call: it mints the browser's LiveKit join grant, puts an agent in the same room, and holds the conversation out loud — the person's speech is transcribed through gpu-manager, answered by the same Send that answers typed messages, and the reply is spoken back through gpu-manager.
Package server is the server half of a voice call: it mints the browser's LiveKit join grant, puts an agent in the same room, and holds the conversation out loud — the person's speech is transcribed through gpu-manager, answered by the same Send that answers typed messages, and the reply is spoken back through gpu-manager.
chat/views
Package views renders the reusable conversation surface and holds the data it draws from.
Package views renders the reusable conversation surface and holds the data it draws from.
form
Package form binds an HTTP form to a Go struct and validates it on the server, then reports every refused field in one shape a screen can render.
Package form binds an HTTP form to a Go struct and validates it on the server, then reports every refused field in one shape a screen can render.
i18n
Package i18n loads an app's translation bundle and carries the active
Package i18n loads an app's translation bundle and carries the active
metrics
Package metricsui renders server-side metric dashboards.
Package metricsui renders server-side metric dashboards.
metrics/views
templ: version: v0.3.1020
templ: version: v0.3.1020
microphone
Package microphone is the browser microphone chooser and the microphone test, shared by every page that records or calls.
Package microphone is the browser microphone chooser and the microphone test, shared by every page that records or calls.
section
Package section renders a nav-target route's response: the bare fragment when HTMX asked for it, and the full webui shell when a browser navigated to the URL directly.
Package section renders a nav-target route's response: the bare fragment when HTMX asked for it, and the full webui shell when a browser navigated to the URL directly.
seo
Package seo owns what every public TransformIA web site needs to be found and indexed, so no app hand-rolls it again: a mandatory favicon rendered from one SVG at startup, a robots.txt that denies everything unless the app declares public URLs, a sitemap.xml assembled from those URLs with per-source caching, IndexNow notification of changed URLs, and the <head> metadata a page needs (canonical, description, Open Graph, hreflang, JSON-LD).
Package seo owns what every public TransformIA web site needs to be found and indexed, so no app hand-rolls it again: a mandatory favicon rendered from one SVG at startup, a robots.txt that denies everything unless the app declares public URLs, a sitemap.xml assembled from those URLs with per-source caching, IndexNow notification of changed URLs, and the <head> metadata a page needs (canonical, description, Open Graph, hreflang, JSON-LD).
templtest
Package templtest provides guard helpers for spotting a specific templ code generation defect: a component call (`@pkg.Func(...)`) written mid-line, after other text on the same source line, is treated by templ as literal text rather than as a statement.
Package templtest provides guard helpers for spotting a specific templ code generation defect: a component call (`@pkg.Func(...)`) written mid-line, after other text on the same source line, is treated by templ as literal text rather than as a statement.
traces
Package tracesui provides a mountable, server-rendered trace-exploration Section (search bar, trace list, waterfall, span detail) backed by an otel/traces client.
Package tracesui provides a mountable, server-rendered trace-exploration Section (search bar, trace list, waterfall, span detail) backed by an otel/traces client.
traces/views
Package views holds the server-rendered templ + HTMX components and view models for the trace explorer (search bar, trace list, waterfall, span detail), plus its built-in en/fr translations.
Package views holds the server-rendered templ + HTMX components and view models for the trace explorer (search bar, trace list, waterfall, span detail), plus its built-in en/fr translations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址