sailfork / t3code-github / .repos/ alchemy-effect/ packages/ integration-tests/ test/ AWS/ Lambda/ InvocationDeadline.test.ts

import { makeFunctionHttpHandler } from "@alchemy.run/aws/Lambda/HttpServer";
import {
  DEFAULT_TIMEOUT_MARGIN_MS,
  HandlerContext,
  InvocationDeadlineState,
  lambdaTimeoutOf,
  readTimeoutGrace,
  TIMEOUT_GRACE_ENV,
  toDurationMillis,
  withInvocationDeadline,
} from "@alchemy.run/aws/Lambda/InvocationDeadline";
import { describe, expect, it } from "@alchemy.run/test";
import type * as lambda from "aws-lambda";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as HttpServerRequest from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as TestClock from "effect/testing/TestClock";

describe(
  "readTimeoutGrace",
  { tags: ["unit", "provider:aws", "provider:aws:lambda", "local"] },
  () => {
    it("never interrupts when unset, empty or unparseable", () => {
      expect(readTimeoutGrace(undefined)).toBe(0);
      expect(readTimeoutGrace("")).toBe(0);
      expect(readTimeoutGrace("abc")).toBe(0);
      expect(readTimeoutGrace("-1")).toBe(0);
    });

    it("parses whole milliseconds", () => {
      expect(readTimeoutGrace("0")).toBe(0);
      expect(readTimeoutGrace("1500")).toBe(1500);
      expect(readTimeoutGrace("250.9")).toBe(250);
    });
  },
);

describe(
  "toDurationMillis",
  { tags: ["unit", "provider:aws", "provider:aws:lambda", "local"] },
  () => {
    it("returns undefined for undefined", () => {
      expect(toDurationMillis(undefined)).toBeUndefined();
    });

    it("converts a Duration to whole milliseconds", () => {
      expect(toDurationMillis(Duration.zero)).toBe(0);
      expect(toDurationMillis(Duration.millis(250))).toBe(250);
      expect(toDurationMillis(Duration.seconds(1))).toBe(1000);
      expect(toDurationMillis(Duration.infinity)).toBeUndefined();
    });

    it("converts a state-JSON rehydrated Duration", () => {
      const json = JSON.parse(JSON.stringify(Duration.millis(750))) as Duration.Duration;
      expect(toDurationMillis(json)).toBe(750);
    });
  },
);

describe(
  "lambdaTimeoutOf",
  { tags: ["unit", "provider:aws", "provider:aws:lambda", "local"] },
  () => {
    const run = (props: Omit<Parameters<typeof lambdaTimeoutOf>[0], "id">) =>
      Effect.runSync(Effect.result(lambdaTimeoutOf({ id: "Fn", ...props })));

    it("adds the default margin to the default timeout", () => {
      expect(DEFAULT_TIMEOUT_MARGIN_MS).toBe(1000);
      expect(run({ timeout: undefined, timeoutMargin: undefined, interrupt: true })).toMatchObject({
        success: { timeoutSeconds: 4, graceMs: 1000 },
      });
    });

    it("interrupts at the exact timeout; Lambda's timeout rounds up", () => {
      expect(
        run({
          timeout: Duration.millis(2500),
          timeoutMargin: Duration.millis(200),
          interrupt: true,
        }),
      ).toMatchObject({ success: { timeoutSeconds: 3, graceMs: 500 } });
    });

    it("configures the timeout as-is when the handler is never interrupted", () => {
      expect(
        run({ timeout: Duration.millis(2500), timeoutMargin: undefined, interrupt: false }),
      ).toMatchObject({ success: { timeoutSeconds: 3, graceMs: 0 } });
      expect(
        run({ timeout: Duration.seconds(60), timeoutMargin: Duration.zero, interrupt: true }),
      ).toMatchObject({ success: { timeoutSeconds: 60, graceMs: 0 } });
      expect(
        run({ timeout: Duration.seconds(900), timeoutMargin: undefined, interrupt: false }),
      ).toMatchObject({ success: { timeoutSeconds: 900, graceMs: 0 } });
    });

    it("rejects a timeout whose margin does not fit in 900 seconds", () => {
      const result = run({
        timeout: Duration.seconds(900),
        timeoutMargin: undefined,
        interrupt: true,
      });
      expect(result).toMatchObject({
        failure: { _tag: "AWS.Lambda.FunctionTimeoutTooLong", timeoutMs: 900_000, marginMs: 1000 },
      });
      expect(
        run({ timeout: Duration.seconds(899), timeoutMargin: undefined, interrupt: true }),
      ).toMatchObject({ success: { timeoutSeconds: 900, graceMs: 1000 } });
    });
  },
);

// A Lambda context whose hard timeout is `remainingMs` away. The guard reads
// it once, when the invocation starts.
const makeContext = (remainingMs: number): lambda.Context =>
  ({
    functionName: "deadline-fn",
    awsRequestId: "req-1",
    getRemainingTimeInMillis: () => remainingMs,
  }) as lambda.Context;

// Runs `self` under the deadline guard with Lambda's timeout `remainingMs`
// away and `graceMs` of it reserved past the Function's timeout. `state` is
// the dispatcher's per-invocation deadline state.
const guarded = <A, E>(
  self: Effect.Effect<A, E>,
  { remainingMs, graceMs }: { remainingMs: number; graceMs: number },
  options?: { interrupt?: boolean },
  state: { fired: boolean } = { fired: false },
) =>
  Effect.gen(function* () {
    process.env[TIMEOUT_GRACE_ENV] = String(graceMs);
    return yield* self.pipe(
      withInvocationDeadline(options),
      Effect.provideService(HandlerContext, makeContext(remainingMs)),
      Effect.provideService(InvocationDeadlineState, state),
      Effect.ensuring(Effect.sync(() => delete process.env[TIMEOUT_GRACE_ENV])),
      Effect.exit,
      Effect.forkChild,
    );
  });

