Skip to content

Open source alternative to Semrush and Ahrefs

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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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,
+ })),
+ ),
+ );
+}