CascadeConfig 0.1.1

CascadeConfig

.NET client SDK for the Cascade hierarchical configuration management system. Provides real-time configuration updates with offline fallback support.

Features

• Hierarchical Configuration Resolution: Dot-notation addresses automatically merge configs from parent to child (e.g., my-app.production.user)
• Real-time Updates: Automatic configuration updates via SignalR when configs change on the server
• Offline Fallback: Local caching ensures your app continues working when disconnected
• Type-safe: Strongly-typed configuration classes with automatic JSON deserialization
• Simple API: Three-step setup: Setup() → Bind<T>() → Get<T>()

Installation

dotnet add package CascadeConfig

Quick Start

1. Setup the Client

Configure the client once at application startup with your API key:

using Cascade.Client;

// Use the Cascade Cloud service (most common)
CX.Setup("your-api-key");

// Or connect to your own self-hosted server
CX.Setup("your-api-key", "https://your-cascade-server.com");

Note: If you don't specify a base URL, the SDK automatically connects to the Cascade Cloud service.

2. Bind a Configuration Type

Bind your configuration class to a hierarchical address:

public class AppConfig
{
    public string DatabaseUrl { get; set; }
    public int Timeout { get; set; }
    public bool EnableDebug { get; set; }
}

// Bind the config type to an address
CX.Bind<AppConfig>("my-app.production");

3. Access the Configuration

Retrieve and use the configuration:

// Get current config value
var config = CX.Get<AppConfig>().Current;
Console.WriteLine($"Database: {config.DatabaseUrl}");

// Subscribe to real-time updates
CX.Get<AppConfig>().OnUpdated += (updatedConfig) =>
{
    Console.WriteLine($"Config updated! New timeout: {updatedConfig.Timeout}");
};

Complete Example

using System.Text.Json;
using Cascade.Client;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            // 1. Setup - connects to Cascade Cloud by default
            CX.Setup("your-api-key");

            // 2. Bind configuration
            CX.Bind<AppConfig>("my-app.production.server1");

            // 3. Access current config
            var config = CX.Get<AppConfig>().Current;
            Console.WriteLine(JsonSerializer.Serialize(config));

            // 4. React to updates
            CX.Get<AppConfig>().OnUpdated += cfg =>
            {
                Console.WriteLine($"Config changed! Debug mode: {cfg.EnableDebug}");
            };

            Console.WriteLine("Press any key to exit...");
            Console.ReadKey();
        }
    }

    public class AppConfig
    {
        public string DatabaseUrl { get; set; }
        public int Timeout { get; set; }
        public bool EnableDebug { get; set; }
        public NestedSettings Settings { get; set; }
    }

    public class NestedSettings
    {
        public string Region { get; set; }
        public int MaxConnections { get; set; }
    }
}

How Hierarchical Resolution Works

When you bind to an address like my-app.production.server1, Cascade:

1. Starts with the root config: my-app
2. Merges in the child: my-app.production
3. Finally merges the leaf: my-app.production.server1

Example:

my-app:                    { "timeout": 30, "retries": 3 }
my-app.production:         { "timeout": 60, "ssl": true }
my-app.production.server1: { "timeout": 120 }

Result: { "timeout": 120, "retries": 3, "ssl": true }

Child properties override parent properties. This allows you to define base configurations and selectively override values at each level.

API Reference

CX.Setup(string apiKey, string baseUrl = "...")

Configures the client with your API key and optional server URL. Call this once at startup.

Parameters:

• apiKey - Your Cascade API key
• baseUrl - (Optional) Your Cascade server URL. If omitted, connects to Cascade Cloud automatically.

Examples:

// Connect to Cascade Cloud (recommended for most users)
CX.Setup("your-api-key");

// Connect to self-hosted server
CX.Setup("your-api-key", "http://localhost:5000");

CX.Bind<T>(string address)

Binds a configuration type to a hierarchical address and starts syncing.

Parameters:

• T - Your configuration class type
• address - Dot-notation address (e.g., "my-app.staging.worker")

Throws:

• Exception - If the type is already bound to a different address

Example:

CX.Bind<AppConfig>("my-app.production");

CX.Get<T>()

Retrieves a previously bound configuration.

Returns: ICascadeConfig<T> - The configuration instance

Throws:

• Exception - If no binding exists for the type

Example:

var config = CX.Get<AppConfig>();

ICascadeConfig<T> Interface

Properties:

• T? Current - The current resolved configuration value
• string Address - The hierarchical address this config is bound to

Events:

• event Action<T>? OnUpdated - Fires when the configuration is updated from the server

Example:

var cascadeConfig = CX.Get<AppConfig>();

// Access current value
var timeout = cascadeConfig.Current.Timeout;

// Subscribe to updates
cascadeConfig.OnUpdated += (newConfig) =>
{
    Console.WriteLine($"Updated: {newConfig.Timeout}");
};

Security Best Practices

Never hardcode API keys in your source code. Use environment variables or configuration files:

Option 1: Environment Variables (Recommended)

var apiKey = Environment.GetEnvironmentVariable("CASCADE_API_KEY");
var baseUrl = Environment.GetEnvironmentVariable("CASCADE_URL");
CX.Setup(apiKey, baseUrl);

Option 2: Configuration Files

// appsettings.json
{
  "Cascade": {
    "ApiKey": "your-api-key",
    "BaseUrl": "https://your-server.com"
  }
}

// Program.cs
var config = builder.Configuration.GetSection("Cascade");
CX.Setup(config["ApiKey"], config["BaseUrl"]);

Option 3: Azure Key Vault / AWS Secrets Manager

var apiKey = await secretClient.GetSecretAsync("cascade-api-key");
CX.Setup(apiKey.Value.Value, "https://your-server.com");

Offline Support

Cascade automatically caches configurations locally. If the server is unreachable during Bind<T>(), the SDK will automatically fall back to the cached configuration.

Cache location: .cascade/ directory in your application's working directory

Manual cache path:

CX.Settings.LocalCachePath = "/path/to/cache";

Error Handling

try
{
    CX.Bind<AppConfig>("my-app.production");
}
catch (Exception ex)
{
    Console.WriteLine($"Failed to load config: {ex.Message}");
    // SDK automatically falls back to local cache if available
}

What happens on error:

• Initial fetch fails: Exception thrown
• SignalR connection fails: Logged but not fatal (config still works, no real-time updates)
• Config update fails to deserialize: Logged, previous config remains active

Advanced: Custom Logger

Implement ICascadeLogger to integrate with your logging framework:

public class MyLogger : ICascadeLogger
{
    private readonly ILogger _logger;

    public MyLogger(ILogger logger)
    {
        _logger = logger;
    }

    public void Debug(string msg) => _logger.LogDebug(msg);
    public void Error(string msg) => _logger.LogError(msg);
}

// Set custom logger
CX.Logger = new MyLogger(myLoggerInstance);

Requirements

• .NET 8.0 or .NET 9.0
• Network access to your Cascade server

Support

• Website: https://cascade-cloud.com
• Documentation: https://cascade-cloud.com/docs
• Issues: https://github.com/ziachap/cascade/issues

License

MIT License - see LICENSE file for details.