@crvouga/mockingbird-service-eventbridge

Local emulators. Real API contracts. Part of Mockingbird.

WIP AWS EventBridge control-plane discovery. Seeded rule and target reads use AWS JSON 1.1; no containers or infrastructure are executed. Follows the official ListRules, ListTargetsByRule and common errors.

Install

bun add @crvouga/mockingbird-service-eventbridge

Usage

import { EventBridgeClient, ListRulesCommand } from "@aws-sdk/client-eventbridge"
import { createServer } from "@crvouga/mockingbird-service-eventbridge/server"

// Test setup: seed a rule, then point the EventBridge client your application already uses
// at the emulator.
const server = await createServer({
  rules: [{ rule: { Name: "nightly", Arn: "arn:aws:events:us-east-1:000000000000:rule/nightly" }, targets: [] }],
})
const eventBridge = new EventBridgeClient({
  endpoint: server.url,
  region: "us-east-1",
  credentials: { accessKeyId: "fixture", secretAccessKey: "fixture" },
})

// Application code, unchanged.
const { Rules } = await eventBridge.send(new ListRulesCommand({ NamePrefix: "night" }))
// Rules[0].Name === "nightly"

await server.close()

CLI: mockingbird-eventbridge serve --port 12128. Set your client factory's endpoint_url or AWS_ENDPOINT_URL_EVENTBRIDGE to that URL. The default instance has no rules. POST / dispatches X-Amz-Target AWSEvents.ListRules and AWSEvents.ListTargetsByRule. NamePrefix filters names; Limit (1–100) and NextToken paginate rules and targets. The terminal page omits NextToken. Missing buses/rules return ResourceNotFoundException (400).

Controls and state

Seed through options.rules ({rule, targets}) or POST /__admin/state/rules with {id: "default:nightly", value: {rule: {Name, Arn}, targets: [{Id, Arn, EcsParameters}]}}. Custom buses must also be seeded in options.buses or /__admin/state/buses ({name}). The default bus always exists. Rule.EventBusName defaults to default. Target objects, including TaskDefinitionArn and awsvpcConfiguration, round-trip without execution. State collections: rules, buses, cursors and initialization marker. Shared /__admin provides health, state, reset, Timeline checkpoints, clock, journal, metrics and UI. Namespaces work via x-mockingbird-namespace, /__admin/ns/name and SigV4 access-key mappings set with PUT /__admin/credentials. No cryptographic signature or IAM evaluation is performed. The journal records metadata, not request bodies or credentials.

Presets: access_denied (403), throttled (AWS 400), rate_limited (explicit HTTP 429 fault), internal_error (500), connection_drop. Standard faults support deterministic latency. No outbound webhooks are emitted.

Verification

Run bun test here for acceptance, JS SDK, self-parity and deliberate divergence tests. Run bun scripts/sdk.ts with uv installed for the separate pinned boto3 1.43.56 drop-in/paginator/error proof (uv obtains that exact package; no AWS credentials are needed). Live safe empty-prefix discovery: bun run parity with EVENTBRIDGE_ACCESS_KEY_ID, EVENTBRIDGE_SECRET_ACCESS_KEY, optional EVENTBRIDGE_REGION. Missing credentials exit 2. The SDK tests prove client compatibility, not live AWS equivalence.

Deliberately not modelled

Rule/target mutation, event delivery, schedules, IAM policy evaluation, cryptographic SigV4 validation, real execution, provisioning and deployment. Seeded resources are fixtures, not AWS accounts. Cursor strings and their one-hour emulator-clock lifetime are deterministic local stand-ins; AWS does not document a fixed lifetime or wire token format. Pagination binds arguments but does not freeze a snapshot of concurrent fixture edits. Result order is fixture insertion order, not a guarantee about AWS ordering. HTTP 429 is a test fault, not the normal EventBridge throttling status.

API

• EventbridgeAPI, createAwsRuntime, and createAwsServer (server entry): separate extended AWS operations runtime.

Main exports: EventBridgeAPI, EVENTBRIDGE_NAMESPACE, createRuntime, EVENTBRIDGE_PRESETS, document, operationIds, supportedOperationIds. Types: Rule, Target, SeedRule, EventBridgeAPIOptions, EventBridgeRuntimeOptions, EventBridgeRuntime. Server entry: createServer, DEFAULT_PORT, serveTarget; type EventBridgeServerOptions. CLI entry runs the serve command and exports no runtime values.

Extended AWS operations runtime

createAwsRuntime (and createAwsServer from the server entry) exposes the additional LocalStack-oriented event bus, rule, target, event ingestion and tagging operations. It has separate state and does not claim the seeded discovery runtime's pagination behavior. The default createRuntime retains the documented discovery contract and fixtures. Both modes remain WIP. Run bun run parity:localstack for the extended runtime.