effect-inngest 0.1.0

package/src/internal/memo.ts

@@ -0,0 +1,73 @@
+/**
+ * Step memoization schemas for decoding cached step results.
+ * @internal
+ */
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+
+// 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);
+
+// Output schemas (tagged structs)
+const MemoDataSchema = Schema.TaggedStruct("MemoData", { data: Schema.Unknown });
+const MemoErrorSchema = Schema.TaggedStruct("MemoError", { error: Schema.Unknown });
+const MemoInputSchema = Schema.TaggedStruct("MemoInput", { input: Schema.Unknown });
+const MemoTimeoutSchema = Schema.TaggedStruct("MemoTimeout", {});
+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 }),
+  }),
+);
+
+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 }),
+  }),
+);
+
+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 }),
+  }),
+);
+
+const TimeoutWire = Schema.transform(Schema.Null, MemoTimeoutSchema, {
+  decode: () => ({ _tag: "MemoTimeout" as const }),
+  encode: () => null,
+});
+
+const NoneWire = Schema.transform(Schema.Undefined, MemoNoneSchema, {
+  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);
+
+// Derived type (only union is needed externally - Match.tag uses string literals)
+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();
+};

package/src/internal/protocol.ts

@@ -0,0 +1,218 @@
+/**
+ * Wire protocol schemas and opcode factories for Inngest communication.
+ * @internal
+ */
+import { Predicate, Struct } from "effect";
+import * as Schema from "effect/Schema";
+
+const stripTags = (value: unknown): unknown => {
+  if (Predicate.isRecord(value)) {
+    const stripped = Struct.omit(value as Record<string, unknown>, "_tag");
+    return Object.fromEntries(Object.entries(stripped).map(([k, v]) => [k, stripTags(v)]));
+  }
+  if (Array.isArray(value)) {
+    return value.map(stripTags);
+  }
+  return value;
+};
+
+const WireUnknown = Schema.transform(Schema.Unknown, Schema.Unknown, {
+  strict: true,
+  decode: (value) => value,
+  encode: (value) => stripTags(value),
+});
+
+export const Opcode = {
+  None: "None",
+  Step: "Step",
+  StepRun: "StepRun",
+  StepError: "StepError",
+  StepPlanned: "StepPlanned",
+  Sleep: "Sleep",
+  WaitForEvent: "WaitForEvent",
+  InvokeFunction: "InvokeFunction",
+  AIGateway: "AIGateway",
+  Gateway: "Gateway",
+  WaitForSignal: "WaitForSignal",
+  RunComplete: "RunComplete",
+  StepFailed: "StepFailed",
+  SyncRunComplete: "SyncRunComplete",
+  DiscoveryRequest: "DiscoveryRequest",
+} as const;
+
+type OpcodeValue = (typeof Opcode)[keyof typeof Opcode];
+
+export class UserError extends Schema.Class<UserError>("UserError")({
+  name: Schema.String,
+  message: Schema.String,
+  stack: Schema.optional(Schema.String),
+  data: Schema.optional(Schema.Unknown),
+  noRetry: Schema.optional(Schema.Boolean),
+  cause: Schema.optional(Schema.Unknown),
+}) {}
+
+export const StepResult = Schema.NullOr(
+  Schema.Record({ key: Schema.String, value: Schema.Unknown }).pipe(
+    Schema.annotations({ identifier: "StepResultObject" }),
+  ),
+);
+
+export class FunctionStack extends Schema.Class<FunctionStack>("FunctionStack")({
+  stack: Schema.Array(Schema.String),
+  current: Schema.Number,
+}) {}
+
+export class InngestEvent extends Schema.Class<InngestEvent>("InngestEvent")({
+  id: Schema.optional(Schema.String),
+  name: Schema.String,
+  data: Schema.optionalWith(Schema.Record({ key: Schema.String, value: Schema.Unknown }), {
+    default: () => ({}),
+    nullable: true,
+  }),
+
+  ts: Schema.optional(Schema.Number),
+  user: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  v: Schema.optional(Schema.String),
+}) {}
+
+export class SDKRequestContext extends Schema.Class<SDKRequestContext>("SDKRequestContext")({
+  fn_id: Schema.String,
+  run_id: Schema.String,
+  env: Schema.optionalWith(Schema.String, { default: () => "dev" }),
+  step_id: Schema.optionalWith(Schema.String, { default: () => "step" }),
+  attempt: Schema.optionalWith(Schema.Number, { default: () => 0 }),
+  max_attempts: Schema.optionalWith(Schema.Number, { default: () => 4 }),
+  stack: Schema.optionalWith(FunctionStack, { default: () => FunctionStack.make({ stack: [], current: 0 }) }),
+  qi_id: Schema.optionalWith(Schema.String, { default: () => "" }),
+  disable_immediate_execution: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  use_api: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+}) {}
+
+export class SDKRequestBody extends Schema.Class<SDKRequestBody>("SDKRequestBody")({
+  event: InngestEvent,
+  events: Schema.Array(InngestEvent),
+  steps: Schema.optionalWith(Schema.Record({ key: Schema.String, value: StepResult }), { default: () => ({}) }),
+  ctx: SDKRequestContext,
+  version: Schema.optionalWith(Schema.Number, { default: () => 1 }),
+  use_api: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+}) {}
+
+export const Headers = {
+  SDK: "X-Inngest-SDK",
+  Signature: "X-Inngest-Signature",
+  RequestVersion: "x-inngest-req-version",
+  NoRetry: "X-Inngest-No-Retry",
+  RetryAfter: "Retry-After",
+  ServerKind: "X-Inngest-Server-Kind",
+  ExpectedServerKind: "X-Inngest-Expected-Server-Kind",
+  RunID: "X-Run-ID",
+  Framework: "X-Inngest-Framework",
+  Platform: "X-Inngest-Platform",
+  Env: "X-Inngest-Env",
+} as const;
+
+export class GeneratorOpcode extends Schema.Class<GeneratorOpcode>("GeneratorOpcode")({
+  op: Schema.Literal(
+    Opcode.None,
+    Opcode.Step,
+    Opcode.StepRun,
+    Opcode.StepError,
+    Opcode.StepPlanned,
+    Opcode.Sleep,
+    Opcode.WaitForEvent,
+    Opcode.InvokeFunction,
+    Opcode.AIGateway,
+    Opcode.Gateway,
+    Opcode.WaitForSignal,
+    Opcode.RunComplete,
+    Opcode.StepFailed,
+    Opcode.SyncRunComplete,
+    Opcode.DiscoveryRequest,
+  ),
+  id: Schema.String,
+  name: Schema.String,
+  mode: Schema.optional(Schema.Literal("sync", "async")),
+  opts: Schema.optional(WireUnknown),
+  data: Schema.optional(WireUnknown),
+  error: Schema.optional(UserError),
+  displayName: Schema.optional(Schema.String),
+  userland: Schema.optional(Schema.Struct({ id: Schema.String })),
+}) {}
+
+interface StepInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly hash: string;
+}
+
+const mkOpcode = (info: StepInfo, op: OpcodeValue, extra?: object): GeneratorOpcode =>
+  GeneratorOpcode.make({ op, id: info.hash, name: info.id, displayName: info.name, ...extra });
+
+export const stepPlanned = (info: StepInfo): GeneratorOpcode => mkOpcode(info, Opcode.StepPlanned);
+
+export const stepRun = (info: StepInfo, data: unknown): GeneratorOpcode => mkOpcode(info, Opcode.StepRun, { data });
+
+export const stepError = (info: StepInfo, error: UserError, noRetry?: boolean): GeneratorOpcode => {
+  // noRetry must be in the error object for Inngest executor to recognize it
+  const errorWithNoRetry =
+    noRetry !== undefined
+      ? UserError.make({ name: error.name, message: error.message, stack: error.stack, noRetry })
+      : error;
+  return mkOpcode(info, Opcode.StepError, { error: errorWithNoRetry });
+};
+
+export const sleep = (info: StepInfo, duration: string): GeneratorOpcode =>
+  // Official SDK puts duration/timestamp in `name` field, not opts.duration
+  // mode: "async" is required per the Op type definition
+  GeneratorOpcode.make({ op: Opcode.Sleep, id: info.hash, name: duration, displayName: info.name, mode: "async" });
+
+export const waitForEvent = (info: StepInfo, opts: { event: string; timeout: string; if?: string }): GeneratorOpcode =>
+  mkOpcode(info, Opcode.WaitForEvent, { mode: "async", opts });
+
+export const invokeFunction = (
+  info: StepInfo,
+  opts: { function_id: string; payload: unknown; timeout: string },
+): GeneratorOpcode => mkOpcode(info, Opcode.InvokeFunction, { mode: "async", opts, userland: { id: info.id } });
+
+const IntrospectionBase = Schema.Struct({
+  function_count: Schema.Number,
+  has_event_key: Schema.Boolean,
+  has_signing_key: Schema.Boolean,
+  has_signing_key_fallback: Schema.Boolean,
+  mode: Schema.Literal("cloud", "dev"),
+  schema_version: Schema.Literal("2024-05-24"),
+  extra: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+});
+
+export const IntrospectionUnauthenticated = Schema.extend(
+  IntrospectionBase,
+  Schema.Struct({
+    authentication_succeeded: Schema.Union(Schema.Literal(false), Schema.Null),
+    functions: Schema.optionalWith(Schema.Array(Schema.Unknown), { exact: true }),
+  }),
+);
+
+export const IntrospectionAuthenticated = Schema.extend(
+  IntrospectionBase,
+  Schema.Struct({
+    authentication_succeeded: Schema.Literal(true),
+    api_origin: Schema.String,
+    app_id: Schema.String,
+    env: Schema.NullOr(Schema.String),
+    event_api_origin: Schema.String,
+    event_key_hash: Schema.NullOr(Schema.String),
+    framework: Schema.String,
+    sdk_language: Schema.String,
+    sdk_version: Schema.String,
+    serve_origin: Schema.NullOr(Schema.String),
+    serve_path: Schema.NullOr(Schema.String),
+    signing_key_fallback_hash: Schema.NullOr(Schema.String),
+    signing_key_hash: Schema.NullOr(Schema.String),
+  }),
+);
+
+export const IntrospectionResponse = Schema.Union(IntrospectionAuthenticated, IntrospectionUnauthenticated);
+
+export const RegisterResponse = Schema.Struct({
+  message: Schema.optional(Schema.String),
+});

