Documentation
¶
Index ¶
Constants ¶
const ( // ErrorParamEmpty indicates that required parameters were not provided. ErrorParamEmpty liberr.CodeError = iota + liberr.MinPkgConfig // ErrorConfigMissingViper indicates that the Viper configuration provider is not registered. // Register one using Config.RegisterFuncViper() before component initialization. ErrorConfigMissingViper // ErrorComponentNotFound indicates that a requested component was not found in the registry. // Verify the component key and ensure the component is registered via ComponentSet(). ErrorComponentNotFound // ErrorComponentFlagError indicates that at least one component failed during flag registration. // Check individual component RegisterFlag() implementations for specific errors. ErrorComponentFlagError // ErrorComponentConfigNotFound indicates that configuration keys for a component are missing. // Ensure the configuration file contains the required component section. ErrorComponentConfigNotFound // ErrorComponentConfigError indicates that a component's configuration is invalid or malformed. // Review the component's configuration structure and validation rules. ErrorComponentConfigError // ErrorComponentStart indicates that at least one component failed to start. // Check component logs for specific startup errors. ErrorComponentStart // ErrorComponentReload indicates that at least one component failed to reload. // Check component logs for specific reload errors. ErrorComponentReload )
Error codes for the config package. These errors are used throughout the config package and its components to provide standardized error reporting with proper error chaining.
const ( // MinErrorComponentAws is the starting error code for AWS component errors. MinErrorComponentAws = ErrorParamEmpty + 10 // MinErrorComponentDatabase is the starting error code for Database component errors. MinErrorComponentDatabase = MinErrorComponentAws + 10 // MinErrorComponentHead is the starting error code for Header component errors. MinErrorComponentHead = MinErrorComponentDatabase + 10 // MinErrorComponentHttp is the starting error code for HTTP server component errors. MinErrorComponentHttp = MinErrorComponentHead + 10 // MinErrorComponentHttpCli is the starting error code for HTTP client component errors. MinErrorComponentHttpCli = MinErrorComponentHttp + 10 // MinErrorComponentLdap is the starting error code for LDAP component errors. MinErrorComponentLdap = MinErrorComponentHttpCli + 10 // MinErrorComponentLog is the starting error code for Logger component errors. MinErrorComponentLog = MinErrorComponentLdap + 10 // MinErrorComponentMail is the starting error code for Mail component errors. MinErrorComponentMail = MinErrorComponentLog + 10 // MinErrorComponentNats is the starting error code for NATS component errors. MinErrorComponentNats = MinErrorComponentMail + 10 // MinErrorComponentNutsDB is the starting error code for NutsDB component errors. MinErrorComponentNutsDB = MinErrorComponentNats + 10 // MinErrorComponentRequest is the starting error code for Request component errors. MinErrorComponentRequest = MinErrorComponentNutsDB + 10 // MinErrorComponentSmtp is the starting error code for SMTP component errors. MinErrorComponentSmtp = MinErrorComponentRequest + 10 // MinErrorComponentTls is the starting error code for TLS component errors. MinErrorComponentTls = MinErrorComponentSmtp + 10 )
Error code ranges reserved for component-specific errors. Each component package has a reserved range of error codes to avoid collisions. Components should define their error codes starting from their MinError constant.
Variables ¶
This section is empty.
Functions ¶
func ShellCommandInfo ¶ added in v1.11.3
func ShellCommandInfo() []shlcmd.CommandInfo
ShellCommandInfo returns metadata for all available shell commands. This is used by shell integration packages to discover available commands without creating the full command implementations.
Returns:
- Slice of CommandInfo containing name and description for each command
Available commands:
- list: Display all registered components
- start: Start components (optionally specify component keys as arguments)
- stop: Stop components (optionally specify component keys as arguments)
- restart: Restart components by stopping then starting them
Example usage in shell integration:
for _, info := range config.ShellCommandInfo() {
fmt.Printf("%s: %s\n", info.Name(), info.Description())
}
func Shutdown ¶ added in v1.10.0
func Shutdown()
Shutdown cancels the main application context, triggering shutdown of all components. This is a package-level function that can be called from any goroutine to initiate a coordinated shutdown. It cancels the shared context, which is monitored by all Config instances.
Usage:
- Call from signal handlers for graceful shutdown
- Call from error handlers for emergency shutdown
- Call from other goroutines to stop the application
Note: This only cancels the context. Components must handle the cancellation through their Config.Stop() method or by monitoring the context.
func WaitNotify ¶ added in v1.10.0
func WaitNotify()
WaitNotify blocks until an interrupt signal is received, then initiates shutdown. This function monitors OS signals (SIGINT, SIGTERM, SIGQUIT) and the application context. When either a signal is received or the context is cancelled, it calls Shutdown() to begin the graceful shutdown sequence.
Typical usage in main():
func main() {
cfg := config.New(version)
cfg.Start()
config.WaitNotify() // Blocks until signal received
}
Monitored signals:
- SIGINT (Ctrl+C): User interrupt from terminal
- SIGTERM: Termination signal (default for 'kill' command)
- SIGQUIT: Quit signal with core dump request
The function returns immediately after calling Shutdown(), allowing the main function to perform final cleanup before exiting.
Types ¶
type Config ¶
type Config interface {
// Context returns the shared application context instance.
// All components receive access to this context for shared state management
// and coordinated cancellation.
Context() libctx.Config[string]
// CancelAdd registers custom functions to be called on context cancellation.
// These functions execute before Stop() when the application receives
// termination signals (SIGINT, SIGTERM, SIGQUIT) or when Shutdown() is called.
// Useful for cleanup tasks that need to happen before component shutdown.
CancelAdd(fct ...func())
// CancelClean removes all registered cancel functions.
// Use this to reset cancellation handlers, typically during testing
// or when reconfiguring the application.
CancelClean()
// Start initiates the startup sequence for all registered components.
// Components are started in dependency order (topological sort).
// The sequence is:
// 1. Execute RegisterFuncStartBefore hooks
// 2. Start each component in dependency order
// 3. Execute RegisterFuncStartAfter hooks
// Returns an error if any hook or component fails to start.
// On error, the start sequence is aborted immediately.
Start() error
// Reload triggers a configuration reload for all registered components.
// Components are reloaded in dependency order.
// The sequence is:
// 1. Execute RegisterFuncReloadBefore hooks
// 2. Reload each component in dependency order
// 3. Execute RegisterFuncReloadAfter hooks
// Returns an error if any hook or component fails to reload.
// Components should implement hot-reload without full restart.
Reload() error
// Stop gracefully shuts down all registered components.
// Components are stopped in reverse dependency order.
// The sequence is:
// 1. Execute RegisterFuncStopBefore hooks
// 2. Stop each component in reverse dependency order
// 3. Execute RegisterFuncStopAfter hooks
// This function does not return errors; components must stop cleanly.
Stop()
// Shutdown performs a complete application termination.
// This function:
// 1. Executes all registered cancel functions (CancelAdd)
// 2. Calls Stop() to shutdown components
// 3. Exits the process with the specified exit code
// This is typically called on fatal errors or during graceful shutdown.
// Note: This function does not return as it calls os.Exit().
Shutdown(code int)
// RegisterFuncViper registers a Viper configuration provider function.
// Components use this to access their configuration sections.
// The function is called when components need to load or reload their configuration.
// Typically registered once during application initialization.
RegisterFuncViper(fct libvpr.FuncViper)
// RegisterFuncStartBefore registers a hook executed before component startup.
// This hook runs before any component's Start() method is called.
// Use for: pre-start validation, initialization logging, resource preparation.
// If the hook returns an error, the start sequence is aborted.
RegisterFuncStartBefore(fct FuncEvent)
// RegisterFuncStartAfter registers a hook executed after component startup.
// This hook runs after all components have started successfully.
// Use for: post-start validation, ready notification, monitoring setup.
// If the hook returns an error, it's treated as a start failure.
RegisterFuncStartAfter(fct FuncEvent)
// RegisterFuncReloadBefore registers a hook executed before component reload.
// This hook runs before any component's Reload() method is called.
// Use for: pre-reload backup, configuration validation, logging.
// If the hook returns an error, the reload sequence is aborted.
RegisterFuncReloadBefore(fct FuncEvent)
// RegisterFuncReloadAfter registers a hook executed after component reload.
// This hook runs after all components have reloaded successfully.
// Use for: post-reload validation, cache clearing, notification.
// If the hook returns an error, it's treated as a reload failure.
RegisterFuncReloadAfter(fct FuncEvent)
// RegisterFuncStopBefore registers a hook executed before component shutdown.
// This hook runs before any component's Stop() method is called.
// Use for: pre-shutdown logging, resource flushing, notification.
// Errors from this hook are logged but do not prevent shutdown.
RegisterFuncStopBefore(fct FuncEvent)
// RegisterFuncStopAfter registers a hook executed after component shutdown.
// This hook runs after all components have stopped.
// Use for: cleanup verification, final logging, monitoring notification.
// Errors from this hook are logged but ignored (shutdown continues).
RegisterFuncStopAfter(fct FuncEvent)
// RegisterDefaultLogger registers a logger provider function for components.
// Components use this logger for operational logging.
// The function is called each time a component needs a logger instance.
// If not registered, components may not have logging capability.
RegisterDefaultLogger(fct liblog.FuncLog)
// ComponentList provides component registry operations.
// Includes: ComponentSet, ComponentGet, ComponentDel, ComponentList,
// ComponentKeys, ComponentStart, ComponentStop, ComponentReload.
cfgtps.ComponentList
// ComponentMonitor provides monitoring integration.
// Allows components to register health checks and metrics.
cfgtps.ComponentMonitor
// GetShellCommand returns interactive shell commands for runtime management.
// Commands include: list (show components), start (start components),
// stop (stop components), restart (restart components).
// These commands can be integrated into CLI applications or interactive shells.
GetShellCommand() []shlcmd.Command
}
Config is the main interface for application lifecycle management. It provides component orchestration, dependency resolution, event hooks, context management, and shell command integration.
Lifecycle Operations:
- Start(): Initialize and start all registered components in dependency order
- Reload(): Hot-reload components without full restart
- Stop(): Gracefully shutdown all components in reverse dependency order
- Shutdown(code): Complete application termination with cleanup and exit
Component Management:
- ComponentSet/Get/Del: Register and manage components
- ComponentList/Keys: Enumerate registered components
- ComponentStart/Stop/Reload: Lifecycle operations on components
Event Hooks:
- RegisterFuncStartBefore/After: Hooks around start operations
- RegisterFuncReloadBefore/After: Hooks around reload operations
- RegisterFuncStopBefore/After: Hooks around stop operations
Context & Cancellation:
- Context(): Shared application context for all components
- CancelAdd/CancelClean: Custom cancellation handlers
Configuration:
- RegisterFuncViper: Viper configuration provider
- RegisterDefaultLogger: Logger provider for components
- DefaultConfig(): Generate default configuration file
Shell Commands:
- GetShellCommand(): Interactive commands for runtime management
func New ¶
New creates and initializes a new Config instance for application lifecycle management.
Parameters:
- vrs: Version information for the application (can be nil)
Returns:
- Config: A fully initialized configuration orchestrator
The returned Config instance:
- Uses a shared application context for all components
- Automatically monitors the context for cancellation
- Provides thread-safe component registration and management
- Supports dependency resolution and ordered lifecycle operations
Initialization:
- Creates internal registries for components, hooks, and functions
- Registers the provided version information
- Starts a goroutine to monitor context cancellation
Example:
version := libver.NewVersion(...)
cfg := config.New(version)
defer cfg.Stop()
// Register components
cfg.ComponentSet("database", dbComponent)
cfg.ComponentSet("cache", cacheComponent)
// Start all components
if err := cfg.Start(); err != nil {
log.Fatal(err)
}
Thread Safety: All operations on the returned Config instance are thread-safe and can be called concurrently from multiple goroutines.