effect-inngest 0.1.0

package/src/internal/driver.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 type { InngestFunction } from "../Function.js";
+import { InngestClient } from "../Client.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 { OtelAttributes } from "./constants.js";
+
+/** Trace context headers extracted from incoming request */
+export interface TraceHeaders {
+  readonly traceparent?: string;
+  readonly tracestate?: string;
+}
+
+const SDK_VERSION = "2.0.0";
+
+export class ExecutionResult extends Schema.Class<ExecutionResult>("ExecutionResult")({
+  status: Schema.Literal(200, 206, 500),
+  body: Schema.Unknown,
+  headers: Schema.Record({ key: Schema.String, value: 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 toUserError = (error: unknown): typeof Protocol.UserError.Type =>
+  Protocol.UserError.make({
+    name: Predicate.hasProperty(error, "name") ? String(error.name) : "Error",
+    message: Predicate.hasProperty(error, "message") ? String(error.message) : String(error),
+    stack: Predicate.hasProperty(error, "stack") ? String(error.stack) : undefined,
+  });
+
+const baseHeaders = (): Record<string, string> => ({
+  "Content-Type": "application/json",
+  [Protocol.Headers.SDK]: `effect-inngest:v${SDK_VERSION}`,
+  [Protocol.Headers.RequestVersion]: "1",
+});
+
+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 = {},
+): 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* 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));
+          }
+          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({
+              status: 500,
+              body: { error: 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) },
+            headers: { ...headers, [Protocol.Headers.NoRetry]: noRetry },
+          }),
+        );
+      }),
+
+      Effect.catchAllDefect((defect) =>
+        Effect.succeed(
+          ExecutionResult.make({
+            status: 500,
+            body: { error: toUserError(defect) },
+            headers: { ...headers, [Protocol.Headers.NoRetry]: "false" },
+          }),
+        ),
+      ),
+    );
+
+    return result;
+  }).pipe(
+    (base) => {
+      const headers: Record<string, string> = {};
+      if (traceHeaders.traceparent) headers["traceparent"] = traceHeaders.traceparent;
+      if (traceHeaders.tracestate) headers["tracestate"] = traceHeaders.tracestate;
+      return pipe(
+        HttpTraceContext.fromHeaders(Headers.fromInput(headers)),
+        Option.match({
+          onNone: () => base,
+          onSome: (externalSpan) => Effect.withParentSpan(base, externalSpan),
+        }),
+      );
+    },
+    Effect.withSpan(`inngest.function/${fn._tag}`, {
+      kind: "server",
+      attributes: {
+        [OtelAttributes.RunId]: request.ctx.run_id,
+        [OtelAttributes.FunctionId]: fn._tag,
+        [OtelAttributes.AppId]: appName,
+        [OtelAttributes.Attempt]: request.ctx.attempt,
+      },
+    }),
+  );
+
+export interface DriverService {
+  readonly execute: <F extends InngestFunction.Any, R>(
+    fn: F,
+    handler: (ctx: HandlerContext<F>) => Effect.Effect<InngestFunction.Success<F>, unknown, R>,
+    request: Protocol.SDKRequestBody,
+  ) => Effect.Effect<ExecutionResult, never, R | InngestClient>;
+}
+
+export class Driver extends Context.Tag("effect-inngest/Driver")<Driver, DriverService>() {}
+
+export const layer = (options: { readonly appName: string }) =>
+  Effect.succeed({
+    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)));

package/src/internal/errors.ts

