add new core server only export

Author: nicktrn

apps/coordinator/src/checkpointer.ts

@@ -1,5 +1,5 @@
 import { ExponentialBackoff } from "@trigger.dev/core/v3/apps";
-import { testDockerCheckpoint } from "@trigger.dev/core/v3/checkpoints";
+import { testDockerCheckpoint } from "@trigger.dev/core/v3/serverOnly";
 import { nanoid } from "nanoid";
 import fs from "node:fs/promises";
 import { ChaosMonkey } from "./chaosMonkey";

packages/core/package.json

@@ -59,7 +59,7 @@
       "./v3/workers": "./src/v3/workers/index.ts",
       "./v3/schemas": "./src/v3/schemas/index.ts",
       "./v3/runEngineWorker": "./src/v3/runEngineWorker/index.ts",
-      "./v3/checkpoints": "./src/v3/checkpoints/index.ts"
+      "./v3/serverOnly": "./src/v3/serverOnly/index.ts"
     },
     "sourceDialects": [
       "@triggerdotdev/source"
@@ -178,8 +178,8 @@
       "v3/runEngineWorker": [
         "dist/commonjs/v3/runEngineWorker/index.d.ts"
       ],
-      "v3/checkpoints": [
-        "dist/commonjs/v3/checkpoints/index.d.ts"
+      "v3/serverOnly": [
+        "dist/commonjs/v3/serverOnly/index.d.ts"
       ]
     }
   },
@@ -663,15 +663,15 @@
         "default": "./dist/commonjs/v3/runEngineWorker/index.js"
       }
     },
-    "./v3/checkpoints": {
+    "./v3/serverOnly": {
       "import": {
-        "@triggerdotdev/source": "./src/v3/checkpoints/index.ts",
-        "types": "./dist/esm/v3/checkpoints/index.d.ts",
-        "default": "./dist/esm/v3/checkpoints/index.js"
+        "@triggerdotdev/source": "./src/v3/serverOnly/index.ts",
+        "types": "./dist/esm/v3/serverOnly/index.d.ts",
+        "default": "./dist/esm/v3/serverOnly/index.js"
       },
       "require": {
-        "types": "./dist/commonjs/v3/checkpoints/index.d.ts",
-        "default": "./dist/commonjs/v3/checkpoints/index.js"
+        "types": "./dist/commonjs/v3/serverOnly/index.d.ts",
+        "default": "./dist/commonjs/v3/serverOnly/index.js"
       }
     }
   },

packages/core/src/v3/checkpoints/index.ts

@@ -0,0 +1,58 @@
+import { CheckpointType } from "./runEngine.js";
+import z from "zod";
+
+const CallbackUrl = z
+  .string()
+  .url()
+  .transform((url) => new URL(url));
+
+export const CheckpointServiceSuspendRequestBody = z.object({
+  type: CheckpointType,
+  containerId: z.string(),
+  simulate: z.boolean().optional(),
+  leaveRunning: z.boolean().optional(),
+  reason: z.string().optional(),
+  callbacks: z
+    .object({
+      /** These headers will sent to all callbacks */
+      headers: z.record(z.string()).optional(),
+      /** This will be hit before suspending the container. Suspension will proceed unless we receive an error response. */
+      preSuspend: CallbackUrl.optional(),
+      /** This will be hit after suspending or failure to suspend the container */
+      completion: CallbackUrl.optional(),
+    })
+    .optional(),
+});
+
+export type CheckpointServiceSuspendRequestBody = z.infer<
+  typeof CheckpointServiceSuspendRequestBody
+>;
+export type CheckpointServiceSuspendRequestBodyInput = z.input<
+  typeof CheckpointServiceSuspendRequestBody
+>;
+
+export const CheckpointServiceSuspendResponseBody = z.object({
+  ok: z.literal(true),
+});
+
+export type CheckpointServiceSuspendResponseBody = z.infer<
+  typeof CheckpointServiceSuspendResponseBody
+>;
+
+export const CheckpointServiceRestoreRequestBody = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal(CheckpointType.Enum.DOCKER),
+    containerId: z.string(),
+  }),
+  z.object({
+    type: z.literal(CheckpointType.Enum.KUBERNETES),
+    containerId: z.string(),
+  }),
+]);
+
+export type CheckpointServiceRestoreRequestBody = z.infer<
+  typeof CheckpointServiceRestoreRequestBody
+>;
+export type CheckpointServiceRestoreRequestBodyInput = z.input<
+  typeof CheckpointServiceRestoreRequestBody
+>;

