Config Resolver
A modular, lightweight, and extensible configuration resolver for Rust that allows auto-detecting and resolving configuration values (such as IP addresses, port numbers, peer IDs, and socket addresses) at runtime.
This is particularly useful for containerized applications, cloud environments (AWS, DigitalOcean), or P2P/distributed systems where static configuration files are insufficient, and bindings must adapt dynamically to the environment.
Features
- Recursive Parsing & Resolution:
- Static values: Supports standard Rust parser values like
127.0.0.1,3000, or127.0.0.1:8080. - Dynamic Lookups: Resolves variables like
DO_PUBLIC_IPorAWS_PRIVATE_IPby querying metadata services. - Combined Addresses: Construct complex Socket addresses dynamically, e.g.,
DO_PUBLIC_IP:3000orIPIFY:8080. - Offset Calculations: Performs mathematical calculations directly on IP addresses (converting IPv4 to a unique
u64base and adding an offset), e.g.,CALC(DO_PUBLIC_IP+10000). Useful for generating unique Peer IDs in distributed protocols.
- Static values: Supports standard Rust parser values like
- Type-Safe: Clean parsing into standard library types like
IpAddr,SocketAddr,u32, andu64via theConfigUnittrait. - Feature-Gated Providers: AWS, DigitalOcean, and Ipify HTTP-based lookups can be compiled conditionally, keeping the crate extremely lightweight when only static resolution or custom providers are needed.
- Extensible: Define your own custom provider by implementing the
ConfigProvidertrait and registering it with theConfigRegistry.
Installation
Add config-resolver to your Cargo.toml:
[]
= "0.2"
If you only need static resolution or custom providers (no remote metadata calls over HTTP), disable the default features to eliminate the dependency on reqwest and TLS:
[]
= { = "0.2", = false }
Cargo Features
By default, all cloud metadata and external providers are enabled. You can disable them or select only what you need:
| Feature | Description | Dependencies | Enabled by Default |
|---|---|---|---|
aws |
AWS EC2 Instance Metadata Service (IMDSv2) provider (AWS_PUBLIC_IP, AWS_PRIVATE_IP) |
reqwest |
Yes |
digital-ocean |
DigitalOcean Droplet metadata provider (DO_PUBLIC_IP, DO_PRIVATE_IP) |
reqwest |
Yes |
ipify |
Public IP lookup via api.ipify.org (IPIFY) |
reqwest |
Yes |
Supported Expressions
The config resolver parses and resolves configuration specification strings into standard Rust types dynamically at runtime. The table below lists all supported syntax patterns and expressions:
| Expression Type | Syntax Pattern / Examples | Target Rust Type | Description |
|---|---|---|---|
| Static Value | 127.0.0.1::1 |
IpAddr |
Standard static IPv4 or IPv6 address. |
| Static Value | 80803000 |
u32 / u64 |
Standard unsigned integers. |
| Static Value | 127.0.0.1:8080 |
SocketAddr |
Standard static socket address (IP + Port). |
| Dynamic Lookup | IPIFY |
IpAddr |
Queries the public IP address via api.ipify.org. |
| Dynamic Lookup | AWS_PUBLIC_IPAWS_PRIVATE_IP |
IpAddr |
Queries AWS IMDSv2 metadata service for the public or private IPv4. |
| Dynamic Lookup | DO_PUBLIC_IPDO_PRIVATE_IP |
IpAddr |
Queries DigitalOcean droplet metadata service for the public or private IPv4. |
| Combined Socket | <IP_EXPR>:<PORT_EXPR>Example: DO_PUBLIC_IP:3000Example: IPIFY:8080Example: AWS_PRIVATE_IP:CONSUL_PORT |
SocketAddr |
Combines any IP specification (static or dynamic) with a port specification (static or dynamic). |
| Offset Calculation | CALC(<IP_EXPR>+<OFFSET>)Example: CALC(127.0.0.1+100)Example: CALC(DO_PUBLIC_IP+10000) |
u64 |
Resolves the IP expression, converts it into its u32 integer equivalent, adds the specified offset, and returns the result as u64. Perfect for generating unique Peer IDs in distributed protocols. |
Usage
1. Basic Resolution
use ;
use create_default_registry;
async
1b. Synchronous Resolution
If you do not have an asynchronous runtime or want to resolve configuration values synchronously (e.g. at the start of your program), you can use the synchronous .resolve_sync() method:
use ;
use create_default_registry;
2. Integration with clap
You can integrate config-resolver with clap to automatically resolve configuration specifications at parse time, allowing your parsed struct fields to have native types (such as u32, u64, IpAddr, or SocketAddr) directly without any wrappers:
use Parser;
use ;
use clap_value_parser;
[!NOTE]
clap_value_parserutilizes a global registry. If you want to use custom providers, register them usingconfig_resolver::init_global_registry(my_registry)at the start of your program before callingArgs::parse().
3. Custom Providers
You can easily register your own resolution providers:
use async_trait;
use ;
use IpAddr;
;
async
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.