effect-inngest 0.1.3 → 0.2.0-beta.0

package/src/internal/driver.ts

@@ -2,15 +2,28 @@
  * Driver execution logic.
  * @internal
  */
-import * as Headers from "@effect/platform/Headers";
-import * as HttpTraceContext from "@effect/platform/HttpTraceContext";
-import { Array as Arr, Chunk, Context, Duration, Effect, HashMap, Option, pipe, Predicate, Ref, Schema } from "effect";
+import * as Headers from "effect/unstable/http/Headers";
+import * as HttpTraceContext from "effect/unstable/http/HttpTraceContext";
+import * as Cause from "effect/Cause";
+import * as Chunk from "effect/Chunk";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HashMap from "effect/HashMap";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { pipe } from "effect/Function";
+import * as Predicate from "effect/Predicate";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
 import type { InngestFunction } from "../Function.js";
 import { InngestClient } from "../Client.js";
+import * as Checkpoint from "./checkpoint.js";
+import type { CheckpointConfig, CheckpointState } from "./checkpoint.js";
 import { isRetryAfterError, isNonRetriableError, isStepError, type RetryAfterError, type StepError } from "./errors.js";
 import * as Protocol from "./protocol.js";
 import { StepInterrupt } from "./interrupts.js";
-import { createStepTools, buildHandlerContext, Step, type HandlerContext } from "./step.js";
+import { createStepTools, buildHandlerContext, type HandlerContext } from "./step.js";
 import { OtelAttributes } from "./constants.js";
 
 /** Trace context headers extracted from incoming request */
