Skip to main content

EventBus

The EventBus construct is a higher level CDK construct that makes it easy to create an EventBridge Event Bus. You can create a bus that has a list of rules and targets. And you can publish messages to it from any part of your serverless app.

You can have two types of targets; Function targets (with a Lambda function) or Queue targets (with an SQS queue). See the examples for more details.

Examples​

Using the minimal config​

import { EventBus } from "sst/constructs";

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/function1.handler",
        myTarget2: "src/function2.handler",
      },
    },
  },
});

Note that, myRule here is simply a key to identify the rule.

Configuring rules​

Lazily adding rules​

Add rules after the EventBus has been created.

const bus = new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

bus.addRules(stack, {
  myRule2: {
    pattern: { source: ["myevent"] },
    targets: {
      myTarget3: "src/target3.main",
      myTarget4: "src/target4.main",
    },
  },
});

Lazily adding targets​

const bus = new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
      },
    },
  },
});

bus.addTargets(stack, "myRule", {
  myTarget2: "src/target2.main",
});

Configuring the Rule​

Configure the internally created CDK Rule instance.

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      ruleName: "MyRule",
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

Configuring Function targets​

Adding targets​

You can directly pass in the path to the Function.

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
      },
    },
  },
});

Specifying function props for all targets​

You can extend the minimal config, to set some function props and have them apply to all the rules.

new EventBus(stack, "Bus", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    },
  },
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

Configuring an individual target​

Configure each Lambda function separately.

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: {
          function: {
            srcPath: "src/",
            handler: "target1.main",
            environment: { tableName: table.tableName },
            permissions: [table],
          },
        },
      },
    },
  },
});

Note that, you can set the defaultFunctionProps while using the function per target. The function will just override the defaultFunctionProps. Except for the environment, the layers, and the permissions properties, that will be merged.

new EventBus(stack, "Bus", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    },
  },
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: {
          function: {
            handler: "src/target1.main",
            timeout: 10,
            environment: { bucketName: bucket.bucketName },
            permissions: [bucket],
          },
        },
        myTarget2: "src/target2.main",
      },
    },
  },
});

So in the above example, the target1 function doesn't use the timeout that is set in the defaultFunctionProps. It'll instead use the one that is defined in the function definition (10 seconds). And the function will have both the tableName and the bucketName environment variables set; as well as permissions to both the table and the bucket.

Configuring the target​

Configure the internally created CDK Target.

import { RuleTargetInput } from "aws-cdk-lib/aws-events";

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: {
          function: "src/target1.main",
          cdk: {
            target: {
              retryAttempts: 20,
              message: RuleTargetInput.fromEventPath("$.detail"),
            },
          },
        },
      },
    },
  },
});

In the example above, the function is invoked with the contents of the detail property on the event, instead of the envelope - i.e. the original payload put onto the EventBus.

Attaching permissions for all targets​

Allow all the targets in the entire EventBus to access S3.

const bus = new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

bus.attachPermissions(["s3"]);

Attaching permissions for a specific target​

Allow one of the targets to access S3.

const bus = new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

bus.attachPermissionsToTarget("myRule", 0, ["s3"]);

Here we are referring to the rule using the rule key, myRule.

Configuring Queue targets​

Specifying the Queue directly​

You can directly pass in a Queue.

const myQueue = new Queue(stack, "MyQueue");

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: myQueue,
      },
    },
  },
});

Configuring the target​

Configure the internally created CDK Target.

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: {
          type: "queue",
          queue: myQueue,
          cdk: {
            target: {
              messageGroupId: "group1",
            },
          },
        },
      },
    },
  },
});

Configuring Log Group targets​

import { LogGroup } from "aws-cdk-lib/aws-logs";

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: {
          type: "log_group",
          cdk: {
            logGroup: LogGroup.fromLogGroupName(stack, "Logs", "/my/target/log"),
          }
        },
      },
    },
  },
});

Receiving AWS events​

When an AWS service in your account emits an event, it goes to your account’s default event bus.

import * as events from "aws-cdk-lib/aws-events";

