infra

package
v0.0.0-...-9f10b58 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 48 Imported by: 2

Documentation

Index

Constants

View Source
const (
	DefaultMQTTKeepAliveSec      = 30
	DefaultMQTTConnectTimeoutSec = 5
)

Defaults for MQTT timing in seconds.

View Source
const (
	DefaultNatsTimeoutSec       = 5
	DefaultNatsReconnectWaitSec = 2
	DefaultNatsMaxReconnects    = 60
)

Defaults for NATS timing.

View Source
const (
	DefaultRedisDialTimeoutSec  = 5
	DefaultRedisReadTimeoutSec  = 3
	DefaultRedisWriteTimeoutSec = 3
)

Default Redis timeouts in seconds.

View Source
const (
	// DefaultRistrettoNumCounters is a infra constant.
	DefaultRistrettoNumCounters = 10000000
	// DefaultRistrettoMaxCost is a infra constant.
	DefaultRistrettoMaxCost = 100000000
	// DefaultRistrettoBufferItems is a infra constant.
	DefaultRistrettoBufferItems = 64
)
View Source
const DefaultElasticTimeoutSec = 5

DefaultElasticTimeoutSec bounds the startup Info() check.

View Source
const DefaultInitTimeoutSec = 5

DefaultInitTimeoutSec bounds dial/ping/connect calls that previously had no deadline (Bun, Redis, MQTT, NATS, S3). Sub-configs may override it with their own Timeout field where one exists.

Variables

View Source
var (
	ErrBadgerPathEmpty     = errors.New("infra: badger path is empty")
	ErrBadgerPathDuplicate = errors.New("infra: badger path is duplicated across instances")
)

ErrBadgerPathEmpty aborts startup: a non-nil BadgerConfig means "enable badger", and an empty path would otherwise open in the CWD or fail late. ErrBadgerPathDuplicate aborts before anything opens: Badger locks its directory, so a second open of the same path fails with a file-lock error that says nothing about which two config blocks collided.

View Source
var (
	ErrBunDSNEmpty          = errors.New("infra: bun dsn is empty")
	ErrBunUnsupportedDriver = errors.New("infra: bun unsupported driver")
	ErrBunDriverMissing     = errors.New("infra: bun driver missing")
	ErrBunPoolInvalid       = errors.New("infra: bun pool setting is negative")
	ErrBunSlowInvalid       = errors.New("infra: bun slow_duration is negative")
	// ErrBunUnavailable marks a transaction request before Bun initialized.
	ErrBunUnavailable = errors.New("infra: bun is not initialized")
)

ErrBunDSNEmpty aborts startup: a non-nil BunConfig means "enable SQL" and an empty DSN would otherwise dial nowhere and fail late. ErrBunUnsupportedDriver aborts startup instead of silently falling back to PostgreSQL on a typo'd driver name. ErrBunDriverMissing aborts startup when driver was left empty and the DSN carries no unambiguous signal to derive it from — a distinct failure from a misspelled driver, so the operator knows to write driver explicitly. ErrBunPoolInvalid aborts startup on negative pool/lifetime settings.

View Source
var (
	ErrElasticAddressesEmpty   = errors.New("infra: elastic addresses is empty")
	ErrElasticNoEndpoint       = errors.New("infra: elastic needs addresses or cloud_id")
	ErrElasticCACertUnreadable = errors.New("infra: elastic ca_cert_file unreadable")
	ErrElasticTimeoutInvalid   = errors.New("infra: elastic timeout_sec is negative")
	ErrElasticUnhealthy        = errors.New("infra: elastic cluster info check failed")
)

ErrElasticNoEndpoint aborts startup: a non-nil ElasticConfig means "enable elasticsearch", and with neither Addresses nor CloudID the client would silently fall back to localhost:9200. ErrElasticAddressesEmpty is kept for compatibility; prefer ErrElasticNoEndpoint for new errors.Is checks. ErrElasticCACertUnreadable / ErrElasticTimeoutInvalid abort startup.

View Source
var (
	ErrInstanceNameEmpty       = errors.New("infra: instance name is empty")
	ErrInstanceNameInvalid     = errors.New("infra: instance name is invalid")
	ErrInstanceNameDuplicate   = errors.New("infra: instance name is duplicated")
	ErrInstanceNested          = errors.New("infra: instance config cannot contain instances/default_instance/no_default")
	ErrInstanceNotFound        = errors.New("infra: instance not found")
	ErrInstanceDecode          = errors.New("infra: instance config cannot be decoded")
	ErrInstancesEmpty          = errors.New("infra: no_default is set but no instances are configured")
	ErrDefaultInstanceConflict = errors.New("infra: no_default and default_instance are mutually exclusive")
	ErrDefaultInstanceNotFound = errors.New("infra: default_instance does not name a configured instance")
)