package/src/internal/signature.ts

@@ -0,0 +1,158 @@
+/**
+ * Signature verification service for Inngest requests.
+ * @internal
+ */
+import * as Crypto from "node:crypto";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Protocol from "./protocol.js";
+
+/**
+ * @internal
+ */
+export class SignatureError extends Schema.TaggedError<SignatureError>()("SignatureError", {
+  reason: Schema.Literal("missing_header", "invalid_format", "expired", "invalid_signature", "missing_signing_key"),
+  message: Schema.String,
+}) {}
+
+/**
+ * @internal
+ */
+export interface VerifyOptions {
+  readonly body: Uint8Array;
+  readonly signatureHeader: string | undefined;
+  readonly signingKey: string | undefined;
+  readonly signingKeyFallback?: string | undefined;
+  readonly isDev: boolean;
+}
+
+/**
+ * @internal
+ */
+export interface SignatureService {
+  readonly verify: (options: VerifyOptions) => Effect.Effect<boolean, SignatureError>;
+  readonly sign: (body: Uint8Array, signingKey: string) => Effect.Effect<string, SignatureError>;
+}
+
+/**
+ * @internal
+ */
+export class Signature extends Context.Tag("effect-inngest/Signature")<Signature, SignatureService>() {}
+
+// ─────────────────────────────────────────────────────────────
+// Schemas (internal)
+// ─────────────────────────────────────────────────────────────
+
+const TimestampSeconds = Schema.NumberFromString.pipe(Schema.int(), Schema.positive());
+// Case-insensitive hex, normalized to lowercase in parseSignatureHeader
+const SignatureHex = Schema.String.pipe(
+  Schema.pattern(/^[a-fA-F0-9]{64}$/),
+  Schema.transform(Schema.String, {
+    decode: (s) => s.toLowerCase(),
+    encode: (s) => s,
+  }),
+);
+const SignatureParams = Schema.Struct({ t: TimestampSeconds, s: SignatureHex });
+
+// ─────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────
+
+const SIGNATURE_VALIDITY_WINDOW_MS = 5 * 60 * 1000;
+
+const parseSignatureHeader = (header: string) => {
+  const params = new URLSearchParams(header);
+  const raw = { t: params.get("t") ?? "", s: params.get("s") ?? "" };
+  return Schema.decodeUnknown(SignatureParams)(raw).pipe(
+    Effect.mapError(
+      () =>
+        new SignatureError({
+          reason: "invalid_format",
+          message: `Invalid signature format: expected t=<int>&s=<64-hex>, got: ${header}`,
+        }),
+    ),
+  );
+};
+
+const extractKeyBytes = (signingKey: string): Buffer => {
+  const keyWithoutPrefix = signingKey.replace(/^signkey-\w+-/, "");
+  return Buffer.from(keyWithoutPrefix, "hex");
+};
+
+const computeSignature = (keyBytes: Buffer, body: Uint8Array, timestamp: string): string =>
+  Crypto.createHmac("sha256", keyBytes).update(body).update(timestamp).digest("hex");
+
+const timingSafeEqual = (a: string, b: string): boolean => {
+  if (a.length !== b.length) return false;
+  try {
+    return Crypto.timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+  } catch {
+    return false;
+  }
+};
+
+const checkSignature = (signature: string, body: Uint8Array, timestamp: string, signingKey: string): boolean => {
+  const keyBytes = extractKeyBytes(signingKey);
+  const expected = computeSignature(keyBytes, body, timestamp);
+  return timingSafeEqual(signature, expected);
+};
+
+// ─────────────────────────────────────────────────────────────
+// Live Layer
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * @internal
+ */
+export const SignatureLive: Layer.Layer<Signature> = Layer.effect(
+  Signature,
+  Effect.succeed({
+    verify: ({ body, signatureHeader, signingKey, signingKeyFallback, isDev }) =>
+      Effect.gen(function* () {
+        if (isDev) return true;
+        if (!signingKey) {
+          return yield* new SignatureError({
+            reason: "missing_signing_key",
+            message: "No signing key configured for production mode",
+          });
+        }
+
+        if (!signatureHeader) {
+          return yield* new SignatureError({
+            reason: "missing_header",
+            message: `Missing ${Protocol.Headers.Signature} header`,
+          });
+        }
+
+        const { t: timestampSeconds, s: signature } = yield* parseSignatureHeader(signatureHeader);
+        const timestampMs = timestampSeconds * 1000;
+        const now = yield* DateTime.now;
+
+        if (Math.abs(now.epochMillis - timestampMs) > SIGNATURE_VALIDITY_WINDOW_MS) {
+          return yield* new SignatureError({
+            reason: "expired",
+            message: `Signature expired: timestamp ${timestampSeconds} is outside the validity window`,
+          });
+        }
+
+        const timestamp = String(timestampSeconds);
+        const keys = [signingKey, signingKeyFallback].filter(Boolean) as string[];
+        const valid = keys.some((key) => checkSignature(signature, body, timestamp, key));
+
+        if (valid) return true;
+
+        return yield* new SignatureError({ reason: "invalid_signature", message: "Invalid signature" });
+      }),
+
+    sign: (body, signingKey) =>
+      DateTime.now.pipe(
+        Effect.map((now) => {
+          const ts = Math.floor(now.epochMillis / 1000);
+          return `t=${ts}&s=${computeSignature(extractKeyBytes(signingKey), body, String(ts))}`;
+        }),
+      ),
+  }),
+);