@@ -22,36 +35,22 @@ export interface TraceHeaders {
 const SDK_VERSION = "2.0.0";
 
 export class ExecutionResult extends Schema.Class<ExecutionResult>("ExecutionResult")({
-  status: Schema.Literal(200, 206, 500),
+  status: Schema.Literals([200, 206, 400, 500]),
   body: Schema.Unknown,
-  headers: Schema.Record({ key: Schema.String, value: Schema.String }),
+  headers: Schema.Record(Schema.String, Schema.String),
 }) {}
 
 const isStepInterrupt = Schema.is(StepInterrupt);
 
-const isSomeWithValue = (v: unknown): v is { _tag: "Some"; value: unknown } =>
-  Predicate.isRecord(v) && Predicate.hasProperty(v, "_tag") && v._tag === "Some" && Predicate.hasProperty(v, "value");
-
-const extractStepInterrupt = (value: unknown): Option.Option<StepInterrupt> =>
-  pipe(
-    Option.liftPredicate(isStepInterrupt)(value),
-    Option.orElse(() =>
-      pipe(
-        Option.liftPredicate(isSomeWithValue)(value),
-        Option.flatMap((v) => Option.liftPredicate(isStepInterrupt)(v.value)),
-      ),
-    ),
-  );
-
-const collectStepInterruptsFromError = (error: unknown): Chunk.Chunk<StepInterrupt> =>
-  pipe(
-    extractStepInterrupt(error),
-    Option.match({
-      onSome: Chunk.of,
-      onNone: () =>
-        Array.isArray(error) ? Chunk.fromIterable(Arr.filterMap(error, extractStepInterrupt)) : Chunk.empty(),
-    }),
-  );
+const collectStepInterruptsFromCause = <E>(cause: Cause.Cause<E>): Chunk.Chunk<StepInterrupt> => {
+  const interrupts: Array<StepInterrupt> = [];
+  for (const reason of cause.reasons) {
+    if (Cause.isFailReason(reason) && isStepInterrupt(reason.error)) {
+      interrupts.push(reason.error);
+    }
+  }
+  return Chunk.fromIterable(interrupts);
+};
 
 const toUserError = (error: unknown): typeof Protocol.UserError.Type =>
   Protocol.UserError.make({
@@ -63,89 +62,236 @@ const toUserError = (error: unknown): typeof Protocol.UserError.Type =>
 const baseHeaders = (): Record<string, string> => ({
   "Content-Type": "application/json",
   [Protocol.Headers.SDK]: `effect-inngest:v${SDK_VERSION}`,
-  [Protocol.Headers.RequestVersion]: "1",
+  [Protocol.Headers.RequestVersion]: "2",
 });
 
+const encodeOpcodes = (opcodes: ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>): unknown =>
+  Schema.encodeSync(Schema.Array(Protocol.GeneratorOpcode))(opcodes);
+
 export const execute = <F extends InngestFunction.Any, R>(
   fn: F,
   handler: (ctx: HandlerContext<F>) => Effect.Effect<InngestFunction.Success<F>, unknown, R>,
   request: Protocol.SDKRequestBody,
   appName: string,
   traceHeaders: TraceHeaders = {},
+  checkpointConfig: Option.Option<CheckpointConfig> = Option.none(),
 ): Effect.Effect<ExecutionResult, never, R | InngestClient> =>
   Effect.gen(function* () {
     const stepIdCounts = yield* Ref.make(HashMap.empty<string, number>());
-    const step = createStepTools(request, appName, stepIdCounts);
-    const context = buildHandlerContext<F>(fn, step, request);
     const headers = baseHeaders();
 
-    const result = yield* Effect.scoped(handler(context)).pipe(
-      Effect.provideService(Step, step),
-      Effect.map((value) => ExecutionResult.make({ status: 200, body: value, headers })),
-      Effect.catchAll((error) => {
-        const interrupts = collectStepInterruptsFromError(error);
-
-        if (!Chunk.isEmpty(interrupts)) {
-          const interruptArray = Chunk.toReadonlyArray(interrupts);
-          const opcodes = interruptArray.map((interrupt) => interrupt.opcode);
-
-          const hasNonRetriableError = opcodes.some(
-            (op) =>
-              op.op === Protocol.Opcode.StepError &&
-              Predicate.isRecord(op.error) &&
-              Predicate.hasProperty(op.error, "noRetry") &&
-              op.error.noRetry === true,
-          );
-
-          const retryAfterMs = interruptArray.find((i) => i.retryAfterMs !== undefined)?.retryAfterMs;
-          const responseHeaders: Record<string, string> = hasNonRetriableError
-            ? { ...headers, [Protocol.Headers.NoRetry]: "true" }
-            : headers;
-          if (retryAfterMs !== undefined) {
-            responseHeaders[Protocol.Headers.RetryAfter] = String(Math.ceil(retryAfterMs / 1000));
+    // Build the optional CheckpointState. In checkpoint mode the step tools
+    // buffer StepRun results into this state and yield (drain + DiscoveryRequest /
+    // RunComplete / interrupt) once the handler resolves.
+    const checkpointState: Option.Option<CheckpointState> = yield* Option.match(checkpointConfig, {
+      onNone: () => Effect.succeed(Option.none<CheckpointState>()),
+      onSome: (config) =>
+        Effect.gen(function* () {
+          const client = yield* InngestClient;
+          const state = yield* Checkpoint.make({
+            config,
+            runId: request.ctx.run_id,
+            fnId: request.ctx.fn_id,
+            qiId: request.ctx.qi_id,
+            checkpointAsync: (steps) =>
+              client.checkpointAsync({
+                runId: request.ctx.run_id,
+                fnId: request.ctx.fn_id,
+                qiId: request.ctx.qi_id,
+                steps,
+              }),
+          });
+          return Option.some(state);
+        }),
+    });
+
+    const step = createStepTools(request, appName, stepIdCounts, checkpointState);
+    const context = buildHandlerContext<F>(fn, step, request);
+
+    /**
+     * Drain any unflushed buffered opcodes (no-op outside checkpoint mode).
+     * Used at every terminal branch so step results are never lost.
+     */
+    const drainBuffer: Effect.Effect<ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>> = Option.match(
+      checkpointState,
+      {
+        onNone: () => Effect.succeed([] as ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>),
+        onSome: (state) => state.drain,
+      },
+    );
+
+    /**
+     * In checkpoint mode wrap the handler in `Effect.raceFirst` against a
+     * `maxRuntime` deadline. Branches produce disjoint `Option` variants —
+     * `Some(value)` for a successful handler result, `None` for the deadline
+     * winning — so no type cast is required. Spec §10.4.1 #7.
+     */
+    type RaceResult = Option.Option<InngestFunction.Success<F>>;
+    const handlerWithRace: Effect.Effect<RaceResult, unknown, R> = Option.match(checkpointState, {
+      onNone: () => Effect.map(handler(context), Option.some<InngestFunction.Success<F>>),
+      onSome: (state) =>
+        // raceFirst (not race) so a handler failure (e.g. sleepInterrupt) is
+        // surfaced immediately instead of waiting for the deadline. Race
+        // would block until a side succeeds — handler interrupts would hang.
+        Effect.raceFirst(
+          Effect.map(handler(context), Option.some<InngestFunction.Success<F>>),
+          Effect.sleep(state.config.maxRuntime).pipe(
+            Effect.tap(() => state.markRuntimeExceeded),
+            Effect.as(Option.none<InngestFunction.Success<F>>()),
+          ),
+        ),
+    });
+
+    const result = yield* Effect.scoped(handlerWithRace).pipe(
+      Effect.flatMap((raced) =>
+        Effect.gen(function* () {
+          const drained = yield* drainBuffer;
+          // Checkpoint mode: assemble [drained..., RunComplete | DiscoveryRequest]
+          // even when buffer is empty — TS reference always emits RunComplete on
+          // completion so the executor can correlate (spec §10.4.1 #8).
+          if (Option.isSome(checkpointState)) {
+            const state = checkpointState.value;
+            const exceeded = (yield* state.isRuntimeExceeded) || Option.isNone(raced);
+            const terminal = exceeded ? Protocol.discoveryRequest() : Protocol.runComplete(raced.value);
+            const opcodes = [...drained, terminal];
+            return ExecutionResult.make({ status: 206, body: encodeOpcodes(opcodes), headers });
+          }
+          // Async mode: classic 200 with the bare return value.
+          // `raced` is always Some in async mode (no deadline branch).
+          return ExecutionResult.make({
+            status: 200,
+            body: Option.getOrThrow(raced),
+            headers,
+          });
+        }),
+      ),
+      Effect.catchCause((cause) =>
+        Effect.gen(function* () {
+          // Drain buffer for inclusion in 206 / error response so step results
+          // are never lost (spec §10.4.3 graceful fallback).
+          const drained = yield* drainBuffer;
+
+          // Collect all step interrupts from the cause (handles parallel failures)
+          const interrupts = collectStepInterruptsFromCause(cause);
+
+          if (!Chunk.isEmpty(interrupts)) {
+            const interruptArray = Chunk.toReadonlyArray(interrupts);
+            const opcodes = [...drained, ...interruptArray.map((interrupt) => interrupt.opcode)];
+
+            const hasNonRetriableError = opcodes.some(
+              (op) =>
+                op.op === Protocol.Opcode.StepError &&
+                Predicate.isObject(op.error) &&
+                Predicate.hasProperty(op.error, "noRetry") &&
+                op.error.noRetry === true,
+            );
+
+            const retryAfterMs = interruptArray.find((i) => i.retryAfterMs !== undefined)?.retryAfterMs;
+            const responseHeaders: Record<string, string> = hasNonRetriableError
+              ? { ...headers, [Protocol.Headers.NoRetry]: "true" }
+              : headers;
+            if (retryAfterMs !== undefined) {
+              responseHeaders[Protocol.Headers.RetryAfter] = String(Math.ceil(retryAfterMs / 1000));
+              // Spec §4.4.3: "If `Retry-After` is set, an SDK MUST also set
+              // `X-Inngest-No-Retry: false`." Overrides any prior value from
+              // the non-retriable branch above — the presence of RetryAfter
+              // implies the caller wants a retry at the specified delay.
+              responseHeaders[Protocol.Headers.NoRetry] = "false";
+            }
+            return ExecutionResult.make({ status: 206, body: encodeOpcodes(opcodes), headers: responseHeaders });
           }
-          const encodedOpcodes = Schema.encodeSync(Schema.Array(Protocol.GeneratorOpcode))(opcodes);
-          return Effect.succeed(ExecutionResult.make({ status: 206, body: encodedOpcodes, headers: responseHeaders }));
-        }
-
-        // Check for RetryAfterError - use type guard and direct access
-        if (isRetryAfterError(error)) {
-          const retryAfterMs = Duration.toMillis((error as RetryAfterError).retryAfter);
-          const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
-          return Effect.succeed(
-            ExecutionResult.make({
+
+          // Extract the first error from cause for non-interrupt error handling.
+          // `findErrorOption` only matches typed failures; fall back to the first
+          // defect (Effect.die, unchecked throws) so we surface the original error.
+          const errorOpt = Option.orElse(Cause.findErrorOption(cause), () => {
+            const dieReason = cause.reasons.find(Cause.isDieReason);
+            return dieReason ? Option.some(dieReason.defect) : Option.none();
+          });
+          if (Option.isNone(errorOpt)) {
+            // No error in cause - shouldn't happen, but handle gracefully.
+            // Buffered steps still surface in a 206 wrapping if any exist.
+            if (drained.length > 0) {
+              return ExecutionResult.make({
+                status: 206,
+                body: encodeOpcodes(drained),
+                headers,
+              });
+            }
+            return ExecutionResult.make({
               status: 500,
-              body: { error: toUserError(error) },
+              body: { name: "Error", message: "Unknown error" },
+              headers: { ...headers, [Protocol.Headers.NoRetry]: "false" },
+            });
+          }
+          const error = errorOpt.value;
+
+          // Check for RetryAfterError - use type guard and direct access
+          if (isRetryAfterError(error)) {
+            const retryAfterMs = Duration.toMillis((error as RetryAfterError).retryAfter);
+            const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
+            // Spec §10.4.3: include drained buffered steps in response when
+            // present; otherwise existing 500 behavior.
+            if (drained.length > 0) {
+              return ExecutionResult.make({
+                status: 206,
+                body: encodeOpcodes(drained),
+                headers: {
+                  ...headers,
+                  [Protocol.Headers.NoRetry]: "false",
+                  [Protocol.Headers.RetryAfter]: String(retryAfterSeconds),
+                },
+              });
+            }
+            return ExecutionResult.make({
+              status: 500,
+              body: toUserError(error),
               headers: {
                 ...headers,
                 [Protocol.Headers.NoRetry]: "false",
                 [Protocol.Headers.RetryAfter]: String(retryAfterSeconds),
               },
-            }),
-          );
-        }
-
-        // Check for NonRetriableError or StepError with noRetry
-        const noRetryValue =
-          isNonRetriableError(error) || (isStepError(error) && (error as StepError).noRetry === true);
-        const noRetry = noRetryValue ? "true" : "false";
-        return Effect.succeed(
-          ExecutionResult.make({
-            status: 500,
-            body: { error: toUserError(error) },
+            });
+          }
+
+          // Check for NonRetriableError or StepError with noRetry
+          const noRetryValue =
+            isNonRetriableError(error) || (isStepError(error) && (error as StepError).noRetry === true);
+          const noRetry = noRetryValue ? "true" : "false";
+          if (drained.length > 0) {
+            return ExecutionResult.make({
+              status: 206,
+              body: encodeOpcodes(drained),
+              headers: { ...headers, [Protocol.Headers.NoRetry]: noRetry },
+            });
+          }
+          // Spec §4.4.3: non-retriable function errors MUST return 400 with
+          // the error payload at the response root; retriable errors return
+          // 500 with the same root shape.
+          return ExecutionResult.make({
+            status: noRetryValue ? 400 : 500,
+            body: toUserError(error),
             headers: { ...headers, [Protocol.Headers.NoRetry]: noRetry },
-          }),
-        );
-      }),
+          });
+        }),
+      ),
 
-      Effect.catchAllDefect((defect) =>
-        Effect.succeed(
-          ExecutionResult.make({
+      Effect.catchDefect((defect) =>
+        Effect.gen(function* () {
+          const drained = yield* drainBuffer;
+          if (drained.length > 0) {
+            return ExecutionResult.make({
+              status: 206,
+              body: encodeOpcodes(drained),
+              headers: { ...headers, [Protocol.Headers.NoRetry]: "false" },
+            });
+          }
+          return ExecutionResult.make({
             status: 500,
-            body: { error: toUserError(defect) },
+            body: toUserError(defect),
             headers: { ...headers, [Protocol.Headers.NoRetry]: "false" },
-          }),
-        ),
+          });
+        }),
       ),
     );
 
@@ -179,16 +325,18 @@ export interface DriverService {
     fn: F,
     handler: (ctx: HandlerContext<F>) => Effect.Effect<InngestFunction.Success<F>, unknown, R>,
     request: Protocol.SDKRequestBody,
+    checkpointConfig?: Option.Option<CheckpointConfig>,
   ) => Effect.Effect<ExecutionResult, never, R | InngestClient>;
 }
 
-export class Driver extends Context.Tag("effect-inngest/Driver")<Driver, DriverService>() {}
+export class Driver extends Context.Service<Driver, DriverService>()("effect-inngest/Driver") {}
 
-export const layer = (options: { readonly appName: string }) =>
-  Effect.succeed({
+export const layer = (options: { readonly appName: string }): Layer.Layer<Driver> =>
+  Layer.succeed(Driver, {
     execute: <F extends InngestFunction.Any, R>(
       fn: F,
       handler: (ctx: HandlerContext<F>) => Effect.Effect<InngestFunction.Success<F>, unknown, R>,
       request: Protocol.SDKRequestBody,
-    ) => execute(fn, handler, request, options.appName),
-  }).pipe(Effect.map((service) => Context.make(Driver, service)));
+      checkpointConfig: Option.Option<CheckpointConfig> = Option.none(),
+    ) => execute(fn, handler, request, options.appName, {}, checkpointConfig),
+  });

package/src/internal/errors.ts

@@ -2,19 +2,20 @@
  * Internal error types for the Effect Inngest SDK.
  * @internal
  */
+import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
 
 /**
  * @internal
  */
-export class SignatureError extends Schema.TaggedError<SignatureError>()("SignatureError", {
+export class SignatureError extends Schema.TaggedErrorClass<SignatureError>()("SignatureError", {
   message: Schema.String,
 }) {}
 
 /**
  * @internal
  */
-export class RegistrationError extends Schema.TaggedError<RegistrationError>()("RegistrationError", {
+export class RegistrationError extends Schema.TaggedErrorClass<RegistrationError>()("RegistrationError", {
   message: Schema.String,
   functions: Schema.Array(Schema.String),
 }) {}
@@ -22,7 +23,7 @@ export class RegistrationError extends Schema.TaggedError<RegistrationError>()("
 /**
  * @internal
  */
-export class FunctionNotFoundError extends Schema.TaggedError<FunctionNotFoundError>()("FunctionNotFoundError", {
+export class FunctionNotFoundError extends Schema.TaggedErrorClass<FunctionNotFoundError>()("FunctionNotFoundError", {
   message: Schema.String,
   functionId: Schema.String,
 }) {}
@@ -30,7 +31,7 @@ export class FunctionNotFoundError extends Schema.TaggedError<FunctionNotFoundEr
 /**
  * @internal
  */
-export class SendEventError extends Schema.TaggedError<SendEventError>()("SendEventError", {
+export class SendEventError extends Schema.TaggedErrorClass<SendEventError>()("SendEventError", {
   message: Schema.String,
   events: Schema.Array(Schema.String),
 }) {}
@@ -38,17 +39,17 @@ export class SendEventError extends Schema.TaggedError<SendEventError>()("SendEv
 /**
  * @internal
  */
-export class UseApiFetchError extends Schema.TaggedError<UseApiFetchError>()("UseApiFetchError", {
+export class UseApiFetchError extends Schema.TaggedErrorClass<UseApiFetchError>()("UseApiFetchError", {
   message: Schema.String,
-  endpoint: Schema.Literal("batch", "actions"),
+  endpoint: Schema.Literals(["batch", "actions"]),
   runId: Schema.String,
-  statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),
+  statusCode: Schema.optional(Schema.Number),
 }) {}
 
 /**
  * @internal
  */
-export class StepError extends Schema.TaggedError<StepError>()("StepError", {
+export class StepError extends Schema.TaggedErrorClass<StepError>()("StepError", {
   message: Schema.String,
   stepId: Schema.String,
   cause: Schema.optional(Schema.Unknown),
@@ -58,12 +59,14 @@ export class StepError extends Schema.TaggedError<StepError>()("StepError", {
 /**
  * @internal
  */
-export const isStepError = Schema.is(StepError);
+export const isStepError: (u: unknown) => u is StepError = Predicate.isTagged("StepError") as (
+  u: unknown,
+) => u is StepError;
 
 /**
  * @internal
  */
-export class TimeoutError extends Schema.TaggedError<TimeoutError>()("TimeoutError", {
+export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()("TimeoutError", {
   message: Schema.String,
   stepId: Schema.optional(Schema.String),
   timeout: Schema.DurationFromMillis,
@@ -76,7 +79,7 @@ export class TimeoutError extends Schema.TaggedError<TimeoutError>()("TimeoutErr
  * @since 0.1.0
  * @category errors
  */
-export class NonRetriableError extends Schema.TaggedError<NonRetriableError>()("NonRetriableError", {
+export class NonRetriableError extends Schema.TaggedErrorClass<NonRetriableError>()("NonRetriableError", {
   message: Schema.String,
   cause: Schema.optional(Schema.Unknown),
 }) {}
@@ -84,7 +87,9 @@ export class NonRetriableError extends Schema.TaggedError<NonRetriableError>()("
 /**
  * @internal
  */
-export const isNonRetriableError = Schema.is(NonRetriableError);
+export const isNonRetriableError: (u: unknown) => u is NonRetriableError = Predicate.isTagged("NonRetriableError") as (
+  u: unknown,
+) => u is NonRetriableError;
 
 /**
  * Thrown to indicate that the operation should be retried after a specific delay.
@@ -93,7 +98,7 @@ export const isNonRetriableError = Schema.is(NonRetriableError);
  * @since 0.1.0
  * @category errors
  */
-export class RetryAfterError extends Schema.TaggedError<RetryAfterError>()("RetryAfterError", {
+export class RetryAfterError extends Schema.TaggedErrorClass<RetryAfterError>()("RetryAfterError", {
   message: Schema.String,
   retryAfter: Schema.DurationFromMillis,
   cause: Schema.optional(Schema.Unknown),
@@ -102,7 +107,9 @@ export class RetryAfterError extends Schema.TaggedError<RetryAfterError>()("Retr
 /**
  * @internal
  */
-export const isRetryAfterError = Schema.is(RetryAfterError);
+export const isRetryAfterError: (u: unknown) => u is RetryAfterError = Predicate.isTagged("RetryAfterError") as (
+  u: unknown,
+) => u is RetryAfterError;
 
 /**
  * @internal