@rpc-bastion/core

The resilience layer as a stack of composable web3.js v2.0 (@solana/kit) RPC transports. An endpoint pool with a health + circuit-breaker model, plus higher-order transports you compose to taste — and one-call presets when you don't want to.

Composition

import { createSolanaRpcFromTransport } from '@solana/kit';
import {
  createEndpointPool, withLoadBalancer, withCircuitBreaker,
  withFailover, withRetry, withMetrics, createEventBus,
} from '@rpc-bastion/core';

const pool = createEndpointPool([
  { url: 'https://rpc-1.example.com' },
  { url: 'https://rpc-2.example.com', weight: 2 },
]);
const bus = createEventBus();

const transport = withMetrics(
  withRetry(
    withFailover(
      withCircuitBreaker(withLoadBalancer(pool, { strategy: 'health-weighted' })),
      { maxFailovers: 2 },
    ),
    { maxAttempts: 3, backoff: 'exponential-jitter' },
  ),
  bus,
);

const rpc = createSolanaRpcFromTransport(transport); // a standard Kit RPC

Or the preset: createResilientRpc(endpoints, { bus, strategy, breaker, retry }).

Layers

| Export | What it does | |---|---| | createEndpointPool | Health model (latency EWMA, sliding error rate, slot lag) + per-endpoint circuit breaker + probes | | createHttpTransport | Per-endpoint Kit transport with timing, error tagging & classification | | withLoadBalancer | health-weighted / round-robin / lowest-latency / sticky selection | | withFailover | Re-issue to the next-best endpoint on transport failures (never on app errors) | | withCircuitBreaker | Per-endpoint breaker (pool-backed) or a standalone single circuit | | withRetry | Exponential full-jitter backoff, Retry-After, retry budget | | withTimeout | Per-request deadline with abort propagation | | withHedging | Fire a backup to another endpoint after delayMs; first response wins | | withRateLimitGuard | Client-side token bucket + concurrency cap, per endpoint | | withMetrics | Installs the event bus so the whole stack emits telemetry | | createResilientTransport / createResilientRpc | The recommended stack in one call |

Design

• No classes — factory functions, plain objects, closures.
• Every layer is a Kit RpcTransport (a function), so it composes with your own.
• Injectable clock/rng make timing and selection deterministic in tests.
• Typed errors with a discriminant code; transport failures classified into network / timeout / rate-limit / server / parse (classifyError).
• Structured events instead of logging (createEventBus); see @rpc-bastion/observability.

Application (JSON-RPC) errors are never retried or failed over — they arrive as resolved { error } responses and reach your caller untouched.