EnumCraft.FeatureFlags.Json 1.0.1

EnumCraft.FeatureFlags.Json

JSON file provider for EnumCraft.FeatureFlags.

Overview

EnumCraft.FeatureFlags.Json is the JSON file-based data provider for the EnumCraft feature flag system. It loads feature flag configuration from a JSON file, supports per-tenant overrides, and automatically reloads when the file changes — using a FileSystemWatcher with a polling fallback for reliability.

This package is part of the EnumCraft ecosystem:

How It Works

JsonFeatureFlagProvider loads the JSON file once at startup and holds the result as an in-memory snapshot. All calls to IsActive and IsActive(tenantId) resolve against that snapshot — no file I/O occurs at query time.

When the file changes, the provider reloads it in the background and atomically swaps the snapshot. All subsequent reads see the new data. If the reload fails, the previous snapshot is retained — no partial reads, no dropped flags.

Querying is safe to call on every request. The per-call cost is a dictionary lookup.

Installation

dotnet add package EnumCraft.FeatureFlags.Json

Requirements

• .NET Standard 2.0+ or .NET 8.0+
• EnumCraft.FeatureFlags
• EnumCraft.Core

Quick Start

using EnumCraft.FeatureFlags.Json;

// Best Practice: name the json file to match its associated derived type
var options = new JsonFeatureFlagProviderOptions { DirectoryPath = AppDomain.CurrentDomain.BaseDirectory,
                                                   FileName      = "AppFeatureFlag.json" };  

var provider = new JsonFeatureFlagProvider(options);

if(!AppFeatureFlag.TryConfigure(provider, out var error))
{
  Console.WriteLine($"Failed to configure flags: {error}");
  return;
}

Optional Logging

Pass an ILogger to the constructor for diagnostic output. Falls back to NullLogger if not provided.

var logger   = loggerFactory.CreateLogger<AppFeatureFlag>();
var provider = new JsonFeatureFlagProvider(options, logger);

You can also set a logger on the provider instance after construction:

provider.SetLogger(logger);

Configuration Options

FullPath is computed automatically from DirectoryPath + FileName.

JSON File Format

Name your JSON file to match your derived flag type (e.g., AppFeatureFlag.json).

{
  "global": {
    "DarkMode":        true,
    "NewDashboard":    true,
    "BetaReporting":   false,
    "MaintenanceMode": false
  },
  "tenants": {
    "1001": {
      "DarkMode":     false,
      "NewDashboard": false
    },
    "1002": {
      "BetaReporting": true
    }
  }
}

Resolution Order

1. Tenant override — per-tenant value, if present
2. Global override — global value from JSON, if present
3. Default — constructor-defined fallback (isActiveDefault)

Key Casing

Flag keys in the JSON file must match the Code property of your flag definition exactly (case-sensitive). If you define your flags using nameof(), the key is the member name as written in C# — for example, "DarkMode", not "darkMode" or "dark_mode". A key mismatch silently falls through to the flag's constructor default with no warning.

Auto-Reload Behavior

When EnableAutoReload is true (the default):

• A FileSystemWatcher monitors the JSON file for changes
• A polling timer runs as a fallback safety net
• A debounce window (default 350ms) prevents rapid successive reloads
• On successful reload, the Changed event is raised and consumers can call GetSnapshot() for the latest data
• On failed reload due to a transient IO error or mid-write corruption, the previous snapshot is retained — no partial reads
• The watcher is automatically recreated if it encounters a buffer overflow error

Emergency Shutoff

Deleting the JSON file reverts all flags to their isActiveDefault constructor values immediately. The Changed event fires on deletion so consumers are notified.

This is the recommended emergency shutoff pattern - no application restart required. Delete the file to revert all flags to their constructor-defined defaults. Flags with isActiveDefault: false will become inactive; flags with isActiveDefault: true will become active.

When the file is recreated, the provider detects the change and reloads the new values automatically.

Production Deployment

Multiple App Servers

Each running instance of your application loads and watches the JSON file independently. There is no cross-process coordination — each process manages its own in-memory snapshot.

For deployments with multiple app servers, point all instances at the same shared file:

• A shared network path (UNC path or mapped drive)
• A mounted volume shared across containers
• A managed file storage location (e.g., Azure Files, AWS EFS)

When the file is updated, each instance will detect the change and reload independently within its configured DebounceMs + PollMs window (worst-case: ~2.35 seconds at defaults).

⚠️ Write coordination is not provided. If multiple processes write to the same file simultaneously, last-write-wins. For v1.0.0, the JSON file is treated as read-only at runtime — updates are made out-of-band (deploy, copy, or manual edit).

Disposal

JsonFeatureFlagProvider implements IDisposable. At application shutdown, dispose the provider to stop the FileSystemWatcher and polling timer cleanly:

provider.Dispose();

After disposal, GetSnapshot() continues to return the last known snapshot — no exceptions thrown. The Changed event will not fire after disposal.

Framework Support

Dependencies

• EnumCraft.Core (v1.0.0 or later)
• EnumCraft.FeatureFlags (v1.0.0 or later)
• System.Text.Json (v4.7.2 or later)

Known Limitations

• Key matching is case-sensitive. A key mismatch silently falls through to the flag's constructor default with no warning. Configurable case sensitivity is planned for a future release.
• No write coordination across processes. See Production Deployment.
• Configure() may only be called once per flag type. Use TryConfigure() for a non-throwing alternative. Runtime provider swapping (Reconfigure()) is planned for a future release.

Related Packages

• EnumCraft.Core — Type-safe enumerations and flags
• EnumCraft.Json — JSON serialization extensions for TypedEnum and TypedFlag
• EnumCraft.FeatureFlags — Feature flag abstraction and resolution engine

License

MIT — see LICENSE for details.

Author

Randel Bjorkquist — GitHub | NuGet