Bus

Reference doc for the `sst.aws.Bus` component.

The Bus component lets you add an Amazon EventBridge Event Bus to your app.

Create a bus

const bus = new sst.aws.Bus("MyBus");

Add a subscriber

bus.subscribe("MySubscriber", "src/subscriber.handler");

Customize the subscriber

bus.subscribe("MySubscriber", {
  handler: "src/subscriber.handler",
  timeout: "60 seconds"
});

Link the bus to a resource

You can link the bus to other resources, like a function or your Next.js app.

new sst.aws.Nextjs("MyWeb", {
  link: [bus]
});

Once linked, you can publish messages to the bus from your app.

import { Resource } from "sst";
import { EventBridgeClient, PutEventsCommand } from "@aws-sdk/client-eventbridge";

const eb = new EventBridgeClient({});

await eb.send(new PutEventsCommand({
  Entries: [
    {
      EventBusName: Resource.MyBus.name,
      Source: "my.source",
      Detail: JSON.stringify({ foo: "bar" })
    }
  ]
}));

Constructor

new Bus(name, args?, opts?)

Parameters

name string
args? BusArgs
opts? ComponentResourceOptions

BusArgs

transform?

Type Object

bus?

Transform how this component creates its underlying resources.

transform.bus?

Type EventBusArgs | (args: EventBusArgs, opts: ComponentResourceOptions, name: string) => void

Transform the EventBus resource.

Properties

arn

Type Output<string>

The ARN of the EventBus.

name

Type Output<string>

The name of the EventBus.

nodes

Type Object

bus

The underlying resources this component creates.

nodes.bus

Type EventBus

The Amazon EventBus resource.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Methods

subscribe(name, subscriber, args?)

Parameters

name string
The name of the subscription.
subscriber Input<string | FunctionArgs | “arn:aws:lambda:${string}”>
The function that’ll be notified.
args? BusSubscriberArgs
Configure the subscription.

Returns Output<BusLambdaSubscriber>

Subscribe to this EventBus with a function.

bus.subscribe("MySubscription", "src/subscriber.handler");

You can add a pattern to the subscription.

bus.subscribe("MySubscription", "src/subscriber.handler", {
  pattern: {
    source: ["my.source", "my.source2"],
    price_usd: [{numeric: [">=", 100]}]
  }
});

To customize the subscriber function:

bus.subscribe("MySubscription", {
  handler: "src/subscriber.handler",
  timeout: "60 seconds"
});

Or pass in the ARN of an existing Lambda function.

bus.subscribe("MySubscription", "arn:aws:lambda:us-east-1:123456789012:function:my-function");

subscribeQueue

subscribeQueue(name, queue, args?)

Parameters

name string
The name of the subscription.
queue Input<string | Queue>
The queue that’ll be notified.
args? BusSubscriberArgs
Configure the subscription.

Returns Output<BusQueueSubscriber>

Subscribe to this EventBus with an SQS Queue.

For example, let’s say you have a queue.

const queue = new sst.aws.Queue("MyQueue");

You can subscribe to this bus with it.

bus.subscribeQueue("MySubscription", queue);

You can also add a filter to the subscription.

bus.subscribeQueue("MySubscription", queue, {
  filter: {
    price_usd: [{numeric: [">=", 100]}]
  }
});

Or pass in the ARN of an existing SQS queue.

bus.subscribeQueue("MySubscription", "arn:aws:sqs:us-east-1:123456789012:my-queue");

static get

Bus.get(name, busName, opts?)

Parameters

name string
The name of the component.
busName Input<string>
The name of the existing EventBus.
opts? ComponentResourceOptions

Returns Bus

Reference an existing EventBus with its ARN. This is useful when you create a bus in one stage and want to share it in another stage. It avoids having to create a new bus in the other stage.

Imagine you create a bus in the dev stage. And in your personal stage frank, instead of creating a new bus, you want to share the bus from dev.

const bus = $app.stage === "frank"
  ? sst.aws.Bus.get("MyBus", "app-dev-MyBus")
  : new sst.aws.Bus("MyBus");