packages/core/src/v3/schemas/checkpoints.ts

@@ -12,3 +12,4 @@ export * from "./config.js";
 export * from "./build.js";
 export * from "./runEngine.js";
 export * from "./webhooks.js";
+export * from "./checkpoints.js";

packages/core/src/v3/schemas/index.ts

@@ -0,0 +1,137 @@
+import { SupervisorHttpClient } from "../runEngineWorker/index.js";
+import {
+  CheckpointServiceSuspendRequestBodyInput,
+  CheckpointServiceSuspendResponseBody,
+  CheckpointServiceRestoreRequestBodyInput,
+} from "../schemas/checkpoints.js";
+import { DequeuedMessage } from "../schemas/runEngine.js";
+import { SimpleStructuredLogger } from "../utils/structuredLogger.js";
+
+export type CheckpointClientOptions = {
+  apiUrl: URL;
+  workerClient: SupervisorHttpClient;
+};
+
+export class CheckpointClient {
+  private readonly logger = new SimpleStructuredLogger("checkpoint-client");
+  private readonly apiUrl: URL;
+  private readonly workerClient: SupervisorHttpClient;
+
+  private get restoreUrl() {
+    return new URL("/api/v1/restore", this.apiUrl);
+  }
+
+  private get suspendUrl() {
+    return new URL("/api/v1/suspend", this.apiUrl);
+  }
+
+  constructor(opts: CheckpointClientOptions) {
+    this.apiUrl = opts.apiUrl;
+    this.workerClient = opts.workerClient;
+  }
+
+  async suspendRun({
+    runFriendlyId,
+    snapshotFriendlyId,
+    containerId,
+    runnerId,
+  }: {
+    runFriendlyId: string;
+    snapshotFriendlyId: string;
+    containerId: string;
+    runnerId: string;
+  }): Promise<boolean> {
+    const completionUrl = this.workerClient.getSuspendCompletionUrl(
+      runFriendlyId,
+      snapshotFriendlyId,
+      runnerId
+    );
+
+    const res = await fetch(this.suspendUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        type: "DOCKER",
+        containerId,
+        callbacks: {
+          completion: completionUrl.url,
+          headers: completionUrl.headers,
+        },
+      } satisfies CheckpointServiceSuspendRequestBodyInput),
+    });
+
+    if (!res.ok) {
+      this.logger.error("[CheckpointClient] Suspend request failed", {
+        runFriendlyId,
+        snapshotFriendlyId,
+        containerId,
+      });
+      return false;
+    }
+
+    this.logger.debug("[CheckpointClient] Suspend request success", {
+      runFriendlyId,
+      snapshotFriendlyId,
+      containerId,
+      status: res.status,
+      contentType: res.headers.get("content-type"),
+    });
+
+    try {
+      const data = await res.json();
+      const parsedData = CheckpointServiceSuspendResponseBody.safeParse(data);
+
+      if (!parsedData.success) {
+        this.logger.error("[CheckpointClient] Suspend response invalid", {
+          runFriendlyId,
+          snapshotFriendlyId,
+          containerId,
+          data,
+        });
+        return false;
+      }
+    } catch (error) {
+      this.logger.error("[CheckpointClient] Suspend response error", {
+        error,
+        text: await res.text(),
+      });
+      return false;
+    }
+
+    return true;
+  }
+
+  async restoreRun({
+    runFriendlyId,
+    snapshotFriendlyId,
+    checkpoint,
+  }: {
+    runFriendlyId: string;
+    snapshotFriendlyId: string;
+    checkpoint: NonNullable<DequeuedMessage["checkpoint"]>;
+  }): Promise<boolean> {
+    const res = await fetch(this.restoreUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        type: "DOCKER",
+        containerId: checkpoint.location,
+      } satisfies CheckpointServiceRestoreRequestBodyInput),
+    });
+
+    if (!res.ok) {
+      this.logger.error("[CheckpointClient] Restore request failed", {
+        runFriendlyId,
+        snapshotFriendlyId,
+        checkpoint,
+      });
+      return false;
+    }
+
+    return true;
+  }
+}