sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Scheduler/ ScheduleEventSource.ts

import { createHash } from "node:crypto";
import type * as scheduler from "@distilled.cloud/aws/scheduler";
import * as Binding from "alchemy/Binding";
import * as Effect from "effect/Effect";
import * as IAM from "../IAM/index.ts";
import type { Function as LambdaFunction } from "../Lambda/Function.ts";
import { qualifiedArnOf } from "../Lambda/QualifiedArn.ts";
import type { ScheduleBuilder, ScheduleBuilderState } from "./builders.ts";
import { Schedule } from "./Schedule.ts";
import type { ScheduleGroup } from "./ScheduleGroup.ts";

/**
 * The typed event a consumed schedule delivers to its handler. EventBridge
 * Scheduler substitutes the `<aws.scheduler.*>` context attributes into the
 * schedule's `Input` template at invocation time; `scheduleId` is the stable
 * route id used to match the invocation to the registered handler.
 */
export interface ScheduleEvent {
  source: "alchemy.scheduler";
  /**
   * Stable route id of the `consumeSchedule` registration that created the
   * schedule.
   */
  scheduleId: string;
  /**
   * ARN of the schedule (`<aws.scheduler.schedule-arn>`).
   */
  scheduleArn: string;
  /**
   * The time the invocation was scheduled for, ISO 8601
   * (`<aws.scheduler.scheduled-time>`).
   */
  scheduledTime: string;
  /**
   * Unique id of this delivery attempt (`<aws.scheduler.execution-id>`).
   */
  executionId: string;
  /**
   * Delivery attempt counter, 1-based (`<aws.scheduler.attempt-number>`).
   */
  attemptNumber: string;
}

/**
 * Narrow an arbitrary Lambda invocation payload to a schedule event produced
 * by `consumeSchedule`.
 */
export const isScheduleEvent = (event: any): event is ScheduleEvent =>
  event?.source === "alchemy.scheduler" && typeof event?.scheduleId === "string";

export interface ScheduleRouteProps {
  /**
   * Optional schedule group the backing schedule is created in.
   * @default the AWS default group
   */
  group?: ScheduleGroup;
  /**
   * Optional description on the backing schedule.
   */
  description?: string;
  /**
   * Desired schedule state (`ENABLED` / `DISABLED`).
   */
  state?: string;
  /**
   * Timezone for cron or at expressions.
   */
  timezone?: string;
  /**
   * Optional start date.
   */
  startDate?: Date;
  /**
   * Optional end date.
   */
  endDate?: Date;
  /**
   * Optional KMS key ARN.
   */
  kmsKeyArn?: string;
  /**
   * Flexible time window configuration.
   * @default { Mode: "OFF" }
   */
  flexibleTimeWindow?: scheduler.FlexibleTimeWindow;
  /**
   * Action after a one-time schedule completes.
   */
  actionAfterCompletion?: string;
  /**
   * Retry policy for failed invocations.
   */
  retryPolicy?: scheduler.RetryPolicy;
  /**
   * Dead-letter queue for undeliverable invocations.
   */
  deadLetterConfig?: scheduler.DeadLetterConfig;
}

export interface ScheduleDescriptor {
  /**
   * Stable route id. Defaults to a hash of the schedule expression and the
   * host Function's logical id.
   */
  id?: string;
  /**
   * Schedule expression: `rate(...)`, `cron(...)`, or `at(...)`.
   */
  expression: string;
  props?: ScheduleRouteProps;
}

/**
 * The cron-handler DX for EventBridge Scheduler: a Lambda consumes its own
 * scheduled invocations. `consumeSchedule(every("5 minutes"), handler)`
 * provisions the backing `Schedule` (plus the synthesized execution role that
 * lets Scheduler invoke the host) and registers the runtime handler with a
 * typed event guard.
 *
 * @binding
 */
export interface ScheduleEventSource extends Binding.Service<
  ScheduleEventSource,
  "AWS.Scheduler.ScheduleEventSource",
  ScheduleEventSourceService
> {}
export const ScheduleEventSource = Binding.Service<ScheduleEventSource>(
  "AWS.Scheduler.ScheduleEventSource",
);

export type ScheduleEventSourceService = <Req = never>(
  descriptor: ScheduleDescriptor,
  process: (event: ScheduleEvent) => Effect.Effect<void, never, Req>,
) => Effect.Effect<void, never, never>;

/**
 * Consume a schedule's invocations on the host Lambda Function — the "cron
 * handler" DX. Build the cadence with `every`/`cron`/`at` and pass the handler
 * as the last argument; the runtime layer provisions the backing schedule,
 * the execution role, and the typed event dispatch.
 *
 * @example Run a handler every 5 minutes
 * ```typescript
 * yield* AWS.Scheduler.consumeSchedule(
 *   AWS.Scheduler.every("5 minutes"),
 *   (event) => Effect.log(`fired at ${event.scheduledTime}`),
 * );
 * ```
 *
 * @example Name the backing schedule route deterministically
 * ```typescript
 * yield* AWS.Scheduler.consumeSchedule(
 *   "NightlyCleanup",
 *   AWS.Scheduler.cron("cron(0 3 * * ? *)"),
 *   (event) => Effect.log(`cleanup ${event.executionId}`),
 * );
 * ```
 */