@@ -0,0 +1,130 @@
+/**
+ * Internal error types for the Effect Inngest SDK.
+ * @internal
+ */
+import * as Schema from "effect/Schema";
+
+/**
+ * @internal
+ */
+export class SignatureError extends Schema.TaggedError<SignatureError>()("SignatureError", {
+  message: Schema.String,
+}) {}
+
+/**
+ * @internal
+ */
+export class RegistrationError extends Schema.TaggedError<RegistrationError>()("RegistrationError", {
+  message: Schema.String,
+  functions: Schema.Array(Schema.String),
+}) {}
+
+/**
+ * @internal
+ */
+export class FunctionNotFoundError extends Schema.TaggedError<FunctionNotFoundError>()("FunctionNotFoundError", {
+  message: Schema.String,
+  functionId: Schema.String,
+}) {}
+
+/**
+ * @internal
+ */
+export class SendEventError extends Schema.TaggedError<SendEventError>()("SendEventError", {
+  message: Schema.String,
+  events: Schema.Array(Schema.String),
+}) {}
+
+/**
+ * @internal
+ */
+export class UseApiFetchError extends Schema.TaggedError<UseApiFetchError>()("UseApiFetchError", {
+  message: Schema.String,
+  endpoint: Schema.Literal("batch", "actions"),
+  runId: Schema.String,
+  statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),
+}) {}
+
+/**
+ * @internal
+ */
+export class StepError extends Schema.TaggedError<StepError>()("StepError", {
+  message: Schema.String,
+  stepId: Schema.String,
+  cause: Schema.optional(Schema.Unknown),
+  noRetry: Schema.optional(Schema.Boolean),
+}) {}
+
+/**
+ * @internal
+ */
+export const isStepError = Schema.is(StepError);
+
+/**
+ * @internal
+ */
+export class TimeoutError extends Schema.TaggedError<TimeoutError>()("TimeoutError", {
+  message: Schema.String,
+  stepId: Schema.optional(Schema.String),
+  timeout: Schema.DurationFromMillis,
+}) {}
+
+/**
+ * Thrown to indicate that the error should not be retried.
+ * Use this when you know retrying won't help (e.g., validation errors, auth failures).
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class NonRetriableError extends Schema.TaggedError<NonRetriableError>()("NonRetriableError", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown),
+}) {}
+
+/**
+ * @internal
+ */
+export const isNonRetriableError = Schema.is(NonRetriableError);
+
+/**
+ * Thrown to indicate that the operation should be retried after a specific delay.
+ * Use this for rate limiting or when you know when a resource will become available.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class RetryAfterError extends Schema.TaggedError<RetryAfterError>()("RetryAfterError", {
+  message: Schema.String,
+  retryAfter: Schema.DurationFromMillis,
+  cause: Schema.optional(Schema.Unknown),
+}) {}
+
+/**
+ * @internal
+ */
+export const isRetryAfterError = Schema.is(RetryAfterError);
+
+/**
+ * @internal
+ */
+export type ServerError = SignatureError | RegistrationError | FunctionNotFoundError;
+
+/**
+ * @internal
+ */
+export type ClientError = SendEventError | UseApiFetchError;
+
+/**
+ * @internal
+ */
+export type ExecutionError = StepError | TimeoutError;
+
+/**
+ * @internal
+ */
+export type RetryControlError = NonRetriableError | RetryAfterError;
+
+/**
+ * @internal
+ */
+export type InngestError = ServerError | ClientError | ExecutionError | RetryControlError;

package/src/internal/handler.ts

