options

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package options defines the configuration option structs for onexmesh, following the onex IOptions convention: each option implements Validate and AddFlags (with a full prefix), and is combined into a ServerOptions root.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ProtocolUsesGRPC 

func ProtocolUsesGRPC(protocol string) bool

ProtocolUsesGRPC reports whether the protocol includes gRPC.

func ProtocolUsesHTTP 

func ProtocolUsesHTTP(protocol string) bool

ProtocolUsesHTTP reports whether the protocol includes HTTP.

Types

type ConfigOptions 

type ConfigOptions struct {
	Type      string   `mapstructure:"type"` // none, file, polaris
	FilePaths []string `mapstructure:"file-paths"`

	// Polaris config center.
	PolarisAddresses []string `mapstructure:"polaris-addresses"`
	PolarisNamespace string   `mapstructure:"polaris-namespace"`
	PolarisFileGroup string   `mapstructure:"polaris-file-group"`
	PolarisFileName  string   `mapstructure:"polaris-file-name"`
}

ConfigOptions selects and configures the configuration center backend.

func NewConfigOptions 

func NewConfigOptions() *ConfigOptions

NewConfigOptions returns default config options.

func (*ConfigOptions) AddFlags 

func (o *ConfigOptions) AddFlags(fs *pflag.FlagSet, prefix string)

func (*ConfigOptions) Validate 

func (o *ConfigOptions) Validate() []error

type IOptions 

type IOptions interface {
	// Validate validates all required options, returning all errors.
	Validate() []error
	// AddFlags registers flags with the given full prefix.
	AddFlags(fs *pflag.FlagSet, fullPrefix string)
}

IOptions is implemented by every option struct. AddFlags receives a full prefix (e.g. "mesh", "otel") and appends its own field names to build flags like --otel.endpoint.

type MeshOptions 

type MeshOptions struct {
	ServiceName string `mapstructure:"service-name"`
	Protocol    string `mapstructure:"protocol"` // "grpc", "http", or "both"
	GRPCAddr    string `mapstructure:"grpc-addr"`
	HTTPAddr    string `mapstructure:"http-addr"`
	Host        string `mapstructure:"host"`
	Port        int    `mapstructure:"port"`
	// MiddlewareRoutes are optional route-level middleware bindings, each of
	// the form "selector=mw1,mw2" (e.g. "/svc.v1.Admin/*=ratelimit").
	MiddlewareRoutes []string `mapstructure:"middleware-route"`
}

MeshOptions holds the core service identity and listen addresses.

func NewMeshOptions 

func NewMeshOptions() *MeshOptions

NewMeshOptions returns default mesh options.

func (*MeshOptions) AddFlags 

func (o *MeshOptions) AddFlags(fs *pflag.FlagSet, prefix string)

func (*MeshOptions) Validate 

func (o *MeshOptions) Validate() []error

type OTelOptions 

type OTelOptions struct {
	// Connection settings.
	Endpoint string `mapstructure:"endpoint"`
	Insecure bool   `mapstructure:"insecure"`

	// Service identification.
	ServiceName       string `mapstructure:"service-name"`
	ServiceVersion    string `mapstructure:"service-version"`
	ServiceInstanceID string `mapstructure:"service-instance-id"`
	Environment       string `mapstructure:"environment"`

	// Behavior settings.
	SamplingRatio float64 `mapstructure:"sampling-ratio"`
	WithResource  bool    `mapstructure:"with-resource"`

	// Output configuration.
	OutputMode OutputMode `mapstructure:"output-mode"`
	OutputDir  string     `mapstructure:"output-dir"`

	// Logging configuration for the OTel log bridge (non-classic modes). Plain
	// slog configuration lives on ServerOptions.Slog and is applied separately.
	Level     string `mapstructure:"level"`
	AddSource bool   `mapstructure:"add-source"`
	// contains filtered or unexported fields
}

OTelOptions configures OpenTelemetry trace, metric and log.

func NewOTelOptions 

func NewOTelOptions() *OTelOptions

