The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Connect usage: count in memory and flush once a minute; cache the sharing preference (DB roadmap Phase 0.4) (#2160)
harness-for-autonomous[bot]1a034eb26672
diff --git a/backend/integration/productUsageConflicts.test.ts b/backend/integration/productUsageConflicts.test.tsindex 43f91b927..1b99eb075 100644--- a/backend/integration/productUsageConflicts.test.ts+++ b/backend/integration/productUsageConflicts.test.ts@@ -68,3 +68,69 @@ it('four backend processes reporting at once still count every report', async ()expect(answers.filter(a => a.status === 'rejected').map(a => (a as PromiseRejectedResult).reason?.code)).toEqual([])expect(await total('queue_capped')).toBe(192)}, 60000)++// Relay connects: counted in memory, written once a minute. Each import after a reset is another process.+const connectDay = new Date('2026-10-27')+const connectTotal = async (metric: string): Promise<number | undefined> =>+ (await db.productUsageTotal.findUnique({ where: { dayUtc_metric: { dayUtc: connectDay, metric } } }))?.value++it('connects from four processes at once, and the people who turned sharing off, total exactly the connects that were counted', async () => {+ const processes = [usage]+ for (let i = 1; i < 4; i++) { vi.resetModules(); processes.push(await import('../src/lib/productUsage.js')) }+ await usage.setProductUsageChoice('6a0000000000000000000f01', false)+ const receiptsBefore = await db.productUsageReceipt.count()+ await Promise.all(processes.map((each, p) => Promise.all(Array.from({ length: 150 }, (_, i) =>+ each.recordRelayUsage(i % 5 === 0 ? '6a0000000000000000000f01' : `6a00000000000000000${p}0${i % 7}`,+ new Date('2026-10-27T10:00:00Z'), 'relay_tui_opens', i % 2 ? ['relay_machine_connections'] : [])))))+ expect(await connectTotal('relay_tui_opens')).toBeUndefined()+ await Promise.all(processes.map(each => each.flushRelayUsage()))+ // 150 per process, minus every fifth (the person who is off): 120; the odd ones also add a machine connection.+ expect(await connectTotal('relay_tui_opens')).toBe(4 * 120)+ expect(await connectTotal('relay_machine_connections')).toBe(4 * 60)+ expect(await db.productUsageReceipt.count()).toBe(receiptsBefore + 4)+ expect(await db.productUsageTotal.count({ where: { dayUtc: connectDay } })).toBe(2)+}, 60000)++it('a flush whose answer was lost and is sent again counts once', async () => {+ vi.resetModules()+ const each = await import('../src/lib/productUsage.js')+ const before = await connectTotal('relay_remote_sessions')+ await each.recordRelayUsage('6a0000000000000000000e01', new Date('2026-10-27T11:00:00Z'), 'relay_remote_sessions')+ const real = db.$transaction.bind(db) as (fn: unknown, options?: unknown) => Promise<unknown>+ const spy = vi.spyOn(db, '$transaction').mockImplementationOnce(async (fn: unknown, options?: unknown) => {+ await real(fn, options)+ throw new Error('connection reset')+ })+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})+ await each.flushRelayUsage()+ await each.flushRelayUsage()+ await each.flushRelayUsage()+ spy.mockRestore(); warn.mockRestore()+ expect(await connectTotal('relay_remote_sessions')).toBe((before ?? 0) + 1)+}, 60000)++it('sharing turned off through one server stops the next connect on another server at once; turned back on, it counts again after a few seconds', async () => {+ const servers = []+ for (let i = 0; i < 2; i++) { vi.resetModules(); servers.push(await import('../src/lib/productUsage.js')) }+ const [one, other] = servers+ const person = '6a0000000000000000000d01'+ const day = new Date('2026-10-27T12:00:00Z')+ const counted = async (): Promise<number> => {+ await Promise.all(servers.map(each => each.flushRelayUsage()))+ return (await connectTotal('relay_desktop_opens')) ?? 0+ }+ const before = await counted()+ await one.recordRelayUsage(person, day, 'relay_desktop_opens')+ expect(await counted()).toBe(before + 1)+ await other.setProductUsageChoice(person, false)+ await one.recordRelayUsage(person, day, 'relay_desktop_opens')+ expect(await counted()).toBe(before + 1)+ // The off answer is kept by the server that read it; a change made through the other server is seen after the TTL.+ await other.setProductUsageChoice(person, true)+ await one.recordRelayUsage(person, day, 'relay_desktop_opens')+ expect(await counted()).toBe(before + 1)+ const clock = vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 6_000)+ await one.recordRelayUsage(person, day, 'relay_desktop_opens')+ clock.mockRestore()+ expect(await counted()).toBe(before + 2)+}, 60000)diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.tsindex a7da115d0..526655ea3 100644--- a/backend/src/lib/productUsage.test.ts+++ b/backend/src/lib/productUsage.test.ts@@ -19,7 +19,7 @@ const db = vi.hoisted(() => ({vi.mock('./prisma.js', () => ({ prisma: db }))// A configured key, so deletion through setProductUsageChoice and the legacy delete path is real.vi.mock('../config/env.js', () => ({ env: { PRODUCT_USAGE_SUBJECT_KEY: 'k'.repeat(32) } }))-import { activitySubject, deleteActivity, deleteLegacyProductUsage, ensureProductUsageExpiry, markActivity, resetActivityMarksForTests, resetStaffAccountsForTests, ingestProductUsage, ingestSetupUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice } from './productUsage.js'+import { activitySubject, deleteActivity, deleteLegacyProductUsage, ensureProductUsageExpiry, markActivity, resetActivityMarksForTests, resetStaffAccountsForTests, ingestProductUsage, ingestSetupUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice, flushRelayUsage, resetRelayUsageForTests } from './productUsage.js'import { LAUNCH_ERROR_CODES, LAUNCH_ERROR_FAMILIES, PRODUCT_USAGE_METRICS, type ProductUsageReport } from '../types/productUsage.js'it('commits release and platform margins under the same unlinked receipt and discards development reports', async () => {@@ -57,6 +57,7 @@ beforeEach(() => {accounts('[email protected]')resetActivityMarksForTests()resetStaffAccountsForTests()+ resetRelayUsageForTests()db.user.findUnique.mockResolvedValue({ createdAt: new Date('2026-10-01T08:00:00Z'), email: '[email protected]' })})@@ -302,35 +303,199 @@ describe('aggregate ingestion', () => {})})-it('the legacy relay respects off and writes only an aggregate counter when on', async () => {- db.productUsagePreference.findUnique.mockResolvedValue({ enabled: false, revision: 1 })- await recordRelayUsage('private-account', now, 'relay_turns_started')- expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()- db.productUsagePreference.findUnique.mockResolvedValue({ enabled: true, revision: 2 })- await recordRelayUsage('private-account', now, 'relay_turns_started')- expect(JSON.stringify(db.productUsageTotal.upsert.mock.calls)).not.toContain('private-account')-})+describe('relay connects', () => {+ const sent = (): Array<[string, string, number]> => db.$runCommandRaw.mock.calls.flatMap(([command]) =>+ (command as { updates: Array<{ q: { dayUtc: { $date: string }; metric: string }; u: { $inc: { value: number } } }> }).updates+ .map(u => [u.q.dayUtc.$date.slice(0, 10), u.q.metric, u.u.$inc.value] as [string, string, number])).sort()+ const choose = (enabled: boolean, revision = 1) => db.productUsagePreference.findUnique.mockResolvedValue({ enabled, revision })-it('one relay event adds to each total it names under a single preference read', async () => {- db.productUsagePreference.findUnique.mockResolvedValue({ enabled: true, revision: 2 })- await recordRelayUsage('private-account', now, 'relay_mobile_opens', ['breakdown:release:phone:1.0.8:relay_mobile_opens'])- expect(db.productUsagePreference.findUnique).toHaveBeenCalledOnce()- expect(db.productUsageTotal.upsert.mock.calls.map(([call]) => [call.where.dayUtc_metric.metric, call.create.value, call.update.value])).toEqual([- ['relay_mobile_opens', 1, { increment: 1 }], ['breakdown:release:phone:1.0.8:relay_mobile_opens', 1, { increment: 1 }]])- expect(JSON.stringify(db.productUsageTotal.upsert.mock.calls)).not.toContain('private-account')- db.productUsageTotal.upsert.mockClear()- db.productUsagePreference.findUnique.mockResolvedValue({ enabled: false, revision: 3 })- await recordRelayUsage('private-account', now, 'relay_mobile_opens', ['relay_mobile_debug_opens'])- expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()-})+ it('respects off, and counts only an aggregate when on', async () => {+ choose(false)+ await recordRelayUsage('private-account', now, 'relay_turns_started')+ await flushRelayUsage()+ expect(db.$transaction).not.toHaveBeenCalled()+ resetRelayUsageForTests()+ choose(true, 2)+ await recordRelayUsage('private-account', now, 'relay_turns_started')+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_turns_started', 1]])+ expect(JSON.stringify([db.$runCommandRaw.mock.calls, db.productUsageReceipt.createMany.mock.calls])).not.toContain('private-account')+ })++ it('many connects in a minute are one write per day and metric with the per-connect sum', async () => {+ choose(true)+ for (let i = 0; i < 50; i++) await recordRelayUsage('a', now, 'relay_tui_opens')+ for (let i = 0; i < 30; i++) await recordRelayUsage('b', now, 'relay_tui_opens', ['relay_mobile_debug_opens'])+ await recordRelayUsage('a', new Date('2026-10-14T00:00:01Z'), 'relay_tui_opens')+ expect(db.$runCommandRaw).not.toHaveBeenCalled()+ await flushRelayUsage()+ expect(db.$transaction).toHaveBeenCalledOnce()+ expect(db.$runCommandRaw).toHaveBeenCalledOnce()+ expect(sent()).toEqual([['2026-10-13', 'relay_mobile_debug_opens', 30], ['2026-10-13', 'relay_tui_opens', 80], ['2026-10-14', 'relay_tui_opens', 1]])+ expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()+ })++ it('writes the flush and its receipt in one transaction', async () => {+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ await flushRelayUsage()+ expect(receipts()).toHaveLength(1)+ expect(receipts()[0]).toMatch(/^relay:/)+ expect(db.productUsageReceipt.createMany.mock.calls[0][0].data[0].expiresAt.getTime()).toBeGreaterThan(Date.now())+ expect(db.$transaction).toHaveBeenCalledOnce()+ })-it('a relay metrics failure cannot interrupt work or log an identity or database error', async () => {- const log = vi.spyOn(console, 'warn').mockImplementation(() => {})- db.productUsagePreference.findUnique.mockRejectedValue(new Error('PRIVATE_DATABASE_CANARY'))- await expect(recordRelayUsage('PRIVATE_ACCOUNT_CANARY', now, 'relay_turns_started')).resolves.toBeUndefined()- expect(JSON.stringify(log.mock.calls)).not.toContain('PRIVATE_')- expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()- log.mockRestore()+ it('a flush that committed but whose answer was lost is sent again and counts once', async () => {+ choose(true)+ const stored = new Set<string>()+ db.productUsageReceipt.findMany.mockImplementation(async ({ where }) => where.id.in.filter((id: string) => stored.has(id)).map((id: string) => ({ id })))+ db.productUsageReceipt.createMany.mockImplementation(async ({ data }) => { data.forEach((r: { id: string }) => stored.add(r.id)); return { count: data.length } })+ db.$transaction.mockImplementationOnce(async (fn: (tx: typeof db) => unknown) => { await fn(db); throw new Error('connection reset') })+ const log = vi.spyOn(console, 'warn').mockImplementation(() => {})+ await recordRelayUsage('a', now, 'relay_tui_opens')+ await flushRelayUsage()+ await flushRelayUsage()+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ expect(db.$transaction).toHaveBeenCalledTimes(2)+ log.mockRestore()+ })++ it('a write conflict with another process\'s flush is retried inside the flush', async () => {+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ db.$transaction.mockRejectedValueOnce(Object.assign(new Error('conflict'), { code: 'P2034' }))+ await flushRelayUsage()+ expect(db.$transaction).toHaveBeenCalledTimes(2)+ expect(delay).toHaveBeenCalledOnce()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ })++ it('a failed flush is retried whole, and counts once when it lands', async () => {+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ db.$transaction.mockRejectedValueOnce(new Error('PRIVATE_DATABASE_CANARY'))+ const log = vi.spyOn(console, 'warn').mockImplementation(() => {})+ await flushRelayUsage()+ expect(db.$runCommandRaw).not.toHaveBeenCalled()+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ expect(JSON.stringify(log.mock.calls)).not.toContain('PRIVATE_')+ log.mockRestore()+ })++ it('one relay event adds to each total it names under a single preference read', async () => {+ choose(true, 2)+ await recordRelayUsage('private-account', now, 'relay_mobile_opens', ['breakdown:release:phone:1.0.8:relay_mobile_opens'])+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledOnce()+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'breakdown:release:phone:1.0.8:relay_mobile_opens', 1], ['2026-10-13', 'relay_mobile_opens', 1]])+ })++ it('a relay metrics failure cannot interrupt work or log an identity or database error', async () => {+ const log = vi.spyOn(console, 'warn').mockImplementation(() => {})+ db.productUsagePreference.findUnique.mockRejectedValue(new Error('PRIVATE_DATABASE_CANARY'))+ await expect(recordRelayUsage('PRIVATE_ACCOUNT_CANARY', now, 'relay_turns_started')).resolves.toBeUndefined()+ await flushRelayUsage()+ expect(JSON.stringify(log.mock.calls)).not.toContain('PRIVATE_')+ expect(db.$transaction).not.toHaveBeenCalled()+ log.mockRestore()+ })++ describe('the preference read', () => {+ it('keeps an off answer for a few seconds, and reads again after them', async () => {+ choose(false)+ const clock = vi.spyOn(Date, 'now')+ clock.mockReturnValue(1_000_000)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ clock.mockReturnValue(1_004_000)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledOnce()+ clock.mockReturnValue(1_006_000)+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledTimes(2)+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ clock.mockRestore()+ })++ it('never keeps an on answer: sharing turned off elsewhere stops the next connect at once', async () => {+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ choose(false, 2)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledTimes(2)+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ })++ it('shares one read between connects that arrive while it is under way', async () => {+ let answer!: (value: { enabled: boolean; revision: number }) => void+ db.productUsagePreference.findUnique.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))+ const burst = Promise.all([1, 2, 3].map(() => recordRelayUsage('a', now, 'relay_tui_opens')))+ answer({ enabled: true, revision: 1 })+ await burst+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledOnce()+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 3]])+ })++ it('drops an off answer when the person turns sharing back on: the next connect is counted at once', async () => {+ choose(false)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ db.productUsagePreference.upsert.mockResolvedValue({ enabled: true, revision: 3 })+ await setProductUsageChoice('a', true)+ choose(true, 3)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ })++ it('does not keep an off answer that was being read while the person turned sharing on', async () => {+ let answer!: (value: { enabled: boolean; revision: number }) => void+ db.productUsagePreference.findUnique.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))+ const inFlight = recordRelayUsage('a', now, 'relay_tui_opens')+ db.productUsagePreference.upsert.mockResolvedValue({ enabled: true, revision: 2 })+ await setProductUsageChoice('a', true)+ answer({ enabled: false, revision: 1 })+ await inFlight+ choose(true, 2)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledTimes(2)+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ })++ it('is kept per person: one person\'s off does not stop another\'s count', async () => {+ db.productUsagePreference.findUnique.mockImplementation(async ({ where }) => ({ enabled: where.userId !== 'off', revision: 1 }))+ await recordRelayUsage('off', now, 'relay_tui_opens')+ await recordRelayUsage('on', now, 'relay_tui_opens')+ await recordRelayUsage('off', now, 'relay_tui_opens')+ expect(db.productUsagePreference.findUnique).toHaveBeenCalledTimes(2)+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ })++ it('is never kept after a failed read', async () => {+ const log = vi.spyOn(console, 'warn').mockImplementation(() => {})+ db.productUsagePreference.findUnique.mockRejectedValueOnce(new Error('unavailable'))+ await recordRelayUsage('a', now, 'relay_tui_opens')+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ await flushRelayUsage()+ expect(sent()).toEqual([['2026-10-13', 'relay_tui_opens', 1]])+ log.mockRestore()+ })++ it('is not used for activity marks, which are about a person: sharing turned off elsewhere stops them at once', async () => {+ choose(true)+ await recordRelayUsage('a', now, 'relay_tui_opens')+ choose(false, 2)+ await markActivity('a', now, { surface: 'desktop' })+ expect(db.productUsageActivity.upsert).not.toHaveBeenCalled()+ })+ })})it('the legacy delete path erases all six linked activity collections', async () => {diff --git a/backend/src/lib/productUsage.ts b/backend/src/lib/productUsage.tsindex cd666aec4..cd1a8f145 100644--- a/backend/src/lib/productUsage.ts+++ b/backend/src/lib/productUsage.ts@@ -10,11 +10,13 @@ import { PRODUCT_USAGE_DAYS, type ProductUsageChoice, type ProductUsageReport }import { ACTIVITY_DAYS, type ActivitySurface } from '../types/productUsageActivity.js'import { incrementUsageTotals, type UsageIncrement } from './productUsageWrite.js'import { createUsageBatch } from './productUsageBatch.js'+import { createRelayTotals } from './productUsageRelay.js'const DAY = 86_400_000type Db = Pick<Prisma.TransactionClient, 'productUsagePreference' | 'analyticsMachineState'>-/** A pre-existing off choice wins over the new default. Never cache an enabled answer. */+/** A pre-existing off choice wins over the new default. Never cache an enabled answer: every caller reads it live.+ * The one cache is `relayEnabled`'s, for counting connects, and it keeps only an off answer. */export async function productUsageChoice(userId: string, db: Db = prisma): Promise<ProductUsageChoice> {const saved = await db.productUsagePreference.findUnique({ where: { userId }, select: { enabled: true, revision: true } })if (saved) return saved@@ -28,6 +30,7 @@ export async function setProductUsageChoice(userId: string, enabled: boolean): Pwhere: { userId }, create: { userId, enabled, revision: 1 },update: { enabled, revision: { increment: 1 } }, select: { enabled: true, revision: true },})+ dropRelayChoice(userId)if (!enabled) await deleteActivity(userId)return choice}@@ -145,18 +148,24 @@ async function commitReports(reports: QueuedReport[]): Promise<IngestResult[]> {return results})} catch (error) {- const code = (error as { code?: string } | null)?.code- const pause = 25 * 2 ** attempt + Math.floor(Math.random() * 50)- // A Mongo lock wait comes without a Prisma code, labelled transient, as Swarm's do (superTabs/store.ts).- const transient = error instanceof Error && error.message.includes('TransientTransactionError')- if ((code !== 'P2034' && code !== 'P2002' && !transient) || attempt >= 3- || performance.now() - started + pause >= 1000) throw error- await delay(pause)- if (performance.now() - started >= 1000) throw error+ await pauseForConflict(error, attempt, started)}}}+/** Waits before another attempt after a write conflict from another process's batch, or throws [error]: any other+ * failure, a fourth attempt, or a wait that would pass a second. */+async function pauseForConflict(error: unknown, attempt: number, started: number): Promise<void> {+ const code = (error as { code?: string } | null)?.code+ const pause = 25 * 2 ** attempt + Math.floor(Math.random() * 50)+ // A Mongo lock wait comes without a Prisma code, labelled transient, as Swarm's do (superTabs/store.ts).+ const transient = error instanceof Error && error.message.includes('TransientTransactionError')+ if ((code !== 'P2034' && code !== 'P2002' && !transient) || attempt >= 3+ || performance.now() - started + pause >= 1000) throw error+ await delay(pause)+ if (performance.now() - started >= 1000) throw error+}+/** One update per day and name, whichever reports added to it. */function summed(increments: UsageIncrement[]): UsageIncrement[] {const totals = new Map<string, UsageIncrement>()@@ -176,22 +185,74 @@ export type RelayUsageMetric = 'relay_desktop_opens' | 'relay_tui_opens' | 'rela| 'relay_mobile_debug_opens' | `breakdown:release:phone:${string}:relay_mobile_opens`let warnedAt = 0+// A person who turned sharing off still opens sockets, so a process keeps that off answer a few seconds and skips the+// read. An on answer is never kept: sharing turned off anywhere stops the next connect here at once (a burst of+// connects that arrive while one read is under way share it). The cost is on the safe side: when a person turns+// sharing back on elsewhere, this process goes on not counting for up to the TTL. Only counting uses it: the+// activity marks are about a person and always read the preference itself. A change in this process drops the entry+// at once, and a read that began before the change is not kept.+const RELAY_CHOICE_TTL_MS = 5_000+const RELAY_CHOICE_MAX = 10_000+const relayOff = new Map<string, number>()+const relayReads = new Map<string, Promise<boolean>>()+let relayChoiceEpoch = 0++function dropRelayChoice(userId: string): void {+ relayChoiceEpoch+++ relayOff.delete(userId)+ relayReads.delete(userId)+}++async function relayEnabled(userId: string): Promise<boolean> {+ const until = relayOff.get(userId)+ if (until !== undefined && until > Date.now()) return false+ const reading = relayReads.get(userId)+ if (reading) return reading+ const epoch = relayChoiceEpoch+ const read = productUsageChoice(userId).then(({ enabled }) => {+ if (!enabled && epoch === relayChoiceEpoch) {+ if (relayOff.size >= RELAY_CHOICE_MAX) relayOff.clear()+ relayOff.set(userId, Date.now() + RELAY_CHOICE_TTL_MS)+ }+ return enabled+ }).finally(() => { if (relayReads.get(userId) === read) relayReads.delete(userId) })+ relayReads.set(userId, read)+ return read+}++/** A batch of connect totals and its receipt commit together; a batch seen again adds nothing. The receipt+ * outlives every retry (a held batch is dropped after five minutes). */+async function writeRelayBatch(id: string, increments: UsageIncrement[]): Promise<void> {+ const receipt = `relay:${id}`+ const started = performance.now()+ for (let attempt = 0; ; attempt++) {+ try {+ return await prisma.$transaction(async tx => {+ if ((await tx.productUsageReceipt.findMany({ where: { id: { in: [receipt] } }, select: { id: true } })).length) return+ await tx.productUsageReceipt.createMany({ data: [{ id: receipt, expiresAt: new Date(Date.now() + 2 * DAY) }] })+ await incrementUsageTotals(tx, increments)+ })+ } catch (error) {+ await pauseForConflict(error, attempt, started)+ }+ }+}++const relayTotals = createRelayTotals({ write: writeRelayBatch })+export const flushRelayUsage = relayTotals.flush+/** Run in each process that takes connections. The stop it returns flushes what is waiting: call it on shutdown. */+export const startRelayUsageFlush = relayTotals.start+export function resetRelayUsageForTests(): void { relayOff.clear(); relayReads.clear(); relayChoiceEpoch++; relayTotals.reset() }+/** Older clients still contribute totals. These are events, never distinct users or installations.- * [also]: more totals the same event adds to, under the one preference read. */+ * [also]: more totals the same event adds to, under the one preference read. Counted in memory and+ * written once a minute (`createRelayTotals`). */export async function recordRelayUsage(userId: string, now: Date, metric: RelayUsageMetric,also: readonly RelayUsageMetric[] = []): Promise<void> {try {- if (!(await productUsageChoice(userId)).enabled) return+ if (!(await relayEnabled(userId))) returnconst dayUtc = new Date(Math.floor(now.getTime() / DAY) * DAY)- for (const name of [metric, ...also]) {- const where = { dayUtc_metric: { dayUtc, metric: name } }- try {- await prisma.productUsageTotal.upsert({ where, create: { dayUtc, metric: name, value: 1 }, update: { value: { increment: 1 } } })- } catch (error) {- if ((error as { code?: string }).code !== 'P2002') throw error- await prisma.productUsageTotal.update({ where, data: { value: { increment: 1 } } })- }- }+ for (const name of [metric, ...also]) relayTotals.add(dayUtc, name)} catch {// Do not let analytics break a session or reach callers that log the account/agent and DB error.if (Date.now() - warnedAt >= 60_000) {diff --git a/backend/src/lib/productUsageRelay.test.ts b/backend/src/lib/productUsageRelay.test.tsnew file mode 100644index 000000000..060e3270b--- /dev/null+++ b/backend/src/lib/productUsageRelay.test.ts@@ -0,0 +1,143 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { createRelayTotals } from './productUsageRelay.js'+import type { UsageIncrement } from './productUsageWrite.js'++const day = new Date('2026-10-29T00:00:00Z')+const nextDay = new Date('2026-10-30T00:00:00Z')+type Write = (id: string, increments: UsageIncrement[]) => Promise<void>+const setup = (write: Write, options: Partial<Parameters<typeof createRelayTotals>[0]> = {}) => {+ let n = 0+ return createRelayTotals({ write, newId: () => `batch-${++n}`, warn: () => {}, ...options })+}+const sorted = (increments: UsageIncrement[]) =>+ increments.map(i => [i.dayUtc.toISOString().slice(0, 10), i.metric, i.value]).sort()++describe('relay totals', () => {+ it('many connects in a minute are one increment per day and metric, equal to their sum', async () => {+ const write = vi.fn<Write>(async () => {})+ const totals = setup(write)+ for (let i = 0; i < 300; i++) totals.add(day, 'relay_tui_opens')+ for (let i = 0; i < 40; i++) totals.add(day, 'relay_machine_connections')+ for (let i = 0; i < 7; i++) totals.add(nextDay, 'relay_tui_opens')+ expect(write).not.toHaveBeenCalled()+ await totals.flush()+ expect(write).toHaveBeenCalledOnce()+ expect(write.mock.calls[0][0]).toBe('batch-1')+ expect(sorted(write.mock.calls[0][1])).toEqual([+ ['2026-10-29', 'relay_machine_connections', 40], ['2026-10-29', 'relay_tui_opens', 300], ['2026-10-30', 'relay_tui_opens', 7]])+ })++ it('writes nothing when nothing was counted', async () => {+ const write = vi.fn<Write>(async () => {})+ await setup(write).flush()+ expect(write).not.toHaveBeenCalled()+ })++ it('counts connects that arrive during a flush in the next one, never twice', async () => {+ let release!: () => void+ const write = vi.fn<Write>(() => new Promise<void>(resolve => { release = resolve }))+ const totals = setup(write)+ totals.add(day, 'm')+ const first = totals.flush()+ totals.add(day, 'm')+ totals.add(day, 'm')+ release()+ await first+ write.mockImplementation(async () => {})+ await totals.flush()+ expect(write.mock.calls.map(([, increments]) => sorted(increments))).toEqual([[['2026-10-29', 'm', 1]], [['2026-10-29', 'm', 2]]])+ })++ it('does not start a second flush while one is writing', async () => {+ let release!: () => void+ const write = vi.fn<Write>(() => new Promise<void>(resolve => { release = resolve }))+ const totals = setup(write)+ totals.add(day, 'm')+ const first = totals.flush()+ const second = totals.flush()+ release()+ await Promise.all([first, second])+ expect(write).toHaveBeenCalledOnce()+ })++ it('retries a failed batch under the same id, so a write that did commit is not counted twice', async () => {+ const write = vi.fn<Write>().mockRejectedValueOnce(new Error('connection reset')).mockResolvedValue(undefined)+ const totals = setup(write)+ totals.add(day, 'm')+ await totals.flush()+ totals.add(day, 'm')+ await totals.flush()+ expect(write).toHaveBeenCalledTimes(3)+ expect(write.mock.calls.map(([id]) => id)).toEqual(['batch-1', 'batch-1', 'batch-2'])+ expect(write.mock.calls[1][1]).toEqual(write.mock.calls[0][1])+ expect(sorted(write.mock.calls[2][1])).toEqual([['2026-10-29', 'm', 1]])+ })++ it('gives up on a batch that keeps failing and warns without an identity', async () => {+ const warn = vi.fn()+ const write = vi.fn<Write>().mockRejectedValue(new Error('PRIVATE_DATABASE_CANARY'))+ const totals = setup(write, { retries: 3, warn })+ totals.add(day, 'm')+ for (let i = 0; i < 5; i++) await totals.flush()+ expect(write).toHaveBeenCalledTimes(3)+ expect(warn).toHaveBeenCalled()+ expect(JSON.stringify(warn.mock.calls)).not.toContain('PRIVATE_')+ })++ it('flushes at once when too many different totals are waiting', async () => {+ const write = vi.fn<Write>(async () => {})+ const totals = setup(write, { maxKeys: 3 })+ for (const metric of ['a', 'b']) totals.add(day, metric)+ expect(write).not.toHaveBeenCalled()+ totals.add(day, 'c')+ await vi.waitFor(() => expect(write).toHaveBeenCalledOnce())+ })++ it('drops new totals instead of growing without bound while the database is down', async () => {+ const warn = vi.fn()+ const write = vi.fn<Write>().mockRejectedValue(new Error('down'))+ const totals = setup(write, { maxKeys: 2, retries: 100, warn })+ totals.add(day, 'a'); totals.add(day, 'b')+ await totals.flush()+ for (const metric of ['c', 'd', 'e', 'f', 'g']) totals.add(day, metric)+ write.mockImplementation(async () => {})+ await totals.flush()+ await totals.flush()+ const written = write.mock.calls.flatMap(([, increments]) => increments.map(i => i.metric))+ expect(written.filter(m => m === 'g')).toEqual([])+ expect(warn).toHaveBeenCalled()+ })++ describe('timer', () => {+ beforeEach(() => { vi.useFakeTimers() })+ afterEach(() => { vi.useRealTimers() })++ it('flushes once a minute and once more on stop, so a clean shutdown loses nothing', async () => {+ const write = vi.fn<Write>(async () => {})+ const totals = setup(write, { firstDelayMs: 60_000 })+ const stop = totals.start()+ totals.add(day, 'm')+ await vi.advanceTimersByTimeAsync(59_000)+ expect(write).not.toHaveBeenCalled()+ await vi.advanceTimersByTimeAsync(1_000)+ expect(write).toHaveBeenCalledOnce()+ totals.add(day, 'm')+ await stop()+ expect(write).toHaveBeenCalledTimes(2)+ await vi.advanceTimersByTimeAsync(120_000)+ expect(write).toHaveBeenCalledTimes(2)+ })++ it('starts its minute at a different moment in each process', async () => {+ const write = vi.fn<Write>(async () => {})+ const totals = setup(write, { firstDelayMs: 80_000 })+ const stop = totals.start()+ totals.add(day, 'm')+ await vi.advanceTimersByTimeAsync(60_000)+ expect(write).not.toHaveBeenCalled()+ await vi.advanceTimersByTimeAsync(20_000)+ expect(write).toHaveBeenCalledOnce()+ await stop()+ })+ })+})diff --git a/backend/src/lib/productUsageRelay.ts b/backend/src/lib/productUsageRelay.tsnew file mode 100644index 000000000..bb820393f--- /dev/null+++ b/backend/src/lib/productUsageRelay.ts@@ -0,0 +1,80 @@+import { randomUUID } from 'node:crypto'+import type { UsageIncrement } from './productUsageWrite.js'++interface Batch { id: string; increments: UsageIncrement[]; attempts: number }++/** Relay connects add to the same few daily totals, so one write per connect made the processes wait on one+ * another's rows (about 350 ms a write when they collided). Here a process counts in memory, keyed by day and+ * name only, and writes the sums once a minute.+ *+ * A batch has an id, and [write] must apply the batch and record that id together, doing nothing for an id it has+ * seen. A batch that fails is held and sent again under the same id, so one whose answer was lost counts once.+ * What a crash loses is what was counted since the last flush: under a minute. A clean stop flushes first.+ * Bounded: past [maxKeys] waiting totals it flushes at once; past twice that, while the database is down, it drops+ * new totals; a batch that failed [retries] times is dropped. Nothing here knows who connected. */+export function createRelayTotals({ write, retries = 5, maxKeys = 1024, intervalMs = 60_000, newId = randomUUID, warn = console.warn,+ firstDelayMs = Math.floor(intervalMs * (0.5 + Math.random() / 2)) }: {+ write: (id: string, increments: UsageIncrement[]) => Promise<void>+ retries?: number; maxKeys?: number; intervalMs?: number; newId?: () => string; warn?: (message: string) => void+ /** The first flush comes earlier by a different amount in each process, so they do not all write together. */+ firstDelayMs?: number+}) {+ let pending = new Map<string, UsageIncrement>()+ let failed: Batch | null = null+ let flushing: Promise<void> | null = null+ let warnedAt = 0+ const complain = (message: string) => {+ if (Date.now() - warnedAt < 60_000) return+ warnedAt = Date.now()+ warn(message)+ }++ async function run(): Promise<void> {+ if (failed) {+ const batch = failed+ try { await write(batch.id, batch.increments); failed = null } catch {+ if (++batch.attempts >= retries) { failed = null; complain('[product-usage] Some relay counts were dropped after repeated write failures.') }+ return+ }+ }+ if (!pending.size) return+ const batch: Batch = { id: newId(), increments: [...pending.values()], attempts: 1 }+ pending = new Map()+ try { await write(batch.id, batch.increments) } catch {+ failed = batch+ complain('[product-usage] Some relay counts are unavailable.')+ }+ }+ function flush(): Promise<void> {+ return flushing ??= run().finally(() => { flushing = null })+ }++ function add(dayUtc: Date, metric: string): void {+ const key = `${dayUtc.getTime()}|${metric}`+ const seen = pending.get(key)+ if (seen) { seen.value++; return }+ if (pending.size >= maxKeys * 2) return complain('[product-usage] Some relay counts were dropped: too many waiting.')+ pending.set(key, { dayUtc, metric, value: 1 })+ if (pending.size >= maxKeys) void flush()+ }++ /** Flushes every [intervalMs]. The returned stop ends the timer and flushes what is left. */+ function start(): () => Promise<void> {+ let timer: NodeJS.Timeout, stopped = false+ const tick = (delay: number) => {+ timer = setTimeout(() => { void flush().finally(() => { if (!stopped) tick(intervalMs) }) }, delay)+ timer.unref()+ }+ tick(firstDelayMs)+ return async () => {+ stopped = true+ clearTimeout(timer)+ // The second pass sends what arrived behind a held batch that the first one retried.+ await flush()+ await flush()+ }+ }++ const reset = () => { pending = new Map(); failed = null }+ return { add, flush, start, reset }+}diff --git a/backend/src/server.ts b/backend/src/server.tsindex df2b66419..e63985f06 100644--- a/backend/src/server.ts+++ b/backend/src/server.ts@@ -29,6 +29,7 @@ import { useSharedRateCounter } from './lib/rateLimit.js'import { createRouteRateLimit } from './middlewares/routeRateLimit.js'import { redisWindowCounter } from './lib/redisRateCounter.js'import { selfProfileFromEnv } from './lib/selfProfile.js'+import { startRelayUsageFlush } from './lib/productUsage.js'import { drainAllSockets, openSocketCount, RELEASE_UPGRADE_SLOT, type SlotSocket } from './lib/wsServer.js'import { endpointOf, refusedUpgrade, startWsCounterLog, watchUpgrade } from './lib/wsAttribution.js'@@ -186,6 +187,8 @@ async function start(): Promise<void> {// Internal mesh listener (Phase 2, MESH_ENABLED) — peers forward here when this instance owns the socket.const meshServer = startMeshProxy()+ // Connect counts are kept in memory and written once a minute; shutdown writes what is left (lib/productUsageRelay.ts).+ const stopRelayUsage = startRelayUsageFlush()let shuttingDown = falseconst shutdown = async (signal: string, exitCode = 0) => {if (shuttingDown) return@@ -210,6 +213,8 @@ async function start(): Promise<void> {await new Promise((resolve) => setTimeout(resolve, 250))// Bounded wait for Fastify to finish its onClose hooks; never block shutdown on it.await Promise.race([fastifyClosed, new Promise((resolve) => setTimeout(resolve, 5_000))])+ // The sockets have closed, so no connect is left to count. Bounded: a slow database must not hold the exit.+ await Promise.race([stopRelayUsage().catch(() => {}), new Promise((resolve) => setTimeout(resolve, 3_000))])// The database stays connected through the drain, for the requests still being served (lib/prisma.ts).await Promise.allSettled([prisma.$disconnect(), closeBus()])process.exit(exitCode)