bootstrap

type BaseBootstrap ¶ added in v1.62.0

type BaseBootstrap struct {
	App                 *app.Application
	MetricsRegistry     *metrics.Registry
	InfraServer         *infra.Server
	HealthcheckRegistry *healthcheck.Registry
	BindingAddress      string
	MigrationsDir       string
	ModuleName          string
	SentryHub           sentry.Hub
	TracingProvider     tracing.Provider
}

BaseBootstrap provides the core initialization context for all application types. It contains shared functionality for application lifecycle, metrics, infrastructure, observability, and health checking.

Fields:

• App: Application instance for lifecycle management and context
• MetricsRegistry: Registry for application metrics
• InfraServer: Infrastructure server for internal endpoints (metrics, health, pprof)
• HealthcheckRegistry: Registry for health check endpoints
• BindingAddress: inner binding address (host:port)
• MigrationsDir: Path to database migrations directory
• ModuleName: Name of the module
• SentryHub: Sentry error reporting hub
• TracingProvider: OpenTelemetry tracing provider

Create a BaseBootstrap through New() or NewStandalone() functions.

func (b *BaseBootstrap) Fatal(err error)

type Bootstrap ¶

type Bootstrap struct {
	*BaseBootstrap

	ClusterCli   ClusterClient
	RemoteConfig *rc.Config
}

Bootstrap represents the main initialization context for clustered applications. It embeds BaseBootstrap and adds cluster-specific functionality including cluster client management and remote configuration.

The Bootstrap instance provides access to:

• Application lifecycle management (via BaseBootstrap)
• Cluster coordination through ClusterCli
• Remote configuration via RemoteConfig

Create a Bootstrap instance using the New() function.

func New(
	moduleVersion string,
	remoteConfig any,
	endpoints []cluster.EndpointDescriptor,
	transport string,
) *Bootstrap

boot := bootstrap.New(
    "1.2.3",
    &MyRemoteConfig{},
    []cluster.EndpointDescriptor{
        {Path: "/api/v1", HttpMethod: "GET"},
    },
    cluster.HttpTransport,
)

type ClusterClient ¶ added in v1.62.0

type ClusterClient interface {
	Run(ctx context.Context, eventHandler *cluster.EventHandler) error
	Close() error
}

ClusterClient defines the interface for cluster coordination operations.

type ClusteredLocalConfig ¶ added in v1.62.0

type ClusteredLocalConfig struct {
	LocalConfig

	ConfigServiceAddress        ConfigServiceAddr
	DefaultRemoteConfigPath     string
	RemoteConfigReceiverTimeout time.Duration
	MetricsAutodiscovery        MetricsAutodiscovery
}

ClusteredLocalConfig extends LocalConfig with additional configuration for clustered applications.

Embedded:

• LocalConfig: All fields from LocalConfig

Additional fields:

• ConfigServiceAddress: Address of the config service for cluster coordination (IP;Port format, required)
• DefaultRemoteConfigPath: Custom path for default remote configuration file (optional)
• RemoteConfigReceiverTimeout: Timeout for receiving remote configuration updates
• MetricsAutodiscovery: Configuration for Prometheus metrics auto-discovery

type ConfigServiceAddr ¶

type ConfigServiceAddr struct {
	IP   string `validate:"required"`
	Port string `validate:"required"`
}

ConfigServiceAddr defines the address configuration for the cluster config service.

Fields:

• IP: Comma-separated list of config service host IPs
• Port: Comma-separated list of config service ports (must match length of IP)

Multiple addresses can be specified using semicolon separation (e.g., "host1;host2" and "port1;port2")

type GrpcInnerAddr ¶

type GrpcInnerAddr struct {
	IP   string `validate:"required"`
	Port int    `validate:"required"`
}

GrpcInnerAddr defines the internal gRPC address configuration.

Fields:

• IP: Internal IP address (required)
• Port: Internal gRPC port (required)

type GrpcOuterAddr ¶

type GrpcOuterAddr struct {
	IP   string
	Port int `validate:"required"`
}

GrpcOuterAddr defines the external gRPC address configuration.

Fields:

• IP: External IP address (can be empty for standalone)
• Port: External gRPC port (required)

type LocalConfig ¶