new EventBus(stack, "Bus", {
  cdk: {
    eventBus: events.EventBus.fromEventBusName(stack, "ImportedBus", "default"),
  },
  rules: {
    myRule: {
      pattern: { source: ["aws.codebuild"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

Advanced examples​

Configuring the EventBus​

Configure the internally created CDK EventBus instance.

new EventBus(stack, "Bus", {
  cdk: {
    eventBus: {
      eventBusName: "MyEventBus",
    },
  },
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

Importing an existing EventBus​

Override the internally created CDK EventBus instance.

import * as events from "aws-cdk-lib/aws-events";

new EventBus(stack, "Bus", {
  cdk: {
    eventBus: events.EventBus.fromEventBusName(
      stack,
      "ImportedBus",
      eventBusArn
    ),
  },
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/target1.main",
        myTarget2: "src/target2.main",
      },
    },
  },
});

Using existing Lambda functions as targets​

import * as lambda from "aws-cdk-lib/aws-lambda";

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget: {
          cdk: {
            function: lambda.Function.fromFunctionName(
              stack,
              "ITarget",
              "my-function"
            ),
          },
        },
      },
    },
  },
});

Sharing an EventBus across stacks​

You can create the EventBus construct in one stack, and add rules in other stacks. To do this, return the EventBus from the stack function

stacks/MainStack.ts
import { EventBus, App, StackContext } from "sst/constructs";

export function MainStack({ stack }: StackContext) {
  const bus = new EventBus(stack, "Bus", {
    rules: {
      myRule: {
        pattern: { source: ["myevent"] },
        targets: {
          myTarget1: "src/target1.main",
          myTarget2: "src/target2.main",
        },
      },
    },
  });

  return {
    bus,
  };
}

Then import the auth construct into another stack with use and call addRules. Note that the AWS resources for the added routes will be created in AnotherStack.

stacks/AnotherStack.ts
import { EventBus, StackContext } from "sst/constructs";
import { MainStack } from "./MainStack";

export function AnotherStack({ stack }: StackContext) {
  const { bus } = use(MainStack);
  bus.addRules(stack, {
    myRule2: {
      targets: {
        myTarget3: "src/target3.main",
        myTarget4: "src/target4.main",
      },
    },
  });
}

Constructor​

new EventBus(scope, id, props)

Parameters

EventBusProps​

defaults?​

Type :

defaults.function?​

Type : FunctionProps

The default function props to be applied to all the Lambda functions in the EventBus. The environment , permissions and layers properties will be merged with per route definitions if they are defined.

new EventBus(stack, "Bus", {
  defaults: {
    function: {
      timeout: 20,
    }
  },
});

defaults.retries?​

Type : number

Enable retries with exponential backoff for all lambda function targets in this eventbus

new EventBus(stack, "Bus", {
  retries: 20
});

rules?​

Type : Record<string, EventBusRuleProps>

The rules for the eventbus

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget: "src/function.handler"
      },
    },
  },
});

cdk?​

Type :

cdk.eventBus?​

Type : IEventBus | EventBusProps

Override the internally created EventBus

new EventBus(stack, "Bus", {
  cdk: {
    eventBus: {
      eventBusName: "MyEventBus",
    },
  }
});

cdk.id?​

Type : string

Allows you to override default id for this construct.

Properties​

An instance of EventBus has the following properties.

eventBusArn​

Type : string

The ARN of the internally created EventBus instance.

eventBusName​

Type : string

The name of the internally created EventBus instance.

id​

Type : string

cdk​

Type :

cdk.eventBus​

Type : IEventBus

The internally created CDK EventBus instance.

Methods​

An instance of EventBus has the following methods.

addRules​

addRules(scope, rules)

Parameters

Add rules after the EventBus has been created.

bus.addRules(stack, {
  myRule2: {
    pattern: { source: ["myevent"] },
      targets: {
        myTarget3: "src/function3.handler"
        myTarget4: "src/function4.handler"
      },
  },
});

addTargets​

addTargets(scope, ruleKey, targets)

Parameters

Add targets to existing rules.

