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.

Recover measurement delivery and verify missing paths (#1360)

Deea163b57c1e27
diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.ts
index f21945876..40d0ccb60 100644
--- a/backend/src/lib/productUsage.test.ts
+++ b/backend/src/lib/productUsage.test.ts
@@ -70,6 +70,21 @@ describe('preference', () => {
})
describe('aggregate ingestion', () => {
+ it('rechecks permission after waiting for another report without caching an enabled choice', async () => {
+ let release!: () => void
+ const gate = new Promise<void>(resolve => { release = resolve })
+ db.$transaction.mockImplementationOnce(async fn => { await gate; return fn(db) })
+ const first = ingestProductUsage('first-account', report, now)
+ const queued = ingestProductUsage('opted-out-while-queued', { ...report, id: 'another-receipt' }, now)
+ await Promise.resolve()
+ expect(db.$transaction).toHaveBeenCalledOnce()
+ db.productUsagePreference.findUnique.mockResolvedValueOnce({ enabled: true, revision: 0 })
+ .mockResolvedValueOnce({ enabled: false, revision: 1 })
+ release()
+ expect(await first).toEqual({ accepted: true })
+ expect(await queued).toMatchObject({ accepted: false, reason: 'CHOICE_CHANGED' })
+ expect(db.productUsageReceipt.create).toHaveBeenCalledOnce()
+ })
it('stores only totals and an unlinked receipt, in one transaction', async () => {
expect(await ingestProductUsage('private-account', report, now)).toEqual({ accepted: true })
expect(db.$transaction).toHaveBeenCalledOnce()
diff --git a/backend/src/lib/productUsage.ts b/backend/src/lib/productUsage.ts
index a19857c63..0ba02a59d 100644
--- a/backend/src/lib/productUsage.ts
+++ b/backend/src/lib/productUsage.ts
@@ -8,8 +8,10 @@ import { prisma } from './prisma.js'
import { PRODUCT_USAGE_DAYS, type ProductUsageChoice, type ProductUsageReport } from '../types/productUsage.js'
import { ACTIVITY_DAYS, type ActivitySurface } from '../types/productUsageActivity.js'
import { incrementUsageTotals, type UsageIncrement } from './productUsageWrite.js'
+import { createUsageAdmission } from './productUsageAdmission.js'
const DAY = 86_400_000
+const writeUsage = createUsageAdmission()
type Db = Pick<Prisma.TransactionClient, 'productUsagePreference' | 'analyticsMachineState'>
/** A pre-existing off choice wins over the new default. Never cache an enabled answer. */
@@ -67,33 +69,35 @@ async function ingestCounters(report: SetupUsageReport & { revision?: number; co
// October's delivery audit found aggregate write conflicts. Retry the entire transaction,
// including permission, without extending a slow request or waiting a full client interval.
// At most four attempts; only fast conflicts may start another within the first second.
- const started = performance.now()
- for (let attempt = 0; ; attempt++) {
- try {
- return await prisma.$transaction(async tx => {
- if (userId) {
- const choice = await productUsageChoice(userId, tx)
- if (!choice.enabled || choice.revision !== report.revision) return { accepted: false, reason: 'CHOICE_CHANGED', ...choice }
- }
- // Receipt and increments commit together; a lost HTTP response can be retried with the same id.
- await tx.productUsageReceipt.create({ data: {
- id: report.id, expiresAt: new Date(Date.parse(report.day) + (PRODUCT_USAGE_DAYS + 1) * DAY),
- } })
- await incrementUsageTotals(tx, increments)
- return { accepted: true }
- })
- } catch (error) {
- // A competing first writer of a daily total is not a duplicate unless its receipt committed.
- const code = (error as { code?: string } | null)?.code
- if (code === 'P2002'
- && await prisma.productUsageReceipt.findUnique({ where: { id: report.id }, select: { id: true } })) return { accepted: true }
- const pause = 25 * 2 ** attempt + Math.floor(Math.random() * 50)
- if ((code !== 'P2034' && code !== 'P2002') || attempt >= 3
- || performance.now() - started + pause >= 1000) throw error
- await delay(pause)
- if (performance.now() - started >= 1000) throw error
+ return writeUsage(async () => {
+ const started = performance.now()
+ for (let attempt = 0; ; attempt++) {
+ try {
+ return await prisma.$transaction(async tx => {
+ if (userId) {
+ const choice = await productUsageChoice(userId, tx)
+ if (!choice.enabled || choice.revision !== report.revision) return { accepted: false, reason: 'CHOICE_CHANGED', ...choice }
+ }
+ // Receipt and increments commit together; a lost HTTP response can be retried with the same id.
+ await tx.productUsageReceipt.create({ data: {
+ id: report.id, expiresAt: new Date(Date.parse(report.day) + (PRODUCT_USAGE_DAYS + 1) * DAY),
+ } })
+ await incrementUsageTotals(tx, increments)
+ return { accepted: true }
+ })
+ } catch (error) {
+ // A competing first writer of a daily total is not a duplicate unless its receipt committed.
+ const code = (error as { code?: string } | null)?.code
+ if (code === 'P2002'
+ && await prisma.productUsageReceipt.findUnique({ where: { id: report.id }, select: { id: true } })) return { accepted: true }
+ const pause = 25 * 2 ** attempt + Math.floor(Math.random() * 50)
+ if ((code !== 'P2034' && code !== 'P2002') || attempt >= 3
+ || performance.now() - started + pause >= 1000) throw error
+ await delay(pause)
+ if (performance.now() - started >= 1000) throw error
+ }
}
- }
+ })
}
export type RelayUsageMetric = 'relay_desktop_opens' | 'relay_tui_opens' | 'relay_mobile_opens' | 'relay_web_opens'
diff --git a/backend/src/lib/productUsageAdmission.test.ts b/backend/src/lib/productUsageAdmission.test.ts
new file mode 100644
index 000000000..b7f6c2d1d
--- /dev/null
+++ b/backend/src/lib/productUsageAdmission.test.ts
@@ -0,0 +1,43 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { createUsageAdmission } from './productUsageAdmission.js'
+
+afterEach(() => vi.useRealTimers())
+const deferred = () => { let resolve!: () => void; const promise = new Promise<void>(r => { resolve = r }); return { promise, resolve } }
+
+it('serializes concurrent transactions in arrival order and releases after an error', async () => {
+ const write = createUsageAdmission(), gate = deferred(), seen: number[] = []
+ const first = write(async () => { seen.push(1); await gate.promise; throw new Error('fixture failure') })
+ const failure = expect(first).rejects.toThrow('fixture failure')
+ const second = write(async () => { seen.push(2); return 'second' })
+ const third = write(async () => { seen.push(3); return 'third' })
+ await Promise.resolve()
+ expect(seen).toEqual([1])
+ gate.resolve()
+ await failure
+ expect(await Promise.all([second, third])).toEqual(['second', 'third'])
+ expect(seen).toEqual([1, 2, 3])
+})
+
+it('bounds waiting work and rejects overflow without executing it', async () => {
+ const write = createUsageAdmission(1), gate = deferred(), skipped = vi.fn()
+ const first = write(() => gate.promise), second = write(async () => 'accepted')
+ await expect(write(skipped)).rejects.toMatchObject({ code: 'USAGE_BUSY' })
+ expect(skipped).not.toHaveBeenCalled()
+ gate.resolve()
+ expect(await second).toBe('accepted'); await first
+})
+
+it('removes expired waiters; no late write, timer, or stuck admission remains', async () => {
+ vi.useFakeTimers()
+ const write = createUsageAdmission(2, 1000), gate = deferred(), skipped = vi.fn()
+ const first = write(() => gate.promise)
+ const expired = expect(write(skipped)).rejects.toMatchObject({ code: 'USAGE_BUSY' })
+ await vi.advanceTimersByTimeAsync(1000)
+ await expired
+ const next = write(async () => 'next')
+ gate.resolve(); await first
+ expect(await next).toBe('next')
+ expect(skipped).not.toHaveBeenCalled()
+ expect(vi.getTimerCount()).toBe(0)
+ expect(await write(async () => 'idle')).toBe('idle')
+})
diff --git a/backend/src/lib/productUsageAdmission.ts b/backend/src/lib/productUsageAdmission.ts
new file mode 100644
index 000000000..1159d30df
--- /dev/null
+++ b/backend/src/lib/productUsageAdmission.ts
@@ -0,0 +1,31 @@
+/** Daily totals are shared rows. Serializing this process's report transactions avoids
+ * making its own uploads fight over them. Other processes still use transaction retries.
+ * Only measurement waits here: bounded RAM, two seconds of queueing, no product traffic. */
+export function createUsageAdmission(maxQueued = 32, waitMs = 2000) {
+ type Waiter = { ready: (release: () => void) => void; timer: ReturnType<typeof setTimeout> }
+ const waiting = new Set<Waiter>()
+ let busy = false
+ const unavailable = () => Object.assign(new Error('Usage measurement busy'), { code: 'USAGE_BUSY' })
+ function release(): void {
+ const next = waiting.values().next().value
+ if (!next) { busy = false; return }
+ waiting.delete(next)
+ clearTimeout(next.timer)
+ next.ready(release)
+ }
+ function acquire(): Promise<() => void> {
+ if (!busy) { busy = true; return Promise.resolve(release) }
+ if (waiting.size >= maxQueued) return Promise.reject(unavailable())
+ return new Promise((ready, reject) => {
+ const waiter: Waiter = { ready, timer: setTimeout(() => {
+ waiting.delete(waiter)
+ reject(unavailable())
+ }, waitMs) }
+ waiting.add(waiter)
+ })
+ }
+ return async function write<T>(operation: () => Promise<T>): Promise<T> {
+ const done = await acquire()
+ try { return await operation() } finally { done() }
+ }
+}
diff --git a/backend/src/routes/productUsage.test.ts b/backend/src/routes/productUsage.test.ts
index a91be7b3f..4bd09127b 100644
--- a/backend/src/routes/productUsage.test.ts
+++ b/backend/src/routes/productUsage.test.ts
@@ -40,6 +40,13 @@ it('does not reflect a database error or report contents', async () => {
expect(response.statusCode).toBe(503)
expect(response.body).not.toContain('PRIVATE_CANARY')
})
+it('returns retryable backpressure without admitting another database write', async () => {
+ methods.ingestProductUsage.mockRejectedValue({ code: 'USAGE_BUSY', message: 'PRIVATE_CANARY' })
+ const response = await submit(good)
+ expect(response.statusCode).toBe(429)
+ expect(response.json().error.code).toBe('USAGE_BUSY')
+ expect(response.body).not.toContain('PRIVATE_CANARY')
+})
it.each([['P2034', 'USAGE_WRITE_CONFLICT'], ['P2002', 'USAGE_WRITE_CONFLICT'],
['P2028', 'USAGE_TRANSACTION_FAILED'], ['PRIVATE_CANARY', 'USAGE_UNAVAILABLE']])(
'returns only the fixed delivery category for storage error %s', async (code, expected) => {
diff --git a/backend/src/routes/productUsage.ts b/backend/src/routes/productUsage.ts
index fd6763998..dc520b23b 100644
--- a/backend/src/routes/productUsage.ts
+++ b/backend/src/routes/productUsage.ts
@@ -79,6 +79,7 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {
catch (error) {
// A fixed category can diagnose delivery without exposing database errors or report contents.
const storageCode = (error as { code?: unknown } | null)?.code
+ if (storageCode === 'USAGE_BUSY') return sendError(reply, 'Usage measurement busy', 'USAGE_BUSY', 429)
const code = storageCode === 'P2034' || storageCode === 'P2002' ? 'USAGE_WRITE_CONFLICT'
: storageCode === 'P2028' ? 'USAGE_TRANSACTION_FAILED' : 'USAGE_UNAVAILABLE'
return sendError(reply, 'Usage report unavailable', code, 503)
diff --git a/backend/src/types/productHealthContract.ts b/backend/src/types/productHealthContract.ts
index 09c293863..865626f81 100644
--- a/backend/src/types/productHealthContract.ts
+++ b/backend/src/types/productHealthContract.ts
@@ -34,6 +34,7 @@ export const RESUME_REASONS = ['runtime_unavailable', 'saved_state_missing', 'pr
export type ResumeReason = typeof RESUME_REASONS[number]
export const PRODUCT_HEALTH_METRICS = [
...CLI_REPORT_FAILURES.map(reason => `health_cli_report_failure_${reason}` as const),
+ ...CLI_REPORT_FAILURES.map(reason => `health_desktop_report_failure_${reason}` as const),
...HEALTH_SOURCES.flatMap(source => RESUME_REASONS.map(reason => `request_${source}_resume_reason_${reason}` as const)),
// hn's (`tui`) come through its daemon's queue, under that daemon's context, never one of their own.
...(['cli', 'desktop', 'tui'] as const).flatMap(surface => HEALTH_MEASURES.map(m => `health_${surface}_${m}` as const)),
diff --git a/cli/src/lib/appProductUsageReport.spec.ts b/cli/src/lib/appProductUsageReport.spec.ts
index cf430708a..a54af7056 100644
--- a/cli/src/lib/appProductUsageReport.spec.ts
+++ b/cli/src/lib/appProductUsageReport.spec.ts
@@ -1,7 +1,7 @@
import { readFileSync } from 'node:fs'
import { expect, it } from 'vitest'
import { isAppProductUsageReport } from './appProductUsageReport.js'
-import { HEALTH_MEASURES } from './productHealthContract.js'
+import { HEALTH_MEASURES, CLI_REPORT_FAILURES } from './productHealthContract.js'
import { PRODUCT_USAGE_UI_METRICS } from './productUsageContract.js'
const native = JSON.parse(readFileSync(new URL('../../../tests/fixtures/desktop-product-usage-report.json', import.meta.url), 'utf8'))
@@ -12,7 +12,8 @@ it('admits the current native report and every fixed Desktop health measure', ()
expect(isAppProductUsageReport(native)).toBe(true)
const dart = readFileSync(new URL('../../../desktop/lib/measurement/product_health_contract.dart', import.meta.url), 'utf8')
const wires = [...dart.split('class ProductUsageContext')[0].matchAll(/\('([^']+)'\)/g)].map(match => match[1])
- expect(wires).toEqual([...HEALTH_MEASURES])
+ expect(wires.toSorted()).toEqual([...HEALTH_MEASURES,
+ ...CLI_REPORT_FAILURES.map(reason => `report_failure_${reason}`)].toSorted())
for (const wire of wires) expect(isAppProductUsageReport({ ...native, counters: { [`health_desktop_${wire}`]: 1000 } })).toBe(true)
for (const platform of ['macos', 'windows', 'linux', 'other']) for (const channel of ['production', 'development']) {
expect(isAppProductUsageReport({ ...native, context: { ...native.context, platform, channel, release: 'unknown' } })).toBe(true)
diff --git a/cli/src/lib/appProductUsageReport.ts b/cli/src/lib/appProductUsageReport.ts
index d03f68039..3d050c756 100644
--- a/cli/src/lib/appProductUsageReport.ts
+++ b/cli/src/lib/appProductUsageReport.ts
@@ -1,4 +1,4 @@
-import { cleanUsageContext, HEALTH_MEASURES } from './productHealthContract.js'
+import { cleanUsageContext, HEALTH_MEASURES, CLI_REPORT_FAILURES } from './productHealthContract.js'
import { PRODUCT_USAGE_UI_METRICS, type ProductUsageReport } from './productUsageContract.js'
// hn's counts reach the daemon's own queue only through hn's `product_observe`; no app can file them.
@@ -6,6 +6,7 @@ const uiMetrics = new Set<string>(PRODUCT_USAGE_UI_METRICS.filter(metric => !met
const desktopMetrics = new Set<string>([
...PRODUCT_USAGE_UI_METRICS.filter(metric => metric.startsWith('ui_desktop_')),
...HEALTH_MEASURES.map(measure => `health_desktop_${measure}`),
+ ...CLI_REPORT_FAILURES.map(reason => `health_desktop_report_failure_${reason}`),
])
const fields = new Set(['schemaVersion', 'revision', 'id', 'day', 'counters', 'context'])
const contextFields = new Set(['surface', 'release', 'platform', 'channel'])
diff --git a/cli/src/lib/productHealthContract.ts b/cli/src/lib/productHealthContract.ts
index 09c293863..865626f81 100644
--- a/cli/src/lib/productHealthContract.ts
+++ b/cli/src/lib/productHealthContract.ts
@@ -34,6 +34,7 @@ export const RESUME_REASONS = ['runtime_unavailable', 'saved_state_missing', 'pr
export type ResumeReason = typeof RESUME_REASONS[number]
export const PRODUCT_HEALTH_METRICS = [
...CLI_REPORT_FAILURES.map(reason => `health_cli_report_failure_${reason}` as const),
+ ...CLI_REPORT_FAILURES.map(reason => `health_desktop_report_failure_${reason}` as const),
...HEALTH_SOURCES.flatMap(source => RESUME_REASONS.map(reason => `request_${source}_resume_reason_${reason}` as const)),
// hn's (`tui`) come through its daemon's queue, under that daemon's context, never one of their own.
...(['cli', 'desktop', 'tui'] as const).flatMap(surface => HEALTH_MEASURES.map(m => `health_${surface}_${m}` as const)),
diff --git a/desktop/lib/api/api_client.dart b/desktop/lib/api/api_client.dart
index f31100660..784fe5507 100644
--- a/desktop/lib/api/api_client.dart
+++ b/desktop/lib/api/api_client.dart
@@ -7,6 +7,8 @@ import '../core/config.dart';
import '../core/models.dart';
import '../core/test_run.dart';
import '../logging/http_log.dart';
+import '../measurement/product_report_failure.dart';
+import '../measurement/product_health_contract.dart';
import '../viewer/device_ack.dart';
import '../viewer/device_log.dart';
import '../viewer/device_log_sync.dart'
@@ -119,16 +121,40 @@ class ApiClient {
Future<Map<String, dynamic>> productUsageReport(
Map<String, dynamic> report,
) async {
- final response = await _dio.post(
- '/api/product-usage/report',
- data: report,
- options: Options(
- headers: {'x-adapter-local': '1'},
- receiveTimeout: const Duration(seconds: 5),
- sendTimeout: const Duration(seconds: 5),
- ),
- );
- return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
+ try {
+ final response = await _dio.post(
+ '/api/product-usage/report',
+ data: report,
+ options: Options(
+ headers: {'x-adapter-local': '1'},
+ receiveTimeout: const Duration(seconds: 5),
+ sendTimeout: const Duration(seconds: 5),
+ ),
+ );
+ final body = response.data;
+ if (response.statusCode != 200 ||
+ body is! Map ||
+ body['success'] != true ||
+ body['data'] is! Map) {
+ throw ProductReportFailure.http(
+ response.statusCode,
+ body is Map && body['error'] is Map
+ ? (body['error'] as Map)['code']
+ : null,
+ );
+ }
+ return Map<String, dynamic>.from(body['data'] as Map);
+ } on DioException catch (error) {
+ throw ProductReportFailure(switch (error.type) {
+ DioExceptionType.connectionTimeout ||
+ DioExceptionType.sendTimeout ||
+ DioExceptionType.receiveTimeout =>
+ ProductHealthMeasure.reportFailureTimeout,
+ DioExceptionType.connectionError =>
+ ProductHealthMeasure.reportFailureUnreachable,
+ _ => ProductHealthMeasure.reportFailureOther,
+ });
+ }
}
Future<void> productUsageFeedback(String answer, String receipt) async {
diff --git a/desktop/lib/measurement/desktop_setup_report.dart b/desktop/lib/measurement/desktop_setup_report.dart
new file mode 100644
index 000000000..f7b562019
--- /dev/null
+++ b/desktop/lib/measurement/desktop_setup_report.dart
@@ -0,0 +1,23 @@
+import 'package:dio/dio.dart';
+
+import 'product_report_failure.dart';
+import 'setup_transport.dart';
+
+/// Keep the shared credential-free transport intact. Desktop's collector only
+/// needs to know whether retrying this immutable packet can ever succeed.
+Future<Map<String, dynamic>> sendDesktopSetupMeasurement(
+ String base,
+ Map<String, dynamic> report,
+) async {
+ try {
+ return await sendSetupMeasurement(base, report);
+ } on DioException catch (error) {
+ final body = error.response?.data;
+ throw ProductReportFailure.http(
+ error.response?.statusCode,
+ body is Map && body['error'] is Map
+ ? (body['error'] as Map)['code']
+ : null,
+ );
+ }
+}
diff --git a/desktop/lib/measurement/product_health_contract.dart b/desktop/lib/measurement/product_health_contract.dart
index d24f68c9e..be4fedc82 100644
--- a/desktop/lib/measurement/product_health_contract.dart
+++ b/desktop/lib/measurement/product_health_contract.dart
@@ -5,6 +5,16 @@ enum ProductHealthMeasure {
reportRejected('report_rejected'),
reportExpired('report_expired'),
reportLate('report_late'),
+ reportFailureInvalid('report_failure_invalid'),
+ reportFailureTooLarge('report_failure_too_large'),
+ reportFailureAuth('report_failure_auth'),
+ reportFailureRateLimited('report_failure_rate_limited'),
+ reportFailureTimeout('report_failure_timeout'),
+ reportFailureUnreachable('report_failure_unreachable'),
+ reportFailureWriteConflict('report_failure_write_conflict'),
+ reportFailureTransaction('report_failure_transaction'),
+ reportFailureServer('report_failure_server'),
+ reportFailureOther('report_failure_other'),
queueCapped('queue_capped'),
observationOverflow('observation_overflow'),
uncleanRestart('unclean_restart'),
diff --git a/desktop/lib/measurement/product_measurement.dart b/desktop/lib/measurement/product_measurement.dart
index b5943552d..d661ba5cc 100644
--- a/desktop/lib/measurement/product_measurement.dart
+++ b/desktop/lib/measurement/product_measurement.dart
@@ -4,6 +4,7 @@ import 'dart:math';
import 'package:flutter/foundation.dart';
import 'product_health_contract.dart';
+import 'product_report_failure.dart';
export 'product_health_contract.dart';
enum ProductFlow {
@@ -482,8 +483,25 @@ class ProductMeasurement extends ChangeNotifier {
_clear('ui');
_clear('setup');
}
- } catch (_) {
- if (channel == 'ui') health(ProductHealthMeasure.reportFailed);
+ } catch (error) {
+ // A late failure belongs to the old choice/account, just like a late success.
+ if (_disposed ||
+ (channel == 'setup'
+ ? epoch != _guestEpoch
+ : epoch != _accountEpoch))
+ continue;
+ if (channel == 'ui') {
+ health(ProductHealthMeasure.reportFailed);
+ health(
+ error is ProductReportFailure
+ ? error.measure
+ : ProductHealthMeasure.reportFailureOther,
+ );
+ }
+ // A malformed/oversized immutable packet will never succeed. Drop only that
+ // packet so new counts can proceed; transient failures keep the same receipt.
+ if (error is ProductReportFailure && error.permanent)
+ _pending.remove(channel);
/* Same receipt on the next timer. No logs, aggressive retry, or product failure. */
}
}
diff --git a/desktop/lib/measurement/product_report_failure.dart b/desktop/lib/measurement/product_report_failure.dart
new file mode 100644
index 000000000..1748da6eb
--- /dev/null
+++ b/desktop/lib/measurement/product_report_failure.dart
@@ -0,0 +1,64 @@
+import 'product_health_contract.dart';
+
+/// Only a fixed category survives the transport boundary. Never retain the
+/// response, URL, error message, credentials, or report in a collector error.
+class ProductReportFailure implements Exception {
+ const ProductReportFailure(this.measure, {this.permanent = false});
+ final ProductHealthMeasure measure;
+ final bool permanent;
+
+ factory ProductReportFailure.http(int? status, Object? code) {
+ if (status == 504 && code == 'BACKEND_TIMEOUT') {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureTimeout,
+ );
+ }
+ if (status == 502 && code == 'BACKEND_UNREACHABLE') {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureUnreachable,
+ );
+ }
+ if (status == 401 ||
+ status == 403 ||
+ code == 'AUTH_UNAVAILABLE' ||
+ code == 'ACCOUNT_CHANGED') {
+ return const ProductReportFailure(ProductHealthMeasure.reportFailureAuth);
+ }
+ if (status == 400) {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureInvalid,
+ permanent: true,
+ );
+ }
+ if (status == 413) {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureTooLarge,
+ permanent: true,
+ );
+ }
+ if (status == 429) {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureRateLimited,
+ );
+ }
+ if (status == 503 && code == 'USAGE_WRITE_CONFLICT') {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureWriteConflict,
+ );
+ }
+ if (status == 503 && code == 'USAGE_TRANSACTION_FAILED') {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureTransaction,
+ );
+ }
+ if (status != null && status >= 500 && status < 600) {
+ return const ProductReportFailure(
+ ProductHealthMeasure.reportFailureServer,
+ );
+ }
+ return const ProductReportFailure(ProductHealthMeasure.reportFailureOther);
+ }
+
+ @override
+ String toString() => 'Product usage delivery unavailable';
+}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 9d7e9bc36..0c04e4a53 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -2,7 +2,7 @@ import '../measurement/product_measurement.dart';
import '../measurement/product_runtime_health.dart';
import '../measurement/product_connections.dart';
import '../core/crash_log.dart';
-import '../measurement/setup_transport.dart';
+import '../measurement/desktop_setup_report.dart';
import 'attached_task_delivery.dart';
import 'task_route.dart';
import '../core/permission_modes.dart';
@@ -3305,7 +3305,7 @@ class AppNotifier extends ChangeNotifier {
)
: null,
sendSetup: (report) =>
- sendSetupMeasurement(this.config.apiBaseUrl, report),
+ sendDesktopSetupMeasurement(this.config.apiBaseUrl, report),
);
productConnections = ProductConnections(this.productMeasurement);
this.productMeasurement.addListener(_measurementChoiceChanged);
@@ -6132,6 +6132,10 @@ class AppNotifier extends ChangeNotifier {
}
info = fresh;
availableUpdate = info;
+ // Start the existing last-run flag while download I/O is in progress. Saving
+ // it only just before exit races the asynchronous disk write on fast updates.
+ // No reporting or disk flush is awaited by the update.
+ productRuntimeHealth?.expectUpdate(info.version);
// One notify per whole percent. Dio reports every chunk, and each notify
// rebuilds the whole app shell (the banner lives in its ListenableBuilder),
// so a 45 MB build would repaint thousands of times for a bar 200px wide.
@@ -6153,12 +6157,12 @@ class AppNotifier extends ChangeNotifier {
);
if (staged == null) {
finish(ProductOutcome.failed);
+ productRuntimeHealth?.cancelUpdate();
updateError = 'Could not download and verify Harness ${info.version}.';
return false;
}
// The next consented launch can confirm the version; never wait for reporting.
finish(ProductOutcome.ok);
- productRuntimeHealth?.expectUpdate(info.version);
finishApply = productMeasurement.begin(ProductFlow.updateApply);
final applied = await updater.applyStaged(staged, selfPid: pid);
finishApply(applied ? ProductOutcome.ok : ProductOutcome.failed);
diff --git a/desktop/test/product_delivery_test.dart b/desktop/test/product_delivery_test.dart
new file mode 100644
index 000000000..c712d705e
--- /dev/null
+++ b/desktop/test/product_delivery_test.dart
@@ -0,0 +1,202 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/api/api_client.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/measurement/product_measurement.dart';
+import 'package:harness/measurement/product_report_failure.dart';
+
+void main() {
+ late HttpServer server;
+ late StreamSubscription<HttpRequest> listener;
+ late ApiClient api;
+ late ProductMeasurement usage;
+ late List<Map<String, dynamic>> attempts, accepted;
+ var status = 200;
+ String? code;
+ Completer<void>? hold;
+ setUp(() async {
+ attempts = [];
+ accepted = [];
+ status = 200;
+ code = null;
+ hold = null;
+ server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+ listener = server.listen((request) async {
+ final report = jsonDecode(
+ await utf8.decoder.bind(request).join(),
+ ) as Map<String, dynamic>;
+ expect(request.uri.path, '/api/product-usage/report');
+ expect(request.headers.value('x-adapter-local'), '1');
+ attempts.add(report);
+ final responseStatus = status, responseCode = code;
+ await hold?.future;
+ if (responseStatus == 200) accepted.add(report);
+ request.response
+ ..statusCode = responseStatus
+ ..headers.contentType = ContentType.json
+ ..write(
+ jsonEncode(
+ responseStatus == 200
+ ? {
+ 'success': true,
+ 'data': {'accepted': true},
+ }
+ : {
+ 'success': false,
+ 'error': {
+ 'code': responseCode,
+ 'message': 'PRIVATE_ERROR_CANARY',
+ },
+ },
+ ),
+ );
+ await request.response.close();
+ });
+ api = ApiClient(
+ config: AppConfig(
+ apiBaseUrl: 'http://unused.invalid',
+ localCliBaseUrl: 'http://127.0.0.1:${server.port}',
+ ),
+ session: AuthSession(),
+ );
+ usage = ProductMeasurement(
+ surface: 'desktop',
+ automatic: false,
+ context: ProductUsageContext(
+ release: '1.2.77',
+ platform: 'macos',
+ production: true,
+ ),
+ sendSetup: (_) async =>
+ throw StateError('No signed-out request expected'),
+ );
+ usage.account(
+ 'PRIVATE_ACCOUNT_CANARY',
+ choice: () async => {'enabled': true, 'revision': 0},
+ send: api.productUsageReport,
+ );
+ await usage.flush();
+ });
+ tearDown(() async {
+ usage.dispose();
+ if (hold != null && !hold!.isCompleted) hold!.complete();
+ await listener.cancel();
+ await server.close(force: true);
+ });
+ Map<String, int> totals() {
+ final result = <String, int>{};
+ for (final r in accepted) {
+ for (final e in (r['counters'] as Map).entries) {
+ result[e.key as String] = (result[e.key] ?? 0) + (e.value as int);
+ }
+ }
+ return result;
+ }
+
+ for (final (http, reason) in [(400, 'invalid'), (413, 'too_large')]) {
+ test(
+ 'HTTP $http discards only the rejected packet and later reports progress',
+ () async {
+ status = http;
+ usage.begin(ProductFlow.viewerLoad)(ProductOutcome.ok);
+ await usage.flush();
+ final rejected = attempts.single;
+ status = 200;
+ usage.begin(ProductFlow.connectUser)(ProductOutcome.ok);
+ await usage.flush();
+ expect(attempts, hasLength(2));
+ expect(attempts.last['id'], isNot(rejected['id']));
+ expect(totals()['ui_desktop_connect_user_ok'], 1);
+ expect(totals()['ui_desktop_viewer_load_ok'], isNull);
+ expect(totals()['health_desktop_report_failure_$reason'], 1);
+ expect(jsonEncode(accepted), isNot(contains('PRIVATE_')));
+ },
+ );
+ }
+
+ test('transient conflict retries the same receipt and counters before draining new work', () async {
+ status = 503;
+ code = 'USAGE_WRITE_CONFLICT';
+ usage.begin(ProductFlow.viewerLoad)(ProductOutcome.ok);
+ await usage.flush();
+ final first = jsonEncode(attempts.single);
+ usage.begin(ProductFlow.connectUser)(ProductOutcome.ok);
+ status = 200;
+ await usage.flush();
+ expect(jsonEncode(attempts.last), first);
+ await usage.flush();
+ expect(totals()['ui_desktop_viewer_load_ok'], 1);
+ expect(totals()['ui_desktop_connect_user_ok'], 1);
+ expect(totals()['health_desktop_report_failure_write_conflict'], 1);
+ expect(jsonEncode(accepted), isNot(contains('PRIVATE_')));
+ });
+
+ test(
+ 'a failure from an old account cannot enter the next account counters',
+ () async {
+ status = 400;
+ hold = Completer<void>();
+ usage.begin(ProductFlow.viewerLoad)(ProductOutcome.ok);
+ final flushing = usage.flush();
+ while (attempts.isEmpty) {
+ await Future<void>.delayed(const Duration(milliseconds: 1));
+ }
+ usage.account(
+ 'OTHER_PRIVATE_ACCOUNT',
+ choice: () async => {'enabled': true, 'revision': 0},
+ send: api.productUsageReport,
+ );
+ usage.savedChoice({'enabled': true, 'revision': 0});
+ usage.begin(ProductFlow.connectUser)(ProductOutcome.ok);
+ hold!.complete();
+ hold = null;
+ await flushing;
+ status = 200;
+ await usage.flush();
+ expect(totals()['ui_desktop_connect_user_ok'], 1);
+ expect(totals()['health_desktop_report_failed'], isNull);
+ expect(totals()['health_desktop_report_failure_invalid'], isNull);
+ },
+ );
+
+ for (final (http, errorCode, measure) in [
+ (401, 'PRIVATE_CODE', ProductHealthMeasure.reportFailureAuth),
+ (403, null, ProductHealthMeasure.reportFailureAuth),
+ (429, 'USAGE_BUSY', ProductHealthMeasure.reportFailureRateLimited),
+ (504, 'BACKEND_TIMEOUT', ProductHealthMeasure.reportFailureTimeout),
+ (502, 'BACKEND_UNREACHABLE', ProductHealthMeasure.reportFailureUnreachable),
+ (
+ 503,
+ 'USAGE_TRANSACTION_FAILED',
+ ProductHealthMeasure.reportFailureTransaction,
+ ),
+ (500, 'PRIVATE_CODE', ProductHealthMeasure.reportFailureServer),
+ (409, 'ACCOUNT_CHANGED', ProductHealthMeasure.reportFailureAuth),
+ (409, 'PRIVATE_CODE', ProductHealthMeasure.reportFailureOther),
+ ]) {
+ test(
+ 'HTTP $http/$errorCode retains only its fixed delivery category',
+ () async {
+ status = http;
+ code = errorCode;
+ await expectLater(
+ api.productUsageReport({'counters': {}}),
+ throwsA(
+ isA<ProductReportFailure>()
+ .having((e) => e.measure, 'category', measure)
+ .having((e) => e.permanent, 'retryable', false)
+ .having(
+ (e) => e.toString(),
+ 'safe error',
+ isNot(contains('PRIVATE')),
+ ),
+ ),
+ );
+ },
+ );
+ }
+}
diff --git a/desktop/test/product_feedback_test.dart b/desktop/test/product_feedback_test.dart
index 955754276..f4c6a1eab 100644
--- a/desktop/test/product_feedback_test.dart
+++ b/desktop/test/product_feedback_test.dart
@@ -1,8 +1,72 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/shared/widgets/product_feedback.dart';
+import 'package:harness/measurement/product_measurement.dart';
+import 'package:harness/measurement/task_feedback.dart';
void main() {
+ testWidgets(
+ 'task outcome dialog emits fixed outcomes and exposure without task context',
+ (tester) async {
+ final answers = <String>[], reports = <Map<String, dynamic>>[];
+ final measurement = ProductMeasurement(
+ surface: 'desktop',
+ automatic: false,
+ context: ProductUsageContext(
+ release: '1.2.77',
+ platform: 'macos',
+ production: true,
+ ),
+ sendSetup: (_) async => {},
+ );
+ addTearDown(measurement.dispose);
+ measurement.account(
+ 'PRIVATE_ACCOUNT',
+ choice: () async => {'enabled': true, 'revision': 0},
+ send: (report) async {
+ reports.add(report);
+ return {'accepted': true};
+ },
+ );
+ await measurement.flush();
+ await tester.pumpWidget(
+ const MaterialApp(home: Scaffold(body: Text('Fixture'))),
+ );
+ final shown = showTaskFeedback(
+ tester.element(find.text('Fixture')),
+ choice: () async => {'enabled': true, 'revision': 0},
+ send: (answer, _) async => answers.add(answer),
+ measurement: measurement,
+ );
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Completed'));
+ await tester.pumpAndSettle();
+ await measurement.flush();
+ expect(answers, ['completed']);
+ final counters = reports
+ .expand((r) => (r['counters'] as Map).entries)
+ .toList();
+ expect(
+ counters.any(
+ (e) =>
+ e.key == 'health_desktop_feedback_outcome_shown' && e.value == 1,
+ ),
+ true,
+ );
+ expect(
+ counters.any(
+ (e) =>
+ e.key == 'health_desktop_feedback_outcome_answered' &&
+ e.value == 1,
+ ),
+ true,
+ );
+ expect(reports.toString(), isNot(contains('PRIVATE')));
+ Navigator.of(tester.element(find.text('Completed'))).pop();
+ await tester.pumpAndSettle();
+ await shown;
+ },
+ );
testWidgets(
'counts exposure, successful answer, and dismissal without task context',
(tester) async {
diff --git a/desktop/test/setup_measurement_transport_test.dart b/desktop/test/setup_measurement_transport_test.dart
index 662207412..451bcdd52 100644
--- a/desktop/test/setup_measurement_transport_test.dart
+++ b/desktop/test/setup_measurement_transport_test.dart
@@ -3,8 +3,48 @@ import 'dart:io';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/measurement/setup_transport.dart';
+import 'package:harness/measurement/product_report_failure.dart';
+import 'package:harness/measurement/desktop_setup_report.dart';
void main() {
+ test(
+ 'a permanent setup rejection is classified without keeping its body',
+ () async {
+ final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+ final received = server.first.then((request) async {
+ await request.drain<void>();
+ request.response
+ ..statusCode = 400
+ ..headers.contentType = ContentType.json
+ ..write(
+ jsonEncode({
+ 'error': {
+ 'message': 'PRIVATE_CANARY',
+ 'code': 'INVALID_SETUP_REPORT',
+ },
+ }),
+ );
+ await request.response.close();
+ });
+ try {
+ await expectLater(
+ sendDesktopSetupMeasurement('http://127.0.0.1:${server.port}', {}),
+ throwsA(
+ isA<ProductReportFailure>()
+ .having((e) => e.permanent, 'permanent', true)
+ .having(
+ (e) => e.toString(),
+ 'safe',
+ isNot(contains('PRIVATE')),
+ ),
+ ),
+ );
+ await received;
+ } finally {
+ await server.close(force: true);
+ }
+ },
+ );
test('signed-out transport uses only a loopback fixture and sends no credentials', () async {
final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
final received = server.first.then((request) async {
diff --git a/desktop/test/terminal_composer_test.dart b/desktop/test/terminal_composer_test.dart
index e8f8026e2..929253c2d 100644
--- a/desktop/test/terminal_composer_test.dart
+++ b/desktop/test/terminal_composer_test.dart
@@ -44,6 +44,7 @@ AppNotifier _notifier({required bool local}) {
Future<TerminalSession> _liveSession(
List<String> outbound, {
bool live = true,
+ List<Map<String, dynamic>>? messages,
}) async {
const streamId = '00112233-4455-6677-8899-aabbccddeeff';
Object? openRequestId;
@@ -52,11 +53,15 @@ Future<TerminalSession> _liveSession(
agentId: 'a1',
agentName: 'a1',
engineId: 'claude',
+ client: const TerminalClientDescriptor(kind: 'desktop', name: 'Fixture'),
send: (type, payload) async {
// The session ignores a `terminal_ready` whose requestId is not the one it sent, so the
// handshake has to answer the real request rather than a placeholder.
if (type == 'terminal_open') openRequestId = payload['requestId'];
- if (type == 'message') outbound.add(payload['content'] as String);
+ if (type == 'message') {
+ outbound.add(payload['content'] as String);
+ messages?.add(Map.of(payload));
+ }
return true;
},
sendBinary: (_) async => true,
@@ -299,8 +304,9 @@ void main() {
testWidgets('Enter sends the message and clears the box', (tester) async {
final outbound = <String>[];
+ final messages = <Map<String, dynamic>>[];
final app = _notifier(local: false);
- final session = await _liveSession(outbound);
+ final session = await _liveSession(outbound, messages: messages);
await tester.pumpWidget(_host(app, session));
await tester.pump();
@@ -313,6 +319,7 @@ void main() {
await tester.pump(const Duration(milliseconds: 12));
expect(outbound, ['deploy it']);
+ expect(messages.single['usageIntent'], 'interactive');
expect(
tester.widget<TextField>(find.byType(TextField)).controller?.text,
'',
diff --git a/desktop/test/update_progress_test.dart b/desktop/test/update_progress_test.dart
index 31fcb09c5..92373eb9d 100644
--- a/desktop/test/update_progress_test.dart
+++ b/desktop/test/update_progress_test.dart
@@ -9,6 +9,16 @@ import 'package:harness/state/app_state.dart';
import 'package:harness/update/desktop_updater.dart';
import 'package:harness/update/manual_update_check.dart';
import 'package:harness/widgets/update_notice.dart';
+import 'package:harness/measurement/product_runtime_health.dart';
+
+class _UpdateHealth extends ProductRuntimeHealth {
+ _UpdateHealth(super.measurement);
+ String? expected;
+ @override
+ void expectUpdate(String version) => expected = version;
+ @override
+ void cancelUpdate() => expected = null;
+}
/// A 45 MB build on a slow link used to look like a hang: the band said
/// "Installing…" behind an indeterminate bar. The manifest carries the exact
@@ -57,6 +67,22 @@ void main() {
expect(installer.progress, isNotNull, reason: 'the hook must be passed in');
}
+ test(
+ 'records the next-version flag during download and clears a failed stage',
+ () async {
+ app.productRuntimeHealth?.dispose();
+ final health = _UpdateHealth(app.productMeasurement);
+ app.productRuntimeHealth = health;
+ final installing = app.installAvailableUpdate();
+ await Future<void>.delayed(Duration.zero);
+ expect(installer.progress, isNotNull);
+ expect(health.expected, _update.version);
+ installer.staged.complete(null);
+ await installing;
+ expect(health.expected, isNull);
+ },
+ );
+
testWidgets('the banner counts the download, then goes quiet to unpack', (
tester,
) async {
diff --git a/docs/product-measurement.md b/docs/product-measurement.md
index 9925313f3..9af19b3ee 100644
--- a/docs/product-measurement.md
+++ b/docs/product-measurement.md
@@ -77,7 +77,8 @@ Desktop's only new disk state is the last consented run's version, clean-exit/up
revision and a local-only account-scope hash. One serialized asynchronous write plus one latest
pending value bounds disk work. It is cleared on sign-out/off and never enters a report. An unclean
run can mean a force quit or power loss, and only becomes observable if the app returns. Update
-flags are best effort; analytics never delays exit. Gateway work-day flags expire after 35 days;
+flags are best effort; the existing expected-version flag starts during download so its disk write
+does not begin only at exit, and failed downloads clear it. Analytics never delays exit. Gateway work-day flags expire after 35 days;
a local yes/no marker prevents an old installation from being counted as newly activated again.
All new fields are allowlisted; no URLs, raw error strings, stack traces, device specifications,
task/session IDs or content are accepted. Feedback is voluntary and shown/answered/dismissed
@@ -102,6 +103,9 @@ invalid, too-large, authentication, rate-limit, timeout, unreachable, write-conf
server and other categories. A transaction failure does not by itself prove a timeout. No raw error
message, database detail, URL or unknown error code is collected. These diagnostics share the same
privacy choice and bounded queue, so a delivery outage can delay its own diagnostic counters.
+Desktop now splits failed delivery attempts into the same fixed categories. A permanently invalid
+or oversized packet is discarded so it cannot block newer reports; transient errors retry the
+same receipt. Delayed errors after a choice or account change are discarded.
The local app proxy accepts only bounded UI counts, or Desktop health/UI counts with the exact
public release, OS and channel context. It does not accept daemon counters or arbitrary context.
@@ -143,6 +147,10 @@ immutable-report retry. Receipts prevent both immediate and later retries from c
Reports update their counters and separate margins in one Mongo update command inside
that transaction. A partial write aborts the receipt and all counts; no per-report body is stored.
This shortens shared-row contention without adding a daemon timer or delaying product actions.
+Each backend process admits one aggregate report transaction at a time, with at most 32 waiting
+reports and a two-second queue deadline. Overflow returns a retryable busy response. Permission
+is checked inside the transaction after admission, including every conflict retry. Other server
+processes can still contend; this does not promise zero delivery failures.
The public `/api/health` response includes validated release tag/SHA coordinates so a successful
image build can be distinguished from the version actually serving requests.
diff --git a/tests/fixtures/desktop-product-usage-report.json b/tests/fixtures/desktop-product-usage-report.json
index 81e51df32..a07b871dc 100644
--- a/tests/fixtures/desktop-product-usage-report.json
+++ b/tests/fixtures/desktop-product-usage-report.json
@@ -17,6 +17,7 @@
"health_desktop_first_response_under_1m": 1,
"health_desktop_frame_under_16ms": 1000,
"health_desktop_feedback_outcome_shown": 1,
- "health_desktop_report_failed": 1
+ "health_desktop_report_failed": 1,
+ "health_desktop_report_failure_write_conflict": 1
}
}