type LocalConfig struct {
	GrpcOuterAddress          GrpcOuterAddr
	GrpcInnerAddress          GrpcInnerAddr
	ModuleName                string `validate:"required"`
	MigrationsDirPath         string
	RemoteConfigOverride      string
	LogFile                   LogFile
	Logs                      Logs
	Observability             Observability
	InfraServerPort           int
	HealthcheckHandlerTimeout time.Duration
	// Path to the application configuration
	RemoteConfigPath string
}

LocalConfig defines the local configuration structure for standalone applications.

Fields:

• GrpcOuterAddress: External address configuration (IP and port)
• GrpcInnerAddress: Internal address configuration (IP and port, required)
• ModuleName: Unique name of the module/application (required)
• MigrationsDirPath: Path to database migrations directory (optional)
• RemoteConfigOverride: Override content for remote configuration (optional)
• LogFile: File-based logging configuration
• Logs: Log sampling and rate limiting configuration
• Observability: Sentry and tracing configuration
• InfraServerPort: Custom port for infrastructure server (optional, defaults to GrpcInnerAddress.Port + 1)
• HealthcheckHandlerTimeout: Timeout for health check requests
• RemoteConfigPath: Path to application configuration file (optional)

type LogFile ¶

type LogFile struct {
	Path       string
	MaxSizeMb  int
	MaxBackups int
	Compress   bool
}

LogFile configures file-based logging output.

Fields:

• Path: Path to the log file
• MaxSizeMb: Maximum file size in megabytes before rotation (default: 512)
• MaxBackups: Maximum number of backup files to keep (default: 4)
• Compress: Whether to compress rotated log files (default: true)

type Logs ¶

type Logs struct {
	Sampling struct {
		Enable       bool
		MaxPerSecond int
		PassEvery    int
	}
}

Logs configures log sampling and rate limiting.

Fields:

• Sampling.Enable: Enable log sampling to prevent log flooding
• Sampling.MaxPerSecond: Maximum log entries per second when sampling is enabled
• Sampling.PassEvery: Number of log entries to pass before sampling again

type MetricsAutodiscovery ¶ added in v1.52.0

type MetricsAutodiscovery struct {
	Enable           bool
	Address          string
	AdditionalLabels map[string]string
}

MetricsAutodiscovery configures Prometheus metrics auto-discovery.

Fields:

• Enable: Enable metrics auto-discovery
• Address: Metrics endpoint address (optional, defaults to infra server address)
• AdditionalLabels: Additional labels to attach to metrics

type Observability ¶

type Observability struct {
	Sentry  Sentry
	Tracing Tracing
}

Observability configures observability features including Sentry and tracing.

Fields:

• Sentry: Error reporting configuration
• Tracing: Distributed tracing configuration

type Sentry ¶

type Sentry struct {
	Enable      bool
	Dsn         string
	Environment string
	Tags        map[string]string
}

Sentry configures Sentry error reporting.

Fields:

• Enable: Enable Sentry error reporting
• Dsn: Sentry DSN (Data Source Name)
• Environment: Environment name (e.g., "production", "development")
• Tags: Additional tags for Sentry events

type StandaloneBootstrap ¶ added in v1.62.0

type StandaloneBootstrap struct {
	*BaseBootstrap
	// contains filtered or unexported fields
}

StandaloneBootstrap represents the initialization context for standalone applications. It embeds BaseBootstrap and provides functionality for reading application configuration from a local file.

Use this type for applications that do not require cluster coordination or remote configuration. Ideal for single-instance services, batch jobs, or development environments.

Create a StandaloneBootstrap using the NewStandalone() function.

func NewStandalone(moduleVersion string) *StandaloneBootstrap

boot := bootstrap.NewStandalone("1.2.3")
var cfg MyConfig
if err := boot.ReadConfig(&cfg); err != nil {
    // handle configuration error
}

func (b *StandaloneBootstrap) ReadConfig(destPtr any) error

var cfg MyConfig
if err := boot.ReadConfig(&cfg); err != nil {
    log.Fatalf("failed to read config: %v", err)
}

type Tracing ¶

type Tracing struct {
	Enable      bool
	Address     string
	Environment string
	Attributes  map[string]string
}

Tracing configures distributed tracing (OpenTelemetry).

Fields:

• Enable: Enable distributed tracing
• Address: Tracing collector endpoint address
• Environment: Environment name for trace attribution
• Attributes: Additional attributes for trace spans