Instance configuration sentinels. They are shared by all components so callers can match the class of failure without knowing which backend they configured.

View Source
var (
	ErrMongoURIEmpty      = errors.New("infra: mongo uri is empty")
	ErrMongoOptionInvalid = errors.New("infra: mongo pool/timeout option is negative")
)

ErrMongoURIEmpty aborts startup: a non-nil MongoConfig means "enable mongo", and an empty URI would otherwise fail late after a 5s ping timeout.

View Source
var (
	ErrMQTTBrokerEmpty       = errors.New("infra: mqtt broker is empty")
	ErrMQTTConnectTimeout    = errors.New("infra: mqtt connect timed out")
	ErrMQTTOptionInvalid     = errors.New("infra: mqtt option invalid")
	ErrMQTTCAUnreadable      = errors.New("infra: mqtt ca_file unreadable")
	ErrMQTTPasswordOrphan    = errors.New("infra: mqtt password without username is discarded")
	ErrMQTTCAWithoutTLS      = errors.New("infra: mqtt ca_file requires enable_tls")
	ErrMQTTClientIDDuplicate = errors.New("infra: mqtt client_id is duplicated across instances")
)

ErrMQTTBrokerEmpty aborts startup: a non-nil MQTTConfig means "enable mqtt", and an empty broker URL would otherwise produce an obscure error from the paho client. ErrMQTTConnectTimeout aborts startup when the broker does not answer within the connect deadline. ErrMQTTOptionInvalid aborts startup on negative timing or an unreadable CA file. ErrMQTTClientIDDuplicate aborts before anything connects: two clients sharing a client_id fight over one broker session.

View Source
var (
	ErrNATSURLEmpty       = errors.New("infra: nats url is empty")
	ErrNATSFileUnreadable = errors.New("infra: nats file unreadable")
	ErrNATSOptionInvalid  = errors.New("infra: nats option invalid")
	ErrNATSAuthConflict   = errors.New("infra: nats at most one of token/username+password/creds_file/nkey_file")
	ErrNATSCAWithoutTLS   = errors.New("infra: nats root_ca_file requires enable_tls")
)

