Skip to content

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.

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.ts
index 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.ts
index 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.ts
index 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_000
type 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): P
where: { 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))) return
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 = false
const 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)