Config Management

Ironflow provides environment-scoped configuration management. It allows you to store, patch, and watch JSON documents representing application settings, feature flags, or system parameters.

Event-Driven by Design

Config Management is built directly on top of Ironflow’s NATS JetStream architecture using system-level KV buckets (SYS_config_*), separate from user-facing KV Store buckets.

• Durable: Every change is persisted to an internal NATS KV bucket (not visible in the KV Store dashboard).
• Atomic: patch operations use automatic CAS (Compare-And-Swap) retries to prevent lost updates.
• Observable: Every configuration change emits a system event that can trigger workflows or real-time dashboards.
• Self-healing: Config buckets are lazily created on first use and automatically recreated if deleted.

When to Use Config Management

Feature	Use For
Config Management	Application settings, Feature flags, Environment toggles.
KV Store	Session data, caching, high-frequency counters.
Secrets	API Keys, DB passwords (encrypted at rest).

---

Quick Start

Node.js (Server-side)

import { createClient } from "@ironflow/node";

const ironflow = createClient({ apiKey: process.env.IRONFLOW_API_KEY });
const config = ironflow.config();

// Set a full document
await config.set("app-settings", { theme: "dark", retries: 3 });

// Patch a specific field (shallow merge)
await config.patch("app-settings", { retries: 5 });

// Watch for real-time changes (Node SDK also supports watch via WebSocket)
const watcher = config.watch("app-settings", {
  onUpdate: (event) => console.log("New settings:", event.data),
});
// watcher.stop() to end the subscription

config.patch() automatically creates the document if it does not exist — no separate “init” call is required.

Browser (Client-side)

import { ironflow } from "@ironflow/browser";

ironflow.configure({ serverUrl: "http://localhost:9123" });

// Watch for real-time changes
const sub = await ironflow.configManager().watch("app-settings", {
  onUpdate: (cfg) => console.log("New settings:", cfg.data),
});

---

REST API Reference

Method	Path	Description
GET	/api/v1/config	List all config documents.
GET	/api/v1/config/{name}	Get a specific document.
POST	/api/v1/config/{name}	Replace a document (Full Set).
PATCH	/api/v1/config/{name}	Shallow merge fields (creates the document if missing).
DELETE	/api/v1/config/{name}	Delete a document.
GET	/api/v1/config/{name}/watch	WebSocket stream of ConfigWatchEvents.

Every write also publishes the system event system.config.{name}.updated, which any subscriber can consume.

---

Error Handling

Config operations throw typed errors consistent with the main Ironflow client:

import { IronflowError, UnauthenticatedError, UnauthorizedError } from "@ironflow/node";

try {
  const entry = await config.get("app-settings");
} catch (err) {
  if (err instanceof UnauthenticatedError) {
    console.error("Invalid or missing API key");
  } else if (err instanceof UnauthorizedError) {
    console.error("Insufficient permissions");
  } else if (err instanceof IronflowError) {
    console.error("Config error:", err.message);
  }
}

Use the global onError handler on createClient() to observe all config errors centrally. Errors from client.config() report method names like "config.get", "config.set", "config.patch".