refactor(webapp): extract synthetic buffered-run response builders + drop scaffolding GET on attempts

d-cs · claude · d-cs · commit 6a81f132b4c4 · 2026-05-28T12:39:18.000+01:00
Two related cleanups on the mollifier read surface:

1. Extract the buffered-run response bodies for the spans-detail and
   trace endpoints into pure helpers
   (apps/webapp/app/v3/mollifier/syntheticApiResponses.server.ts:
   buildSyntheticSpanDetailBody, buildSyntheticTraceBody). The route
   bodies were carrying the only copy of the terminal-state derivation
   (CANCELED / FAILED → isError / isPartial / isCancelled) with no unit
   coverage; extracting them lets us pin the contract directly. The
   route files now just authenticate, resolve, validate the spanId, and
   forward — no body shape logic in routes.

2. Drop the GET loader on api.v1.runs.\$runParam.attempts.ts. It was
   added in this PR solely to fix a pre-existing Remix "no loader" 400
   on a URL no SDK consumer was actually calling, and to give the
   mollifier-parity script a stable assertion target. The detailed
   attempt list lives on the v3 retrieve endpoint — the GET was
   scaffolding rather than product surface, and Devin's review flagged
   it as such. Reverted to action-only.

Tests: 16 cases in apps/webapp/test/mollifierSyntheticApiResponses.test.ts
covering QUEUED / CANCELED / FAILED for each body, plus identity and
default-field passthrough. Pins the FAILED-terminal-state regression that
shipped briefly with isPartial:true.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/apps/webapp/app/routes/api.v1.runs.$runId.spans.$spanId.ts b/apps/webapp/app/routes/api.v1.runs.$runId.spans.$spanId.ts
@@ -10,6 +10,7 @@ import {
 import { getEventRepositoryForStore } from "~/v3/eventRepository/index.server";
 import { getTaskEventStoreTableForRun } from "~/v3/taskEventStore.server";
 import { findRunByIdWithMollifierFallback } from "~/v3/mollifier/readFallback.server";
+import { buildSyntheticSpanDetailBody } from "~/v3/mollifier/syntheticApiResponses.server";
 
 const ParamsSchema = z.object({
   runId: z.string(),
@@ -89,26 +90,7 @@ export const loader = createLoaderApiRoute(
       if (resolved.run.spanId !== params.spanId) {
         return json({ error: "Span not found" }, { status: 404 });
       }
-      // CANCELED and FAILED are terminal states. A FAILED buffered run is
-      // errored (drainer exhausted retries or gate rejected it) and must
-      // not signal "still in progress" — mirrors syntheticTrace.server.ts.
-      const isCancelled = resolved.run.status === "CANCELED";
-      const isFailed = resolved.run.status === "FAILED";
-      return json(
-        {
-          spanId: resolved.run.spanId,
-          parentId: resolved.run.parentSpanId ?? null,
-          runId: resolved.run.friendlyId,
-          message: resolved.run.taskIdentifier ?? "",
-          isError: isFailed,
-          isPartial: !isCancelled && !isFailed,
-          isCancelled,
-          level: "TRACE",
-          startTime: resolved.run.createdAt,
-          durationMs: 0,
-        },
-        { status: 200 }
-      );
+      return json(buildSyntheticSpanDetailBody(resolved.run), { status: 200 });
     }
 
     const run = resolved.run;
diff --git a/apps/webapp/app/routes/api.v1.runs.$runId.trace.ts b/apps/webapp/app/routes/api.v1.runs.$runId.trace.ts
@@ -9,6 +9,7 @@ import {
 import { getEventRepositoryForStore } from "~/v3/eventRepository/index.server";
 import { getTaskEventStoreTableForRun } from "~/v3/taskEventStore.server";
 import { findRunByIdWithMollifierFallback } from "~/v3/mollifier/readFallback.server";
+import { buildSyntheticTraceBody } from "~/v3/mollifier/syntheticApiResponses.server";
 
 const ParamsSchema = z.object({
   runId: z.string(), // This is the run friendly ID
@@ -81,40 +82,10 @@ export const loader = createLoaderApiRoute(
     if (resolved.source === "buffer") {
       // Buffered runs have no events ingested yet — the drainer hasn't
       // materialised the PG row and the worker hasn't started executing.
-      // Synthesise a single partial span that satisfies the SDK's
-      // RetrieveRunTraceResponseBody schema (rootSpan is non-nullable).
-      const buffered = resolved.run;
-      return json(
-        {
-          trace: {
-            traceId: buffered.traceId ?? "",
-            rootSpan: {
-              id: buffered.spanId ?? "",
-              runId: buffered.friendlyId,
-              data: {
-                message: buffered.taskIdentifier ?? "",
-                taskSlug: buffered.taskIdentifier ?? undefined,
-                events: [],
-                startTime: buffered.createdAt,
-                duration: 0,
-                isError: buffered.status === "FAILED",
-                // CANCELED and FAILED are terminal states — the span
-                // shouldn't signal "still in progress" once the run has
-                // reached either. Mirrors the sibling
-                // api.v1.runs.$runId.spans.$spanId.ts and
-                // syntheticTrace.server.ts logic.
-                isPartial: buffered.status !== "CANCELED" && buffered.status !== "FAILED",
-                isCancelled: buffered.status === "CANCELED",
-                level: "TRACE",
-                queueName: buffered.queue ?? undefined,
-                machinePreset: buffered.machinePreset ?? undefined,
-              },
-              children: [],
-            },
-          },
-        },
-        { status: 200 }
-      );
+      // The helper synthesises a single root span that satisfies the SDK's
+      // RetrieveRunTraceResponseBody schema (rootSpan is non-nullable) and
+      // reflects the buffered terminal state.
+      return json(buildSyntheticTraceBody(resolved.run), { status: 200 });
     }
 
     const run = resolved.run;
diff --git a/apps/webapp/app/routes/api.v1.runs.$runParam.attempts.ts b/apps/webapp/app/routes/api.v1.runs.$runParam.attempts.ts
@@ -1,15 +1,8 @@
 import type { ActionFunctionArgs } from "@remix-run/server-runtime";
 import { json } from "@remix-run/server-runtime";
-import { BatchId } from "@trigger.dev/core/v3/isomorphic";
 import { z } from "zod";
-import { $replica } from "~/db.server";
 import { authenticateApiRequest } from "~/services/apiAuth.server";
 import { logger } from "~/services/logger.server";
-import {
-  anyResource,
-  createLoaderApiRoute,
-} from "~/services/routeBuilders/apiBuilder.server";
-import { findRunByIdWithMollifierFallback } from "~/v3/mollifier/readFallback.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { CreateTaskRunAttemptService } from "~/v3/services/createTaskRunAttempt.server";
 
@@ -18,87 +11,6 @@ const ParamsSchema = z.object({
   runParam: z.string(),
 });
 
-// GET handler added to fix the pre-existing route bug where this URL
-// returned a Remix "no loader" 400 with an internal error message — only
-// `action` (POST creates a new attempt) was exported, so any
-// well-intentioned SDK probe hit the framework error instead of a proper
-// API response.
-//
-// Returns `{ attempts: [] }` for both PG and buffered runs. The detailed
-// attempt list belongs on the v3 retrieve endpoint, not here — this is
-// the dual of the POST that creates attempts, and the empty-list shape
-// gives the parity script a stable contract to assert against.
-//
-// Built with createLoaderApiRoute so it matches the sibling read routes
-// (spans, trace, retrieve): it accepts JWTs (`allowJWT`) with the same
-// run/task/tag/batch resource scoping, and a not-found run returns 404
-// with `x-should-retry: true` (`shouldRetryNotFound`) so SDK pollers keep
-// retrying a run that the drainer hasn't materialised yet. PG-first then
-// buffer fallback, so a third party can't distinguish "exists" from
-// "doesn't exist" cross-environment.
-type ResolvedRun =
-  | { source: "pg"; run: NonNullable<Awaited<ReturnType<typeof findPgRun>>> }
-  | { source: "buffer"; run: NonNullable<Awaited<ReturnType<typeof findRunByIdWithMollifierFallback>>> };
-
-async function findPgRun(runId: string, environmentId: string) {
-  return $replica.taskRun.findFirst({
-    where: { friendlyId: runId, runtimeEnvironmentId: environmentId },
-    select: { friendlyId: true, taskIdentifier: true, runTags: true, batchId: true },
-  });
-}
-
-export const loader = createLoaderApiRoute(
-  {
-    params: ParamsSchema,
-    allowJWT: true,
-    corsStrategy: "all",
-    findResource: async (params, auth): Promise<ResolvedRun | null> => {
-      const pgRun = await findPgRun(params.runParam, auth.environment.id);
-      if (pgRun) return { source: "pg", run: pgRun };
-
-      const buffered = await findRunByIdWithMollifierFallback({
-        runId: params.runParam,
-        environmentId: auth.environment.id,
-        organizationId: auth.environment.organizationId,
-      });
-      if (buffered) return { source: "buffer", run: buffered };
-
-      return null;
-    },
-    shouldRetryNotFound: true,
-    authorization: {
-      action: "read",
-      resource: (resolved) => {
-        if (resolved.source === "pg") {
-          const run = resolved.run;
-          const resources = [
-            { type: "runs", id: run.friendlyId },
-            { type: "tasks", id: run.taskIdentifier },
-            ...run.runTags.map((tag) => ({ type: "tags", id: tag })),
-          ];
-          if (run.batchId) {
-            resources.push({ type: "batch", id: BatchId.toFriendlyId(run.batchId) });
-          }
-          return anyResource(resources);
-        }
-        const run = resolved.run;
-        const resources = [
-          { type: "runs", id: run.friendlyId },
-          ...(run.taskIdentifier ? [{ type: "tasks", id: run.taskIdentifier }] : []),
-          ...run.tags.map((tag) => ({ type: "tags", id: tag })),
-        ];
-        if (run.batchId) {
-          resources.push({ type: "batch", id: BatchId.toFriendlyId(run.batchId) });
-        }
-        return anyResource(resources);
-      },
-    },
-  },
-  async () => {
-    return json({ attempts: [] }, { status: 200 });
-  }
-);
-
 export async function action({ request, params }: ActionFunctionArgs) {
   // Authenticate the request
   const authenticationResult = await authenticateApiRequest(request);
diff --git a/apps/webapp/app/v3/mollifier/syntheticApiResponses.server.ts b/apps/webapp/app/v3/mollifier/syntheticApiResponses.server.ts
@@ -0,0 +1,73 @@
+import type { SyntheticRun } from "./readFallback.server";
+
+// Buffered runs have no execution data — the drainer hasn't materialised
+// the PG row and the worker hasn't started. The SDK-facing read routes
+// still need to return a span/trace shape that satisfies their response
+// schemas; these helpers build that minimal shape from the buffered
+// SyntheticRun.
+//
+// CANCELED and FAILED are terminal states: a FAILED buffered run is
+// errored (drainer exhausted retries or the gate rejected it) and must
+// not signal "still in progress." The flags below mirror
+// syntheticTrace.server.ts so the SDK contract stays consistent across
+// the three read paths (spans, trace, dashboard trace presenter).
+
+function deriveTerminalFlags(status: SyntheticRun["status"]): {
+  isError: boolean;
+  isPartial: boolean;
+  isCancelled: boolean;
+} {
+  const isCancelled = status === "CANCELED";
+  const isFailed = status === "FAILED";
+  return {
+    isError: isFailed,
+    isPartial: !isCancelled && !isFailed,
+    isCancelled,
+  };
+}
+
+// Body for GET /api/v1/runs/:runId/spans/:spanId when the run is buffered
+// and `:spanId` has already been verified against `buffered.spanId` by the
+// route. Pure function so the route layer just authenticates, resolves
+// the run, validates the spanId, and forwards the buffered run here.
+export function buildSyntheticSpanDetailBody(buffered: SyntheticRun) {
+  const flags = deriveTerminalFlags(buffered.status);
+  return {
+    spanId: buffered.spanId,
+    parentId: buffered.parentSpanId ?? null,
+    runId: buffered.friendlyId,
+    message: buffered.taskIdentifier ?? "",
+    ...flags,
+    level: "TRACE" as const,
+    startTime: buffered.createdAt,
+    durationMs: 0,
+  };
+}
+
+// Body for GET /api/v1/runs/:runId/trace when the run is buffered.
+// Returns the `{ trace: { traceId, rootSpan } }` envelope expected by the
+// SDK's RetrieveRunTraceResponseBody schema.
+export function buildSyntheticTraceBody(buffered: SyntheticRun) {
+  const flags = deriveTerminalFlags(buffered.status);
+  return {
+    trace: {
+      traceId: buffered.traceId ?? "",
+      rootSpan: {
+        id: buffered.spanId ?? "",
+        runId: buffered.friendlyId,
+        data: {
+          message: buffered.taskIdentifier ?? "",
+          taskSlug: buffered.taskIdentifier ?? undefined,
+          events: [] as unknown[],
+          startTime: buffered.createdAt,
+          duration: 0,
+          ...flags,
+          level: "TRACE" as const,
+          queueName: buffered.queue ?? undefined,
+          machinePreset: buffered.machinePreset ?? undefined,
+        },
+        children: [] as unknown[],
+      },
+    },
+  };
+}
diff --git a/apps/webapp/test/mollifierSyntheticApiResponses.test.ts b/apps/webapp/test/mollifierSyntheticApiResponses.test.ts
