feat(tfe-job-agent): webhook-based TFC job agent

.env.compose

@@ -33,5 +33,8 @@ GITHUB_BOT_CLIENT_SECRET=
 GITHUB_BOT_PRIVATE_KEY=
 GITHUB_WEBHOOK_SECRET=
 
+# TFE (optional)
+TFE_WEBHOOK_SECRET= # openssl rand -hex 32
+
 ROUTER_URL=http://workspace-engine-router:9091
 WORKSPACE_ENGINE_URL=http://workspace-engine:9090

apps/api/src/config.ts

@@ -32,6 +32,7 @@ export const env = createEnv({
     GITHUB_BOT_APP_ID: z.string().optional(),
     GITHUB_BOT_PRIVATE_KEY: z.string().optional(),
     GITHUB_WEBHOOK_SECRET: z.string().optional(),
+    TFE_WEBHOOK_SECRET: z.string().optional(),
 
     BASE_URL: z.string().optional(),
 

apps/api/src/routes/tfe/__tests__/run_notification.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { JobStatus } from "@ctrlplane/validators/jobs";
+
+import { mapTriggerToStatus } from "../run_notification.js";
+
+describe("mapTriggerToStatus", () => {
+  it.each([
+    ["run:created", JobStatus.Pending],
+    ["run:planning", JobStatus.InProgress],
+    ["run:needs_attention", JobStatus.ActionRequired],
+    ["run:applying", JobStatus.InProgress],
+    ["run:completed", JobStatus.Successful],
+    ["run:errored", JobStatus.Failure],
+  ])("maps trigger %s to %s", (trigger, expected) => {
+    expect(mapTriggerToStatus(trigger)).toBe(expected);
+  });
+
+  it("returns null for unknown triggers", () => {
+    expect(mapTriggerToStatus("run:unknown")).toBeNull();
+    expect(mapTriggerToStatus("")).toBeNull();
+    expect(mapTriggerToStatus("something:else")).toBeNull();
+  });
+});

apps/api/src/routes/tfe/__tests__/webhook_router.test.ts

@@ -0,0 +1,164 @@
+import crypto from "node:crypto";
+import type { Request, Response } from "express";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// Mock config before importing the module under test
+vi.mock("@/config.js", () => ({
+  env: { TFE_WEBHOOK_SECRET: "test-secret-123" },
+}));
+
+vi.mock("@ctrlplane/logger", () => ({
+  logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn() },
+}));
+
+const mockHandleRunNotification = vi.fn().mockResolvedValue(undefined);
+vi.mock("../run_notification.js", () => ({
+  handleRunNotification: (...args: unknown[]) =>
+    mockHandleRunNotification(...args),
+}));
+
+import { createTfeRouter } from "../index.js";
+
+function signPayload(body: object, secret: string): string {
+  const json = JSON.stringify(body);
+  return crypto.createHmac("sha512", secret).update(json).digest("hex");
+}
+
+function makeMockRes() {
+  const res = { statusCode: 200, _json: null as unknown };
+  return Object.assign(res, {
+    status: (code: number) => {
+      res.statusCode = code;
+      return res;
+    },
+    json: (data: unknown) => {
+      res._json = data;
+      return res;
+    },
+  }) as typeof res & Response;
+}
+
+function getWebhookHandler() {
+  const router = createTfeRouter();
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  const layer = (router as any).stack.find(
+    (l: any) => l.route?.path === "/webhook" && l.route?.methods?.post,
+  );
+  if (!layer) throw new Error("POST /webhook route not found on router");
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  const handlers = layer.route.stack.filter(
+    (s: any) => s.method === "post",
+  );
+  return handlers[handlers.length - 1].handle as (
+    req: Request,
+    res: Response,
+  ) => Promise<void>;
+}
+
+describe("TFE webhook router", () => {
+  let handler: (req: Request, res: Response) => Promise<void>;
+
+  beforeEach(() => {
+    handler = getWebhookHandler();
+    vi.clearAllMocks();
+  });
+
+  const payload = {
+    payload_version: 1,
+    notification_configuration_id: "nc-test",
+    run_url: "https://app.terraform.io/runs/run-abc",
+    run_id: "run-abc",
+    run_message: "test",
+    run_created_at: "2024-01-01T00:00:00Z",
+    run_created_by: "user",
+    workspace_id: "ws-test",
+    workspace_name: "test-ws",
+    organization_name: "org",
+    notifications: [
+      {
+        message: "Applied",
+        trigger: "run:completed",
+        run_status: "applied",
+        run_updated_at: "2024-01-01T00:01:00Z",
+        run_updated_by: "user",
+      },
+    ],
+  };
+
+  it("returns 200 and calls handler with valid signature", async () => {
+    const signature = signPayload(payload, "test-secret-123");
+    const req = {
+      headers: { "x-tfe-notification-signature": signature },
+      body: payload,
+    } as unknown as Request;
+    const res = makeMockRes();
+
+    await handler(req, res);
+
+    expect(res.statusCode).toBe(200);
+    expect((res as any)._json).toEqual({ message: "OK" });
+    expect(mockHandleRunNotification).toHaveBeenCalledOnce();
+    expect(mockHandleRunNotification).toHaveBeenCalledWith(payload);
+  });
+
+  it("returns 401 with missing signature header", async () => {
+    const req = {
+      headers: {},
+      body: payload,
+    } as unknown as Request;
+    const res = makeMockRes();
+
+    await handler(req, res);
+
+    expect(res.statusCode).toBe(401);
+    expect((res as any)._json).toEqual({ message: "Unauthorized" });
+    expect(mockHandleRunNotification).not.toHaveBeenCalled();
+  });
+
+  it("returns 401 with wrong signature", async () => {
+    const req = {
+      headers: {
+        "x-tfe-notification-signature": "deadbeef".repeat(16),
+      },
+      body: payload,
+    } as unknown as Request;
+    const res = makeMockRes();
+
+    await handler(req, res);
+
+    expect(res.statusCode).toBe(401);
+    expect(mockHandleRunNotification).not.toHaveBeenCalled();
+  });
+
+  it("returns 200 without calling handler when notifications is empty", async () => {
+    const emptyPayload = { ...payload, notifications: [] };
+    const signature = signPayload(emptyPayload, "test-secret-123");
+    const req = {
+      headers: { "x-tfe-notification-signature": signature },
+      body: emptyPayload,
+    } as unknown as Request;
+    const res = makeMockRes();
+
+    await handler(req, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(mockHandleRunNotification).not.toHaveBeenCalled();
+  });
+
+  it("returns 500 when handler throws", async () => {
+    mockHandleRunNotification.mockRejectedValueOnce(
+      new Error("db connection lost"),
+    );
+    const signature = signPayload(payload, "test-secret-123");
+    const req = {
+      headers: { "x-tfe-notification-signature": signature },
+      body: payload,
+    } as unknown as Request;
+    const res = makeMockRes();
+
+    await handler(req, res);
+
+    expect(res.statusCode).toBe(500);
+    expect((res as any)._json).toEqual({ message: "db connection lost" });
+  });
+});

apps/api/src/routes/tfe/index.ts

@@ -0,0 +1,49 @@
+import type { Request, Response } from "express";
+import crypto from "node:crypto";
+import { env } from "@/config.js";
+import { Router } from "express";
+
+import { logger } from "@ctrlplane/logger";
+
+import { handleRunNotification } from "./run_notification.js";
+
+export const createTfeRouter = (): Router =>
+  Router().post("/webhook", handleWebhookRequest);
+
+const verifySignature = (req: Request): boolean => {
+  const secret = env.TFE_WEBHOOK_SECRET;
+  if (secret == null) return false;
+
+  const signature = req.headers["x-tfe-notification-signature"]?.toString();
+  if (signature == null) return false;
+
+  const body = JSON.stringify(req.body);
+  const expected = crypto
+    .createHmac("sha512", secret)
+    .update(body)
+    .digest("hex");
+
+  const sigBuf = Buffer.from(signature, "hex");
+  const expBuf = Buffer.from(expected, "hex");
+  if (sigBuf.length !== expBuf.length) return false;
+  return crypto.timingSafeEqual(sigBuf, expBuf);
+};
+
+const handleWebhookRequest = async (req: Request, res: Response) => {
+  try {
+    if (!verifySignature(req)) {
+      res.status(401).json({ message: "Unauthorized" });
+      return;
+    }
+
+    const payload = req.body;
+    if (payload.notifications != null && payload.notifications.length > 0)
+      await handleRunNotification(payload);
+
+    res.status(200).json({ message: "OK" });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(message);
+    res.status(500).json({ message });
+  }
+};

apps/api/src/routes/tfe/run_notification.ts

@@ -0,0 +1,117 @@
+import { eq, sql, takeFirstOrNull } from "@ctrlplane/db";
+import { db } from "@ctrlplane/db/client";
+import { enqueueAllReleaseTargetsDesiredVersion } from "@ctrlplane/db/reconcilers";
+import * as schema from "@ctrlplane/db/schema";
+import { logger } from "@ctrlplane/logger";
+import { ReservedMetadataKey } from "@ctrlplane/validators/conditions";
+import { exitedStatus, JobStatus } from "@ctrlplane/validators/jobs";
+
+/**
+ * TFC notification trigger → ctrlplane job status.
+ * https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/notifications#notification-triggers
+ */
+const triggerStatusMap: Record<string, JobStatus> = {
+  "run:created": JobStatus.Pending,
+  "run:planning": JobStatus.InProgress,
+  "run:needs_attention": JobStatus.ActionRequired,
+  "run:applying": JobStatus.InProgress,
+  "run:completed": JobStatus.Successful,
+  "run:errored": JobStatus.Failure,
+};
+
+export const mapTriggerToStatus = (trigger: string): JobStatus | null =>
+  triggerStatusMap[trigger] ?? null;
+
+const uuidRegex =
+  /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/;
+
+/**
+ * Extract the ctrlplane job ID from the TFC run message.
+ * The dispatcher sets: "Triggered by ctrlplane job <uuid>"
+ */
+const extractJobId = (runMessage: string): string | null => {
+  const match = uuidRegex.exec(runMessage);
+  return match ? match[0] : null;
+};
+
+export const handleRunNotification = async (payload: {
+  run_url: string;
+  run_id: string;
+  run_message: string;
+  workspace_name: string;
+  organization_name: string;
+  notifications: Array<{ message: string; trigger: string }>;
+}) => {
+  if (payload.notifications.length === 0) return;
+
+  const notification = payload.notifications[0]!;
+  const status = mapTriggerToStatus(notification.trigger);
+  if (status == null) {
+    logger.warn("Unknown TFC notification trigger, ignoring", {
+      trigger: notification.trigger,
+    });
+    return;
+  }
+
+  const jobId = extractJobId(payload.run_message);
+  if (jobId == null) return;
+
+  const now = new Date();
+  const isCompleted = exitedStatus.includes(status);
+  const isInProgress = status === JobStatus.InProgress;
+
+  const [updated] = await db
+    .update(schema.job)
+    .set({
+      externalId: payload.run_id,
+      status,
+      updatedAt: now,
+      message: notification.message,
+      ...(isInProgress
+        ? { startedAt: sql`COALESCE(${schema.job.startedAt}, ${now})` }
+        : {}),
+      ...(isCompleted ? { completedAt: now } : {}),
+    })
+    .where(eq(schema.job.id, jobId))
+    .returning();
+
+  if (updated == null) return;
+
+  // Derive workspace URL from run_url (works for both TFC and TFE)
+  const runUrlParts = payload.run_url.split("/runs/");
+  const workspaceUrl = runUrlParts[0] ?? payload.run_url;
+  const links = JSON.stringify({
+    Run: payload.run_url,
+    Workspace: workspaceUrl,
+  });
+  const metadataEntries = [
+    { jobId, key: String(ReservedMetadataKey.Links), value: links },
+    { jobId, key: "run_url", value: payload.run_url },
+  ];
+
+  for (const entry of metadataEntries)
+    await db
+      .insert(schema.jobMetadata)
+      .values(entry)
+      .onConflictDoUpdate({
+        target: [schema.jobMetadata.key, schema.jobMetadata.jobId],
+        set: { value: entry.value },
+      });
+
+  const result = await db
+    .select({ workspaceId: schema.deployment.workspaceId })
+    .from(schema.releaseJob)
+    .innerJoin(
+      schema.release,
+      eq(schema.releaseJob.releaseId, schema.release.id),
+    )
+    .innerJoin(
+      schema.deployment,
+      eq(schema.release.deploymentId, schema.deployment.id),
+    )
+    .where(eq(schema.releaseJob.jobId, jobId))
+    .then(takeFirstOrNull);
+
+  if (result?.workspaceId != null)
+    enqueueAllReleaseTargetsDesiredVersion(db, result.workspaceId);
+};

apps/api/src/server.ts

@@ -17,6 +17,7 @@ import { appRouter, createTRPCContext } from "@ctrlplane/trpc";
 
 import swaggerDocument from "../openapi/openapi.json" with { type: "json" };
 import { createGithubRouter } from "./routes/github/index.js";
+import { createTfeRouter } from "./routes/tfe/index.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -25,7 +26,7 @@ const specFile = join(__dirname, "../openapi/openapi.json");
 const oapiValidatorMiddleware = OpenApiValidator.middleware({
   apiSpec: specFile,
   validateRequests: true,
-  ignorePaths: /\/api\/(auth|trpc|github|ui|healthz)/,
+  ignorePaths: /\/api\/(auth|trpc|github|tfe|ui|healthz)/,
 });
 
 const trpcMiddleware = trpcExpress.createExpressMiddleware({
@@ -79,6 +80,7 @@ const app = express()
   .use("/api/v1", requireAuth)
   .use("/api/v1", createV1Router())
   .use("/api/github", createGithubRouter())
+  .use("/api/tfe", createTfeRouter())
   .use("/api/trpc", trpcMiddleware)
   .use(errorHandler);