NewOTelOptions creates a new OTelOptions with sensible defaults.

func (*OTelOptions) AddFlags 

func (o *OTelOptions) AddFlags(fs *pflag.FlagSet, fullPrefix string)

AddFlags adds command line flags.

func (*OTelOptions) Apply 

func (o *OTelOptions) Apply() error

Apply applies the configuration by initializing all three signals. If a later signal fails, any earlier-initialized providers and files are rolled back so a partial initialization does not leak resources.

func (*OTelOptions) GetLoggerProvider 

func (o *OTelOptions) GetLoggerProvider() *otellog.LoggerProvider

GetLoggerProvider returns the logger provider.

func (*OTelOptions) GetMeterProvider 

func (o *OTelOptions) GetMeterProvider() *metric.MeterProvider

GetMeterProvider returns the meter provider.

func (*OTelOptions) GetResource 

func (o *OTelOptions) GetResource() *resource.Resource

GetResource creates or returns the cached resource configuration for this options instance. The cache is per-instance (not package-level) so multiple OTelOptions with different service identities do not cross-contaminate.

func (*OTelOptions) GetTracerProvider 

func (o *OTelOptions) GetTracerProvider() *trace.TracerProvider

GetTracerProvider returns the tracer provider.

func (*OTelOptions) Shutdown 

func (o *OTelOptions) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down all providers and closes files.

func (*OTelOptions) Validate 

func (o *OTelOptions) Validate() []error

Validate validates the configuration.

type OTelProviders 

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

OTelProviders holds all OpenTelemetry providers.

type OutputMode 

type OutputMode string

OutputMode represents the output mode for OpenTelemetry data. 

const (
	// OutputModeOTLP sends all three signals to an OTel collector over OTLP.
	OutputModeOTLP OutputMode = "otel"
	// OutputModeFile writes all three signals to local files.
	OutputModeFile OutputMode = "file"
	// OutputModeConsole writes all three signals to standard output.
	OutputModeConsole OutputMode = "console"
	// OutputModeClassic uses traditional logging/metrics only (no OTel trace).
	OutputModeClassic OutputMode = "classic"
	// OutputModeHybrid routes each signal independently:
	// log->stdout, metric->prometheus, trace->otel.
	OutputModeHybrid OutputMode = "hybrid"
)

func (OutputMode) IsValid 

func (o OutputMode) IsValid() bool

IsValid reports whether the output mode is a known value.

func (OutputMode) String 

func (o OutputMode) String() string

String implements the Stringer interface.

type Provider 

type Provider interface {
	Shutdown(context.Context) error
}

Provider wraps OpenTelemetry providers with shutdown capability.

type RegistryOptions 

type RegistryOptions struct {
	// Type is the registry backend name: none, polaris, etcd, kubernetes,
	// consul, nacos or eureka.
	Type string `mapstructure:"type"`
	// contains filtered or unexported fields
}

RegistryOptions selects the registry backend and delegates backend-specific configuration to the self-describing backends registered via registry.RegisterBackend. This keeps the options layer open to new backends without a per-backend field list or switch: adding a backend is one new package plus a blank import in pkg/registry/all.

func NewRegistryOptions 

func NewRegistryOptions() *RegistryOptions

NewRegistryOptions returns default registry options.

func (*RegistryOptions) AddFlags 

func (o *RegistryOptions) AddFlags(fs *pflag.FlagSet, prefix string)

AddFlags registers the shared registry type flag, then lets every registered backend contribute its own flags under a nested prefix (--registry.<name>.*). All backends are registered up front so the flag set does not depend on which type is selected.

func (*RegistryOptions) NewDiscovery 

func (o *RegistryOptions) NewDiscovery() (registry.Discovery, error)

NewDiscovery creates the client-side discovery for this configuration. It returns (nil, nil) when the registry type is "none".

func (*RegistryOptions) NewRegistrar 

func (o *RegistryOptions) NewRegistrar(host string, port int, protocol string) (registry.Registrar, error)

