sql-switch - v1.0.1
    Preparing search index...

    Interface CollectorHooks

    Optional callbacks the collector fires so an app can observe what the buffer is doing.

    Hooks are for observability => they're called from the flush path, so keep them cheap & don't throw from them (a throwing hook is caught & logged, it can't take the flush down with it).

    interface CollectorHooks {
        onStateChange?: (state: BreakerState, reason?: string) => void;
        onFlushError?: (
            error: unknown,
            context: { schema: string; table: string; writes: number },
        ) => void;
        onDrop?: (writes: number, reason: string) => void;
        onBackpressure?: (pending: number, max: number) => void;
    }
    Index
    onStateChange? onFlushError? onDrop? onBackpressure?
    onStateChange?: (state: BreakerState, reason?: string) => void

    Fired on every circuit breaker transition, with a short reason on the way to open.

    A trip to read-only mode is observed here (state === 'open') => there's no separate "onTrip", it'd fire for the same event.

    collector: {
      hooks: {
        onStateChange: (state) => metrics.gauge('db.breaker', state === 'closed' ? 0 : 1),
      },
    }
    onFlushError?: (
        error: unknown,
        context: { schema: string; table: string; writes: number },
    ) => void

    Fired when a flush group fails => the writes go back in the buffer & are retried, this is your hook to log/count the transient failure.

    Type Declaration

      • (
            error: unknown,
            context: { schema: string; table: string; writes: number },
        ): void

      • Parameters

        • error: unknown

          Whatever the driver threw.

        • context: { schema: string; table: string; writes: number }

          Which group failed & how many keys were in it.

        Returns void

    Registering this replaces the default console.error for a failed flush => wire it to your logger. It fires per failed group, per flush, so a sustained outage fires it every interval.

    onDrop?: (writes: number, reason: string) => void

    Fired when buffered writes are lost for good => the buffer overflowed while retrying a failed group, or close()/shutdown couldn't drain what was left.

    Type Declaration

      • (writes: number, reason: string): void

      • Parameters

        • writes: number

          How many writes were dropped.

        • reason: string

          Short description of which of the two happened.

        Returns void

    This is real data loss, not a retry => the one hook worth paging on. Replaces the default console.error for the same events.

    onBackpressure?: (pending: number, max: number) => void

    Fired once each time the buffer crosses its high-water mark (80% of the cap) on the way up => the flush isn't keeping up with incoming writes and the breaker is getting closer to tripping.

    Type Declaration

      • (pending: number, max: number): void

      • Parameters

        • pending: number

          Buffered writes at the crossing.

        • max: number

          The cap the breaker trips at (BreakerState open).

        Returns void

    Edge triggered per flush cycle, not per write => it won't spam. An early warning to shed load or widen the flush before writes start getting rejected.

    Settings
    Member Visibility

    On This Page
    Properties