Error Boundary

🛟 Error Boundary

📜 Every publishing spell - Strand, Pluck, Loom, Shuttle - registers your observable behind a per-spell error boundary. OnError that reaches rzeka without being handled by you is caught and whispered to Eris as a Horror message with the spell's title and owner. The river survives, all other spells keep channeling.

User-side error handling runs first - .Catch, .Retry, .OnErrorResumeNext work as usual. The boundary only sees errors that fall through them:

// User handles upstream - boundary never sees the error
Q += rzeka.Strand(
    this,
    flakySource
        .Retry(3)
        .Catch<Reading, TimeoutException>(_ => Observable.Empty<Reading>())
);

// User doesn't handle - boundary catches, whispers to Eris with attribution,
// the river keeps running
Q += rzeka.Strand(this, flakySource);

Crash-on-error (opt-in)

The boundary makes errors visible in Eris, not fatal. If you want unhandled source errors to purposefully crash the process - common in dev builds - add following a callback when you create the river:

IRzeka rzeka = new Spring().Create(
    "Nile",
    onUnhandledSourceError: (spell, ex) => throw ex
);

The callback runs for Weave failures too (see below), so one callback covers the whole river.

What the Horror knows

The Horror's circumstances point at the matter the spell was handling when it failed, so in Eris you can follow the failure back through its causal chain:

• Loom - its latest inputs. Shuttle - its latest request.
• Weave - the exact matter being delivered.
• Strand - nothing; the source itself failed.

For Looms and Shuttles this is exact when your lambda is synchronous. After an await it is only the latest input, not necessarily the one that failed.

Weave errors

Weave has its own boundary: if your subscribe function (or an operator inside it) throws, rzeka whispers a Horror with the matter being delivered and contains the exception. Your failing Weave's subscription ends - Rx unsubscribes an observer that throws, just like a failing source completes - but every other subscriber of that matter keeps receiving.

📜 Before this boundary existed, a throwing Weave didn't just fail on its own: the exception escaped to whoever pushed the matter and silently stopped that matter type from reaching any subscriber for the rest of the session.