bus.addRules(stack, "myRule", {
  myTarget1: "src/function1.handler"
  myTarget2: "src/function2.handler"
});

attachPermissions​

attachPermissions(permissions)

Parameters

Add permissions to all event targets in this EventBus.

bus.attachPermissions(["s3"]);

attachPermissionsToTarget​

attachPermissionsToTarget(ruleKey, targetName, permissions)

Parameters

Add permissions to a specific event bus rule target

const bus = new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/function1.handler"
        myTarget2: "src/function2.handler"
      },
    },
  },
});

bus.attachPermissionsToTarget("myRule", 0, ["s3"]);

bind​

bind(constructs)

Parameters

  • constructs Array<BindingResource>

Binds the given list of resources to all event targets in this EventBus.

bus.bind([STRIPE_KEY, bucket]);

bindToTarget​

bindToTarget(ruleKey, targetName, constructs)

Parameters

  • ruleKey string
  • targetName string
  • constructs Array<BindingResource>

Binds the given list of resources to a specific event bus rule target

const bus = new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
      targets: {
        myTarget1: "src/function1.handler"
        myTarget2: "src/function2.handler"
      },
    },
  },
});

bus.bindToTarget("myRule", 0, [STRIPE_KEY, bucket]);

getRule​

getRule(key)

Parameters

  • key string

Get a rule

bus.getRule("myRule");

subscribe​

subscribe(type, target, props)

Parameters

props.retries?​

Type : number

subscribe(scope, type, target, props)

Parameters

props.retries?​

Type : number

EventBusRuleProps​

Used to configure an EventBus rule

pattern?​

Type :

pattern.detail?​

Type :

Fields to match on the detail field

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { detail: { FOO: 1 }  },
    },
  },
});

pattern.detailType?​

Type : Array<string>

A list of detailTypes to filter on

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { detailType: ["foo"]  },
    },
  },
});

pattern.source?​

Type : Array<string>

A list of sources to filter on

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      pattern: { source: ["myevent"] },
    },
  },
});

targets?​

Type : Record<string, Queue | string | Function | EventBusFunctionTargetProps | EventBusQueueTargetProps | EventBusLogGroupTargetProps>

Configure targets for this rule.

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      targets: {
        myTarget1: "src/function.handler",
        myTarget2: new Queue(stack, "MyQueue"),
      }
    },
  },
});

cdk?​

Type :

cdk.rule?​

Type : Omit<RuleProps, "eventBus" | "targets">

Configure the internally created CDK Rule instance.

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      cdk: {
        rule: {
          ruleName: "my-rule",
          enabled: false,
        },
      },
      targets: {
        myTarget1: "src/lambda.handler",
      },
    },
  },
});

EventBusQueueTargetProps​

Used to configure an EventBus queue target

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      targets: {
        myTarget: {
          type: "queue",
          queue: new Queue(stack, "Queue")
        }
      }
    },
  },
});

queue​

Type : Queue

The queue to trigger

type​

Type : "queue"

String literal to signify that the target is a queue

cdk?​

Type :

cdk.target?​

Type : SqsQueueProps

EventBusFunctionTargetProps​

Used to configure an EventBus function target

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      targets: {
        myTarget: { function: "src/function.handler" },
      }
    },
  },
});

function?​

Type : string | Function | FunctionProps

The function to trigger

retries?​

Type : number

Number of retries

type?​

Type : "function"

String literal to signify that the target is a function

cdk?​

Type :

cdk.function?​

Type : IFunction

cdk.target?​

Type : LambdaFunctionProps

EventBusLogGroupTargetProps​

Used to configure an EventBus log group target

new EventBus(stack, "Bus", {
  rules: {
    myRule: {
      targets: {
        myTarget: {
          type: "log_group",
          cdk: {
           logGroup: LogGroup.fromLogGroupName(stack, "Logs", "/my/target/log"),
          }
        }
      }
    },
  },
});

type​

Type : "log_group"

String literal to signify that the target is a log group

cdk​

Type :

cdk.logGroup​

Type : ILogGroup

cdk.target?​

Type : LogGroupProps