Skip to content

Open source alternative to Semrush and Ahrefs

7.4 KB
Raw Blame
import {
  WorkflowEntrypoint,
  type WorkflowEvent,
  type WorkflowStep,
} from "cloudflare:workers";
import { pgStep } from "./pgStep";
import {
  collectAiLiveBatch,
  collectAiModelBatch,
  collectAiRound,
  finalizeAiRun,
  markAiRunFailed,
  postAiBatch,
  prepareAiRun,
  type AiPendingTask,
} from "@/server/features/ai-visibility/services/aiVisibilityCollection";
import { runAiResearchSetup } from "@/server/features/ai-visibility/services/aiResearchKeywords";
import type { BillingCustomerContext } from "@/server/billing/subscription";
import { describeError } from "@/server/lib/errors";

// One binding serves answer collection runs and the one-time research setup,
// so setup needs no new workflow infrastructure.
type AiVisibilityPayload = (
  | { runId: string }
  | { setupProjectId: string; runSeededTracking?: boolean }
) & {
  customer: BillingCustomerContext;
};

// Metered and paid steps run once: a retry could post (and bill) twice.
const SINGLE_ATTEMPT = {
  retries: { limit: 0, delay: "1 second" as const },
  timeout: "2 minutes" as const,
};
// Steps that only read and write our own rows are free and safe to repeat, so
// an engine failure on one attempt does not fail the run.
const FREE_STEP = {
  retries: { limit: 2, delay: "10 seconds" as const },
  timeout: "2 minutes" as const,
};
// task_get is free and saving an answer replaces its evidence, so collect
// steps can retry.
const COLLECT_STEP = {
  retries: { limit: 2, delay: "10 seconds" as const },
  timeout: "5 minutes" as const,
};
// Live answers are billed per call, so a live step runs once too. It waits for
// up to 6 answers, each up to 120 seconds, and asks a failed answer up to 3
// times.
const LIVE_STEP = { ...SINGLE_ATTEMPT, timeout: "10 minutes" as const };
// Standard-queue answers usually arrive within minutes. Cumulative waits are
// 2 / 4 / 7 / 10 / 14 / 18 / 22 / 26 / 30 minutes; anything still missing then
// fails as not collected. Each sleep stays under 5 minutes, like rank check's:
// the engine cancels an invocation idling in a longer sleep.
const POLL_INTERVALS = [
  "2 minutes",
  "2 minutes",
  "3 minutes",
  "3 minutes",
  "4 minutes",
  "4 minutes",
  "4 minutes",
  "4 minutes",
  "4 minutes",
] as const;

export class AiVisibilityWorkflow extends WorkflowEntrypoint<
  Env,
  AiVisibilityPayload
> {
  async run(event: WorkflowEvent<AiVisibilityPayload>, step: WorkflowStep) {
    const { payload } = event;
    if ("setupProjectId" in payload)
      // No retries: each attempt is a paid model call. The user can retry.
      return pgStep(
        step,
        "research-setup",
        { retries: { limit: 0, delay: "1 second" }, timeout: "5 minutes" },
        () =>
          runAiResearchSetup(
            { projectId: payload.setupProjectId },
            payload.customer,
            { runSeededTracking: payload.runSeededTracking },
          ),
      );
    const { runId, customer } = payload;
    const markFailed = async (error: unknown) => {
      await pgStep(step, "mark-failed", FREE_STEP, () =>
        markAiRunFailed(runId),
      );
      throw error;
    };
    const failRun = (error: unknown) => {
      console.error(
        `[ai-visibility] ${runId} failed: ${describeError(error)}`,
        error,
      );
      return markFailed(error);
    };
    let pending: AiPendingTask[] = [];
    let plan: Awaited<ReturnType<typeof prepareAiRun>>;
    // Reads the pending answers once, then posts each answer that DataForSEO's
    // backend failed again in its own step, since a post is billed. The read
    // steps are `read-*`, not the older `collect-*`: a run in flight across a
    // deploy must not replay a `collect-*` output, which had another shape.
    const collect = async (name: string, canRetry: boolean) => {
      const remaining = pending;
      let round: Awaited<ReturnType<typeof collectAiRound>>;
      try {
        round = await pgStep(step, `read-${name}`, COLLECT_STEP, () =>
          collectAiRound(runId, remaining, canRetry),
        );
      } catch (error) {
        // Posted tasks are already paid for; keep polling them next round.
        console.warn(
          `[ai-visibility] ${runId} read-${name}: ${describeError(error)}`,
        );
        return;
      }
      pending = round.pending;
      for (const [index, batch] of round.retry.entries()) {
        try {
          pending.push(
            ...(await pgStep(
              step,
              `repost-${name}-${index}`,
              SINGLE_ATTEMPT,
              () => postAiBatch(runId, customer, plan.market, batch),
            )),
          );
        } catch (error) {
          // Its answers fail at finalize.
          console.warn(
            `[ai-visibility] ${runId} repost-${name}: ${describeError(error)}`,
          );
        }
      }
    };
    try {
      plan = await pgStep(step, "prepare", FREE_STEP, () =>
        prepareAiRun(runId),
      );
    } catch (error) {
      return failRun(error);
    }
    // A batch whose step fails, on the engine's own error or a timeout, leaves
    // its answers pending for finalize to fail. The other batches still run,
    // so the run keeps every answer it got.
    if (plan.live)
      // Live runs save each live batch as it returns, so nothing is left
      // pending to poll.
      for (const [index, tasks] of plan.batches.entries())
        try {
          await pgStep(step, `live-${index}`, LIVE_STEP, () =>
            collectAiLiveBatch(runId, customer, plan.market, tasks),
          );
        } catch (error) {
          console.warn(
            `[ai-visibility] ${runId} live-${index}: ${describeError(error)}`,
          );
        }
    else
      for (const [index, batch] of plan.batches.entries())
        try {
          pending.push(
            ...(await pgStep(step, `post-${index}`, SINGLE_ATTEMPT, () =>
              postAiBatch(runId, customer, plan.market, batch),
            )),
          );
        } catch (error) {
          console.warn(
            `[ai-visibility] ${runId} post-${index}: ${describeError(error)}`,
          );
        }
    // Claude and Perplexity answers come from the model API on every run.
    // Queued answers process meanwhile, and each model batch is followed by
    // one free read of them.
    for (const [index, batch] of plan.modelBatches.entries()) {
      try {
        await pgStep(step, `model-${index}`, LIVE_STEP, () =>
          collectAiModelBatch(runId, customer, plan.market, batch),
        );
      } catch (error) {
        // Its unsaved answers fail at finalize; the other batches continue.
        console.warn(
          `[ai-visibility] ${runId} model-${index}: ${describeError(error)}`,
        );
      }
      if (pending.length) await collect(`model-${index}`, true);
    }
    for (
      let round = 0;
      round < POLL_INTERVALS.length && pending.length > 0;
      round++
    ) {
      try {
        await step.sleep(`wait-${round}`, POLL_INTERVALS[round]);
      } catch (error) {
        // The engine cancels an invocation idling in a long sleep, which
        // rejects it here, then resumes the instance on wake. That interrupt
        // never runs mark-failed, so only a real failure fails the run. Don't
        // log it as one.
        return markFailed(error);
      }
      // A task posted after the last round would never be read.
      await collect(`${round}`, round < POLL_INTERVALS.length - 1);
    }
    try {
      await pgStep(step, "finalize", FREE_STEP, () => finalizeAiRun(runId));
    } catch (error) {
      return failRun(error);
    }
  }
}