{"id":19674755,"url":"https://github.com/cloudwego/configmanager","last_synced_at":"2025-04-29T02:30:26.166Z","repository":{"id":165999161,"uuid":"632314101","full_name":"cloudwego/configmanager","owner":"cloudwego","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-17T02:31:21.000Z","size":68,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-05T12:33:10.930Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudwego.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-25T06:45:30.000Z","updated_at":"2025-04-04T03:55:50.000Z","dependencies_parsed_at":"2024-04-29T08:55:36.992Z","dependency_job_id":null,"html_url":"https://github.com/cloudwego/configmanager","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":"cloudwego/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwego%2Fconfigmanager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwego%2Fconfigmanager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwego%2Fconfigmanager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwego%2Fconfigmanager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudwego","download_url":"https://codeload.github.com/cloudwego/configmanager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251420862,"owners_count":21586693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T17:19:40.936Z","updated_at":"2025-04-29T02:30:25.781Z","avatar_url":"https://github.com/cloudwego.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Config Manager\n\n## Introduction\n\nThe `configmanager` is a package that provides a robust and efficient way to manage and\nhandle configuration data in your application. It's designed to load configurations\nperiodically from arbitrary sources, such as a file, a database, or a web service. The\nmodule also provides monitoring on configuration changes and allows instant callback of\na registered listener.\n\n## Features\n\n* Refreshes configuration data at regular intervals specified\n* Provides methods for accessing configuration data\n* Supports configuration change listeners for efficient handling of updates\n* Includes a default FileProvider for loading configurations from a file\n* Allows for customizable options and arbitrary sources\n\n## Overview\n\nConfigManager is designed with a 4-level hierarchy:\n\n- ConfigManager:\n  - Holds a `Provider` for loading of all configurations\n  - Compares two versions of config and notify registered listeners if there's any difference\n  - Provides APIs to reload config, retrieve certain config value/item, dump to files, etc.\n- Provider:\n  - Responsible for loading configurations from desired source(s)\n  - Returns all configs in the form of `map[string]iface.ConfigValue` to the calling ConfigManager\n- ConfigValue:\n  - Holding a set of `iface.ConfigValueItem`\n    - The builtin `ConfigValueImpl` is designed with a `map[iface.ItemType]iface.ConfigValueItem`\n  - Provides APIs to retrieve certain config item\n- ConfigValueItem:\n  - Holds specific configurations according to requirement\n\n## Usage\n\n### Quick Start\n\n\u003e You can go directly to the `example/main.go` for a runnable example of the following steps.\n\n`configmanager` ships with a `FileProvider` which loads from a config file in JSON format.\n\nWe'll begin with a JSON config file below (save it as `config.json`):\n\n```\n{\n  \"test1\": {\n    \"item-max-retry\": 1,\n    \"item-max-limit\": 2,\n    \"item-service-name\": \"service_name\"\n  }\n}\n```\n\nImport the package into your application.\n\n```\nimport (\n\t\"github.com/cloudwego/configmanager\"\n\t\"github.com/cloudwego/configmanager/configvalue/items\"\n\t\"github.com/cloudwego/configmanager/fileprovider\"\n\t\"github.com/cloudwego/configmanager/iface\n)\n```\n\nInitialize a FileProvider\n```\n// define your own item type for builtin items\nconst TypeItemMaxRetry iface.ItemType = \"item-max-retry\"\nconst TypeItemMaxLimit iface.ItemType = \"item-max-limit\"\nconst TypeItemServiceName iface.ItemType = \"item-service-name\"\n\nitemFactory := fileprovider.NewItemFactory(map[iface.ItemType]iface.ItemInitializer{\n    TypeItemMaxRetry:    items.NewItemInt64,\n    TypeItemMaxLimit:    items.NewItemInt64, // an item can be used with multiple item types\n    TypeItemServiceName: items.NewItemString,\n    // you can register your own ConfigValueItem(s) here\n})\n\nprovider := fileprovider.NewFileProvider(\n    fileprovider.WithFileProviderItemFactory(itemFactory),\n    fileprovider.WithFileProviderPath(\"config.json\"),\n)\n```\n\nCreate a new instance of ConfigManager with the desired options.\n```\nmanager := configmanager.NewConfigManager([]configmanager.ConfigManagerOption{\n    configmanager.WithRefreshInterval(10 * time.Second),\n    configmanager.WithConfigProvider(provider),\n)\n```\n\nRegister configuration change listeners as needed:\n```\nmanager.RegisterConfigChangeListener(\"unique-id-for-each-listener\", func(change iface.ConfigChange) {\n    // update something according to the change\n    log.Println(\"Change:\", string(util.MustJsonMarshal(change)))\n})\n```\n\nRefresh the configuration data manually if necessary.\n```\n// send a refresh signal and return immediately:\nmanager.Refresh()\n\n// or if you need to wait until the loading completes:\nmanager.RefreshAndWait()\n```\n\nAccess and retrieve configuration using the provided methods:\n```\n// define your iface.ConfigKey with a ToString() method\nconfigKey := \"SomeConfigKey\"\n\n// it's recommended to retrieve the ConfigValueItem directly:\nmaxRetryItem, err := manager.GetConfigItem(configKey, TypeItemMaxRetry)\nif err == nil {\n    maxRetry := maxRetryItem.(*items.ItemInt64).Value()\n    ...\n}\n\n// you can also retrieve the ConfigValueImpl for other purposes\nconfigValue, err := manager.GetConfig(configKey)\nif err == nil {\n    maxRetryLimit, err := configValue.GetItem(TypeItemMaxLimit)\n    // or call GetItemOrDefault() with a default item value\n    serviceName := configValue.GetItemOrDefault(TypeItemServiceName, items.CopyDefaultItemString())\n}\n```\n\nExport the configuration data to a file using the `Dump` method.\n```\nerr := manager.Dump(\"local_dump.json\")\n```\n\n### Customization\n\n#### ConfigValueItems\n\nBasic items like ItemBool, ItemInt64, ItemPair, ItemString is shipped with this package. You can\ndefine your own ItemType for simple configuration only holding basic go type values with these items.\n\nIf you need items more complicated, just create your own items implementing the `iface.ConfigValueItem`.\nIt might be easier to copy from items.ItemPair and make modifications.\n\n#### ConfigValue\n\nThe built-in `ConfigValueImpl` mainly focuses on its extensibility, which allows for extending of new\ntypes of ConfigValueItem without modifying ConfigValueImpl and FileProvider, at the cost of increasing\nits complexity (harder to comprehend).\n\nIf you wish, you can write your own implementation of `iface.ConfigValue`. It's not recommended, because\nit's not compatible with the builtin FileProvider.\n\n#### Provider\n\n##### FileProvider\n\nAvailable Options are:\n\n* WithFileProviderPath\n  * The specified file will be used to load the configuration data.\n* WithFileProviderItemFactory\n  * The ItemFactory is responsible for creating new instances of ConfigValueItem when loading data from the file.\n* WithFileProviderLogger\n  * This option sets a custom logger implementation for the FileProvider.\n  * By default, the logger uses log.Printf.\n\n##### Provider for other sources\n\nYou can implement your own Provider to load config from other sources, as long as it implements the\n`iface.ConfigProvider`.\n\nIt's recommended to use `ConfigValueImpl` as the value in the returned config map, thus you can easily\nswitch your provider to `FileProvider`.\n\n#### ConfigManager\n\nAvailable Options are:\n\n* WithRefreshInterval\n  * This option sets the interval for refreshing the configuration data.\n  * If not set, the interval defaults to 10 seconds.\n* WithConfigProvider\n  * This option sets the given ConfigProvider as the source for configuration data.\n* WithErrorLogger\n  * This option sets a custom error logger for the ConfigManager instance.\n  * If not set, the logger defaults to log.Printf.\n* WithConfigSerializer\n  * This option sets a custom ConfigSerializer for the ConfigManager.\n  * If not set, the serializer defaults to util.JSONSerializer.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwego%2Fconfigmanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudwego%2Fconfigmanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwego%2Fconfigmanager/lists"}