import * as eventbridge from "@distilled.cloud/aws/eventbridge";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import {
createInternalTags,
createTagsList,
diffTags,
hasAlchemyTags,
tagRecord,
} from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import { canonicalJson } from "../internal/Observe.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
export class RuleInvalidProps extends Data.TaggedError("RuleInvalidProps")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class RuleOperationFailed extends Data.TaggedError("RuleOperationFailed")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export type {
AppSyncParameters,
AssignPublicIp,
AwsVpcConfiguration,
CapacityProviderStrategyItem,
HttpParameters,
InputTransformer,
KinesisParameters,
LaunchType,
NetworkConfiguration,
PlacementConstraint,
PlacementConstraintType,
PlacementStrategy,
PlacementStrategyType,
PropagateTags,
RedshiftDataParameters,
RetryPolicy,
RuleState,
RunCommandParameters,
RunCommandTarget,
SageMakerPipelineParameter,
SageMakerPipelineParameters,
SqsParameters,
} from "@distilled.cloud/aws/eventbridge";
export type RuleName = string;
export type RuleArn = `arn:aws:events:${RegionID}:${AccountID}:rule/${string}`;
export interface RuleTarget {
/** Unique identifier for this target within the rule. */
Id: string;
/** ARN of the target resource. */
Arn: string;
/** ARN of the IAM role to use for this target when the rule is triggered. */
RoleArn?: string;
/** Valid JSON text passed to the target. Mutually exclusive with InputPath and InputTransformer. */
Input?: string;
/** JSONPath expression to extract from the event and send to the target. Mutually exclusive with Input and InputTransformer. */
InputPath?: string;
/** Settings to transform input before sending to the target. Mutually exclusive with Input and InputPath. */
InputTransformer?: eventbridge.InputTransformer;
/** Settings for a Kinesis Data Stream target. */
KinesisParameters?: eventbridge.KinesisParameters;
/** Parameters for Systems Manager Run Command targets. */
RunCommandParameters?: eventbridge.RunCommandParameters;
/** Parameters for ECS task targets. */
EcsParameters?: RuleTargetEcsParameters;
/** Parameters for AWS Batch job targets. */
BatchParameters?: RuleTargetBatchParameters;
/** Parameters for SQS queue targets (e.g., FIFO message group ID). */
SqsParameters?: eventbridge.SqsParameters;
/** Parameters for HTTP endpoint targets (API Gateway, API Destinations). */
HttpParameters?: eventbridge.HttpParameters;
/** Parameters for Amazon Redshift Data API targets. */
RedshiftDataParameters?: eventbridge.RedshiftDataParameters;
/** Parameters for SageMaker Pipeline targets. */
SageMakerPipelineParameters?: eventbridge.SageMakerPipelineParameters;
/** Dead-letter queue configuration for failed event delivery. */
DeadLetterConfig?: RuleTargetDeadLetterConfig;
/** Retry policy settings for the target. */
RetryPolicy?: eventbridge.RetryPolicy;
/** Parameters for AWS AppSync GraphQL API targets. */
AppSyncParameters?: eventbridge.AppSyncParameters;
}
/** ECS parameters for a rule target with Input-wrapped ARN fields. */
export interface RuleTargetEcsParameters extends Omit<
eventbridge.EcsParameters,
"TaskDefinitionArn"
> {
/** ARN of the ECS task definition to run. */
TaskDefinitionArn: string;
}
/** Batch parameters for a rule target with Input-wrapped ARN fields. */
export interface RuleTargetBatchParameters extends Omit<
eventbridge.BatchParameters,
"JobDefinition"
> {
/** ARN or name of the Batch job definition. */
JobDefinition: string;
}
/** Dead-letter config for a rule target with Input-wrapped ARN. */
export interface RuleTargetDeadLetterConfig {
/** ARN of the SQS queue used as the dead-letter queue. */
Arn?: string;
}
export interface RuleProps {
/**
* Name of the rule. Must match [\.\-_A-Za-z0-9]+, 1-64 characters.
* If omitted, a unique name will be generated.
*/
name?: string;
/**
* Description of the rule. Max 512 characters.
*/
description?: string;
/**
* The name or ARN of the event bus to associate with this rule.
* If omitted, the default event bus is used.
*/
eventBusName?: string;
/**
* The event pattern that triggers this rule. Specified as a JSON-compatible object.
* A rule must contain at least an eventPattern or scheduleExpression.
*/
eventPattern?: Record<string, any>;
/**
* The scheduling expression (e.g. "rate(5 minutes)", "cron(0 20 * * ? *)").
* A rule must contain at least an eventPattern or scheduleExpression.
*/
scheduleExpression?: string;
/**
* Whether the rule is enabled or disabled.
* @default "ENABLED"
*/
state?: eventbridge.RuleState;
/**
* ARN of the IAM role associated with the rule. Required for targets that need
* IAM roles (e.g. Kinesis, Step Functions, ECS, API Gateway).
*/
roleArn?: string;
/**
* The targets to invoke when this rule is triggered. Maximum 5 targets per rule.
*/
targets?: RuleTarget[];
/**
* Tags to assign to the rule.
*/
tags?: Record<string, string>;
}
/**
* An Amazon EventBridge rule that matches events and routes them to targets.
* ### Creating Rules
* **Example:** Event Pattern Rule
* ```typescript
* const rule = yield* Rule("S3Events", {
* eventPattern: {
* source: ["aws.s3"],
* "detail-type": ["Object Created"],
* },
* targets: [{
* Id: "MyTarget",
* Arn: yield* queue.queueArn,
* }],
* });
* ```
*
* **Example:** Scheduled Rule
* ```typescript
* const rule = yield* Rule("EveryFiveMinutes", {
* scheduleExpression: "rate(5 minutes)",
* targets: [{
* Id: "LambdaTarget",
* Arn: yield* fn.functionArn(),
* }],
* });
* ```
*
* ### Targeting
* **Example:** Rule with Input Transformer
* ```typescript
* const rule = yield* Rule("TransformedEvents", {
* eventPattern: {
* source: ["aws.ec2"],
* "detail-type": ["EC2 Instance State-change Notification"],
* },
* targets: [{
* Id: "SqsTarget",
* Arn: yield* queue.queueArn,
* InputTransformer: {
* InputPathsMap: {
* instance: "$.detail.instance-id",
* state: "$.detail.state",
* },
* InputTemplate: '{"instanceId": <instance>, "newState": <state>}',
* },
* }],
* });
* ```
*
* **Example:** Rule with Dead Letter Queue
* ```typescript
* const rule = yield* Rule("ReliableEvents", {
* eventPattern: { source: ["my.app"] },
* targets: [{
* Id: "Target",
* Arn: yield* fn.functionArn(),
* DeadLetterConfig: {
* Arn: yield* dlq.queueArn,
* },
* RetryPolicy: {
* MaximumRetryAttempts: 3,
* MaximumEventAgeInSeconds: 3600,
* },
* }],
* });
* ```
*
* **Example:** Rule with ECS Target
* ```typescript
* const rule = yield* Rule("EcsSchedule", {
* scheduleExpression: "rate(1 hour)",
* roleArn: yield* role.roleArn(),
* targets: [{
* Id: "EcsTask",
* Arn: yield* cluster.clusterArn(),
* RoleArn: yield* ecsRole.roleArn(),
* EcsParameters: {
* TaskDefinitionArn: yield* taskDef.taskDefinitionArn(),
* TaskCount: 1,
* LaunchType: "FARGATE",
* NetworkConfiguration: {
* awsvpcConfiguration: {
* Subnets: ["subnet-abc123"],
* AssignPublicIp: "ENABLED",
* },
* },
* },
* }],
* });
* ```
*
* @resource
*/
export interface Rule extends Resource<
"AWS.EventBridge.Rule",
RuleProps,
{
/** The name of the rule. */
ruleName: RuleName;
/** The ARN of the rule. */
ruleArn: RuleArn;
/** The event bus associated with the rule. */
eventBusName: string;
/**
* The rule definition (pattern, schedule, state, role, description), its
* targets and its tags, as observed. Lets `alchemy drift` detect
* out-of-band changes.
*/
configuration?: {
description?: string;
eventPattern?: string;
scheduleExpression?: string;
state?: string;
roleArn?: string;
targets: eventbridge.Target[];
tags: Record<string, string>;
};
},
never,
Providers
> {}
export const Rule = Resource<Rule>("AWS.EventBridge.Rule");
export const RuleProvider = () =>
Provider.effect(
Rule,
Effect.gen(function* () {
const createRuleName = (id: string, props: { name?: string } = {}) => {
if (props.name) {
return Effect.succeed(props.name);
}
return createPhysicalName({
id,
maxLength: 64,
});
};
/**
* Everything reconcile converges on a rule, as observed. `read` and
* `reconcile` share it so a converged rule reads unchanged.
*/
const observeRuleConfiguration = Effect.fn(function* (
described: eventbridge.DescribeRuleResponse,
eventBusParam: string | undefined,
tags: eventbridge.Tag[],
) {
const targets = yield* eventbridge
.listTargetsByRule({ Rule: described.Name!, EventBusName: eventBusParam })
.pipe(
Effect.map((r) => r.Targets ?? []),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed([] as eventbridge.Target[]),
),
);
return {
description: described.Description || undefined,
eventPattern: canonicalJson(described.EventPattern),
scheduleExpression: described.ScheduleExpression,
state: described.State,
roleArn: described.RoleArn,
targets: [...targets].sort((a, b) => a.Id.localeCompare(b.Id)),
tags: tagRecord(tags),
};
});
return {
stables: ["ruleName", "ruleArn", "eventBusName"],
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return;
const oldName = yield* createRuleName(id, olds);
const newName = yield* createRuleName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
const oldBus = (olds.eventBusName as string | undefined) ?? "default";
const newBus = (news.eventBusName as string | undefined) ?? "default";
if (oldBus !== newBus) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const { accountId, region } = yield* AWSEnvironment.current;
// The engine guarantees `olds` is fully resolved before calling
// `read` (Plan.ts guards every read site with `isResolved`), so
// props can be used directly to derive identity.
const ruleName = output?.ruleName ?? (yield* createRuleName(id, { name: olds?.name }));
const eventBusName = output?.eventBusName ?? olds?.eventBusName ?? "default";
const described = yield* eventbridge
.describeRule({
Name: ruleName,
EventBusName: eventBusName !== "default" ? eventBusName : undefined,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
if (!described?.Name) {
return undefined;
}
const resolvedEventBusName = described.EventBusName ?? eventBusName;
const ruleArn = toRuleArn(region, accountId, resolvedEventBusName, described.Name);
const { Tags } = yield* eventbridge.listTagsForResource({
ResourceARN: described.Arn ?? ruleArn,
});
const attrs = {
ruleName: described.Name,
ruleArn,
eventBusName: resolvedEventBusName,
configuration: yield* observeRuleConfiguration(
described,
resolvedEventBusName !== "default" ? resolvedEventBusName : undefined,
Tags ?? [],
),
};
return (yield* hasAlchemyTags(id, Tags ?? [])) ? attrs : Unowned(attrs);
}),
list: () =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
// A Rule belongs to an event bus and `listRules` is scoped to one
// bus (defaulting to "default"). To enumerate every rule in the
// account/region we first enumerate all event buses (manual
// NextToken pagination — neither op is a paginated distilled op),
// then list rules per bus with bounded concurrency.
const busNames: string[] = [];
let busToken: string | undefined;
do {
const page = yield* eventbridge.listEventBuses({
NextToken: busToken,
});
for (const bus of page.EventBuses ?? []) {
if (bus.Name) {
busNames.push(bus.Name);
}
}
busToken = page.NextToken;
} while (busToken);
// `listEventBuses` should include the default bus, but guarantee it.
if (!busNames.includes("default")) {
busNames.push("default");
}
const perBus = yield* Effect.forEach(
busNames,
(busName) =>
Effect.gen(function* () {
const eventBusParam = busName !== "default" ? busName : undefined;
const attrs: {
ruleName: RuleName;
ruleArn: RuleArn;
eventBusName: string;
}[] = [];
let ruleToken: string | undefined;
do {
// A peer reconciler may delete an event bus between our
// `listEventBuses` snapshot and this `listRules` call —
// treat a vanished bus as contributing zero rules rather
// than failing the whole enumeration.
const page = yield* eventbridge
.listRules({
EventBusName: eventBusParam,
NextToken: ruleToken,
})
.pipe(
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed(undefined as eventbridge.ListRulesResponse | undefined),
),
);
if (!page) {
break;
}
for (const rule of page.Rules ?? []) {
if (!rule.Name) {
continue;
}
// Rules created and owned by another AWS service (e.g.
// B2BI's DO-NOT-DELETE-* or DevOpsGuru's managed rules)
// reject DeleteRule without Force and are recreated by
// the owning service anyway — skip them in enumeration
// for account-wide teardown (nuke).
if (rule.ManagedBy) {
continue;
}
const resolvedBus = rule.EventBusName ?? busName;
attrs.push({
ruleName: rule.Name,
ruleArn:
(rule.Arn as RuleArn | undefined) ??
toRuleArn(region, accountId, resolvedBus, rule.Name),
eventBusName: resolvedBus,
});
}
ruleToken = page.NextToken;
} while (ruleToken);
return attrs;
}),
{ concurrency: 5 },
);
return perBus.flat();
}),
reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
yield* validateRuleProps(news);
const ruleName = output?.ruleName ?? (yield* createRuleName(id, news));
const eventBusName =
output?.eventBusName ?? (news.eventBusName as string | undefined) ?? "default";
const eventBusParam = eventBusName !== "default" ? eventBusName : undefined;
const internalTags = yield* createInternalTags(id);
const desiredTags = {
...internalTags,
...(news.tags as Record<string, string> | undefined),
};
// Ensure + Sync rule definition — `putRule` is the single
// create-or-update API for the rule itself. It's idempotent on
// matching params and overwrites schedule/eventPattern/state/etc.
// on differences, so we call it unconditionally. `Tags` only
// applies when creating; tags are reconciled separately below
// against observed cloud tags.
const { RuleArn } = yield* eventbridge.putRule({
Name: ruleName,
Description: news.description,
EventBusName: eventBusParam,
EventPattern: news.eventPattern ? JSON.stringify(news.eventPattern) : undefined,
ScheduleExpression: news.scheduleExpression,
State: news.state ?? "ENABLED",
RoleArn: news.roleArn as string | undefined,
Tags: createTagsList(desiredTags),
});
const ruleArn =
(RuleArn as RuleArn | undefined) ??
toRuleArn(region, accountId, eventBusName, ruleName);
// Sync targets — observed cloud targets vs desired. `listTargetsByRule`
// gives us the live target ids; we remove anything no longer desired,
// and `putTargets` overwrites/upserts the rest.
const resolvedTargets = (news.targets as Input.Resolve<RuleTarget>[] | undefined) ?? [];
const desiredTargetIds = new Set(resolvedTargets.map((t) => t.Id));
const observedTargets = yield* eventbridge
.listTargetsByRule({
Rule: ruleName,
EventBusName: eventBusParam,
})
.pipe(
Effect.map((r) => r.Targets ?? []),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed([] as eventbridge.Target[]),
),
);
const removedTargetIds = observedTargets
.map((t) => t.Id)
.filter((tid): tid is string => !!tid && !desiredTargetIds.has(tid));
if (removedTargetIds.length > 0) {
const response = yield* eventbridge
.removeTargets({
Rule: ruleName,
EventBusName: eventBusParam,
Ids: removedTargetIds,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
if (response) {
yield* assertRemoveTargetsSucceeded(response);
}
}
if (resolvedTargets.length > 0) {
const response = yield* eventbridge.putTargets({
Rule: ruleName,
EventBusName: eventBusParam,
Targets: resolvedTargets.map(toTarget),
});
yield* assertPutTargetsSucceeded(response);
}
// Sync tags — diff observed cloud tags against desired. Adoption
// and partial prior runs both converge here.
const observedTagsList = yield* eventbridge
.listTagsForResource({
ResourceARN: ruleArn,
})
.pipe(Effect.map((r) => r.Tags ?? []));
const observedTags: Record<string, string> = {};
for (const tag of observedTagsList) {
if (tag.Key && tag.Value !== undefined) {
observedTags[tag.Key] = tag.Value;
}
}
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (removed.length > 0) {
yield* eventbridge.untagResource({
ResourceARN: ruleArn,
TagKeys: removed,
});
}
if (upsert.length > 0) {
yield* eventbridge.tagResource({
ResourceARN: ruleArn,
Tags: upsert,
});
}
yield* session.note(ruleArn);
const described = yield* eventbridge.describeRule({
Name: ruleName,
EventBusName: eventBusParam,
});
return {
ruleName,
ruleArn,
eventBusName,
configuration: yield* observeRuleConfiguration(
described,
eventBusParam,
createTagsList(desiredTags),
),
};
}),
delete: Effect.fn(function* (input) {
const ruleName = input.output.ruleName;
const eventBusName = input.output.eventBusName;
const eventBusParam = eventBusName !== "default" ? eventBusName : undefined;
const { Targets } = yield* eventbridge
.listTargetsByRule({
Rule: ruleName,
EventBusName: eventBusParam,
})
.pipe(
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed({ Targets: undefined }),
),
);
if (Targets && Targets.length > 0) {
const response = yield* eventbridge
.removeTargets({
Rule: ruleName,
EventBusName: eventBusParam,
Ids: Targets.map((t) => t.Id),
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
if (response) {
yield* assertRemoveTargetsSucceeded(response);
}
}
yield* eventbridge
.deleteRule({
Name: ruleName,
EventBusName: eventBusParam,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
};
}),
);
const toTarget = (target: Input.Resolve<RuleTarget>): eventbridge.Target => ({
Id: target.Id,
Arn: target.Arn,
RoleArn: target.RoleArn,
Input: target.Input,
InputPath: target.InputPath,
InputTransformer: target.InputTransformer,
KinesisParameters: target.KinesisParameters,
RunCommandParameters: target.RunCommandParameters,
EcsParameters: target.EcsParameters
? {
...target.EcsParameters,
TaskDefinitionArn: target.EcsParameters.TaskDefinitionArn,
}
: undefined,
BatchParameters: target.BatchParameters
? {
...target.BatchParameters,
JobDefinition: target.BatchParameters.JobDefinition,
}
: undefined,
SqsParameters: target.SqsParameters,
HttpParameters: target.HttpParameters,
RedshiftDataParameters: target.RedshiftDataParameters,
SageMakerPipelineParameters: target.SageMakerPipelineParameters,
DeadLetterConfig: target.DeadLetterConfig ? { Arn: target.DeadLetterConfig.Arn } : undefined,
RetryPolicy: target.RetryPolicy,
AppSyncParameters: target.AppSyncParameters,
});
const toRuleArn = (
region: RegionID,
accountId: AccountID,
eventBusName: string,
ruleName: string,
): RuleArn =>
(eventBusName === "default"
? `arn:aws:events:${region}:${accountId}:rule/${ruleName}`
: `arn:aws:events:${region}:${accountId}:rule/${eventBusName}/${ruleName}`) as RuleArn;
const validateRuleProps = Effect.fn(function* (props: RuleProps) {
if (!props.eventPattern && !props.scheduleExpression) {
return yield* new RuleInvalidProps({
message: "EventBridge Rule requires either `eventPattern` or `scheduleExpression`",
});
}
});
const assertPutTargetsSucceeded = Effect.fn(function* (response: eventbridge.PutTargetsResponse) {
if ((response.FailedEntryCount ?? 0) > 0) {
return yield* new RuleOperationFailed({
message: `Failed to attach EventBridge targets: ${JSON.stringify(response.FailedEntries ?? [])}`,
});
}
});
const assertRemoveTargetsSucceeded = Effect.fn(function* (
response: eventbridge.RemoveTargetsResponse,
) {
if ((response.FailedEntryCount ?? 0) > 0) {
return yield* new RuleOperationFailed({
message: `Failed to remove EventBridge targets: ${JSON.stringify(response.FailedEntries ?? [])}`,
});
}
});