Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Retry a device's miss when a retry finds the keyword on the other device (#980)
Carter Smith2c83d71c7fca
diff --git a/src/server/workflows/RankCheckWorkflow.ts b/src/server/workflows/RankCheckWorkflow.tsindex 84942e7c..9fef811c 100644--- a/src/server/workflows/RankCheckWorkflow.ts+++ b/src/server/workflows/RankCheckWorkflow.ts@@ -9,10 +9,10 @@ import type { BillingCustomerContext } from "@/server/billing/subscription";import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";import { failRunIfActive } from "@/server/features/rank-tracking/services/rankCheckRunGuards";import {- retryRankChecks,runLiveCheck,runQueuedCheck,} from "@/server/workflows/rankCheckPaths";+import { retryRankChecks } from "@/server/workflows/rankCheckRetries";import { pgStep } from "@/server/workflows/pgStep";import { createDataforseoClient } from "@/server/lib/dataforseo";import { captureServerEvent } from "@/server/lib/posthog";diff --git a/src/server/workflows/rankCheckPaths.test.ts b/src/server/workflows/rankCheckPaths.test.tsindex f3238077..60a0d192 100644--- a/src/server/workflows/rankCheckPaths.test.ts+++ b/src/server/workflows/rankCheckPaths.test.ts@@ -1,7 +1,8 @@import { beforeEach, describe, expect, it, vi } from "vitest";import type { WorkflowStep } from "cloudflare:workers";import type { RankCheckTaskInput } from "@/server/lib/dataforseo";-import { retryRankChecks, runLiveCheck } from "./rankCheckPaths";+import { runLiveCheck } from "./rankCheckPaths";+import { retryRankChecks } from "./rankCheckRetries";const mocks = vi.hoisted(() => ({getSnapshotsForRun: vi.fn(),@@ -148,6 +149,28 @@ describe("retryRankChecks", () => {]);});+ it("retries a device's miss once a retry finds the keyword on the other device", async () => {+ // Desktop missed on the first check and mobile errored.+ mocks.getSnapshotsForRun.mockResolvedValue([snapshot("kw_new", null)]);+ // Retry 1 answers mobile at #3; retry 2 answers desktop.+ queuedResults(3, null);++ await retryRankChecks(+ step,+ { ...checkContext(["kw_new"]), devices: "both" },+ "config_1",+ );++ expect(mocks.rankCheckTaskPost).toHaveBeenLastCalledWith(+ expect.objectContaining({+ tasks: [expect.objectContaining({ device: "desktop" })],+ }),+ );+ expect(mocks.deleteNotFoundSnapshots).toHaveBeenCalledWith([+ { runId: "run_1", trackingKeywordId: "kw_new", device: "desktop" },+ ]);+ });+it("never saves a not found for a keyword that ranked before", async () => {mocks.getSnapshotsForRun.mockResolvedValue([snapshot("kw_0", null)]);queuedResults(null, null);diff --git a/src/server/workflows/rankCheckPaths.ts b/src/server/workflows/rankCheckPaths.tsindex 1e527fcf..a9eb575d 100644--- a/src/server/workflows/rankCheckPaths.ts+++ b/src/server/workflows/rankCheckPaths.ts@@ -12,7 +12,7 @@ import type {} from "@/server/lib/dataforseo";import { AppError } from "@/server/lib/errors";import type { RankTrackingConfig } from "@/types/schemas/rank-tracking";-import { KEYWORDS_PER_BATCH, RETRY_ROUNDS } from "@/shared/rank-tracking";+import { KEYWORDS_PER_BATCH } from "@/shared/rank-tracking";import { pgStep } from "@/server/workflows/pgStep";const SINGLE_ATTEMPT_STEP_CONFIG = {@@ -21,11 +21,11 @@ const SINGLE_ATTEMPT_STEP_CONFIG = {};type KeywordEntry = { id: string; keyword: string };-type RankCheckResultWithDevice = RankCheckResult & {+export type RankCheckResultWithDevice = RankCheckResult & {device: "desktop" | "mobile";};-function mapResultsToSnapshotRows(+export function mapResultsToSnapshotRows(runId: string,results: RankCheckResultWithDevice[],) {@@ -41,7 +41,7 @@ function mapResultsToSnapshotRows(}));}-interface CheckContext {+export interface CheckContext {client: ReturnType<typeof createDataforseoClient>;keywords: KeywordEntry[];devices: RankTrackingConfig["devices"];@@ -54,7 +54,7 @@ interface CheckContext {}/** Expand keywords into one task input per keyword/device pair. */-function expandToTaskInputs(+export function expandToTaskInputs(keywords: KeywordEntry[],devices: RankTrackingConfig["devices"],): RankCheckTaskInput[] {@@ -200,7 +200,7 @@ const TASK_GETS_PER_COLLECT = 500;// than SINGLE_ATTEMPT_STEP_CONFIG's 2-minute timeout. Unlike the metered// steps, retrying is safe and free: task_get isn't charged and snapshot// writes are idempotent.-const COLLECT_STEP_CONFIG = {+export const COLLECT_STEP_CONFIG = {retries: { limit: 2, delay: "10 seconds" as const },timeout: "5 minutes" as const,};@@ -261,7 +261,7 @@ async function fetchQueuedRound(* each collect step with that round's results. A task that's rejected, fails* or never finishes gets no result. Returns every collected result.*/-async function runQueuedTasks(+export async function runQueuedTasks(step: WorkflowStep,ctx: CheckContext,tasks: RankCheckTaskInput[],@@ -361,154 +361,3 @@ export async function runQueuedCheck(},);}--// ----------------------------------------------------------------------------// Retries. A check that errors gets retried, and so does one that reads far-// worse than the keyword's known position: Google serves some scraped searches-// a fake results page that looks normal but leaves out sites that really rank.-// Retries are billed like any other check, and the best position found wins.-// -----------------------------------------------------------------------------/** A result this many positions below the keyword's known rank is retried. */-const RETRY_DROP_POSITIONS = 10;--interface RetryPair extends RankCheckTaskInput {- /** Best position saved for this run; null if not found or never answered. */- position: number | null;- /** Whether any try got a results page back. */- answered: boolean;- /**- * Best position the keyword has had: on either device in an earlier check,- * or on its other device in this run. Null if it never ranked.- */- knownPosition: number | null;-}--function needsRetry(pair: RetryPair): boolean {- if (!pair.answered) return true;- if (pair.knownPosition === null) return false;- return (- pair.position === null ||- pair.position - pair.knownPosition >= RETRY_DROP_POSITIONS- );-}--function key(keywordId: string, device: string) {- return `${keywordId}:${device}`;-}--/**- * Find the pairs to retry: ones the first check got no answer for, and ones- * that miss or fall far below the keyword's known position.- */-async function findRetryPairs(- ctx: CheckContext,- configId: string,-): Promise<RetryPair[]> {- // The run is still active, so completed runs are all earlier checks.- const [current, previous] = await Promise.all([- RankTrackingRepository.getSnapshotsForRun(ctx.runId),- RankTrackingRepository.getBestPositionsForKeywords(configId),- ]);- const previousPositions = new Map(- previous.map((s) => [s.trackingKeywordId, s.position]),- );- const currentPositions = new Map(- current.map((s) => [key(s.trackingKeywordId, s.device), s.position]),- );-- return expandToTaskInputs(ctx.keywords, ctx.devices).flatMap((task) => {- const otherDevice = task.device === "desktop" ? "mobile" : "desktop";- const known = [- previousPositions.get(task.keywordId),- currentPositions.get(key(task.keywordId, otherDevice)),- ].filter((position) => position != null);- const pair: RetryPair = {- ...task,- position: currentPositions.get(key(task.keywordId, task.device)) ?? null,- answered: currentPositions.has(key(task.keywordId, task.device)),- knownPosition: known.length > 0 ? Math.min(...known) : null,- };- return needsRetry(pair) ? [pair] : [];- });-}--/**- * Save any position that beats a pair's saved one, plus the first answer for- * a keyword that never ranked, and return each pair updated.- */-async function saveRetryResults(- runId: string,- pairs: RetryPair[],- collected: RankCheckResultWithDevice[],-): Promise<RetryPair[]> {- const results = new Map(- collected.map((result) => [key(result.keywordId, result.device), result]),- );- const toSave: RankCheckResultWithDevice[] = [];- const updated = pairs.map((pair) => {- const result = results.get(key(pair.keywordId, pair.device));- if (!result) return pair;- const answered = { ...pair, answered: true };- const isBetter =- result.position !== null &&- (pair.position === null || result.position < pair.position);- const isFirstForNewKeyword = !pair.answered && pair.knownPosition === null;- if (!isBetter && !isFirstForNewKeyword) return answered;- toSave.push(result);- return { ...answered, position: result.position };- });- if (toSave.length > 0) {- await RankTrackingRepository.upsertSnapshots(- mapResultsToSnapshotRows(runId, toSave),- );- }- return updated;-}--/**- * Retry each keyword/device pair whose check errored or reads far worse than- * its known position, up to RETRY_ROUNDS more times through the task queue- * (queue price, for manual runs too), stopping once a retry settles it. A- * keyword that ranked before is never saved as not found: if no try found it,- * its miss is removed, so it reads as not checked and keeps its previous- * position.- */-export async function retryRankChecks(- step: WorkflowStep,- ctx: CheckContext,- configId: string,-): Promise<void> {- let pairs = await pgStep(step, "find-retries", COLLECT_STEP_CONFIG, () =>- findRetryPairs(ctx, configId),- );- if (pairs.length === 0) return;-- console.log(`[rank-check] ${ctx.runId} retrying ${pairs.length} check(s)`);-- for (let round = 0; round < RETRY_ROUNDS && pairs.length > 0; round++) {- const label = `retry-${round}-`;- const collected = await runQueuedTasks(step, ctx, pairs, label);- const updated = await pgStep(- step,- `${label}save`,- COLLECT_STEP_CONFIG,- () => saveRetryResults(ctx.runId, pairs, collected),- );- pairs = updated.filter(needsRetry);- }-- const unconfirmed = pairs.filter(- (pair) => pair.position === null && pair.knownPosition !== null,- );- if (unconfirmed.length === 0) return;- await pgStep(step, "drop-unconfirmed-misses", COLLECT_STEP_CONFIG, () =>- RankTrackingRepository.deleteNotFoundSnapshots(- unconfirmed.map((pair) => ({- runId: ctx.runId,- trackingKeywordId: pair.keywordId,- device: pair.device,- })),- ),- );-}diff --git a/src/server/workflows/rankCheckRetries.ts b/src/server/workflows/rankCheckRetries.tsnew file mode 100644index 00000000..12722977--- /dev/null+++ b/src/server/workflows/rankCheckRetries.ts@@ -0,0 +1,193 @@+import type { WorkflowStep } from "cloudflare:workers";+import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";+import type { RankCheckTaskInput } from "@/server/lib/dataforseo";+import { RETRY_ROUNDS } from "@/shared/rank-tracking";+import { pgStep } from "@/server/workflows/pgStep";+import {+ COLLECT_STEP_CONFIG,+ expandToTaskInputs,+ mapResultsToSnapshotRows,+ runQueuedTasks,+ type CheckContext,+ type RankCheckResultWithDevice,+} from "@/server/workflows/rankCheckPaths";++// ---------------------------------------------------------------------------+// Retries. A check that errors gets retried, and so does one that reads far+// worse than the keyword's known position: Google serves some scraped searches+// a fake results page that looks normal but leaves out sites that really rank.+// Retries are billed like any other check, and the best position found wins.+// ---------------------------------------------------------------------------++/** A result this many positions below the keyword's known rank is retried. */+const RETRY_DROP_POSITIONS = 10;++interface RetryPair extends RankCheckTaskInput {+ /** Best position saved for this run; null if not found or never answered. */+ position: number | null;+ /** Whether any try got a results page back. */+ answered: boolean;+ /**+ * Best position the keyword has had: on either device in an earlier check,+ * or on its other device in this run. Null if it never ranked.+ */+ knownPosition: number | null;+}++function needsRetry(pair: RetryPair): boolean {+ if (!pair.answered) return true;+ if (pair.knownPosition === null) return false;+ return (+ pair.position === null ||+ pair.position - pair.knownPosition >= RETRY_DROP_POSITIONS+ );+}++function key(keywordId: string, device: string) {+ return `${keywordId}:${device}`;+}++function otherDevice(device: "desktop" | "mobile") {+ return device === "desktop" ? "mobile" : "desktop";+}++/**+ * Find the keywords to retry: ones with a device the first check got no answer+ * for, or that misses or falls far below the keyword's known position. Both+ * devices of each are returned, so a position a retry finds on one can make+ * the other's miss suspect.+ */+async function findRetryPairs(+ ctx: CheckContext,+ configId: string,+): Promise<RetryPair[]> {+ // The run is still active, so completed runs are all earlier checks.+ const [current, previous] = await Promise.all([+ RankTrackingRepository.getSnapshotsForRun(ctx.runId),+ RankTrackingRepository.getBestPositionsForKeywords(configId),+ ]);+ const previousPositions = new Map(+ previous.map((s) => [s.trackingKeywordId, s.position]),+ );+ const currentPositions = new Map(+ current.map((s) => [key(s.trackingKeywordId, s.device), s.position]),+ );++ const pairs = expandToTaskInputs(ctx.keywords, ctx.devices).map((task) => {+ const known = [+ previousPositions.get(task.keywordId),+ currentPositions.get(key(task.keywordId, otherDevice(task.device))),+ ].filter((position) => position != null);+ return {+ ...task,+ position: currentPositions.get(key(task.keywordId, task.device)) ?? null,+ answered: currentPositions.has(key(task.keywordId, task.device)),+ knownPosition: known.length > 0 ? Math.min(...known) : null,+ };+ });+ const retryKeywords = new Set(+ pairs.filter(needsRetry).map((pair) => pair.keywordId),+ );+ return pairs.filter((pair) => retryKeywords.has(pair.keywordId));+}++/**+ * Save any position that beats a pair's saved one, plus the first answer for+ * a keyword that never ranked, and return each pair updated.+ */+async function saveRetryResults(+ runId: string,+ pairs: RetryPair[],+ collected: RankCheckResultWithDevice[],+): Promise<RetryPair[]> {+ const results = new Map(+ collected.map((result) => [key(result.keywordId, result.device), result]),+ );+ const toSave: RankCheckResultWithDevice[] = [];+ const updated = pairs.map((pair) => {+ const result = results.get(key(pair.keywordId, pair.device));+ if (!result) return pair;+ const answered = { ...pair, answered: true };+ const isBetter =+ result.position !== null &&+ (pair.position === null || result.position < pair.position);+ const isFirstForNewKeyword = !pair.answered && pair.knownPosition === null;+ if (!isBetter && !isFirstForNewKeyword) return answered;+ toSave.push(result);+ return { ...answered, position: result.position };+ });+ if (toSave.length > 0) {+ await RankTrackingRepository.upsertSnapshots(+ mapResultsToSnapshotRows(runId, toSave),+ );+ }+ return updated;+}++/**+ * Add a position a retry just found to the known position of the keyword's+ * other device, as findRetryPairs does for the first check, so a miss on one+ * device isn't saved as not found while the other ranks in the same run.+ */+function withOtherDevicePositions(pairs: RetryPair[]): RetryPair[] {+ const positions = new Map(+ pairs.map((pair) => [key(pair.keywordId, pair.device), pair.position]),+ );+ return pairs.map((pair) => {+ const other = positions.get(key(pair.keywordId, otherDevice(pair.device)));+ if (other == null) return pair;+ return {+ ...pair,+ knownPosition: Math.min(pair.knownPosition ?? other, other),+ };+ });+}++/**+ * Retry each keyword/device pair whose check errored or reads far worse than+ * its known position, up to RETRY_ROUNDS more times through the task queue+ * (queue price, for manual runs too), stopping once a retry settles it. A+ * keyword that ranked before is never saved as not found: if no try found it,+ * its miss is removed, so it reads as not checked and keeps its previous+ * position.+ */+export async function retryRankChecks(+ step: WorkflowStep,+ ctx: CheckContext,+ configId: string,+): Promise<void> {+ let pairs = await pgStep(step, "find-retries", COLLECT_STEP_CONFIG, () =>+ findRetryPairs(ctx, configId),+ );++ for (let round = 0; round < RETRY_ROUNDS; round++) {+ const toRetry = pairs.filter(needsRetry);+ if (toRetry.length === 0) break;+ console.log(+ `[rank-check] ${ctx.runId} retry ${round + 1}: ${toRetry.length} check(s)`,+ );+ const label = `retry-${round}-`;+ const collected = await runQueuedTasks(step, ctx, toRetry, label);+ const updated = await pgStep(+ step,+ `${label}save`,+ COLLECT_STEP_CONFIG,+ () => saveRetryResults(ctx.runId, pairs, collected),+ );+ pairs = withOtherDevicePositions(updated);+ }++ const unconfirmed = pairs.filter(+ (pair) => pair.position === null && pair.knownPosition !== null,+ );+ if (unconfirmed.length === 0) return;+ await pgStep(step, "drop-unconfirmed-misses", COLLECT_STEP_CONFIG, () =>+ RankTrackingRepository.deleteNotFoundSnapshots(+ unconfirmed.map((pair) => ({+ runId: ctx.runId,+ trackingKeywordId: pair.keywordId,+ device: pair.device,+ })),+ ),+ );+}