export function consumeSchedule<Req = never>(
  builder: ScheduleBuilder,
  process: (event: ScheduleEvent) => Effect.Effect<void, never, Req>,
): Effect.Effect<void, never, ScheduleEventSource | Req>;
export function consumeSchedule<Req = never>(
  id: string,
  builder: ScheduleBuilder,
  process: (event: ScheduleEvent) => Effect.Effect<void, never, Req>,
): Effect.Effect<void, never, ScheduleEventSource | Req>;
export function consumeSchedule(...args: any[]) {
  const process = args[args.length - 1] as (
    event: ScheduleEvent,
  ) => Effect.Effect<void, never, never>;
  const head = args.slice(0, -1);
  const id = typeof head[0] === "string" ? (head[0] as string) : undefined;
  const builder = (id === undefined ? head[0] : head[1]) as ScheduleBuilder;
  return ScheduleEventSource.use((source) =>
    source(toScheduleDescriptor(id, builder.state), process),
  );
}

const toScheduleDescriptor = (
  id: string | undefined,
  state: ScheduleBuilderState,
): ScheduleDescriptor => ({
  id: id ?? state.name,
  expression: state.expression,
  props: {
    group: state.group,
    description: state.description,
    state: state.state,
    timezone: state.timezone,
    startDate: state.startDate,
    endDate: state.endDate,
    kmsKeyArn: state.kmsKeyArn,
    flexibleTimeWindow: state.flexibleTimeWindow,
    actionAfterCompletion: state.actionAfterCompletion,
  },
});

/**
 * Derive the stable route id for a schedule descriptor: the explicit id when
 * given, otherwise a hash of the expression and the host Function's logical
 * id. Computed identically at deploy time (to name the backing resources) and
 * at runtime (to match incoming events to the handler).
 */
export const createScheduleRouteId = (descriptor: ScheduleDescriptor, fn: LambdaFunction): string =>
  descriptor.id ??
  `Scheduler${createHash("sha1")
    .update(
      JSON.stringify({
        expression: descriptor.expression,
        host: fn.LogicalId,
      }),
    )
    .digest("hex")
    .slice(0, 10)}`;

/**
 * Deploy-time half of `consumeSchedule`: synthesize the execution role that
 * lets EventBridge Scheduler invoke the host Function and create the backing
 * `Schedule` whose `Input` template carries the typed event envelope.
 *
 * @binding
 */
export const createScheduleRoute = (
  routeId: string,
  descriptor: ScheduleDescriptor,
  fn: LambdaFunction,
) =>
  Effect.gen(function* () {
    const props = descriptor.props ?? {};

    const role = yield* IAM.Role(`${routeId}Role`, {
      assumeRolePolicyDocument: {
        Version: "2012-10-17",
        Statement: [
          {
            Effect: "Allow",
            Principal: { Service: "scheduler.amazonaws.com" },
            Action: ["sts:AssumeRole"],
          },
        ],
      },
      inlinePolicies: {
        InvokeHost: {
          Version: "2012-10-17",
          Statement: [
            {
              Effect: "Allow",
              Action: ["lambda:InvokeFunction"],
              Resource: [qualifiedArnOf(fn)],
            },
          ],
        },
      },
    });

    return yield* Schedule(routeId, {
      groupName: props.group?.scheduleGroupName,
      scheduleExpression: descriptor.expression,
      description: props.description,
      scheduleExpressionTimezone: props.timezone,
      startDate: props.startDate,
      endDate: props.endDate,
      state: props.state,
      kmsKeyArn: props.kmsKeyArn,
      flexibleTimeWindow: props.flexibleTimeWindow ?? { Mode: "OFF" },
      actionAfterCompletion: props.actionAfterCompletion,
      target: {
        Arn: qualifiedArnOf(fn) as any,
        RoleArn: role.roleArn as any,
        // EventBridge Scheduler substitutes the <aws.scheduler.*> context
        // attributes into this template at invocation time; the resulting
        // JSON is the Lambda event payload matched by `isScheduleEvent`.
        Input: JSON.stringify({
          source: "alchemy.scheduler",
          scheduleId: routeId,
          scheduleArn: "<aws.scheduler.schedule-arn>",
          scheduledTime: "<aws.scheduler.scheduled-time>",
          executionId: "<aws.scheduler.execution-id>",
          attemptNumber: "<aws.scheduler.attempt-number>",
        }),
        RetryPolicy: props.retryPolicy,
        DeadLetterConfig: props.deadLetterConfig,
      },
    });
  });