Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import {
auditRenderingUnavailableMessage,
isAuditRenderingAllowed,
} from "@/server/lib/audit/rendering-policy";
import {
lockRenderingCredits,
releaseRenderingLocks,
type RenderingLock,
} from "@/server/lib/audit/rendering-billing";
import { env } from "cloudflare:workers";
import {
customerHasPaidPlan,
getOrCreateOrganizationCustomer,
type BillingCustomerContext,
} from "@/server/billing/subscription";
import { AuditRepository } from "@/server/features/audit/repositories/AuditRepository";
import { CrawlerCredentialService } from "@/server/features/audit/services/CrawlerCredentialService";
import {
AUDIT_LIMITS,
clampAuditMaxPages,
getEstimatedAuditCapacity,
type AuditLimitTier,
} from "@/server/features/audit/services/audit-capacity";
import { AppError } from "@/server/lib/errors";
import { deleteR2Prefix } from "@/server/lib/r2";
import { AuditProgressKV } from "@/server/lib/audit/progress-kv";
import {
parseAuditConfig,
type AuditConfig,
type LighthouseStrategy,
} from "@/server/lib/audit/types";
import { normalizeAndValidateStartUrl } from "@/server/lib/audit/url-policy";
import { reconcileRunningAudit } from "@/server/features/audit/services/auditReconciler";
import { isHostedServerAuthMode } from "@/server/lib/runtime-env";
import { startWorkflow } from "@/server/lib/startWorkflow";
// Free accounts keep bounded audit capacity; rendering reserves usage credits.
async function resolveAuditLimitTier(
customer: BillingCustomerContext,
): Promise<AuditLimitTier> {
if (!(await isHostedServerAuthMode())) return "self_hosted";
await getOrCreateOrganizationCustomer(customer);
return (await customerHasPaidPlan(customer.organizationId)) ? "paid" : "free";
}
async function startAudit(input: {
actorUserId: string;
billingCustomer: BillingCustomerContext;
projectId: string;
startUrl: string;
maxPages?: number;
lighthouseStrategy?: LighthouseStrategy;
limitTier: AuditLimitTier;
renderJavaScript?: boolean;
}) {
const renderJavaScript = input.renderJavaScript ?? false;
if (renderJavaScript && !(await isAuditRenderingAllowed())) {
throw new AppError(
"AUDIT_RENDERING_UNAVAILABLE",
await auditRenderingUnavailableMessage(),
);
}
const limits = AUDIT_LIMITS[input.limitTier];
const maxPages = clampAuditMaxPages(input.maxPages);
if (maxPages > limits.maxPagesPerAudit) {
throw new AppError("AUDIT_PAGE_LIMIT_EXCEEDED");
}
const lighthouseStrategy = input.lighthouseStrategy ?? "auto";
const reservation = getEstimatedAuditCapacity({
maxPages,
lighthouseStrategy,
});
const auditId = crypto.randomUUID();
const organizationId = input.billingCustomer.organizationId;
// The site itself is first contacted by the workflow's first step
// (resolveAuditStart), so starting an audit never waits on a slow site.
const startUrl = await normalizeAndValidateStartUrl(input.startUrl);
const credential = await CrawlerCredentialService.resolveCrawlerAccess(
organizationId,
input.projectId,
new URL(startUrl).hostname,
);
const config: AuditConfig = {
maxPages,
lighthouseStrategy,
renderJavaScript,
crawlerCredentialId: credential?.id,
};
await AuditRepository.createAudit({
id: auditId,
projectId: input.projectId,
startedByUserId: input.actorUserId,
startUrl,
workflowInstanceId: auditId,
config,
pagesTotal: reservation.pagesTotal,
lighthouseTotal: reservation.lighthouseTotal,
});
let renderLocks: RenderingLock[] = [];
try {
// Concurrency and capacity are enforced after the insert, not before: a
// pre-insert read is a check-then-act race, so parallel requests would all
// pass the free tier's running-audits gate. Post-insert, each request sees
// at least its own row, so racers can't all slip under the limit; the
// losers roll back via the catch below. Racers at the boundary may all
// abort — the user just retries. Usage counts per ORGANIZATION, not per
// user: the free ceiling is the org's, so N members don't multiply it.
const usage = await AuditRepository.getAuditUsageForOrganization(
input.billingCustomer.organizationId,
);
if (usage.runningCount > limits.maxRunningAudits) {
throw new AppError("AUDIT_ALREADY_RUNNING");
}
if (usage.capacityUnits > limits.maxCapacityUnits) {
throw new AppError("AUDIT_CAPACITY_REACHED");
}
// Holds the worst-case rendering cost for the whole audit. Refused here,
// the audit never runs; the workflow settles the hold when it ends.
if (renderJavaScript) {
renderLocks = await lockRenderingCredits({
customer: input.billingCustomer,
auditId,
maxPages,
});
}
await startWorkflow(
env.SITE_AUDIT_WORKFLOW,
{
id: auditId,
params: {
auditId,
billingCustomer: {
userId: input.billingCustomer.userId,
userEmail: input.billingCustomer.userEmail,
organizationId: input.billingCustomer.organizationId,
projectId: input.billingCustomer.projectId,
},
projectId: input.projectId,
startUrl,
config,
access: credential?.sealed,
renderLocks,
},
},
"site audit",
);
} catch (error) {
try {
const instance = await env.SITE_AUDIT_WORKFLOW.get(auditId);
await instance.terminate();
} catch {
// The workflow may never have been created, or may already be gone.
}
await releaseRenderingLocks(renderLocks);
await AuditRepository.deleteAuditForProject(auditId, input.projectId);
throw error;
}
await markOnboardingMilestone(input.billingCustomer, "auditStarted");
return { auditId };
}
async function getStatus(auditId: string, projectId: string) {
let audit = await AuditRepository.getAuditForProject(auditId, projectId);
if (!audit)
throw new AppError("NOT_FOUND", "Audit not found in this project.");
// Self-heal audits whose workflow died without reaching the mark-failed
// step (instance terminated/errored, instance expired from retention, ...).
// Without this they stay "running" forever and hold capacity.
if (audit.status === "running") {
const reconciled = await reconcileRunningAudit(audit);
if (reconciled) {
audit =
(await AuditRepository.getAuditForProject(auditId, projectId)) ?? audit;
}
}
return {
id: audit.id,
startUrl: audit.startUrl,
status: audit.status,
pagesCrawled: audit.pagesCrawled,
pagesTotal: audit.pagesTotal,
lighthouseTotal: audit.lighthouseTotal,
lighthouseCompleted: audit.lighthouseCompleted,
lighthouseFailed: audit.lighthouseFailed,
currentPhase: audit.currentPhase,
errorCode: audit.errorCode,
startedAt: audit.startedAt,
completedAt: audit.completedAt,
};
}
async function getResults(auditId: string, projectId: string) {
const { audit, pages, lighthouse, issues } =
await AuditRepository.getAuditResultsForProject(auditId, projectId);
if (!audit) throw new AppError("NOT_FOUND");
const parsedConfig = parseAuditConfig(audit.config);
if (!parsedConfig) {
throw new AppError("INTERNAL_ERROR", "Invalid audit configuration");
}
return {
audit: {
id: audit.id,
startUrl: audit.startUrl,
status: audit.status,
pagesCrawled: audit.pagesCrawled,
pagesTotal: audit.pagesTotal,
startedAt: audit.startedAt,
completedAt: audit.completedAt,
config: parsedConfig,
},
pages,
lighthouse,
issues,
};
}
async function getHistory(projectId: string) {
const auditList = await AuditRepository.getAuditsByProject(projectId);
return auditList.map((audit) => {
const parsedConfig = parseAuditConfig(audit.config);
const ranLighthouse = parsedConfig?.lighthouseStrategy !== "none";
return {
id: audit.id,
startUrl: audit.startUrl,
status: audit.status,
pagesCrawled: audit.pagesCrawled,
pagesTotal: audit.pagesTotal,
ranLighthouse,
startedAt: audit.startedAt,
completedAt: audit.completedAt,
};
});
}
async function getCrawlProgress(auditId: string, projectId: string) {
const audit = await AuditRepository.getAuditForProject(auditId, projectId);
if (!audit) {
throw new AppError("NOT_FOUND");
}
return AuditProgressKV.getCrawledUrls(auditId);
}
async function remove(auditId: string, projectId: string) {
const audit = await AuditRepository.getAuditForProject(auditId, projectId);
if (!audit) {
throw new AppError("NOT_FOUND");
}
if (audit.status === "running") {
if (!audit.workflowInstanceId) {
throw new AppError(
"CONFLICT",
"Cannot delete a running audit without workflow context.",
);
}
// A row can be "running" with no live workflow instance if a start failed
// between the row insert and workflow creation and its rollback delete
// also failed. Nothing to terminate then — deleting the row is the fix.
const instance = await env.SITE_AUDIT_WORKFLOW.get(
audit.workflowInstanceId,
).catch(() => null);
try {
await instance?.terminate();
} catch (error) {
// terminate() throws when the instance already reached a terminal state
// (it completed or errored in the moment before the user hit stop). That
// race shouldn't block deletion — re-check the live status and only fail
// if the workflow is genuinely still running.
const status = await instance?.status().catch(() => null);
const stillRunning =
status != null &&
["queued", "running", "paused", "waiting", "waitingForPause"].includes(
status.status,
);
if (stillRunning) {
console.error(`Failed to terminate audit workflow ${audit.id}:`, error);
throw new AppError("CONFLICT", "Unable to stop the running audit.");
}
}
}
await AuditRepository.deleteAuditForProject(auditId, projectId);
// Best-effort: drop the crawl scratchpad DO with the audit (it lives in
// the open-seo-audit worker, behind the AuditEngine RPC). A missed destroy
// self-cleans via the DO's 7-day alarm.
try {
await env.AUDIT_ENGINE.destroyScratchpad(auditId);
} catch (error) {
console.warn(`Failed to destroy audit scratchpad ${auditId}:`, error);
}
// Best-effort: the stored Lighthouse reports. A miss is swept when the
// account is erased (storage-erasure.ts).
try {
await deleteR2Prefix(env.R2, `site-audit/${projectId}/${auditId}/`);
} catch (error) {
console.warn(`Failed to delete audit files ${auditId}:`, error);
}
}
export const AuditService = {
resolveAuditLimitTier,
startAudit,
getStatus,
getCrawlProgress,
getResults,
getHistory,
remove,
} as const;