Fjall Docs — deploy AWS infrastructure into your own account

Overview

The EventBridgeBus construct creates an Amazon EventBridge custom event bus. Publishers put events on the bus, subscriptions filter them by content, and matching events fan out to Lambda, SQS, ECS, CodeBuild, or a log group. Every Fjall application has a default bus. Call app.getEventBus() to get it. Add extra buses with the MessagingFactory when you want separate domains on separate buses.

Import

import {
  EventBridgeBus,
  MessagingFactory,
} from "@fjall/components-infrastructure";

Messaging, networking, storage, CDN and EC2 constructs are exported from the package root. Database constructs and the Lambda and ECS constructs are not, so those need the deep @fjall/components-infrastructure/lib/... path.

Direct construction

const bus = new EventBridgeBus(scope, "AppEvents", {});

The bare EventBridgeBus construct carries the grant and accessor methods but not subscribe(). Reach for app.getEventBus() or the MessagingFactory instead, both of which return the EventBusMessaging wrapper.

The default application bus

app.getEventBus() is lazy and idempotent. The first call creates the bus in the application’s messaging stack, every later call returns the same instance.

const bus = app.getEventBus();

bus.grantPutEventsTo(apiService);

Override the bus name or removal policy at application construction:

const app = App.getApp("api", {
  eventBus: { name: "api-domain-events", removalPolicy: "RETAIN" },
});

The bus name defaults to the application name.

Using the messaging factory

Add a second bus through the MessagingFactory:

const domainEvents = app.addMessaging(
  MessagingFactory.build("DomainEvents", {
    type: "eventBus",
  }),
);

domainEvents.grantPutEventsTo(apiService);

addMessaging places the bus in the messaging stack. Pass { stackPlacement: "compute" } as the second argument to put it in the compute stack instead.

Properties

Property	Type	Default	Description
`eventBusName`	`string`	Auto-generated	Physical AWS event bus name
`appName`	`string`	None	Application name used to build the default bus description
`description`	`string`	`EventBus <appName> — Fjall app event bus`	Event bus description
`removalPolicy`	`"DESTROY" \| "RETAIN"`	`"RETAIN"` in production, else `"DESTROY"`	What happens on stack deletion

Removal policy resolution

The default comes from the deploy’s resolved environment, not from NODE_ENV. Production resolves to RETAIN, every other recognised stage resolves to DESTROY. Two cases fail synth rather than guessing:

An unrecognised environment value (a typo such as ENVIRONMENT=prod).
A Fjall-driven deploy whose target account resolves to no environment at all.

Both throw because silently choosing DESTROY deletes data when the stack is deleted. Outside a Fjall deploy (a bare cdk synth with no environment signal) the default is DESTROY with a warning. Set removalPolicy explicitly when you synthesise outside a Fjall application context.

Methods

Method	Returns	Description
`getEventBusArn()`	`string`	Event bus ARN
`getEventBusName()`	`string`	Event bus name
`getEventBus()`	`IEventBus`	Underlying CDK event bus (not `app.getEventBus()`, which returns the Fjall wrapper)
`grantPutEventsTo(grantee)`	`Grant`	Grant permission to publish events
`subscribe(id, props)`	`Subscription`	Route matching events to a target on this bus

subscribe() is available on the wrapper returned by app.getEventBus() and MessagingFactory.build(..., { type: "eventBus" }).

Routing events with subscriptions

A subscription is an event pattern plus one target. Pass Fjall construct instances directly as the target, not CDK target adapters.

const bus = app.getEventBus();

bus.subscribe("OrderCreated", {
  pattern: {
    source: ["orders"],
    detailType: ["OrderCreated"],
  },
  target: orderProcessor,
});

Supported targets

Target	Pass
Lambda	The `LambdaCompute` instance
SQS queue	The `SQSQueue` or `QueueMessaging` instance
ECS task	`{ ecs: ecsCompute, serviceName, taskCount? }`
CodeBuild project	The `CodeBuildProject` instance
CloudWatch log group	The `LogGroup` instance

Another event bus is not a valid subscription target. Bus-to-bus replication is a different shape.