Here app-dev-MyBus is the name of the bus created in the dev stage. You can find this by outputting the bus name in the dev stage.

return bus.name;

Bus.subscribe(name, busArn, subscriber, args?)

Parameters

name string
The name of the subscription.
busArn Input<string>
The ARN of the EventBus to subscribe to.
subscriber Input<string | FunctionArgs | “arn:aws:lambda:${string}”>
The function that’ll be notified.
args? BusSubscriberArgs
Configure the subscription.

Returns Output<BusLambdaSubscriber>

Subscribe to an EventBus that was not created in your app with a function.

For example, let’s say you have an existing EventBus with the following ARN.

const busArn = "arn:aws:events:us-east-1:123456789012:event-bus/my-bus";

You can subscribe to it by passing in the ARN.

sst.aws.Bus.subscribe("MySubscription", busArn, "src/subscriber.handler");

To add a pattern to the subscription.

sst.aws.Bus.subscribe("MySubscription", busArn, "src/subscriber.handler", {
  pattern: {
    price_usd: [{numeric: [">=", 100]}]
  }
});

Or customize the subscriber function.

sst.aws.Bus.subscribe("MySubscription", busArn, {
  handler: "src/subscriber.handler",
  timeout: "60 seconds"
});

static subscribeQueue

Bus.subscribeQueue(name, busArn, queue, args?)

Parameters

name string
The name of the subscription.
busArn Input<string>
The ARN of the EventBus to subscribe to.
queue Input<string | Queue>
The queue that’ll be notified.
args? BusSubscriberArgs
Configure the subscription.

Returns Output<BusQueueSubscriber>

Subscribe to an existing EventBus with an SQS Queue.

For example, let’s say you have an existing EventBus and an SQS Queue.

const busArn = "arn:aws:events:us-east-1:123456789012:event-bus/MyBus";
const queue = new sst.aws.Queue("MyQueue");

You can subscribe to the bus with the queue.

sst.aws.Bus.subscribeQueue("MySubscription", busArn, queue);

Add a filter to the subscription.

sst.aws.Bus.subscribeQueue(MySubscription, busArn, queue, {
  filter: {
    price_usd: [{numeric: [">=", 100]}]
  }
});

Or pass in the ARN of an existing SQS queue.

sst.aws.Bus.subscribeQueue("MySubscription", busArn, "arn:aws:sqs:us-east-1:123456789012:my-queue");

BusSubscriberArgs

pattern?

Type Input<Object>

detail?
detailType?
source?

Filter the messages that’ll be processed by the subscriber.

If any single property in the pattern doesn’t match an attribute assigned to the message, then the pattern rejects the message.

For example, if your EventBus message contains this in a JSON format.

{
  source: "my.source",
  detail: {
     price_usd: 210.75
  },
  "detail-type": "orderPlaced"
}

Then this pattern accepts the message.

{
  pattern: {
    source: ["my.source", "my.source2"]
  }
}

pattern.detail?

Type Record<string, any>

An object of detail values to match against, where the key is the name and the value is the pattern to match. The detail contains the actual data associated with the event.

{
  pattern: {
    detail: {
      price_usd: [{numeric: [">=", 100]}]
    }
  }
}

pattern.detailType?

Type any[]

A list of detail-type values to match against. The detail-type typically defines the kind of event that is emitted.

{
  pattern: {
    detailType: ["orderPlaced"]
  }
}

pattern.source?

Type any[]

A list of source values to match against. The source indicates where the event originated.

{
  pattern: {
    source: ["my.source", "my.source2"]
  }
}

transform?

Type Object

rule?
target?

Transform how this subscription creates its underlying resources.

transform.rule?

Type EventRuleArgs | (args: EventRuleArgs, opts: ComponentResourceOptions, name: string) => void

Transform the EventBus rule resource.

transform.target?

Type EventTargetArgs | (args: EventTargetArgs, opts: ComponentResourceOptions, name: string) => void

Transform the EventBus target resource.