Subscriptions

Subscription patterns determine which events are delivered to a subscriber. Ironflow uses NATS-style wildcards for flexible pattern matching.

Wildcard Syntax

Token	Description	Example
*	Matches one segment.	system.run.*.created
>	Matches all remaining segments.	events:>

---

Connection Lifecycle

For real-time subscriptions, the SDK maintains a persistent connection (WebSocket or ConnectRPC stream).

TypeScript

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

// 1. Connect to the stream
await ironflow.connect();

// 2. Monitor connection state
const off = ironflow.onConnectionChange((state) => {
  console.log(`Connection state: ${state}`); // 'connected', 'reconnecting', etc.
});

// 3. Disconnect when finished
ironflow.disconnect();
off();

Go

// Connect with a timeout context
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

if err := subClient.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer subClient.Close()

---

Pattern Helpers

TypeScript

Browser (Singleton):

import { ironflow } from "@ironflow/browser";
await ironflow.subscribe("events:order.*", { onEvent: (e) => {} });

Node.js (Instance):

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

const subClient = createSubscriptionClient({
  serverUrl: "http://localhost:9123",
  apiKey: "...",
});
await subClient.connect();
const sub = await subClient.subscribe("system.run.>", { onEvent: (e) => {} });

Go

sub, err := client.Subscribe(ctx, ironflow.Patterns.AllRuns(), nil)

---

Lifecycle & Storage

Regular subscriptions are ephemeral and stored in-memory on the server.

1. Disconnect: If a client disconnects, the subscription is removed from the server.
2. Reconnect: SDKs automatically restore subscriptions upon reconnection.
3. Replay: Use the replay option to retrieve missed events during a reconnect.

await ironflow.subscribe("events:>", {
  replay: 10, // Replay last 10 events on every (re)connect
  onEvent: (e) => console.log(e)
});