confx

confx

confx is the application layer of xoctopus: it turns a plain Go struct into a configured, observable, and gracefully stoppable service.

Declare the configuration and infrastructure a service needs as struct fields. confx binds them to environment variables, generates configuration templates, initializes each component in order, and closes them on shutdown.

• Configuration as types: struct fields map to environment variables, with defaults taken from your Go values.
• Unified component lifecycle: components share one initialization and shutdown contract.
• Fail fast: a missing address or an unreachable dependency stops the service at startup, not on the first request.
• Ready-made infrastructure: Redis, relational databases, Pulsar, RabbitMQ, WebSocket, JWT, OpenTelemetry, and more.

[!NOTE] confx is pre-1.0, so APIs may change between minor versions.

Install

Requires Go 1.27.3 or later.

go get github.com/xoctopus/confx

Quick start

package main

import (
	"context"
	"log"

	"github.com/xoctopus/confx/pkg/appx"
	"github.com/xoctopus/confx/pkg/types"
)

var (
	app *appx.AppCtx
	ctx = context.Background()

	// Field values are the defaults.
	config = &struct {
		WorkerID uint64
		Endpoint types.EndpointNoOption
	}{WorkerID: 100}
)

func init() {
	app = appx.NewAppContext(
		Main,
		appx.WithMeta(appx.Meta{
			Name:    "example",
			Version: "v0.1.0",
			Runtime: appx.GetRuntime(),
		}),
		appx.WithRoot("."),
	)
	ctx = app.Conf(ctx, config)
}

func Main() error {
	defer func() { _ = app.Close(ctx) }()

	log.Printf("worker=%d endpoint=%q", config.WorkerID, config.Endpoint.Address)
	return nil
}

func main() {
	if err := app.Execute(); err != nil {
		log.Fatal(err)
	}
}

Variable names combine the application name and the field path:

go run . run
# worker=100 endpoint=""

EXAMPLE__WorkerID=200 EXAMPLE__Endpoint_Address=redis://127.0.0.1:6379 go run . run
# worker=200 endpoint="redis://127.0.0.1:6379"

go run . version
# example:@v0.1.0#(PROD)[commit=|build=]

Each run also writes the available variables and their defaults to config/default.yml and config/.env. Values can be overridden locally in config/local.yml.

Add a component

A component is just another field. This one connects to Redis during app.Conf:

config = &struct {
	Redis confredis.Endpoint
}{}

EXAMPLE__Redis_Address=redis://127.0.0.1:6379 go run . run

The service panics at startup if the address is empty or Redis is unreachable.

Application lifecycle

app.Conf     load config -> write defaults -> PreInit -> initialize components
app.Execute  PreRun -> Serve -> Main
app.Close    close components -> WithClose hooks

Main decides whether to wait or exit, and calls app.Close. One-shot commands, such as migrations, can be added with app.AddCommand.

Packages

Application

Components

confkafka, confbranca, and confethcli are incomplete and not ready for use.

Examples

• example/appx: an application with configuration, startup hooks, and detached modules
• example/cmdx: a CLI defined with tagged structs

Development

make test   # start dependencies from hack/ and run tests
make lint
make cover

License

MIT