NewRegistrar creates the server-side registrar for this configuration. It returns (nil, nil) when the registry type is "none".

func (*RegistryOptions) Validate 

func (o *RegistryOptions) Validate() []error

type ResilienceOptions 

type ResilienceOptions struct {
	MaxAttempts          int           `mapstructure:"max-attempts"`
	BaseBackoff          time.Duration `mapstructure:"base-backoff"`
	MaxBackoff           time.Duration `mapstructure:"max-backoff"`
	BreakerWindow        time.Duration `mapstructure:"breaker-window"`
	BreakerProbeInterval time.Duration `mapstructure:"breaker-probe-interval"`
	Timeout              time.Duration `mapstructure:"timeout"`
	// Bulkhead bounds the number of concurrent in-flight requests to a single
	// downstream service. 0 disables the bulkhead.
	Bulkhead int `mapstructure:"bulkhead"`
	// PolicyPath enables declarative resilience: one or more resiliency YAML
	// files whose named policies (timeout/retry/breaker) are bound to endpoints.
	// When set, declarative policies take precedence over the imperative fields.
	PolicyPath []string `mapstructure:"policy-path"`
}

ResilienceOptions configures client-side resilience.

func NewResilienceOptions 

func NewResilienceOptions() *ResilienceOptions

NewResilienceOptions returns default resilience options.

func (*ResilienceOptions) AddFlags 

func (o *ResilienceOptions) AddFlags(fs *pflag.FlagSet, prefix string)

func (*ResilienceOptions) DialOptions 

func (o *ResilienceOptions) DialOptions() []client.DialOption

DialOptions converts the resilience settings into client DialOptions.

func (*ResilienceOptions) Validate 

func (o *ResilienceOptions) Validate() []error

type SelectorOptions 

type SelectorOptions struct {
	Strategy string `mapstructure:"strategy"` // round_robin, random, weighted, p2c
	// DiscoveryCacheTTL enables the read-through discovery cache when > 0.
	DiscoveryCacheTTL time.Duration `mapstructure:"discovery-cache-ttl"`
}

SelectorOptions selects the load-balancing strategy and client-side discovery caching.

func NewSelectorOptions 

func NewSelectorOptions() *SelectorOptions

NewSelectorOptions returns default selector options.

func (*SelectorOptions) AddFlags 

func (o *SelectorOptions) AddFlags(fs *pflag.FlagSet, prefix string)

func (*SelectorOptions) DialOption 

func (o *SelectorOptions) DialOption() client.DialOption

DialOption converts the strategy selection into a client DialOption.

func (*SelectorOptions) Validate 

func (o *SelectorOptions) Validate() []error

type ServerOptions 

type ServerOptions struct {
	Mesh       *MeshOptions       `mapstructure:"mesh"`
	Slog       *SlogOptions       `mapstructure:"log"`
	OTel       *OTelOptions       `mapstructure:"otel"`
	Registry   *RegistryOptions   `mapstructure:"registry"`
	Config     *ConfigOptions     `mapstructure:"-"`
	Selector   *SelectorOptions   `mapstructure:"selector"`
	Resilience *ResilienceOptions `mapstructure:"resilience"`
}

ServerOptions is the root options struct combining all leaf options. It satisfies the app.FlagSetOptions contract (AddFlags without prefix and Validate returning a single error) so it can be passed directly to app.

func NewServerOptions 

func NewServerOptions() *ServerOptions

NewServerOptions returns a ServerOptions with all leaf defaults.

func (*ServerOptions) AddFlags 

func (o *ServerOptions) AddFlags(fs *pflag.FlagSet)

AddFlags registers all leaf flags under their section prefixes.

func (*ServerOptions) Apply 

func (o *ServerOptions) Apply() error

Apply initializes the runtime capabilities (plain slog, then OTel trace/metric/ log) so logging, metrics and tracing all take effect. It is the single entry point the composition root calls after options are validated. Plain slog is applied first; for non-classic OTel modes initLogs then bridges slog into OTel.