describe(
  "withInvocationDeadline",
  // Sets the grace env var, which the guard reads per invocation.
  { tags: ["unit", "provider:aws", "provider:aws:lambda", "local"] },
  () => {
    it.effect(
      "leaves a handler that finishes inside its timeout untouched",
      () =>
        Effect.gen(function* () {
          const state = { fired: false };
          const fiber = yield* guarded(
            Effect.sleep("2 seconds").pipe(Effect.as("done")),
            { remainingMs: 4000, graceMs: 1000 },
            undefined,
            state,
          );
          yield* TestClock.adjust("2 seconds");
          expect(yield* Fiber.join(fiber)).toEqual(Exit.succeed("done"));
          expect(state.fired).toBe(false);
        }),
      { exclusive: true },
    );

    it.effect(
      "interrupts a handler at its timeout and runs its finalizers",
      () =>
        Effect.gen(function* () {
          const events: string[] = [];
          const state = { fired: false };
          const fiber = yield* guarded(
            Effect.never.pipe(
              Effect.ensuring(Effect.sync(() => events.push("finalizer"))),
              Effect.onInterrupt(() => Effect.sync(() => events.push("interrupted"))),
            ),
            { remainingMs: 4000, graceMs: 1000 },
            undefined,
            state,
          );
          yield* TestClock.adjust("2999 millis");
          expect(events).toEqual([]);
          yield* TestClock.adjust("1 millis");
          const exit = yield* Fiber.join(fiber);
          expect(events).toEqual(["finalizer", "interrupted"]);
          // The dispatcher holds a fired invocation until Lambda's timeout.
          expect(state.fired).toBe(true);
          expect(exit).toMatchObject({
            _tag: "Failure",
            cause: {
              reasons: [
                {
                  _tag: "Fail",
                  error: { _tag: "AWS.Lambda.InvocationTimeoutError", budgetMs: 3000 },
                },
              ],
            },
          });
        }),
      { exclusive: true },
    );

    it.effect(
      "never interrupts a handler without grace",
      () =>
        Effect.gen(function* () {
          const fiber = yield* guarded(Effect.sleep("3500 millis").pipe(Effect.as("done")), {
            remainingMs: 4000,
            graceMs: 0,
          });
          yield* TestClock.adjust("3500 millis");
          expect(yield* Fiber.join(fiber)).toEqual(Exit.succeed("done"));
        }),
      { exclusive: true },
    );

    it.effect(
      "never interrupts a handler that opts out",
      () =>
        Effect.gen(function* () {
          const fiber = yield* guarded(
            Effect.sleep("3500 millis").pipe(Effect.as("done")),
            { remainingMs: 4000, graceMs: 1000 },
            { interrupt: false },
          );
          yield* TestClock.adjust("3500 millis");
          expect(yield* Fiber.join(fiber)).toEqual(Exit.succeed("done"));
        }),
      { exclusive: true },
    );

    it.effect(
      "an inner guard that opts out stands the outer one down",
      () =>
        Effect.gen(function* () {
          const fiber = yield* guarded(
            Effect.sleep("3500 millis").pipe(
              Effect.as("done"),
              withInvocationDeadline({ interrupt: false }),
            ),
            { remainingMs: 4000, graceMs: 1000 },
          );
          yield* TestClock.adjust("3500 millis");
          expect(yield* Fiber.join(fiber)).toEqual(Exit.succeed("done"));
        }),
      { exclusive: true },
    );

    it.effect(
      "fails an HTTP request that runs past its timeout after its finalizers",
      () =>
        Effect.gen(function* () {
          const events: string[] = [];
          const handler = Effect.never.pipe(
            Effect.ensuring(Effect.sync(() => events.push("finalizer"))),
            Effect.as(HttpServerResponse.text("never")),
          );
          const out = makeFunctionHttpHandler(
            handler as Effect.Effect<
              HttpServerResponse.HttpServerResponse,
              never,
              HttpServerRequest.HttpServerRequest
            >,
          )(functionUrlEvent);
          if (!Effect.isEffect(out)) {
            return yield* Effect.die("Expected Effect from Function URL handler");
          }
          const state = { fired: false };
          const fiber = yield* guarded(out, { remainingMs: 4000, graceMs: 1000 }, undefined, state);
          yield* TestClock.adjust("3 seconds");
          const exit = yield* Fiber.join(fiber);
          expect(events).toEqual(["finalizer"]);
          expect(state.fired).toBe(true);
          expect(exit).toMatchObject({
            _tag: "Failure",
            cause: {
              reasons: [{ _tag: "Fail", error: { _tag: "AWS.Lambda.InvocationTimeoutError" } }],
            },
          });
        }),
      { exclusive: true },
    );
  },
);

const functionUrlEvent = {
  version: "2.0",
  routeKey: "$default",
  rawPath: "/",
  rawQueryString: "",
  headers: { host: "example.lambda-url.us-east-1.on.aws", "x-forwarded-proto": "https" },
  requestContext: {
    accountId: "123456789012",
    apiId: "api-id",
    domainName: "example.lambda-url.us-east-1.on.aws",
    domainPrefix: "example",
    http: {
      method: "GET",
      path: "/",
      protocol: "HTTP/1.1",
      sourceIp: "203.0.113.42",
      userAgent: "test",
    },
    requestId: "request-id",
    routeKey: "$default",
    stage: "$default",
    time: "01/Jan/2026:00:00:00 +0000",
    timeEpoch: 0,
  },
  isBase64Encoded: false,
} satisfies lambda.LambdaFunctionURLEvent;