@@ -0,0 +1,222 @@
+/**
+ * Internal handler implementation.
+ * @internal
+ */
+import * as HttpClient from "@effect/platform/HttpClient";
+import * as HttpClientRequest from "@effect/platform/HttpClientRequest";
+import * as HttpClientResponse from "@effect/platform/HttpClientResponse";
+import * as HttpServerRequest from "@effect/platform/HttpServerRequest";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { InngestClient } from "../Client.js";
+import type { InngestFunction } from "../Function.js";
+import type { InngestGroup } from "../Group.js";
+import { Signature, SignatureError } from "./signature.js";
+import * as Protocol from "./protocol.js";
+export { SignatureError } from "./signature.js";
+import { execute, type TraceHeaders } from "./driver.js";
+export type { TraceHeaders } from "./driver.js";
+
+export class InvalidRequestError extends Schema.TaggedError<InvalidRequestError>()("InvalidRequestError", {
+  message: Schema.String,
+}) {}
+
+const SDK_VERSION = "2.0.0";
+
+const baseHeaders = (): Record<string, string> => ({
+  "Content-Type": "application/json",
+  [Protocol.Headers.SDK]: `effect-inngest:v${SDK_VERSION}`,
+  [Protocol.Headers.RequestVersion]: "1",
+});
+
+const buildServeUrl = (requestUrl: string, serveHost?: string, servePath?: string): URL => {
+  const url = new URL(requestUrl);
+  if (servePath) {
+    url.pathname = servePath;
+  }
+  if (serveHost) {
+    return new URL(url.pathname + url.search, serveHost);
+  }
+  return url;
+};
+
+export interface HandlerResponse<T> {
+  readonly status: number;
+  readonly headers: Record<string, string>;
+  readonly body: T;
+}
+
+export const verifyAndParseRequestBody = (
+  request: HttpServerRequest.HttpServerRequest,
+): Effect.Effect<
+  typeof Protocol.SDKRequestBody.Type,
+  SignatureError | InvalidRequestError,
+  InngestClient | Signature
+> =>
+  Effect.gen(function* () {
+    const client = yield* InngestClient;
+    const sig = yield* Signature;
+    const config = client.config;
+    const isDev = client.mode === "dev";
+
+    const bodyText = yield* request.text.pipe(
+      Effect.mapError((error) => new InvalidRequestError({ message: `Failed to read request body: ${String(error)}` })),
+    );
+
+    yield* sig.verify({
+      body: new TextEncoder().encode(bodyText),
+      signatureHeader: request.headers[Protocol.Headers.Signature.toLowerCase()],
+      signingKey: config.signingKey,
+      signingKeyFallback: config.signingKeyFallback,
+      isDev,
+    });
+
+    return yield* Schema.decodeUnknown(Schema.parseJson(Protocol.SDKRequestBody))(bodyText).pipe(
+      Effect.mapError((error) => new InvalidRequestError({ message: `Invalid request body: ${String(error)}` })),
+    );
+  });
+
+export const handleIntrospection = (
+  group: InngestGroup.Any,
+  _requestUrl: string,
+): Effect.Effect<HandlerResponse<typeof Protocol.IntrospectionResponse.Type>, never, InngestClient> =>
+  Effect.gen(function* () {
+    const client = yield* InngestClient;
+    const config = client.config;
+
+    const body: typeof Protocol.IntrospectionResponse.Type = {
+      function_count: group.functions.size,
+      has_event_key: config.eventKey !== undefined,
+      has_signing_key: config.signingKey !== undefined,
+      has_signing_key_fallback: config.signingKeyFallback !== undefined,
+      mode: client.mode === "dev" ? "dev" : "cloud",
+      schema_version: "2024-05-24",
+      authentication_succeeded: null,
+    };
+
+    return { status: 200, headers: baseHeaders(), body };
+  });
+
+const RegisterRequest = Schema.Struct({
+  url: Schema.String,
+  v: Schema.String,
+  deployType: Schema.Literal("ping"),
+  sdk: Schema.String,
+  appName: Schema.String,
+  framework: Schema.String,
+  functions: Schema.Array(Schema.Unknown),
+});
+
+export const handleRegistration = (
+  group: InngestGroup.Any,
+  requestUrl: string,
+): Effect.Effect<
+  HandlerResponse<typeof Protocol.RegisterResponse.Type>,
+  never,
+  InngestClient | HttpClient.HttpClient
+> =>
+  Effect.gen(function* () {
+    const client = yield* InngestClient;
+    const httpClient = yield* HttpClient.HttpClient;
+    const config = client.config;
+    const url = buildServeUrl(requestUrl, config.serveHost, config.servePath);
+
+    const functions = Array.from(group.functions.values()).map((fn) =>
+      fn.toRegistration({ appId: config.id, url: url.href }),
+    );
+
+    const registerUrl = new URL("fn/register", client.apiBaseUrl).toString();
+    const request = HttpClientRequest.post(registerUrl).pipe(
+      HttpClientRequest.setHeaders({
+        ...baseHeaders(),
+        Authorization: `Bearer ${config.signingKey ?? ""}`,
+      }),
+      HttpClientRequest.schemaBodyJson(RegisterRequest)({
+        url: url.href,
+        v: "0.1",
+        deployType: "ping" as const,
+        sdk: `effect-inngest:v${SDK_VERSION}`,
+        appName: config.id,
+        framework: "effect",
+        functions,
+      }),
+    );
+
+    const response = yield* request.pipe(
+      Effect.flatMap(httpClient.execute),
+      Effect.flatMap(HttpClientResponse.schemaBodyJson(Protocol.RegisterResponse)),
+      Effect.scoped,
+      Effect.catchAll((error) =>
+        Effect.succeed({
+          message: `Registration failed: ${Predicate.hasProperty(error, "message") ? (error.message as string) : "Unknown error"}`,
+        }),
+      ),
+    );
+
+    return {
+      status: 200,
+      headers: baseHeaders(),
+      body: response,
+    };
+  });
+
+export interface Handler<Tag extends string> {
+  readonly tag: Tag;
+  readonly handler: (ctx: any) => Effect.Effect<any, any, any>;
+  readonly context: Context.Context<any>;
+}
+
+export const handleExecution = (
+  group: InngestGroup.Any,
+  fnId: string,
+  urlStepId: string | undefined,
+  body: typeof Protocol.SDKRequestBody.Type,
+  traceHeaders: TraceHeaders = {},
+): Effect.Effect<HandlerResponse<unknown>, never, InngestClient> =>
+  Effect.gen(function* () {
+    const client = yield* InngestClient;
+    const context = yield* Effect.context<never>();
+
+    const appId = client.config.id;
+    const prefix = `${appId}-`;
+    const fnTag = fnId.startsWith(prefix) ? fnId.slice(prefix.length) : fnId;
+
+    const fn = group.functions.get(fnTag) as InngestFunction.Any | undefined;
+    const entry = fn ? (context.unsafeMap.get(fn.key) as Handler<string> | undefined) : undefined;
+
+    if (!fn || !entry) {
+      return {
+        status: 404 as const,
+        headers: { ...baseHeaders(), [Protocol.Headers.NoRetry]: "true" },
+        body: {
+          error: Protocol.UserError.make({ name: "FunctionNotFoundError", message: `Unknown function: ${fnId}` }),
+        },
+      };
+    }
+
+    // URL stepId takes precedence over body.ctx.step_id
+    // This is how Inngest requests execution of a specific step
+    const effectiveBody =
+      urlStepId && urlStepId !== body.ctx.step_id
+        ? Protocol.SDKRequestBody.make({
+            event: body.event,
+            events: body.events,
+            steps: body.steps,
+            ctx: Protocol.SDKRequestContext.make({
+              fn_id: body.ctx.fn_id,
+              run_id: body.ctx.run_id,
+              step_id: urlStepId,
+              attempt: body.ctx.attempt,
+              disable_immediate_execution: body.ctx.disable_immediate_execution,
+              use_api: body.ctx.use_api,
+              stack: body.ctx.stack,
+            }),
+            use_api: body.use_api,
+          })
+        : body;
+
+    const result = yield* Effect.provide(execute(fn, entry.handler, effectiveBody, appId, traceHeaders), entry.context);
+    return { status: result.status, headers: result.headers, body: result.body };
+  });