How a rule is granted an SQS queue

A rule cannot reach SQS through an IAM role. The queue’s resource policy is the only grant. From fjall 38 every rule delivering to the same queue shares one statement on that queue’s policy, under the Sid EventBridgeRuleTargetGrant. The statement grants events.amazonaws.com the actions sqs:SendMessage, sqs:GetQueueAttributes and sqs:GetQueueUrl, and names each rule in an ArnEquals condition on aws:SourceArn. A rule costs one ARN rather than a whole statement, so a queue takes many more rules before it reaches the 8,192-byte queue-policy limit. Fjall 38 checks that policy at synthesis and refuses an over-budget queue, at 61 rules on the default bus and sooner on an application’s own bus, whose name rides in every rule ARN. See Queue-policy limits. Through 37.x each rule added its own statement of about 430 bytes, so a queue shared by about eighteen rules stopped deploying with “Submitted policy is over max allowed size”. The Sid is load-bearing. @aws-cdk/aws-iam:minimizePolicies merges statements that carry no Sid whose conditions serialise alike, and every lazy condition serialises alike, so a queue that is one rule’s target and another rule’s dead-letter queue would have its two grants merged into one that kept only the first aws:SourceArn list. The other rule would lose access. A queue encrypted with a customer-managed KMS key keeps CDK’s target adapter, which grants the account rather than each rule. Naming each rule there would create a dependency cycle through the key policy.

Subscription options

Option	Type	Default	Description
`pattern`	`EventPattern`	Required	EventBridge content filter
`target`	`SubscriptionTarget`	Required	What receives matching events
`payload`	`Record<string, unknown>`	Full event forwarded	Override the delivered detail. Throws on ECS and log-group targets
`messageGroupId`	`string`	None	Required for FIFO queue targets, rejected for every other target
`deadLetterQueue`	`{ enabled: true, queue? }` \| `{ enabled: false }` \| `SQSQueue`	Disabled	Capture undeliverable events
`retryPolicy`	`EventBridgeRetryPolicy`	AWS defaults (24 hours, 185 tries)	Tighten the retry window for time-sensitive routes
`description`	`string`	`Subscription <id> for <appName>`	Rule description
`enabled`	`boolean`	`true`	Disable the rule without deleting it
`alertsTopic`	`ITopic`	None	SNS topic for failed-invocation and throttled-rule alarms
`alarms`	`boolean`	`true` when `alertsTopic` is set	Set `false` to suppress alarms while keeping the topic

The subscription returns a Subscription with getRule() and getRuleArn(). From fjall 38 every subscription dead-lettering into the same queue shares one statement on that queue’s policy, under the Sid EventBridgeRuleDeadLetterGrant. It grants events.amazonaws.com the action sqs:SendMessage and names each rule in an ArnEquals condition on aws:SourceArn. Through 37.x each rule added its own AllowEventRule<id> statement, so a shared dead-letter queue grew one statement per subscriber. A queue that is both a rule target and a dead-letter queue carries both statements, EventBridgeRuleTargetGrant and EventBridgeRuleDeadLetterGrant. A dead-letter queue in another region is refused at synth. One in another account is left to its owner with a warning, so add that grant by hand in the owning account.

Substituting event fields into the payload

Use EventField to pull values out of the matched event:

import { EventField } from "@fjall/components-infrastructure";

bus.subscribe("BuildOnUpload", {
  pattern: {
    source: ["uploads"],
    detailType: ["ObjectUploaded"],
  },
  target: buildProject,
  payload: {
    environmentVariablesOverride: [
      {
        name: "OBJECT_KEY",
        value: EventField.fromPath("$.detail.object.key"),
      },
    ],
  },
});

EventBridge can deliver the same event up to retryAttempts + 1 times. Lambda handlers must be idempotent. FIFO queues with content-based deduplication absorb same-content retries.

Scheduling events onto a bus

A schedule may target a bus, even though a subscription may not:

app.addSchedule("MetricsTick", {
  schedule: "rate(5 minutes)",
  target: app.getEventBus(),
});

