Best Practices

This guide covers strategies for managing subscriptions, handling failures, and optimizing event-driven logic.

Subscription Resource Management

1. Reuse Clients: Create one client per application lifecycle. Do not create a new client for every subscription.
2. Specific Patterns: Use specific patterns (e.g., events:order.123) instead of wildcards (events:>) where possible to reduce network traffic.
3. Limit In-Flight: Use maxInflight in consumer groups to prevent your worker from being overwhelmed.

---

Error Handling Patterns

Real-time subscriptions can fail due to network drops or server restarts. Ironflow SDKs handle reconnection automatically, but your application should be aware of the state.

TypeScript

const sub = await ironflow.subscribe("events:>", {
  onEvent: (e) => handle(e),
  onError: (error) => {
    // 'retrying' means the SDK is already attempting to reconnect
    if (error.retrying) {
      console.warn("Connection lost, reconnecting...");
    } else {
      console.error("Terminal subscription error:", error.code);
    }
  }
});

Go

for {
    select {
    case event := <-sub.Events():
        handle(event)
    case err := <-sub.Errors():
        log.Printf("Sub error [%s]: %s (retrying: %v)",
            err.Code, err.Message, err.Retrying)
    }
}

---

Idempotency

Events may be delivered more than once (At-Least-Once delivery). Your logic should be idempotent:

const processedEvents = new Set();

onEvent: (event) => {
  if (processedEvents.has(event.eventId)) return;
  processedEvents.add(event.eventId);

  // Perform logic...
}

---

Performance Considerations

Scenario	Recommendation
High Volume	Use CEL Filtering to filter on the server.
Slow Consumers	Increase the buffer size or use Consumer Groups.

---

Monitoring & Debugging

Use the Ironflow CLI to monitor events in real-time while developing your application.

# Watch all system and user events
ironflow subscribe "system.>" "events:>" --json

# Monitor a specific workflow run
ironflow subscribe "system.run.run_abc123.>" --replay 100

# Watch for failures only
ironflow subscribe "system.run.*.failed" --json | jq

Common Troubleshooting

Issue	Check
No events received	Verify the pattern matches (e.g., events: prefix) and the server is reachable.
Duplicate events	Expected in At-Least-Once delivery. Ensure your handlers are idempotent.
Connection drops	Check for proxy/load-balancer timeouts. Reconnect is handled automatically by SDKs.