package/src/internal/helpers.ts

@@ -0,0 +1,58 @@
+/**
+ * Internal helper utilities.
+ * @internal
+ */
+import * as Duration from "effect/Duration";
+
+const millisecond = 1;
+const second = millisecond * 1000;
+const minute = second * 60;
+const hour = minute * 60;
+const day = hour * 24;
+const week = day * 7;
+
+const periods = [
+  ["w", week],
+  ["d", day],
+  ["h", hour],
+  ["m", minute],
+  ["s", second],
+] as const;
+
+/**
+ * Convert a Duration to an Inngest-compatible time string (e.g. `"1d"` or `"2h30m"`).
+ *
+ * Supports weeks, days, hours, minutes, and seconds. Years/months are converted
+ * to their equivalent in weeks/days.
+ */
+export const timeStr = (input: Duration.DurationInput): string => {
+  let ms = Duration.toMillis(Duration.decode(input));
+
+  const [, result] = periods.reduce<[number, string]>(
+    ([num, str], [suffix, period]) => {
+      const numPeriods = Math.floor(num / period);
+
+      if (numPeriods > 0) {
+        return [num % period, `${str}${numPeriods}${suffix}`];
+      }
+
+      return [num, str];
+    },
+    [ms, ""],
+  );
+
+  return result || "0s";
+};
+
+/**
+ * Format a timestamp as an ISO string for Inngest's sleepUntil.
+ */
+export const formatTimestamp = (timestamp: Date | number | string): string => {
+  if (timestamp instanceof Date) {
+    return timestamp.toISOString();
+  }
+  if (typeof timestamp === "number") {
+    return new Date(timestamp).toISOString();
+  }
+  return timestamp;
+};