Every tick puts the scheduled event on the bus, where subscriptions pick it up like any other event. The forwarded event keeps EventBridge’s own source, aws.events, and the detail type Scheduled Event. An application bus refuses an aws.* source pattern, so match the tick on its detail type rather than its source:

bus.subscribe("CollectMetrics", {
  pattern: { detailType: ["Scheduled Event"] },
  target: metricsCollector,
});

From fjall 38 a payload on that schedule is refused at synthesis:

payload is not supported on event-bus targets — the rule forwards the matched event to the bus unchanged, so a payload would be dropped. Target the consumer directly to send it a payload.

Through 37.x the payload was accepted and dropped without a word. CDK’s EventBus target carries no input, so the rule always forwarded the scheduled event unchanged. Remove the payload to keep exactly what deployed before, or target the consumer directly so it receives one.

Importing an existing bus

From an ARN

Wrap a bus that lives in another stack, account, or region. No AWS::Events::EventBus is synthesised, and bus-level settings (description, removal policy, outputs) are skipped. Rules created by subscribe() are owned by the importing stack.

import { EventBusMessaging } from "@fjall/components-infrastructure";

const sharedBus = EventBusMessaging.fromEventBusArn(
  this,
  "SharedEvents",
  "arn:aws:events:eu-west-1:123456789012:event-bus/platform-events",
);

sharedBus.subscribe("PlatformAudit", {
  pattern: { source: ["platform"] },
  target: auditQueue,
});

From the AWS default bus

AWS service events (aws.ecr, aws.ec2, aws.ecs) fire only on the account and region default bus. Custom application buses never receive them. Import the default bus to subscribe to service events:

import { Stack } from "aws-cdk-lib";

const serviceBus = EventBusMessaging.fromAwsServiceBus(
  this,
  "AwsEvents",
  Stack.of(this).region,
  Stack.of(this).account,
);

serviceBus.subscribe("RepositoryCreated", {
  pattern: {
    source: ["aws.ecr"],
    detailType: ["AWS API Call via CloudTrail"],
    detail: {
      eventSource: ["ecr.amazonaws.com"],
      eventName: ["CreateRepository"],
    },
  },
  target: imageBuildProject,
});

Subscribing an aws.* source pattern on a custom application bus throws at synth. The rule would deploy cleanly and never fire, so Fjall refuses it and points you at fromAwsServiceBus().

CloudFormation outputs

Output	Description
`{id}EventBusArn`	Event bus ARN
`{id}EventBusName`	Event bus name

Imported buses emit no outputs.

Next Steps

Messaging Factory

Create messaging resources via the factory pattern

Lambda Function

Process events with Lambda

SQS Queue

Buffer and decouple work with a managed queue

SNS Topic

Fan out notifications to multiple subscribers

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

EventBridge Bus

Overview

Import

Direct construction

The default application bus

Using the messaging factory

Properties

Removal policy resolution

Methods

Routing events with subscriptions

Supported targets

How a rule is granted an SQS queue

Subscription options

Substituting event fields into the payload

Scheduling events onto a bus

Importing an existing bus

From an ARN

From the AWS default bus

CloudFormation outputs

Next Steps

Messaging Factory

Lambda Function

SQS Queue

SNS Topic

​Overview

​Import

​Direct construction

​The default application bus

​Using the messaging factory

​Properties

​Removal policy resolution

​Methods

​Routing events with subscriptions

​Supported targets

​How a rule is granted an SQS queue

​Subscription options

​Substituting event fields into the payload

​Scheduling events onto a bus

​Importing an existing bus

​From an ARN

​From the AWS default bus

​CloudFormation outputs

​Next Steps

Messaging Factory

Lambda Function

SQS Queue

SNS Topic

Overview

Import

Direct construction

The default application bus

Using the messaging factory

Properties

Removal policy resolution

Methods

Routing events with subscriptions

Supported targets

How a rule is granted an SQS queue

Subscription options

Substituting event fields into the payload

Scheduling events onto a bus

Importing an existing bus

From an ARN

From the AWS default bus

CloudFormation outputs

Next Steps