configmanager

README

Config Manager

Introduction

The configmanager is a package that provides a robust and efficient way to manage and handle configuration data in your application. It's designed to load configurations periodically from arbitrary sources, such as a file, a database, or a web service. The module also provides monitoring on configuration changes and allows instant callback of a registered listener.

Features

• Refreshes configuration data at regular intervals specified
• Provides methods for accessing configuration data
• Supports configuration change listeners for efficient handling of updates
• Includes a default FileProvider for loading configurations from a file
• Allows for customizable options and arbitrary sources

Overview

ConfigManager is designed with a 4-level hierarchy:

• ConfigManager:
  • Holds a Provider for loading of all configurations
  • Compares two versions of config and notify registered listeners if there's any difference
  • Provides APIs to reload config, retrieve certain config value/item, dump to files, etc.
• Provider:
  • Responsible for loading configurations from desired source(s)
  • Returns all configs in the form of map[string]iface.ConfigValue to the calling ConfigManager
• ConfigValue:
  • Holding a set of iface.ConfigValueItem
    • The builtin ConfigValueImpl is designed with a map[iface.ItemType]iface.ConfigValueItem
  • Provides APIs to retrieve certain config item
• ConfigValueItem:
  • Holds specific configurations according to requirement

Usage

Quick Start

You can go directly to the example/main.go for a runnable example of the following steps.

configmanager ships with a FileProvider which loads from a config file in JSON format.

We'll begin with a JSON config file below (save it as config.json):

{
  "test1": {
    "item-max-retry": 1,
    "item-max-limit": 2,
    "item-service-name": "service_name"
  }
}

Import the package into your application.

import (
	"github.com/cloudwego/configmanager"
	"github.com/cloudwego/configmanager/configvalue/items"
	"github.com/cloudwego/configmanager/fileprovider"
	"github.com/cloudwego/configmanager/iface
)

Initialize a FileProvider

// define your own item type for builtin items
const TypeItemMaxRetry iface.ItemType = "item-max-retry"
const TypeItemMaxLimit iface.ItemType = "item-max-limit"
const TypeItemServiceName iface.ItemType = "item-service-name"

itemFactory := fileprovider.NewItemFactory(map[iface.ItemType]iface.ItemInitializer{
    TypeItemMaxRetry:    items.NewItemInt64,
    TypeItemMaxLimit:    items.NewItemInt64, // an item can be used with multiple item types
    TypeItemServiceName: items.NewItemString,
    // you can register your own ConfigValueItem(s) here
})

provider := fileprovider.NewFileProvider(
    fileprovider.WithFileProviderItemFactory(itemFactory),
    fileprovider.WithFileProviderPath("config.json"),
)

Create a new instance of ConfigManager with the desired options.

