effect-inngest 0.1.2 → 0.2.0-beta.0

package/src/internal/handler.ts

@@ -2,24 +2,28 @@
  * 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 Headers from "effect/unstable/http/Headers";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
+import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 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 * as Checkpoint from "./checkpoint.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", {
+export class InvalidRequestError extends Schema.TaggedErrorClass<InvalidRequestError>()("InvalidRequestError", {
   message: Schema.String,
 }) {}
 
@@ -28,7 +32,7 @@ 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",
+  [Protocol.Headers.RequestVersion]: "2",
 });
 
 const buildServeUrl = (requestUrl: string, serveHost?: string, servePath?: string): URL => {
@@ -48,119 +52,140 @@ export interface HandlerResponse<T> {
   readonly body: T;
 }
 
-export const verifyAndParseRequestBody = (
+export const verifyAndParseRequestBody = Effect.fn("effect-inngest/handler/verifyAndParseRequestBody")(function* (
   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)}` })),
-    );
+) {
+  const client = yield* InngestClient;
+  const sig = yield* Signature;
+  const config = client.config;
+  const isDev = client.mode === "dev";
 
-    yield* sig.verify({
-      body: new TextEncoder().encode(bodyText),
-      signatureHeader: request.headers[Protocol.Headers.Signature.toLowerCase()],
-      signingKey: config.signingKey,
-      signingKeyFallback: config.signingKeyFallback,
-      isDev,
-    });
+  const bodyText = yield* request.text.pipe(
+    Effect.mapError((error) => {
+      const msg =
+        Predicate.hasProperty(error, "message") && typeof error.message === "string" ? error.message : "unknown";
+      return new InvalidRequestError({ message: `Failed to read request body: ${msg}` });
+    }),
+  );
 
-    return yield* Schema.decodeUnknown(Schema.parseJson(Protocol.SDKRequestBody))(bodyText).pipe(
-      Effect.mapError((error) => new InvalidRequestError({ message: `Invalid request body: ${String(error)}` })),
-    );
+  yield* sig.verify({
+    body: new TextEncoder().encode(bodyText),
+    signatureHeader: Option.getOrUndefined(Headers.get(request.headers, Protocol.Headers.Signature)),
+    signingKey: config.signingKey,
+    signingKeyFallback: config.signingKeyFallback,
+    isDev,
   });
 
-export const handleIntrospection = (
+  return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Protocol.SDKRequestBody))(bodyText).pipe(
+    Effect.mapError((error) => new InvalidRequestError({ message: `Invalid request body: ${String(error)}` })),
+  );
+});
+
+export const handleIntrospection = Effect.fn("effect-inngest/handler/handleIntrospection")(function* (
   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,
-    };
+) {
+  const client = yield* InngestClient;
+  const config = client.config;
 
-    return { status: 200, headers: baseHeaders(), body };
-  });
+  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,
+  };
 
-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),
+  return { status: 200, headers: baseHeaders(), body } as HandlerResponse<typeof Protocol.IntrospectionResponse.Type>;
 });
 
-export const handleRegistration = (
+export const handleRegistration = Effect.fn("effect-inngest/handler/handleRegistration")(function* (
   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 client = yield* InngestClient;
+  const httpClient = yield* HttpClient.HttpClient;
+  const config = client.config;
+  const url = buildServeUrl(requestUrl, config.serveHost, config.servePath);
 
-    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 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.bodyJsonUnsafe({
+      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"}`,
-        }),
-      ),
+  // Spec §4.3.1: PUT sync responds with `{ message: string; modified: boolean }`.
+  // Spec §4.3.3 / §4.3.4: 500 on failure with `modified: false`; 200 on success
+  // with the executor-supplied `modified` value (or `false` if omitted).
+  return yield* Effect.gen(function* () {
+    const response = yield* httpClient.execute(request).pipe(Effect.scoped);
+    const responseBody = yield* HttpClientResponse.schemaBodyJson(Protocol.RegisterServerResponse)(response).pipe(
+      Effect.catch(() => Effect.succeed({ error: "Unknown registration response" } as const)),
     );
 
+    if (response.status !== 200 || !Predicate.hasProperty(responseBody, "ok")) {
+      return {
+        status: 500,
+        headers: baseHeaders(),
+        body: {
+          message:
+            Predicate.hasProperty(responseBody, "error") && responseBody.error
+              ? responseBody.error
+              : `Registration failed with status ${response.status}`,
+          modified: false,
+        },
+      } as HandlerResponse<typeof Protocol.RegisterResponse.Type>;
+    }
+
     return {
       status: 200,
       headers: baseHeaders(),
-      body: response,
-    };
-  });
+      body: {
+        message: "Successfully synced.",
+        modified: responseBody.modified ?? false,
+      },
+    } as HandlerResponse<typeof Protocol.RegisterResponse.Type>;
+  }).pipe(
+    Effect.catchCause((cause) => {
+      // Network/transport failure (e.g. die from HttpClient mock). Per
+      // §4.3.3 SHOULD return 500 with the body shape; never let the
+      // toWebHandler default 500 wrapper escape.
+      const errorOpt = Cause.findErrorOption(cause);
+      const dieReason = cause.reasons.find(Cause.isDieReason);
+      const message = Option.isSome(errorOpt)
+        ? Predicate.hasProperty(errorOpt.value, "message") && typeof errorOpt.value.message === "string"
+          ? errorOpt.value.message
+          : "Registration failed"
+        : dieReason
+          ? Predicate.hasProperty(dieReason.defect, "message") && typeof dieReason.defect.message === "string"
+            ? dieReason.defect.message
+            : "Registration failed"
+          : "Registration failed";
+      return Effect.succeed({
+        status: 500,
+        headers: baseHeaders(),
+        body: { message, modified: false },
+      } as HandlerResponse<typeof Protocol.RegisterResponse.Type>);
+    }),
+  );
+});
 
 export interface Handler<Tag extends string> {
   readonly tag: Tag;
@@ -168,55 +193,73 @@ export interface Handler<Tag extends string> {
   readonly context: Context.Context<any>;
 }
 
-export const handleExecution = (
+export const handleExecution = Effect.fn("effect-inngest/handler/handleExecution")(function* (
   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 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 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;
+  const fn = group.functions.get(fnTag) as InngestFunction.Any | undefined;
+  const entry = fn ? (context.mapUnsafe.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}` }),
-        },
-      };
-    }
+  if (!fn || !entry) {
+    // Spec §4.4.1: unknown function MUST return 500 with the error payload
+    // at the response root (no { error: ... } envelope).
+    // Spec §4.4.3 pair rule: 500 MUST pair with X-Inngest-No-Retry: false.
+    return {
+      status: 500 as const,
+      headers: { ...baseHeaders(), [Protocol.Headers.NoRetry]: "false" },
+      body: 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 };
-  });
+  // 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,
+            env: body.ctx.env,
+            step_id: urlStepId,
+            attempt: body.ctx.attempt,
+            max_attempts: body.ctx.max_attempts,
+            qi_id: body.ctx.qi_id,
+            disable_immediate_execution: body.ctx.disable_immediate_execution,
+            use_api: body.ctx.use_api,
+            stack: body.ctx.stack,
+          }),
+          version: body.version,
+          use_api: body.use_api,
+        })
+      : body;
+
+  // Checkpoint mode entry decision (spec §10):
+  //   - URL stepId NOT set (we are not running a targeted step)
+  //   - ctx.fn_id present (executor knows the function)
+  //   - ctx.disable_immediate_execution false (executor allowed it)
+  //   - resolved per-fn or per-client config not opted out
+  const enterCheckpoint =
+    !urlStepId && effectiveBody.ctx.fn_id !== "" && !effectiveBody.ctx.disable_immediate_execution;
+  const checkpointConfig = enterCheckpoint
+    ? Option.fromNullishOr(Checkpoint.resolveConfig(fn.options.checkpointing, client.config.checkpointing))
+    : Option.none<Checkpoint.CheckpointConfig>();
+
+  const result = yield* Effect.provide(
+    execute(fn, entry.handler, effectiveBody, appId, traceHeaders, checkpointConfig),
+    entry.context,
+  );
+  return { status: result.status, headers: result.headers, body: result.body } as HandlerResponse<unknown>;
+});

package/src/internal/helpers.ts

@@ -2,6 +2,7 @@
  * Internal helper utilities.
  * @internal
  */
+import * as DateTime from "effect/DateTime";
 import * as Duration from "effect/Duration";
 
 const millisecond = 1;
@@ -17,6 +18,7 @@ const periods = [
   ["h", hour],
   ["m", minute],
   ["s", second],
+  ["ms", millisecond],
 ] as const;
 
 /**
@@ -25,8 +27,8 @@ const periods = [
  * 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));
+export const timeStr = (input: Duration.Input): string => {
+  let ms = Duration.toMillis(Duration.fromInputUnsafe(input));
 
   const [, result] = periods.reduce<[number, string]>(
     ([num, str], [suffix, period]) => {
@@ -46,13 +48,11 @@ export const timeStr = (input: Duration.DurationInput): string => {
 
 /**
  * Format a timestamp as an ISO string for Inngest's sleepUntil.
+ *
+ * String inputs are passed through unchanged (assumed ISO-formatted), matching
+ * the prior contract. Date/number inputs are normalized via DateTime.
  */
 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;
+  if (typeof timestamp === "string") return timestamp;
+  return DateTime.formatIso(DateTime.makeUnsafe(timestamp));
 };

package/src/internal/memo.ts

@@ -2,14 +2,16 @@
  * Step memoization schemas for decoding cached step results.
  * @internal
  */
+import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
 
 // Wire format: require property KEY to exist (not just value to be defined)
 const hasKey =
   (key: string) =>
   (u: unknown): u is Record<string, unknown> =>
-    Predicate.isRecord(u) && Predicate.hasProperty(u, key);
+    Predicate.isObject(u) && Predicate.hasProperty(u, key);
 
 // Output schemas (tagged structs)
 const MemoDataSchema = Schema.TaggedStruct("MemoData", { data: Schema.Unknown });
@@ -20,41 +22,60 @@ const MemoNoneSchema = Schema.TaggedStruct("MemoNone", {});
 
 // Wire schemas with property existence filters + tag attachment
 const DataWire = Schema.Unknown.pipe(
-  Schema.filter(hasKey("data")),
-  Schema.transform(MemoDataSchema, {
-    decode: (v) => ({ _tag: "MemoData" as const, data: (v as Record<string, unknown>).data }),
-    encode: ({ data }) => ({ data }),
-  }),
+  Schema.check(Schema.makeFilter(hasKey("data"))),
+  Schema.decodeTo(
+    MemoDataSchema,
+    SchemaTransformation.transform({
+      decode: (v) => ({ _tag: "MemoData" as const, data: (v as Record<string, unknown>).data }),
+      encode: ({ data }) => ({ data }),
+    }),
+  ),
 );
 
 const ErrorWire = Schema.Unknown.pipe(
-  Schema.filter(hasKey("error")),
-  Schema.transform(MemoErrorSchema, {
-    decode: (v) => ({ _tag: "MemoError" as const, error: (v as Record<string, unknown>).error }),
-    encode: ({ error }) => ({ error }),
-  }),
+  Schema.check(Schema.makeFilter(hasKey("error"))),
+  Schema.decodeTo(
+    MemoErrorSchema,
+    SchemaTransformation.transform({
+      decode: (v) => ({ _tag: "MemoError" as const, error: (v as Record<string, unknown>).error }),
+      encode: ({ error }) => ({ error }),
+    }),
+  ),
 );
 
 const InputWire = Schema.Unknown.pipe(
-  Schema.filter(hasKey("input")),
-  Schema.transform(MemoInputSchema, {
-    decode: (v) => ({ _tag: "MemoInput" as const, input: (v as Record<string, unknown>).input }),
-    encode: ({ input }) => ({ input }),
-  }),
+  Schema.check(Schema.makeFilter(hasKey("input"))),
+  Schema.decodeTo(
+    MemoInputSchema,
+    SchemaTransformation.transform({
+      decode: (v) => ({ _tag: "MemoInput" as const, input: (v as Record<string, unknown>).input }),
+      encode: ({ input }) => ({ input }),
+    }),
+  ),
 );
 
-const TimeoutWire = Schema.transform(Schema.Null, MemoTimeoutSchema, {
-  decode: () => ({ _tag: "MemoTimeout" as const }),
-  encode: () => null,
-});
+const TimeoutWire = Schema.Null.pipe(
+  Schema.decodeTo(
+    MemoTimeoutSchema,
+    SchemaTransformation.transform({
+      decode: () => ({ _tag: "MemoTimeout" as const }),
+      encode: () => null,
+    }),
+  ),
+);
 
-const NoneWire = Schema.transform(Schema.Undefined, MemoNoneSchema, {
-  decode: () => ({ _tag: "MemoNone" as const }),
-  encode: () => undefined,
-});
+const NoneWire = Schema.Undefined.pipe(
+  Schema.decodeTo(
+    MemoNoneSchema,
+    SchemaTransformation.transform({
+      decode: () => ({ _tag: "MemoNone" as const }),
+      encode: () => undefined,
+    }),
+  ),
+);
 
 // Union order matters: error > input > data (more specific first)
-const MemoSchema = Schema.Union(ErrorWire, InputWire, DataWire, TimeoutWire, NoneWire);
+const MemoSchema = Schema.Union([ErrorWire, InputWire, DataWire, TimeoutWire, NoneWire]);
 
 // Derived type (only union is needed externally - Match.tag uses string literals)
 export type Memo = Schema.Schema.Type<typeof MemoSchema>;
@@ -63,11 +84,5 @@ export type Memo = Schema.Schema.Type<typeof MemoSchema>;
  * Decode a step result into a Memo type.
  * Order matters: error > input > data (more specific properties first).
  */
-export const decodeMemo = (value: unknown): Memo => {
-  const result = Schema.decodeUnknownOption(MemoSchema)(value);
-  if (result._tag === "Some") {
-    return result.value;
-  }
-
-  return MemoNoneSchema.make();
-};
+export const decodeMemo = (value: unknown): Memo =>
+  Option.getOrElse(Schema.decodeUnknownOption(MemoSchema)(value), () => MemoNoneSchema.make({}));