ErrNATSURLEmpty aborts startup: a non-nil NATSConfig means "enable nats", and an empty URL would otherwise silently connect to the client default (nats://127.0.0.1:4222). ErrNATSFileUnreadable aborts on missing auth/CA files. ErrNATSOptionInvalid aborts on negative timing. ErrNATSAuthConflict aborts when more than one auth method is set. ErrNATSCAWithoutTLS aborts when RootCAFile is set without EnableTLS.

View Source
var (
	// Deprecated: use ErrNATSURLEmpty.
	ErrNatsURLEmpty = ErrNATSURLEmpty
	// Deprecated: use ErrNATSFileUnreadable.
	ErrNatsFileUnreadable = ErrNATSFileUnreadable
	// Deprecated: use ErrNATSOptionInvalid.
	ErrNatsOptionInvalid = ErrNATSOptionInvalid
	// Deprecated: use ErrNATSAuthConflict.
	ErrNatsAuthConflict = ErrNATSAuthConflict
	// Deprecated: use ErrNATSCAWithoutTLS.
	ErrNatsCAWithoutTLS = ErrNATSCAWithoutTLS
)
View Source
var (
	ErrRedisAddrEmpty       = errors.New("infra: redis addr is empty")
	ErrRedisDBNegative      = errors.New("infra: redis db is negative")
	ErrRedisTimeoutInvalid  = errors.New("infra: redis timeout/pool setting is negative")
	ErrRedisIdleExceedsPool = errors.New("infra: redis min_idle_conns exceeds pool_size")
)

ErrRedisAddrEmpty / ErrRedisDBNegative / ErrRedisTimeoutInvalid abort startup: a non-nil RedisConfig means "enable redis".

View Source
var (
	// ErrRistrettoNegativeNumCounters is a shared infra value.
	ErrRistrettoNegativeNumCounters = errors.New("infra: ristretto num_counters is negative")
	// ErrRistrettoNegativeMaxCost is a shared infra value.
	ErrRistrettoNegativeMaxCost = errors.New("infra: ristretto max_cost is negative")
	// ErrRistrettoNegativeBufferItems is a shared infra value.
	ErrRistrettoNegativeBufferItems = errors.New("infra: ristretto buffer_items is negative")
)
View Source
var (
	ErrS3RegionEmpty    = errors.New("infra: s3 region is empty")
	ErrS3SecretEmpty    = errors.New("infra: s3 secret_key is empty")
	ErrS3TimeoutInvalid = errors.New("infra: s3 timeout is negative")
)

ErrS3RegionEmpty aborts startup: a non-nil S3Config means "enable s3". ErrS3TimeoutInvalid aborts startup on a negative load timeout.

View Source
var Badger *badger.DB

Badger is a shared infra value.

View Source
var Bun *bun.DB

Bun is a shared infra value.

View Source
var ClickHouse *ch.DB

ClickHouse is the shared singleton.

View Source
var Clickhouse *ch.DB

Deprecated: use ClickHouse. Kept in sync by InitClickHouse/ClearClickHouse.

Elastic is a shared infra value.

View Source
var ErrClickHouseDSNEmpty = errors.New("infra: clickhouse dsn is empty")

ErrClickHouseDSNEmpty aborts startup: a non-nil ClickHouseConfig means "enable clickhouse", and an empty DSN would otherwise fail late after a 5s ping timeout.

View Source
var ErrClickhouseDSNEmpty = ErrClickHouseDSNEmpty

Deprecated: use ErrClickHouseDSNEmpty.

MQTT is a shared infra value.

View Source
var Mongo *mongo.Client

Mongo is a shared infra value.

View Source
var NATS *nats.Conn

NATS is the shared connection singleton.

View Source
var Nats *nats.Conn

Deprecated: use NATS. Kept in sync by InitNATS/ClearNATS.

View Source
var Redis *redis.Client

Redis is a shared infra value.

View Source
var Ristretto *ristretto.Cache[string, any]

Ristretto is a shared infra value.

S3 is a shared infra value.

Functions

func BunDB

func BunDB(ctx context.Context) bun.IDB

BunDB returns the Bun executor carried by ctx, or the package-level Bun handle when no transaction is active. It returns a nil interface when Bun is uninitialized, so callers can compare the result with nil.

func ClearBadger

func ClearBadger(names ...string)

ClearBadger clears the shared badger. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearBadgerAll

func ClearBadgerAll()

ClearBadgerAll clears the shared badger and every named instance.

func ClearBun

func ClearBun(names ...string)

ClearBun clears the shared bun. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearBunAll

func ClearBunAll()

ClearBunAll clears the shared bun and every named instance.

func ClearClickHouse

func ClearClickHouse(names ...string)

ClearClickHouse clears the shared clickhouse. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearClickHouseAll

func ClearClickHouseAll()

ClearClickHouseAll clears the shared clickhouse and every named instance.

func ClearClickhouse deprecated

func ClearClickhouse(names ...string)

Deprecated: use ClearClickHouse.

func ClearElastic

func ClearElastic(names ...string)

ClearElastic clears the shared elastic. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearElasticAll

func ClearElasticAll()

ClearElasticAll clears the shared elastic and every named instance.

func ClearMQTT

func ClearMQTT(names ...string)

ClearMQTT clears the shared mqtt. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearMQTTAll

func ClearMQTTAll()

ClearMQTTAll clears the shared mqtt and every named instance.

func ClearMongo

func ClearMongo(names ...string)

ClearMongo clears the shared mongo. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearMongoAll

func ClearMongoAll()

ClearMongoAll clears the shared mongo and every named instance.

func ClearNATS

func ClearNATS(names ...string)

ClearNATS clears the shared nats. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearNATSAll

func ClearNATSAll()

ClearNATSAll clears the shared nats and every named instance.

func ClearNats deprecated

func ClearNats(names ...string)

Deprecated: use ClearNATS.

func ClearRedis

func ClearRedis(names ...string)

ClearRedis clears the shared redis. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearRedisAll

func ClearRedisAll()

ClearRedisAll clears the shared redis and every named instance.

func ClearRistretto

func ClearRistretto(names ...string)

ClearRistretto clears the shared ristretto. With a name it clears that named instance instead.

func ClearRistrettoAll

func ClearRistrettoAll()

ClearRistrettoAll clears the shared ristretto and every named instance.

func ClearS3

func ClearS3(names ...string)

ClearS3 clears the shared s3. With a name it clears that named instance instead; the default alias reference is dropped when they match.

func ClearS3All

func ClearS3All()

ClearS3All clears the shared s3 and every named instance.

func GetBadger

func GetBadger(name ...string) *badger.DB

GetBadger returns the badger. With a name it returns the named instance.

func GetBadgerInstances

func GetBadgerInstances() map[string]*badger.DB

GetBadgerInstances returns a snapshot of the named badger instances.

func GetBun

func GetBun(name ...string) *bun.DB

GetBun returns the bun. With a name it returns the named instance.

func GetBunInstances

func GetBunInstances() map[string]*bun.DB

GetBunInstances returns a snapshot of the named bun instances.

func GetClickHouse

func GetClickHouse(name ...string) *ch.DB

GetClickHouse returns the clickhouse. With a name it returns the named instance.

func GetClickHouseInstances

func GetClickHouseInstances() map[string]*ch.DB

GetClickHouseInstances returns a snapshot of the named clickhouse instances.

func GetClickhouse deprecated

func GetClickhouse(name ...string) *ch.DB

Deprecated: use GetClickHouse.

func GetElastic

func GetElastic(name ...string) *elasticsearch.Client

GetElastic returns the elastic. With a name it returns the named instance.

func GetElasticInstances

func GetElasticInstances() map[string]*elasticsearch.Client

GetElasticInstances returns a snapshot of the named elastic instances.

func GetMQTT

func GetMQTT(name ...string) mqtt.Client

GetMQTT returns the mqtt. With a name it returns the named instance.

func GetMQTTInstances

func GetMQTTInstances() map[string]mqtt.Client

GetMQTTInstances returns a snapshot of the named mqtt instances.

func GetMongo

func GetMongo(name ...string) *mongo.Client

GetMongo returns the mongo. With a name it returns the named instance.

func GetMongoDB

func GetMongoDB(name ...string) *mongo.Database

GetMongoDB returns a database handle: the explicit name wins, then the effective configured name (MongoConfig.DB, else the URI path database). It returns nil when mongo is not initialized or no name resolves.

func GetMongoDBOf

func GetMongoDBOf(instance string, name ...string) *mongo.Database

GetMongoDBOf returns a database handle for a named instance. An empty instance name selects the shared singleton, so it behaves exactly like GetMongoDB. An explicit name wins, then the instance's effective configured database; an unknown instance or an unresolvable name returns nil.

func GetMongoInstances

func GetMongoInstances() map[string]*mongo.Client

GetMongoInstances returns a snapshot of the named mongo instances.

func GetNATS

func GetNATS(name ...string) *nats.Conn

GetNATS returns the nats. With a name it returns the named instance.

func GetNATSInstances

func GetNATSInstances() map[string]*nats.Conn

GetNATSInstances returns a snapshot of the named nats instances.

func GetNats deprecated

func GetNats(name ...string) *nats.Conn

Deprecated: use GetNATS.

func GetRedis

func GetRedis(name ...string) *redis.Client

GetRedis returns the redis. With a name it returns the named instance.

func GetRedisInstances

func GetRedisInstances() map[string]*redis.Client

GetRedisInstances returns a snapshot of the named redis instances.

func GetRistretto

func GetRistretto(name ...string) *ristretto.Cache[string, any]

GetRistretto returns the ristretto. With a name it returns the named instance.

func GetRistrettoInstances

func GetRistrettoInstances() map[string]*ristretto.Cache[string, any]

GetRistrettoInstances returns a snapshot of the named ristretto instances.

func GetS3

func GetS3(name ...string) *s3.Client

GetS3 returns the s3. With a name it returns the named instance. An empty name returns the shared singleton; "default" is not a reserved alias.

func GetS3Bucket

func GetS3Bucket(name ...string) string

GetS3Bucket returns the bucket configured for the shared S3 client, or for the named instance when a name is given. It returns "" when the component or instance is not configured, or when that instance has no bucket. An empty name returns the shared singleton; "default" is not a reserved alias — only an instance literally named "default".

func GetS3Instances

func GetS3Instances() map[string]*s3.Client

GetS3Instances returns a snapshot of the named s3 instances.

func InitBadger

func InitBadger(cfg *BadgerConfig) (*badger.DB, error)

InitBadger is part of the public API.

func InitBun

func InitBun(cfg *BunConfig) (*bun.DB, error)

InitBun is part of the public API.

func InitClickHouse

func InitClickHouse(cfg *ClickHouseConfig) (*ch.DB, error)

InitClickHouse connects and stores the shared singleton (first-wins, nil cfg disables).

func InitClickhouse deprecated

func InitClickhouse(cfg *ClickHouseConfig) (*ch.DB, error)

Deprecated: use InitClickHouse.

func InitElastic

func InitElastic(cfg *ElasticConfig) (*elasticsearch.Client, error)

InitElastic is part of the public API.

func InitMQTT

func InitMQTT(cfg *MQTTConfig) (mqtt.Client, error)

InitMQTT is part of the public API.

func InitMongo

func InitMongo(cfg *MongoConfig) (*mongo.Client, error)

InitMongo is part of the public API.

func InitNATS

func InitNATS(cfg *NATSConfig) (*nats.Conn, error)

InitNATS connects and stores the shared singleton (first-wins, nil cfg disables).

func InitNats deprecated

func InitNats(cfg *NATSConfig) (*nats.Conn, error)

Deprecated: use InitNATS.

func InitRedis

func InitRedis(cfg *RedisConfig) (*redis.Client, error)

InitRedis is part of the public API.

func InitRistretto

func InitRistretto(cfg *RistrettoConfig) (*ristretto.Cache[string, any], error)

InitRistretto is part of the public API.

func InitS3

func InitS3(cfg *S3Config) (*s3.Client, error)

InitS3 is part of the public API.

func PingElastic

func PingElastic(ctx context.Context, name ...string) error

PingElastic checks the shared singleton; nil means not configured.

func PingS3

func PingS3(ctx context.Context, name ...string) error

PingS3 checks the shared singleton for /health; nil means not configured (healthy-by-absence, following the other local checks). With a name it checks that named instance instead.

func RedactDSN

func RedactDSN(raw string) string

RedactDSN strips credentials (userinfo and common password query keys) from DSN/URI strings before they are written to logs or error strings. Clickhouse DSN and Mongo URI both embed user:password, so they must never be logged raw. Callers outside the infra package (broker, registry) use this exported form.

It delegates to utils.RedactDSN, the single implementation. The copy that used to live here is gone: together with tracer.RedactDSN there were two independent implementations, and the permissive one failed open.

func RunInBunTx

func RunInBunTx(ctx context.Context, opts *sql.TxOptions, fn func(context.Context) error) error

RunInBunTx runs fn inside a Bun transaction and injects the transaction into the context passed to fn. The transaction is committed when fn returns nil and rolled back otherwise.

func RunInBunTxIns

func RunInBunTxIns(ctx context.Context, instance string, opts *sql.TxOptions, fn func(context.Context) error) error

RunInBunTxIns runs fn inside a transaction on the named Bun instance. An empty instance name selects the shared singleton, so it then behaves exactly like RunInBunTx.

func ShutdownBadger

func ShutdownBadger() error

ShutdownBadger closes the shared badger and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is closed exactly once.

func ShutdownBun

func ShutdownBun() error

ShutdownBun closes the shared bun and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is closed exactly once.

func ShutdownClickHouse

func ShutdownClickHouse() error

ShutdownClickHouse closes the shared clickhouse and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is closed exactly once.

func ShutdownElastic

func ShutdownElastic() error

ShutdownElastic closes the shared elastic client and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is closed exactly once. One 5s deadline bounds the whole component.

func ShutdownMQTT

func ShutdownMQTT() error

ShutdownMQTT disconnects the shared client and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is disconnected exactly once.

func ShutdownMongo

func ShutdownMongo() error

ShutdownMongo disconnects the shared mongo client and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is disconnected exactly once. One 5s deadline bounds the component.

func ShutdownNATS

func ShutdownNATS() error

ShutdownNATS closes the shared connection and every named instance, then clears their references. Named instances close first so a default alias is closed exactly once.

func ShutdownRedis

func ShutdownRedis() error

ShutdownRedis closes the shared client and every named instance, then clears their references. Named instances are detached before closing so a reader cannot observe a closed handle through the registry; a default alias is closed exactly once.

func ShutdownRistretto

func ShutdownRistretto() error

ShutdownRistretto closes the shared cache and every named instance, then clears their references. Named instances close first so a default alias is closed exactly once.

func ShutdownS3

func ShutdownS3() error

ShutdownS3 clears the shared client and every named instance. S3 clients hold no closable resources; the AWS SDK manages its HTTP transports. Named instances are detached before clearing so a reader cannot observe a stale handle through the registry.

func WithBunTx

func WithBunTx(ctx context.Context, db bun.IDB) context.Context

WithBunTx returns a context carrying db as the current Bun executor. A nil executor leaves the context unchanged.

Types

type BadgerConfig

type BadgerConfig struct {
	Path string `json:"path" mapstructure:"path" yaml:"path"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete Badger configurations. They do not inherit fields
	// from the block above.
	Instances map[string]*BadgerConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

BadgerConfig is a infra component.

func (*BadgerConfig) Ensure

func (c *BadgerConfig) Ensure() *BadgerConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*BadgerConfig) Validate

func (c *BadgerConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type BunConfig

type BunConfig struct {
	Driver string `json:"driver" mapstructure:"driver" yaml:"driver"`
	DSN    string `json:"dsn"    mapstructure:"dsn"    yaml:"dsn"`
	Debug  bool   `json:"debug"  mapstructure:"debug"  yaml:"debug"`
	// Verbose enables full query logging including bound arguments.
	// Arguments may contain secrets: keep false in production.
	Verbose bool `json:"verbose" mapstructure:"verbose" yaml:"verbose"`
	// SlowDuration is a threshold placeholder, not a duration in
	// milliseconds: it only gates the query hook (>0 enables it, <=0
	// leaves it off) because bundebug v1.2.x exposes no threshold option.
	// The number itself is never compared against a query's latency, so
	// setting it does not make slow-query logging selective.
	//
	// Negative aborts startup, matching every other int here — a negative
	// value used to mean "hook off" silently, which is indistinguishable
	// from omitting the key.
	SlowDuration int `json:"slow_duration" mapstructure:"slow_duration" yaml:"slow_duration"`
	// Connection pool. Zero means driver default (unlimited open
	// connections); negative aborts startup.
	MaxOpenConns       int `json:"max_open_conns"         mapstructure:"max_open_conns"         yaml:"max_open_conns"`
	MaxIdleConns       int `json:"max_idle_conns"         mapstructure:"max_idle_conns"         yaml:"max_idle_conns"`
	ConnMaxLifetimeSec int `json:"conn_max_lifetime_sec"  mapstructure:"conn_max_lifetime_sec"  yaml:"conn_max_lifetime_sec"`
	ConnMaxIdleTimeSec int `json:"conn_max_idle_time_sec" mapstructure:"conn_max_idle_time_sec" yaml:"conn_max_idle_time_sec"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete SQL configurations. They do not inherit fields
	// from the block above.
	Instances map[string]*BunConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

BunConfig is a infra component.

func (*BunConfig) Ensure

func (c *BunConfig) Ensure() *BunConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe). A blank Driver is derived from the DSN when the DSN carries an unambiguous signal — the operator may then configure only dsn. The derived name is written back so logs, /config and initBun all see the same driver; an underivable one stays empty and Validate rejects it.

func (*BunConfig) Validate

func (c *BunConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type ClickHouseConfig

type ClickHouseConfig struct {
	DSN string `json:"dsn" mapstructure:"dsn" yaml:"dsn"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level DSN is empty.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete ClickHouse configurations. They do not inherit
	// fields from the block above.
	Instances map[string]*ClickHouseConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

ClickHouseConfig holds ClickHouse connection settings.

func (*ClickHouseConfig) Ensure

func (c *ClickHouseConfig) Ensure() *ClickHouseConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*ClickHouseConfig) Validate

func (c *ClickHouseConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type ClickhouseConfig deprecated

type ClickhouseConfig = ClickHouseConfig

Deprecated: use ClickHouseConfig.

type ElasticConfig

type ElasticConfig struct {
	Addresses []string `json:"addresses" mapstructure:"addresses" yaml:"addresses"`
	Username  string   `json:"username"  mapstructure:"username"  yaml:"username"`
	Password  string   `json:"password"  mapstructure:"password"  yaml:"password"`
	// CloudID targets Elastic Cloud; when set it takes precedence over
	// Addresses (following client semantics).
	CloudID string `json:"cloud_id" mapstructure:"cloud_id" yaml:"cloud_id"`
	// APIKey (base64) overrides Username/Password and ServiceToken.
	APIKey string `json:"api_key" mapstructure:"api_key" yaml:"api_key"`
	// ServiceToken overrides Username/Password.
	ServiceToken string `json:"service_token" mapstructure:"service_token" yaml:"service_token"`
	// CertificateFingerprint pins the server certificate (SHA256 hex).
	CertificateFingerprint string `json:"certificate_fingerprint" mapstructure:"certificate_fingerprint" yaml:"certificate_fingerprint"`
	// CACertFile loads a custom CA bundle (PEM file path).
	CACertFile string `json:"ca_cert_file" mapstructure:"ca_cert_file" yaml:"ca_cert_file"`
	// TimeoutSec bounds the startup Info() check. Seconds.
	// It does not bound regular API calls: pass a context deadline per
	// call (manager health uses a 2s context).
	TimeoutSec int `json:"timeout_sec" mapstructure:"timeout_sec" yaml:"timeout_sec"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete Elasticsearch configurations. They do not
	// inherit fields from the block above.
	Instances map[string]*ElasticConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

ElasticConfig is a infra component.

func (*ElasticConfig) Ensure

func (c *ElasticConfig) Ensure() *ElasticConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*ElasticConfig) Validate

func (c *ElasticConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config). A missing top-level endpoint is only an error when no instance can serve as the default, so the identity verdict is handed to resolveDefaultSelection rather than returned immediately.

type MQTTConfig

type MQTTConfig struct {
	Broker   string `json:"broker"    mapstructure:"broker"    yaml:"broker"`
	ClientID string `json:"client_id" mapstructure:"client_id" yaml:"client_id"`
	Username string `json:"username"  mapstructure:"username"  yaml:"username"`
	Password string `json:"password"  mapstructure:"password"  yaml:"password"`
	// EnableTLS wraps the connection in TLS 1.2+. CAFile optionally pins
	// a custom CA bundle (PEM path).
	EnableTLS bool   `json:"enable_tls" mapstructure:"enable_tls" yaml:"enable_tls"`
	CAFile    string `json:"ca_file"    mapstructure:"ca_file"    yaml:"ca_file"`
	// KeepAliveSec is the paho keepalive interval. Seconds.
	KeepAliveSec int `json:"keep_alive_sec" mapstructure:"keep_alive_sec" yaml:"keep_alive_sec"`
	// ConnectTimeoutSec bounds the initial connect. Seconds.
	ConnectTimeoutSec int `json:"connect_timeout_sec" mapstructure:"connect_timeout_sec" yaml:"connect_timeout_sec"`
	// CleanSession toggles a clean session on connect (default true).
	CleanSession *bool `json:"clean_session" mapstructure:"clean_session" yaml:"clean_session"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete MQTT configurations. They do not inherit fields
	// from the block above.
	Instances map[string]*MQTTConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

MQTTConfig is a infra component.

func (*MQTTConfig) Ensure

func (c *MQTTConfig) Ensure() *MQTTConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*MQTTConfig) Validate

func (c *MQTTConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type MongoConfig

type MongoConfig struct {
	URI string `json:"uri" mapstructure:"uri" yaml:"uri"`
	DB  string `json:"db"  mapstructure:"db"  yaml:"db"`
	// MaxPoolSize caps driver connections. 0 keeps the driver default
	// (100).
	MaxPoolSize uint64 `json:"max_pool_size" mapstructure:"max_pool_size" yaml:"max_pool_size"`
	// ConnectTimeoutSec bounds initial dial/server selection. 0 keeps the
	// driver default (30s); negative aborts startup.
	ConnectTimeoutSec int `json:"connect_timeout_sec" mapstructure:"connect_timeout_sec" yaml:"connect_timeout_sec"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete MongoDB configurations. They do not inherit
	// fields from the block above.
	Instances map[string]*MongoConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

MongoConfig is a infra component.

func (*MongoConfig) Ensure

func (c *MongoConfig) Ensure() *MongoConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*MongoConfig) Validate

func (c *MongoConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type NATSConfig

type NATSConfig struct {
	URL string `json:"url" mapstructure:"url" yaml:"url"`
	// Auth: set at most one of Token / Username+Password / CredsFile /
	// NkeyFile. Credentials are never logged.
	Token     string `json:"token"      mapstructure:"token"      yaml:"token"`
	Username  string `json:"username"   mapstructure:"username"   yaml:"username"`
	Password  string `json:"password"   mapstructure:"password"   yaml:"password"`
	CredsFile string `json:"creds_file" mapstructure:"creds_file" yaml:"creds_file"`
	NkeyFile  string `json:"nkey_file"  mapstructure:"nkey_file"  yaml:"nkey_file"`
	// EnableTLS wraps the connection in TLS 1.2+. RootCAFile optionally
	// pins a custom CA bundle (PEM path).
	EnableTLS  bool   `json:"enable_tls"   mapstructure:"enable_tls"   yaml:"enable_tls"`
	RootCAFile string `json:"root_ca_file" mapstructure:"root_ca_file" yaml:"root_ca_file"`
	// TimeoutSec bounds the initial connect. Seconds.
	TimeoutSec int `json:"timeout_sec" mapstructure:"timeout_sec" yaml:"timeout_sec"`
	// ReconnectWaitSec is the delay between reconnect attempts. Seconds.
	ReconnectWaitSec int `json:"reconnect_wait_sec" mapstructure:"reconnect_wait_sec" yaml:"reconnect_wait_sec"`
	// MaxReconnects caps reconnect attempts. 0 fills 60 (the library
	// default); -1 retries forever (opt-in: a permanently down server
	// then never surfaces as a startup error); other negatives abort.
	MaxReconnects int `json:"max_reconnects" mapstructure:"max_reconnects" yaml:"max_reconnects"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete NATS configurations. They do not inherit fields
	// from the block above.
	Instances map[string]*NATSConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

NATSConfig holds NATS connection settings.

func (*NATSConfig) Ensure

func (c *NATSConfig) Ensure() *NATSConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*NATSConfig) Validate

func (c *NATSConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type NatsConfig deprecated

type NatsConfig = NATSConfig

Deprecated: use NATSConfig.

type RedisConfig

type RedisConfig struct {
	Addr     string `json:"addr"     mapstructure:"addr"     yaml:"addr"`
	Username string `json:"username" mapstructure:"username" yaml:"username"`
	Password string `json:"password" mapstructure:"password" yaml:"password"`
	DB       int    `json:"db"       mapstructure:"db"       yaml:"db"`
	// EnableTLS wraps the connection in TLS 1.2+. TLSSkipVerify disables
	// certificate verification: development only, never in production.
	EnableTLS       bool `json:"enable_tls"        mapstructure:"enable_tls"        yaml:"enable_tls"`
	TLSSkipVerify   bool `json:"tls_skip_verify"   mapstructure:"tls_skip_verify"   yaml:"tls_skip_verify"`
	DialTimeoutSec  int  `json:"dial_timeout_sec"  mapstructure:"dial_timeout_sec"  yaml:"dial_timeout_sec"`
	ReadTimeoutSec  int  `json:"read_timeout_sec"  mapstructure:"read_timeout_sec"  yaml:"read_timeout_sec"`
	WriteTimeoutSec int  `json:"write_timeout_sec" mapstructure:"write_timeout_sec" yaml:"write_timeout_sec"`
	PoolSize        int  `json:"pool_size"         mapstructure:"pool_size"         yaml:"pool_size"`
	MinIdleConns    int  `json:"min_idle_conns"    mapstructure:"min_idle_conns"    yaml:"min_idle_conns"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete Redis configurations. They do not inherit fields
	// from the block above.
	Instances map[string]*RedisConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

RedisConfig is a infra component.

func (*RedisConfig) Ensure

func (c *RedisConfig) Ensure() *RedisConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*RedisConfig) Validate

func (c *RedisConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type RistrettoConfig

type RistrettoConfig struct {
	NumCounters int64 `json:"num_counters" mapstructure:"num_counters" yaml:"num_counters"`
	MaxCost     int64 `json:"max_cost"     mapstructure:"max_cost"     yaml:"max_cost"`
	BufferItems int64 `json:"buffer_items" mapstructure:"buffer_items" yaml:"buffer_items"`
	// DefaultInstance is accepted for config symmetry but always ignored:
	// ristretto has no required identity, so the top-level config is always
	// the shared singleton. A no_default block refuses it.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the top-level cache on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete Ristretto configurations. They do not inherit
	// fields from the block above.
	Instances map[string]*RistrettoConfig `json:"instances" mapstructure:"instances" yaml:"instances"`
}

RistrettoConfig is a infra component.

func (*RistrettoConfig) Ensure

func (c *RistrettoConfig) Ensure() *RistrettoConfig

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*RistrettoConfig) Validate

func (c *RistrettoConfig) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

type S3Config

type S3Config struct {
	// Region is required: without it every S3 call fails at request time,
	// so a missing region aborts startup instead of failing late.
	Region string `json:"region" mapstructure:"region" yaml:"region"`
	// Endpoint overrides the service endpoint (MinIO, LocalStack, ...).
	Endpoint string `json:"endpoint" mapstructure:"endpoint" yaml:"endpoint"`
	// Static credentials. Empty means fall back to the default chain
	// (env, shared config, IMDS).
	AccessKey    string `json:"access_key"    mapstructure:"access_key"    yaml:"access_key"`
	SecretKey    string `json:"secret_key"    mapstructure:"secret_key"    yaml:"secret_key"`
	SessionToken string `json:"session_token" mapstructure:"session_token" yaml:"session_token"`
	// Bucket is optional: it may be selected at call time instead.
	Bucket string `json:"bucket" mapstructure:"bucket" yaml:"bucket"`
	// UsePathStyle forces path-style addressing (required by MinIO).
	UsePathStyle bool `json:"use_path_style" mapstructure:"use_path_style" yaml:"use_path_style"`
	// Timeout bounds LoadDefaultConfig (IMDS lookups can stall for
	// seconds outside AWS). Seconds, defaults to DefaultInitTimeoutSec.
	Timeout int `json:"timeout" mapstructure:"timeout" yaml:"timeout"`
	// RequestTimeoutSec bounds whole S3 API calls (headers + body) via the
	// HTTP client. 0 keeps the SDK default (unbounded); negative aborts.
	// Prefer a context deadline per call when you need tighter control.
	RequestTimeoutSec int `json:"request_timeout_sec" mapstructure:"request_timeout_sec" yaml:"request_timeout_sec"`
	// DefaultInstance names the instance that also serves as the shared
	// singleton when the top-level fields do not form a complete config.
	DefaultInstance string `json:"default_instance" mapstructure:"default_instance" yaml:"default_instance"`
	// NoDefault suppresses the shared singleton on a fresh init; only Instances are created.
	NoDefault bool `json:"no_default" mapstructure:"no_default" yaml:"no_default"`
	// Instances are complete S3 configurations. They do not inherit fields
	// from the block above.
	Instances map[string]*S3Config `json:"instances" mapstructure:"instances" yaml:"instances"`
}

S3Config is a infra component.

func (*S3Config) Ensure

func (c *S3Config) Ensure() *S3Config

Ensure fills zero-valued fields with defaults and returns the receiver (nil-safe).

func (*S3Config) Validate

func (c *S3Config) Validate() error

Validate rejects half-configured or illegal values and resolves the named instances (without mutating the caller's config).

Jump to

Keyboard shortcuts

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