manager := configmanager.NewConfigManager([]configmanager.ConfigManagerOption{
    configmanager.WithRefreshInterval(10 * time.Second),
    configmanager.WithConfigProvider(provider),
)

Register configuration change listeners as needed:

manager.RegisterConfigChangeListener("unique-id-for-each-listener", func(change iface.ConfigChange) {
    // update something according to the change
    log.Println("Change:", string(util.MustJsonMarshal(change)))
})

Refresh the configuration data manually if necessary.

// send a refresh signal and return immediately:
manager.Refresh()

// or if you need to wait until the loading completes:
manager.RefreshAndWait()

Access and retrieve configuration using the provided methods:

// define your iface.ConfigKey with a ToString() method
configKey := "SomeConfigKey"

// it's recommended to retrieve the ConfigValueItem directly:
maxRetryItem, err := manager.GetConfigItem(configKey, TypeItemMaxRetry)
if err == nil {
    maxRetry := maxRetryItem.(*items.ItemInt64).Value()
    ...
}

// you can also retrieve the ConfigValueImpl for other purposes
configValue, err := manager.GetConfig(configKey)
if err == nil {
    maxRetryLimit, err := configValue.GetItem(TypeItemMaxLimit)
    // or call GetItemOrDefault() with a default item value
    serviceName := configValue.GetItemOrDefault(TypeItemServiceName, items.CopyDefaultItemString())
}

Export the configuration data to a file using the Dump method.

err := manager.Dump("local_dump.json")

Customization

ConfigValueItems

Basic items like ItemBool, ItemInt64, ItemPair, ItemString is shipped with this package. You can define your own ItemType for simple configuration only holding basic go type values with these items.

If you need items more complicated, just create your own items implementing the iface.ConfigValueItem. It might be easier to copy from items.ItemPair and make modifications.

ConfigValue

The built-in ConfigValueImpl mainly focuses on its extensibility, which allows for extending of new types of ConfigValueItem without modifying ConfigValueImpl and FileProvider, at the cost of increasing its complexity (harder to comprehend).

If you wish, you can write your own implementation of iface.ConfigValue. It's not recommended, because it's not compatible with the builtin FileProvider.

Provider

FileProvider

Available Options are:

• WithFileProviderPath
  • The specified file will be used to load the configuration data.
• WithFileProviderItemFactory
  • The ItemFactory is responsible for creating new instances of ConfigValueItem when loading data from the file.
• WithFileProviderLogger
  • This option sets a custom logger implementation for the FileProvider.
  • By default, the logger uses log.Printf.

Provider for other sources

You can implement your own Provider to load config from other sources, as long as it implements the iface.ConfigProvider.

It's recommended to use ConfigValueImpl as the value in the returned config map, thus you can easily switch your provider to FileProvider.

ConfigManager

Available Options are:

• WithRefreshInterval
  • This option sets the interval for refreshing the configuration data.
  • If not set, the interval defaults to 10 seconds.
• WithConfigProvider
  • This option sets the given ConfigProvider as the source for configuration data.
• WithErrorLogger
  • This option sets a custom error logger for the ConfigManager instance.
  • If not set, the logger defaults to log.Printf.
• WithConfigSerializer
  • This option sets a custom ConfigSerializer for the ConfigManager.
  • If not set, the serializer defaults to util.JSONSerializer.

Documentation

Index

• Constants
• type ConfigManager
  • func NewConfigManager(options []ConfigManagerOption) *ConfigManager
  • func (m *ConfigManager) DeregisterConfigChangeListener(identifier string)
  • func (m *ConfigManager) Dump(filepath string) error
  • func (m *ConfigManager) GetAllConfig() map[string]iface.ConfigValue
  • func (m *ConfigManager) GetConfig(key string) (iface.ConfigValue, error)
  • func (m *ConfigManager) GetConfigItem(key string, itemType iface.ItemType) (iface.ConfigValueItem, error)
  • func (m *ConfigManager) GetProvider() iface.ConfigProvider
  • func (m *ConfigManager) Refresh() iface.RefreshCompleteSignal
  • func (m *ConfigManager) RefreshAndWait() error
  • func (m *ConfigManager) RegisterConfigChangeListener(identifier string, listener iface.ConfigChangeListener)
  • func (m *ConfigManager) Stop()
• type ConfigManagerOption
  • func WithConfigProvider(provider iface.ConfigProvider) ConfigManagerOption
  • func WithConfigSerializer(serializer iface.ConfigSerializer) ConfigManagerOption
  • func WithErrorLogger(logger iface.LogFunc) ConfigManagerOption
  • func WithLogLimiter(limiter iface.Limiter) ConfigManagerOption
  • func WithRefreshInterval(interval time.Duration) ConfigManagerOption
  • func WithWaitTimeout(timeout time.Duration) ConfigManagerOption

Constants

const (
	Name    = "ConfigManager"
	Version = "v0.2.2"
	Home    = "https://github.com/cloudwego/configmanager"
)

Types

type ConfigManager

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

ConfigManager is a struct that manages configuration data, including refreshing it at regular intervals. It uses a read-only sync.Map to store the current configuration, and provides methods for accessing it.

func NewConfigManager

func NewConfigManager(options []ConfigManagerOption) *ConfigManager

NewConfigManager creates a new instance of ConfigManager with the given options.

func (*ConfigManager) DeregisterConfigChangeListener

func (m *ConfigManager) DeregisterConfigChangeListener(identifier string)

DeregisterConfigChangeListener removes a listener from config manager

func (*ConfigManager) Dump

func (m *ConfigManager) Dump(filepath string) error

Dump exports the ConfigManager's configuration to a file specified by the file path.

func (*ConfigManager) GetAllConfig

func (m *ConfigManager) GetAllConfig() map[string]iface.ConfigValue

GetAllConfig retrieves all configuration values stored in the ConfigManager's map and returns it in a map with a string key and iface.ConfigValue value. **DO NOT MODIFY** values in the returned map.

func (*ConfigManager) GetConfig

func (m *ConfigManager) GetConfig(key string) (iface.ConfigValue, error)

GetConfig retrieves the configuration value for the given key from the ConfigManager. If the key is not found, it returns an error indicating the key was not found. If the value of the key is not of type ConfigValue, it panics with an error message.

func (*ConfigManager) GetConfigItem

func (m *ConfigManager) GetConfigItem(key string, itemType iface.ItemType) (iface.ConfigValueItem, error)

GetConfigItem retrieves a specific value from the configuration based on the given key and item type. Returns the retrieved configuration value item and an error if unable to retrieve it.

func (*ConfigManager) GetProvider

func (m *ConfigManager) GetProvider() iface.ConfigProvider

GetProvider returns the ConfigProvider interface associated with the ConfigManager instance. In some scenarios, there's need to call the provider's API

func (*ConfigManager) Refresh

func (m *ConfigManager) Refresh() iface.RefreshCompleteSignal

Refresh is called to refresh the configuration manager by sending a refresh signal. It may block if there are lots of callers

func (*ConfigManager) RefreshAndWait

func (m *ConfigManager) RefreshAndWait() error

RefreshAndWait updates the configuration of ConfigManager and waits until the update process completes.

func (*ConfigManager) RegisterConfigChangeListener

func (m *ConfigManager) RegisterConfigChangeListener(identifier string, listener iface.ConfigChangeListener)

RegisterConfigChangeListener registers a listener to config manager with a unique identifier for deregistration

func (*ConfigManager) Stop

func (m *ConfigManager) Stop()

Stop ends the ConfigManager's refreshConfigLoop

type ConfigManagerOption

type ConfigManagerOption func(*ConfigManager)

ConfigManagerOption is a function type that modifies the configuration of a ConfigManager

func WithConfigProvider

func WithConfigProvider(provider iface.ConfigProvider) ConfigManagerOption

WithConfigProvider sets the given ConfigProvider as the source for configuration data.

func WithConfigSerializer

func WithConfigSerializer(serializer iface.ConfigSerializer) ConfigManagerOption

WithConfigSerializer sets the ConfigSerializer for the ConfigManager. If not set, the serializer defaults to be util.JSONSerializer

func WithErrorLogger

func WithErrorLogger(logger iface.LogFunc) ConfigManagerOption

WithErrorLogger sets the error logger for the ConfigManager instance If not set, the logger defaults to be log.Printf

func WithLogLimiter

func WithLogLimiter(limiter iface.Limiter) ConfigManagerOption

WithLogLimiter sets a Limiter for logging in ConfigManager.

func WithRefreshInterval

func WithRefreshInterval(interval time.Duration) ConfigManagerOption

WithRefreshInterval sets the interval time for refreshing the configuration. If not set, the interval defaults to be defaultRefreshInterval

func WithWaitTimeout

func WithWaitTimeout(timeout time.Duration) ConfigManagerOption

WithWaitTimeout sets the timeout for waiting for the configuration update to complete. if not set, the timeout defaults to be defaultWaitTimeout