func (*ServerOptions) BuildClientDialOptions 

func (o *ServerOptions) BuildClientDialOptions() ([]client.DialOption, error)

BuildClientDialOptions assembles the client DialOptions from the selector, resilience and registry settings. It returns an error when the registry type is "none", since service discovery requires a backend.

func (*ServerOptions) BuildMatcher 

func (o *ServerOptions) BuildMatcher() (*matcher.Matcher, error)

BuildMatcher returns a route-aware matcher when route-level middleware bindings are configured, or (nil, nil) otherwise. The global chain from BuildMiddleware is registered via Use, and each "selector=mw1,mw2" binding is resolved through the middleware registry and registered via Add.

func (*ServerOptions) BuildMiddleware 

func (o *ServerOptions) BuildMiddleware() []middleware.Middleware

BuildMiddleware assembles the server middleware chain, outermost first. The resulting order is recovery -> tracing -> logging -> metrics -> timeout.

func (*ServerOptions) ServiceInstance 

func (o *ServerOptions) ServiceInstance() *registry.ServiceInstance

ServiceInstance builds the registry.ServiceInstance for this service from the mesh listen addresses. Endpoints are advertised exactly as configured, so the addresses should be reachable by clients (avoid "0.0.0.0").

func (*ServerOptions) ServiceInstanceFor 

func (o *ServerOptions) ServiceInstanceFor(protocol string) *registry.ServiceInstance

ServiceInstanceFor builds a single-protocol registry.ServiceInstance for the given protocol, so the gRPC and HTTP servers each register their own endpoint (rather than both advertising the gRPC endpoint). It returns nil when the configured protocol does not include the requested one.

func (*ServerOptions) Shutdown 

func (o *ServerOptions) Shutdown(ctx context.Context) error

Shutdown releases the OTel providers and any open output files (both OTel and plain slog).

func (*ServerOptions) Validate 

func (o *ServerOptions) Validate() error

Validate aggregates all leaf validation errors into a single error.

type SlogOptions 

type SlogOptions struct {
	Level      string `mapstructure:"level"`
	AddSource  bool   `mapstructure:"add-source"`
	Format     string `mapstructure:"format"`
	TimeFormat string `mapstructure:"time-format"`
	Output     string `mapstructure:"output"`
	// contains filtered or unexported fields
}

SlogOptions configures the slog logger.

func NewSlogOptions 

func NewSlogOptions() *SlogOptions

NewSlogOptions returns default slog options.

func (*SlogOptions) AddFlags 

func (o *SlogOptions) AddFlags(fs *pflag.FlagSet, prefix string)

func (*SlogOptions) Apply 

func (o *SlogOptions) Apply() error

Apply sets the global default slog logger.

func (*SlogOptions) BuildHandler 

func (o *SlogOptions) BuildHandler() (slog.Handler, error)

BuildHandler builds a slog.Handler from the options.

func (*SlogOptions) BuildLogger 

func (o *SlogOptions) BuildLogger() (*slog.Logger, error)

BuildLogger builds a slog.Logger without touching the global logger.

func (*SlogOptions) Shutdown 

func (o *SlogOptions) Shutdown() error

Shutdown closes any output file opened by the writer. It is idempotent.

func (*SlogOptions) ToSlogLevel 

func (o *SlogOptions) ToSlogLevel() slog.Level

ToSlogLevel converts the level string to slog.Level.

func (*SlogOptions) Validate 

func (o *SlogOptions) Validate() []error

type TraceIDHandler 

type TraceIDHandler struct {
	slog.Handler
}

TraceIDHandler decorates a slog.Handler, attaching the current trace/span ids from the request context to every record.

func (*TraceIDHandler) Handle 

func (h *TraceIDHandler) Handle(ctx context.Context, r slog.Record) error

func (*TraceIDHandler) WithAttrs 

func (h *TraceIDHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (*TraceIDHandler) WithGroup 

func (h *TraceIDHandler) WithGroup(name string) slog.Handler

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.