Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

Close the rerun-divergence holes cubic found in the key design

Rakshith Ramprakashefd26caf79cb
diff --git a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
index 7c5bc469b..42249c36c 100644
--- a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
+++ b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
@@ -739,10 +739,19 @@ describe("firebill routing", () => {
).toBe(false);
});
- it("gives a refund its own key, distinct from the track's", async () => {
+ it("a track/refund pair for one charge carries two distinct keys", async () => {
state.configRef = firebillConfig();
const svc = makeService();
+ // The convention the billers rely on: same charge identity, different
+ // prefix per direction β€” a shared key would 409 as a duplicate of the
+ // track and silently drop the refund.
+ await svc.trackCredits({
+ teamId: "team-1",
+ value: 5,
+ properties: { source: "billScrapeJob", endpoint: "scrape" },
+ idempotencyKey: "fc:track:scrape:job-123",
+ });
await svc.refundCredits({
teamId: "team-1",
value: 5,
@@ -750,11 +759,15 @@ describe("firebill routing", () => {
idempotencyKey: "fc:refund:scrape:job-123",
});
- const [url, init] = mockFetch.mock.calls[0]!;
- expect(String(url)).toContain("/v1/refund");
- expect(JSON.parse(init.body).idempotency_key).toBe(
- "fc:refund:scrape:job-123",
- );
+ const [trackUrl, trackInit] = mockFetch.mock.calls[0]!;
+ const [refundUrl, refundInit] = mockFetch.mock.calls[1]!;
+ expect(String(trackUrl)).toContain("/v1/track");
+ expect(String(refundUrl)).toContain("/v1/refund");
+ const trackKey = JSON.parse(trackInit.body).idempotency_key;
+ const refundKey = JSON.parse(refundInit.body).idempotency_key;
+ expect(trackKey).toBe("fc:track:scrape:job-123");
+ expect(refundKey).toBe("fc:refund:scrape:job-123");
+ expect(trackKey).not.toBe(refundKey);
});
it("routes trackCredits for an allowlisted org to firebill, not Autumn", async () => {
diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.ts
index 462f68e70..020d44427 100644
--- a/apps/api/src/services/autumn/autumn.service.ts
+++ b/apps/api/src/services/autumn/autumn.service.ts
@@ -209,6 +209,22 @@ export class AutumnService {
}
}
+ /**
+ * Whether this team's usage is currently routed through firebill. Used by
+ * billers to pick route-specific failure handling (on the firebill route a
+ * recorded charge stands and dedupes, so compensating refunds and duplicate
+ * enqueues behave differently). Never throws: an error means "not routed",
+ * falling back to the pre-firebill behavior.
+ */
+ async isRoutedThroughFirebill(teamId: string): Promise<boolean> {
+ if (this.isPreviewTeam(teamId)) return false;
+ try {
+ return shouldRouteToFirebill(await this.resolveOrgId(teamId));
+ } catch {
+ return false;
+ }
+ }
+
private async track({
customerId,
entityId,
diff --git a/apps/api/src/services/billing/__tests__/credit_billing.test.ts b/apps/api/src/services/billing/__tests__/credit_billing.test.ts
index fdbca451f..452fa7320 100644
--- a/apps/api/src/services/billing/__tests__/credit_billing.test.ts
+++ b/apps/api/src/services/billing/__tests__/credit_billing.test.ts
@@ -2,13 +2,19 @@ import { vi } from "vitest";
// vi.mock is hoisted; factory-referenced values must be created in vi.hoisted().
// (Jest didn't hoist jest.mock here because `jest` was imported from @jest/globals.)
-const { withAuth, queueBillingOperation, trackCredits, refundCredits } =
- vi.hoisted(() => ({
- withAuth: vi.fn((fn: any) => fn),
- queueBillingOperation: vi.fn<(args: any[]) => Promise<any>>(),
- trackCredits: vi.fn<(args: any) => Promise<boolean>>(),
- refundCredits: vi.fn<(args: any) => Promise<void>>(),
- }));
+const {
+ withAuth,
+ queueBillingOperation,
+ trackCredits,
+ refundCredits,
+ isRoutedThroughFirebill,
+} = vi.hoisted(() => ({
+ withAuth: vi.fn((fn: any) => fn),
+ queueBillingOperation: vi.fn<(args: any[]) => Promise<any>>(),
+ trackCredits: vi.fn<(args: any) => Promise<boolean>>(),
+ refundCredits: vi.fn<(args: any) => Promise<void>>(),
+ isRoutedThroughFirebill: vi.fn<(teamId: string) => Promise<boolean>>(),
+}));
vi.mock("../../../lib/withAuth", () => ({
withAuth,
@@ -22,6 +28,7 @@ vi.mock("../../autumn/autumn.service", () => ({
autumnService: {
trackCredits,
refundCredits,
+ isRoutedThroughFirebill,
},
featureIdForBillingEndpoint: (endpoint?: string) =>
endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",
@@ -49,6 +56,7 @@ beforeEach(() => {
queueBillingOperation.mockResolvedValue({ success: true });
trackCredits.mockResolvedValue(true);
refundCredits.mockResolvedValue(undefined);
+ isRoutedThroughFirebill.mockResolvedValue(false);
});
describe("billTeam", () => {
@@ -68,6 +76,23 @@ describe("billTeam", () => {
);
});
+ it("skips the compensating refund on the firebill route β€” the charge stands", async () => {
+ isRoutedThroughFirebill.mockResolvedValue(true);
+ queueBillingOperation.mockResolvedValueOnce({
+ success: false,
+ message: "enqueue failed",
+ });
+ trackCredits.mockResolvedValueOnce(true);
+
+ await billTeam("team-1", 3, 123, {
+ endpoint: "map",
+ jobId: "map-1",
+ chargeId: "map-1",
+ });
+
+ expect(refundCredits).not.toHaveBeenCalled();
+ });
+
it("gives the compensating refund its own fc:refund key", async () => {
queueBillingOperation.mockResolvedValueOnce({
success: false,
diff --git a/apps/api/src/services/billing/credit_billing.ts b/apps/api/src/services/billing/credit_billing.ts
index 9da9d6268..8083aa90d 100644
--- a/apps/api/src/services/billing/credit_billing.ts
+++ b/apps/api/src/services/billing/credit_billing.ts
@@ -50,16 +50,28 @@ export async function billTeam(
);
if (!result.success && trackedInRequest) {
- await autumnService.refundCredits({
- teamId: team_id,
- value: credits,
- properties: autumnProperties,
- featureId,
- // Distinct from the track key: the refund is its own charge event.
- idempotencyKey: billing.chargeId
- ? `fc:refund:${billing.endpoint}:${billing.chargeId}`
- : undefined,
- });
+ if (await autumnService.isRoutedThroughFirebill(team_id)) {
+ // No compensating refund on the firebill route: the tracked charge
+ // is durable and correct, and a refund here poisons a retried
+ // request β€” its track would dedupe against the intent row (no new
+ // charge) while the ledger enqueue succeeds, leaving Autumn
+ // net-zero for billed work.
+ logger?.warn(
+ "billing enqueue failed on the firebill route; charge stands",
+ { team_id, credits, billing },
+ );
+ } else {
+ await autumnService.refundCredits({
+ teamId: team_id,
+ value: credits,
+ properties: autumnProperties,
+ featureId,
+ // Distinct from the track key: the refund is its own charge event.
+ idempotencyKey: billing.chargeId
+ ? `fc:refund:${billing.endpoint}:${billing.chargeId}`
+ : undefined,
+ });
+ }
}
return result;
diff --git a/apps/api/src/services/worker/scrape-worker.ts b/apps/api/src/services/worker/scrape-worker.ts
index a0c94697e..0ac252a65 100644
--- a/apps/api/src/services/worker/scrape-worker.ts
+++ b/apps/api/src/services/worker/scrape-worker.ts
@@ -171,6 +171,9 @@ async function billScrapeJob(
config.USE_DB_AUTHENTICATION
) {
try {
+ const routedToFirebill = await autumnService.isRoutedThroughFirebill(
+ job.data.team_id,
+ );
trackedInRequest = await autumnService.trackCredits({
teamId: job.data.team_id,
value: creditsToBeBilled,
@@ -183,7 +186,13 @@ async function billScrapeJob(
// the re-run dedupes instead of double-billing (firebill route).
idempotencyKey: `fc:track:${billing.endpoint}:${job.id}`,
});
- const billingJobId = uuidv7();
+ // On the firebill route the ledger enqueue must be idempotent by the
+ // originating job: a stalled job reruns under the same job.id, the
+ // track dedupes in firebill, and a fresh random billing job id would
+ // debit the ledger twice (the same pattern monitors already use with
+ // their deterministic monitor-bill-{id}). Off the route, behavior is
+ // unchanged.
+ const billingJobId = routedToFirebill ? `bill-${job.id}` : uuidv7();
logger.debug(
`Adding billing job to queue for team ${job.data.team_id}`,
{
@@ -226,15 +235,28 @@ async function billScrapeJob(
{ error },
);
if (trackedInRequest && creditsToBeBilled !== null) {
- await autumnService.refundCredits({
- teamId: job.data.team_id,
- value: creditsToBeBilled,
- properties: autumnProperties,
- featureId,
- // Distinct from the track key: a refund is its own charge event
- // (same key would 409 as a duplicate of the track and be dropped).
- idempotencyKey: `fc:refund:${billing.endpoint}:${job.id}`,
- });
+ if (routedToFirebill) {
+ // No compensating refund on the firebill route: the tracked charge
+ // is durable and correct (the scrape ran), and refunding it here
+ // poisons a rerun β€” the rerun's track dedupes against the intent
+ // row (no new charge) while the ledger enqueue succeeds, leaving
+ // Autumn net-zero for work the ledger billed. The rerun retries
+ // the enqueue under the deterministic bill-{job.id} instead.
+ logger.warn(
+ "billing enqueue failed on the firebill route; charge stands, enqueue retries on rerun",
+ { jobId: job.id, credits: creditsToBeBilled },
+ );
+ } else {
+ await autumnService.refundCredits({
+ teamId: job.data.team_id,
+ value: creditsToBeBilled,
+ properties: autumnProperties,
+ featureId,
+ // Distinct from the track key: a refund is its own charge event
+ // (same key would 409 as a duplicate of the track and be dropped).
+ idempotencyKey: `fc:refund:${billing.endpoint}:${job.id}`,
+ });
+ }
}
// The billing operation never reached the queue, so no debit will
// commit and no confirmation will ever arrive: void the Exchange