package/src/internal/interrupts.ts

@@ -0,0 +1,62 @@
+/**
+ * StepInterrupt schema and factory functions.
+ * @internal
+ */
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as Protocol from "./protocol.js";
+
+/** @internal */
+export class StepInterrupt extends Schema.TaggedClass<StepInterrupt>()("StepInterrupt", {
+  opcode: Protocol.GeneratorOpcode,
+  retryAfterMs: Schema.optional(Schema.Number),
+}) {}
+
+/** @internal */
+export interface StepInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly hash: string;
+}
+
+const toUserError = (error: unknown): typeof Protocol.UserError.Type =>
+  Protocol.UserError.make({
+    name: Predicate.hasProperty(error, "name") ? String(error.name) : "Error",
+    message: Predicate.hasProperty(error, "message") ? String(error.message) : String(error),
+    stack: Predicate.hasProperty(error, "stack") ? String(error.stack) : undefined,
+  });
+
+/** @internal */
+export const sleepInterrupt = (opts: { info: StepInfo; duration: string }) =>
+  StepInterrupt.make({ opcode: Protocol.sleep(opts.info, opts.duration) });
+
+/** @internal */
+export const waitForEventInterrupt = (opts: { info: StepInfo; event: string; timeout: string; if?: string }) =>
+  StepInterrupt.make({
+    opcode: Protocol.waitForEvent(opts.info, { event: opts.event, timeout: opts.timeout, if: opts.if }),
+  });
+
+/** @internal */
+export const invokeInterrupt = (opts: { info: StepInfo; functionId: string; payload: unknown; timeout: string }) =>
+  StepInterrupt.make({
+    opcode: Protocol.invokeFunction(opts.info, {
+      function_id: opts.functionId,
+      payload: opts.payload,
+      timeout: opts.timeout,
+    }),
+  });
+
+/** @internal */
+export const plannedInterrupt = (opts: { info: StepInfo }) =>
+  StepInterrupt.make({ opcode: Protocol.stepPlanned(opts.info) });
+
+/** @internal */
+export const runInterrupt = (opts: { info: StepInfo; data: unknown }) =>
+  StepInterrupt.make({ opcode: Protocol.stepRun(opts.info, opts.data) });
+
+/** @internal */
+export const errorInterrupt = (opts: { info: StepInfo; error: unknown; noRetry?: boolean; retryAfterMs?: number }) =>
+  StepInterrupt.make({
+    opcode: Protocol.stepError(opts.info, toUserError(opts.error), opts.noRetry),
+    retryAfterMs: opts.retryAfterMs,
+  });