From 6d7fdcbc2b38362a508e27e53cda630019ec15bd Mon Sep 17 00:00:00 2001 From: Volta Date: Tue, 17 Nov 2026 18:43:53 +0800 Subject: [PATCH 1/2] feat(feedback): merge an app exit report and the SDK native record of one crash Hands kept one ticket per submission_id but rejected a second, different report under it. An Android app that reports its own process exits and the SDK's native crash record of the same process therefore produced two tickets, or lost one side's evidence. Server: two different crash/error reports under one explicit submission_id merge into the first ticket when exactly one is the SDK native record (or both are the same native record resent). Native evidence decides classification and signature, other fields from both sides are kept, losing values are recorded under crash_merge, attachments are appended without duplicates, an auto-closed background-kill ticket reopens and its crash alerts fire. Android SDK 0.13.2: HandsFeedback.submit/submitReport accept submissionId; native records carry a per-process processEventId and processStartAt and upload under that id; HandsNativeCrash.uploadPending returns one result per record. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Volta --- .../android/src/main/cpp/hands_native_crash.c | 22 +- .../build/hands/update/HandsFeedback.kt | 54 +- .../build/hands/update/HandsNativeCrash.kt | 104 +++- .../hands/update/HandsNativeCrashTest.kt | 44 ++ docs/public/android-sdk.md | 37 ++ docs/public/public-api-reference.md | 26 +- docs/public/zh/android-sdk.md | 17 + docs/public/zh/public-api-reference.md | 12 +- worker/src/routes/feedback.ts | 481 +++++++++++++++--- worker/test/routes.test.ts | 193 ++++++- 10 files changed, 896 insertions(+), 94 deletions(-) diff --git a/clients/android/src/main/cpp/hands_native_crash.c b/clients/android/src/main/cpp/hands_native_crash.c index cb9543d9..a6e6f70b 100644 --- a/clients/android/src/main/cpp/hands_native_crash.c +++ b/clients/android/src/main/cpp/hands_native_crash.c @@ -49,6 +49,9 @@ static struct sigaction g_previous[sizeof(g_fatal_signals) / sizeof(int)]; static char g_altstack[SIGSTKSZ * 2]; static struct hands_module g_modules[HANDS_MAX_MODULES]; static size_t g_module_count = 0; +/* Per-process identity set once at install; read-only in the handler. */ +static uint64_t g_process_start_at = 0; +static char g_process_event_id[40]; static size_t hands_strlen(const char *text) { size_t n = 0; @@ -409,6 +412,12 @@ static void hands_signal_handler(int signo, siginfo_t *info, void *ucontext) { hands_write_key_dec(fd, "crash_at", ts); hands_write_key_dec(fd, "pid", (uint64_t)getpid()); hands_write_key_dec(fd, "tid", (uint64_t)tid); + if (g_process_start_at != 0) hands_write_key_dec(fd, "process_start_at", g_process_start_at); + if (g_process_event_id[0] != '\0') { + hands_write_text(fd, "process_event_id "); + hands_write_text(fd, g_process_event_id); + hands_write_text(fd, "\n"); + } hands_write_thread_name(fd, tid); hands_write_context(fd, ucontext); hands_write_modules(fd); @@ -431,8 +440,19 @@ static void hands_signal_handler(int signo, siginfo_t *info, void *ucontext) { } JNIEXPORT void JNICALL -Java_build_hands_update_HandsNativeCrash_nativeInstall(JNIEnv *env, jclass clazz, jstring crash_dir) { +Java_build_hands_update_HandsNativeCrash_nativeInstall(JNIEnv *env, jclass clazz, jstring crash_dir, + jlong process_start_at, jstring process_event_id) { (void)clazz; + g_process_start_at = process_start_at > 0 ? (uint64_t)process_start_at : 0; + g_process_event_id[0] = '\0'; + if (process_event_id != NULL) { + const char *event_id = (*env)->GetStringUTFChars(env, process_event_id, NULL); + if (event_id != NULL) { + strncpy(g_process_event_id, event_id, sizeof(g_process_event_id) - 1); + g_process_event_id[sizeof(g_process_event_id) - 1] = '\0'; + (*env)->ReleaseStringUTFChars(env, process_event_id, event_id); + } + } const char *dir = (*env)->GetStringUTFChars(env, crash_dir, NULL); if (dir == NULL) return; strncpy(g_crash_dir, dir, sizeof(g_crash_dir) - 1); diff --git a/clients/android/src/main/kotlin/build/hands/update/HandsFeedback.kt b/clients/android/src/main/kotlin/build/hands/update/HandsFeedback.kt index 1884375e..7dfaff09 100644 --- a/clients/android/src/main/kotlin/build/hands/update/HandsFeedback.kt +++ b/clients/android/src/main/kotlin/build/hands/update/HandsFeedback.kt @@ -56,7 +56,13 @@ class HandsFeedback( * @param attachments up to 9 files; ≤ 10 MB inline, up to 200 MB via * presigned direct-to-R2 upload (server enforced) * @param extras extra metadata merged into the ticket's metadata_json - * @return ticket id + * @param submissionId optional UUID idempotency key. Hands keeps one ticket per + * key: resending the same report returns the first ticket; a + * different crash/error report under the same key is merged into + * that ticket; any other reuse fails with HTTP 409. + * @return ticket id, or "" when the report was merged into an existing ticket whose + * id Hands does not disclose to anonymous clients. Use [submitReport] to + * tell the two apart. */ suspend fun submit( message: String, @@ -64,8 +70,30 @@ class HandsFeedback( contact: String? = null, attachments: List = emptyList(), extras: Map = emptyMap(), - ): String = withContext(Dispatchers.IO) { + submissionId: String? = null, + ): String = submitReport(message, kind, contact, attachments, extras, submissionId).ticketId.orEmpty() + + /** Outcome of [submitReport]. */ + data class Submission( + /** The ticket id; null only when [merged] and the id was not disclosed. */ + val ticketId: String?, + /** True when Hands merged this report into the ticket already holding its submissionId. */ + val merged: Boolean, + ) + + /** Same as [submit], but reports whether the submission was merged. */ + suspend fun submitReport( + message: String, + kind: String = "feedback", + contact: String? = null, + attachments: List = emptyList(), + extras: Map = emptyMap(), + submissionId: String? = null, + ): Submission = withContext(Dispatchers.IO) { require(message.isNotBlank()) { "message must not be blank" } + require(submissionId == null || SUBMISSION_ID_PATTERN.matches(submissionId)) { + "submissionId must be a UUID" + } val selected = attachments.filter { it.isFile }.take(MAX_ATTACHMENTS) for (file in selected) { @@ -121,6 +149,9 @@ class HandsFeedback( if (!contact.isNullOrBlank()) { bodyBuilder.addFormDataPart("contact", contact) } + if (submissionId != null) { + bodyBuilder.addFormDataPart("submission_id", submissionId.lowercase(Locale.ROOT)) + } for (file in inline) { bodyBuilder.addFormDataPart( "attachments", @@ -153,10 +184,8 @@ class HandsFeedback( if (response.code !in 200..299) { throw HandsFeedbackException(response.code, body.take(300)) } - // {"id":"…","status":"open","attachments":N} - JSONObject(body).optString("id").ifBlank { - throw HandsFeedbackException(response.code, "missing ticket id in response") - } + // {"id":"…","status":"open","attachments":N} or {"merged":true[,"id":"…"]} + parseSubmission(response.code, body) } } @@ -248,9 +277,22 @@ class HandsFeedback( } companion object { + internal fun parseSubmission(code: Int, body: String): Submission { + val json = runCatching { JSONObject(body) }.getOrNull() + ?: throw HandsFeedbackException(code, "response is not JSON") + val id = json.optString("id").takeIf(String::isNotBlank) + val merged = json.optBoolean("merged", false) + if (id == null && !merged) throw HandsFeedbackException(code, "missing ticket id in response") + return Submission(ticketId = id, merged = merged) + } + /** Hands Android SDK version reported in feedback/crash metadata. */ const val SDK_VERSION = BuildConfig.HANDS_SDK_VERSION + /** Same shape the server accepts for submission_id (UUID versions 1-8). */ + internal val SUBMISSION_ID_PATTERN = + Regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$") + /** Server-enforced: at most 9 attachments per ticket. */ const val MAX_ATTACHMENTS = 9 diff --git a/clients/android/src/main/kotlin/build/hands/update/HandsNativeCrash.kt b/clients/android/src/main/kotlin/build/hands/update/HandsNativeCrash.kt index ea8104a7..9db46e4d 100644 --- a/clients/android/src/main/kotlin/build/hands/update/HandsNativeCrash.kt +++ b/clients/android/src/main/kotlin/build/hands/update/HandsNativeCrash.kt @@ -4,9 +4,12 @@ import android.app.ActivityManager import android.app.ApplicationExitInfo import android.content.Context import android.os.Build +import android.os.Process +import android.os.SystemClock import org.json.JSONArray import org.json.JSONObject import java.io.File +import java.util.UUID import kotlin.math.abs /** @@ -32,7 +35,27 @@ object HandsNativeCrash { private const val MAX_EXIT_TRACE_BYTES = 2 * 1024 * 1024L @JvmStatic - private external fun nativeInstall(crashDir: String) + private external fun nativeInstall(crashDir: String, processStartAt: Long, processEventId: String) + + /** + * A random UUID for this process, written into any native crash record it + * leaves and used as that crash ticket's `submission_id`. Store it with your + * own launch record: a system-exit report for the same process sent with + * `HandsFeedback.submit(submissionId = it)` then shares one ticket with the + * native crash instead of creating a second one. + */ + @JvmStatic + val processEventId: String by lazy { UUID.randomUUID().toString() } + + /** + * This process's start time, epoch milliseconds (from + * `Process.getStartElapsedRealtime`, so it does not depend on when the SDK + * is installed). Computed once per process. + */ + @JvmStatic + val processStartAt: Long by lazy { + System.currentTimeMillis() - (SystemClock.elapsedRealtime() - Process.getStartElapsedRealtime()) + } internal fun crashDir(context: Context): File = File(context.filesDir, "quiver/native-crashes") @@ -43,7 +66,7 @@ object HandsNativeCrash { val dir = crashDir(context) dir.mkdirs() System.loadLibrary("handscrash") - nativeInstall(dir.absolutePath) + nativeInstall(dir.absolutePath, processStartAt, processEventId) true }.getOrDefault(false) } @@ -57,15 +80,17 @@ object HandsNativeCrash { versionCode: Long? = null, channel: String? = null, clientKey: String? = null, - ) { + ): List { + val results = mutableListOf() val dir = crashDir(context) val records = (dir.listFiles { f -> f.name.endsWith(".qnc") } ?: emptyArray()) .sortedBy { it.name } - if (records.isEmpty()) return + if (records.isEmpty()) return results // Retention: newest survive, same policy as HandsCrash. records.dropLast(MAX_STORED).forEach { it.delete() deleteExitSidecars(it) + results += NativeCrashUpload.discarded() } val pending = records.takeLast(MAX_STORED).mapNotNull { record -> @@ -73,12 +98,13 @@ object HandsNativeCrash { if (parsed == null) { record.delete() deleteExitSidecars(record) + results += NativeCrashUpload.discarded() null } else { PendingRecord(record, parsed) } } - if (pending.isEmpty()) return + if (pending.isEmpty()) return results // Reuse only a sidecar whose recorded QNC coordinates still match. // Valid bindings also reserve the system exit identity so another QNC @@ -129,7 +155,7 @@ object HandsNativeCrash { } val top = parsed.frames.firstOrNull() val result = runCatching { - feedback.submit( + feedback.submitReport( message = buildString { append("Native crash: ").append(parsed.signalName) parsed.threadName?.let { append(" on thread ").append(it) } @@ -137,6 +163,7 @@ object HandsNativeCrash { }, kind = "crash", attachments = attachments, + submissionId = parsed.processEventId, extras = buildMap { put("crash_exception_class", parsed.signalName) put("crash_top_frame", top?.let { "${it.soname}+0x${it.offset.toString(16)}" } ?: "") @@ -150,6 +177,8 @@ object HandsNativeCrash { parsed.signalCode?.let { put("crash_signal_code", it) } parsed.faultAddress?.let { put("crash_fault_addr", "0x${it.toString(16)}") } parsed.pid?.let { put("crash_process_id", it) } + parsed.processStartAt?.let { put("crash_process_start_at", it) } + parsed.processEventId?.let { put("crash_process_event_id", it) } parsed.tid?.let { put("crash_thread_id", it) } parsed.threadName?.let { put("crash_thread_name", it) } parsed.registers["pc"]?.let { put("crash_context_pc", it) } @@ -171,10 +200,60 @@ object HandsNativeCrash { }, ) } - if (result.isSuccess) { + val submission = result.getOrNull() + val outcome = when { + submission == null -> NativeCrashUpload.Outcome.FAILED_WILL_RETRY + submission.merged -> NativeCrashUpload.Outcome.MERGED + else -> NativeCrashUpload.Outcome.UPLOADED + } + if (outcome != NativeCrashUpload.Outcome.FAILED_WILL_RETRY) { record.delete() deleteExitSidecars(record) } + results += NativeCrashUpload( + outcome = outcome, + pid = parsed.pid, + processStartAt = parsed.processStartAt, + processEventId = parsed.processEventId, + crashAt = parsed.crashAt, + exitTimestamp = exitEvidence?.timestamp, + ticketId = submission?.ticketId, + ) + } + return results + } + + /** + * What happened to one pending native crash record in [uploadPending]. + * + * - [Outcome.UPLOADED]: Hands accepted it as ticket [ticketId]; the record is gone. + * - [Outcome.MERGED]: Hands already had a ticket under this record's [processEventId] + * (for example the app reported the same process exit first, or an earlier upload's + * response was lost) and merged this record into it; the record is gone. [ticketId] + * is null unless the app submits as a trusted reporter. + * - [Outcome.FAILED_WILL_RETRY]: the upload failed; the record is kept for the next call. + * - [Outcome.DISCARDED]: the record was unreadable or over the retention limit and was + * deleted without uploading; every other field is null. + * + * [pid], [processStartAt] and [processEventId] identify the crashed process + * ([processEventId] is the value [HandsNativeCrash.processEventId] had in it); + * the last two are null for records written by SDKs before 0.13.2. [crashAt] is + * the crash time (epoch ms) and [exitTimestamp] the matched ApplicationExitInfo + * timestamp, when one was matched. + */ + data class NativeCrashUpload( + val outcome: Outcome, + val pid: Long?, + val processStartAt: Long?, + val processEventId: String?, + val crashAt: Long?, + val exitTimestamp: Long?, + val ticketId: String?, + ) { + enum class Outcome { UPLOADED, MERGED, FAILED_WILL_RETRY, DISCARDED } + + internal companion object { + fun discarded() = NativeCrashUpload(Outcome.DISCARDED, null, null, null, null, null, null) } } @@ -202,6 +281,8 @@ object HandsNativeCrash { val pid: Long?, val tid: Long?, val threadName: String?, + val processStartAt: Long? = null, + val processEventId: String? = null, val arch: String?, val registers: Map, val modules: List, @@ -287,6 +368,8 @@ object HandsNativeCrash { var pid: Long? = null var tid: Long? = null var threadName: String? = null + var processStartAt: Long? = null + var processEventId: String? = null var arch: String? = null val contextFrames = mutableListOf>() val maps = mutableListOf() @@ -312,6 +395,11 @@ object HandsNativeCrash { pid = trimmed.removePrefix("pid ").trim().toLongOrNull() section == "header" && trimmed.startsWith("tid ") -> tid = trimmed.removePrefix("tid ").trim().toLongOrNull() + section == "header" && trimmed.startsWith("process_start_at ") -> + processStartAt = trimmed.removePrefix("process_start_at ").trim().toLongOrNull()?.takeIf { it > 0 } + section == "header" && trimmed.startsWith("process_event_id ") -> + processEventId = trimmed.removePrefix("process_event_id ").trim().lowercase() + .takeIf { HandsFeedback.SUBMISSION_ID_PATTERN.matches(it) } section == "header" && trimmed.startsWith("thread_name_hex ") -> threadName = decodeHexUtf8(trimmed.removePrefix("thread_name_hex ").trim()) section == "registers" && trimmed.startsWith("arch ") -> @@ -355,6 +443,8 @@ object HandsNativeCrash { pid = pid, tid = tid, threadName = threadName, + processStartAt = processStartAt, + processEventId = processEventId, arch = arch, registers = registers, modules = modules, diff --git a/clients/android/src/test/kotlin/build/hands/update/HandsNativeCrashTest.kt b/clients/android/src/test/kotlin/build/hands/update/HandsNativeCrashTest.kt index 91a189d6..cae4c529 100644 --- a/clients/android/src/test/kotlin/build/hands/update/HandsNativeCrashTest.kt +++ b/clients/android/src/test/kotlin/build/hands/update/HandsNativeCrashTest.kt @@ -215,4 +215,48 @@ class HandsNativeCrashTest { ) assertTrue(assignments.isEmpty()) } + + private val minimalFrames = """ + registers + pc 0x70001234 + frames + 0x70001234 context_pc + modules + 0x70000000-0x70010000 1de2e1c0bc046f0654f9fdc8173912735aeea751 /data/app/lib/arm64/libraft.so + maps + 70000000-70010000 r-xp 00000000 00:00 0 /data/app/lib/arm64/libraft.so + """.trimIndent() + + @Test + fun parsesProcessIdentityAndRejectsMalformedEventIds() { + val withIdentity = HandsNativeCrash.parseRecord( + "QNC2\nsignal 11\ncrash_at 1721810000123\npid 4123\nprocess_start_at 1721809990000\n" + + "process_event_id 3F2B9C1E-8D4A-4B6E-9C1F-2A7D5E8B0C34\n" + minimalFrames, + )!! + assertEquals(1721809990000L, withIdentity.processStartAt) + assertEquals("3f2b9c1e-8d4a-4b6e-9c1f-2a7d5e8b0c34", withIdentity.processEventId) + + val malformed = HandsNativeCrash.parseRecord( + "QNC2\nsignal 11\ncrash_at 1\npid 1\nprocess_start_at 0\nprocess_event_id not-a-uuid\n" + minimalFrames, + )!! + assertNull(malformed.processStartAt) + assertNull(malformed.processEventId) + + val legacy = HandsNativeCrash.parseRecord("QNC2\nsignal 11\ncrash_at 1\npid 1\n" + minimalFrames)!! + assertNull(legacy.processEventId) + } + + @Test + fun mergedResponsesAreSuccessWithOrWithoutAnId() { + assertEquals(HandsFeedback.Submission("t1", false), HandsFeedback.parseSubmission(201, """{"id":"t1","status":"open"}""")) + assertEquals(HandsFeedback.Submission(null, true), HandsFeedback.parseSubmission(200, """{"merged":true}""")) + assertEquals(HandsFeedback.Submission("t1", true), HandsFeedback.parseSubmission(200, """{"id":"t1","merged":true}""")) + assertTrue(runCatching { HandsFeedback.parseSubmission(200, """{"status":"open"}""") }.exceptionOrNull() is HandsFeedbackException) + } + + @Test + fun submissionIdPatternMatchesTheServer() { + assertTrue(HandsFeedback.SUBMISSION_ID_PATTERN.matches(java.util.UUID.randomUUID().toString())) + assertTrue(!HandsFeedback.SUBMISSION_ID_PATTERN.matches("3f2b9c1e8d4a4b6e9c1f2a7d5e8b0c34")) + } } diff --git a/docs/public/android-sdk.md b/docs/public/android-sdk.md index 83c89a42..4099209c 100644 --- a/docs/public/android-sdk.md +++ b/docs/public/android-sdk.md @@ -185,6 +185,43 @@ match requires the recorded process id, native-crash reason, and a narrow timestamp window; retained evidence is assigned one-to-one and persisted for deterministic retry rather than guessed from the nearest package exit. +### One ticket per crashed process + +Since `0.13.2`, every native crash record carries the crashed process's +`HandsNativeCrash.processEventId` (a random UUID per process) and +`processStartAt` (epoch ms), and is uploaded with that id as its +`submission_id`. An app that also files its own report for the same process +exit (for example from `ApplicationExitInfo`) should store both values with its +launch record and send its report under the same id: + +```kotlin +// at launch +launchLog.save(pid = Process.myPid(), eventId = HandsNativeCrash.processEventId, + startedAt = HandsNativeCrash.processStartAt) + +// later, reporting that process's exit +HandsFeedback(context, baseUrl, appSlug, clientKey = key).submitReport( + message = "Process exited: ${exit.reason}", + kind = "crash", + extras = exitFields, + submissionId = launch.eventId, +) +``` + +Whichever report arrives second is merged into the first ticket: the native +record decides the crash type and grouping signature, the exit report's fields +are kept alongside, and values that disagree are preserved under the ticket's +`crash_merge` metadata. A ticket auto-closed as a background system kill +reopens when the native record shows it was a real crash. + +`HandsNativeCrash.uploadPending(...)` returns one `NativeCrashUpload` per +record: `UPLOADED` (with `ticketId`), `MERGED` (`ticketId` is null for +anonymous clients), `FAILED_WILL_RETRY` (the record is kept), or `DISCARDED` +(unreadable or over the retention limit). Each carries `pid`, +`processStartAt`, `processEventId`, `crashAt`, and the matched +`exitTimestamp`; records written before 0.13.2 have no process id or start +time. + ### ANRs Since `0.13.0`, on Android 11+ (API 30) the SDK also reports ANRs diff --git a/docs/public/public-api-reference.md b/docs/public/public-api-reference.md index 4e278867..0b1a8737 100644 --- a/docs/public/public-api-reference.md +++ b/docs/public/public-api-reference.md @@ -408,7 +408,7 @@ find and rotate the key in the app's Settings tab or via | Field | Required | Description | |---|---|---| | `message` | Yes | Feedback text (max 10,000 chars). | -| `submission_id` | No | Client-generated UUID for idempotent retries. Keep it fixed for one draft. An exact replay returns the original ticket; reusing it with different content returns `409` (see [`submission_id` conflicts](#submission-id-conflicts)). | +| `submission_id` | No | Client-generated UUID for idempotent retries. Keep it fixed for one draft. An exact replay returns the original ticket; reusing it with different content returns `409` (see [`submission_id` conflicts](#submission-id-conflicts)), except for the crash merge below. | | `kind` | No | `feedback` (default), `bug`, or `crash`. | | `contact` | No | Reply-to handle (email, Raft name, …). | | `metadata` | No | JSON string: `version_name`, `version_code`, `channel`, `device_id`, `device_model`, `os_version`, `arch`, `locale`, plus custom keys. Crash tickets add `crash_exception_class` / `crash_top_frame` (grouping signature). QNC2 Android native reports add `crash_native_frames` (`{ index, offset, soname, build_id, source }`), `crash_registers`, crash thread fields, and `crash_native_images`; server symbolication requires an exact per-frame BuildId match against the build's `native-symbols` asset. API 30+ reports may also include `crash_exit_*` metadata and a retained system trace attachment. | @@ -435,6 +435,30 @@ idempotent replays return the same attachment references, for example: } ``` +#### Crash reports merged under one `submission_id` {#crash-merge} + +Two different `crash`/`error` reports under one `submission_id` merge into the +first ticket instead of returning `409` when exactly one of them is an Android +SDK native crash record (`crash_reason: "native_signal"` with +`crash_native_frames`) — the app's own exit report and the SDK's native record +for the same process — or when both are the same native record +(`crash_process_event_id` equal) resent. The native side decides the +classification fields (`crash_type`, `crash_reason`, exception class, top +frame) and the grouping signature; every other field from both sides is kept, +and the losing side's differing values are recorded under the ticket's +`crash_merge` metadata together with any attachment dropped at the limit. A +ticket auto-closed as a background system kill reopens, and its crash alerts +fire, when the merged report is no longer one. The response is `200`: + +```json +{ "merged": true, "reopened": true, "attachments_added": 1, "attachments_dropped": 0, "idempotent_replay": false } +``` + +`id` is included only for a trusted reporter that owns the ticket. Resending +the same merge returns `idempotent_replay: true` and changes nothing. A `503` +with code `submission_merge_conflict` means another merge changed the ticket at +the same moment; retry with the same body. + #### `submission_id` conflicts {#submission-id-conflicts} A `409` for a reused `submission_id` carries a stable `code`. Branch on `code`, diff --git a/docs/public/zh/android-sdk.md b/docs/public/zh/android-sdk.md index 6b0bcd71..634b6c83 100644 --- a/docs/public/zh/android-sdk.md +++ b/docs/public/zh/android-sdk.md @@ -138,6 +138,23 @@ class App : Application() { 在 Android 11 及以上版本,如果操作系统保留了匹配的 `ApplicationExitInfo` 跟踪和退出描述,SDK 也会附加它们,提供受支持的 tombstone 或中止消息等效信息,无需读取 `/data/tombstones`。匹配要求已记录的进程 ID、原生崩溃原因和较窄的时间窗口;保留的证据一对一分配并持久化,以便确定性重试,而不是猜测最近的应用退出。 +### 同一进程只出一张票 + +从 `0.13.2` 起,每条原生崩溃记录都带上崩溃进程的 `HandsNativeCrash.processEventId`(每个进程一个随机 UUID)和 `processStartAt`(进程启动时间,毫秒),并用这个 ID 作为 `submission_id` 上传。App 如果也会为同一次进程退出自己报一张票(例如读 `ApplicationExitInfo`),在启动时把这两个值和自己的启动记录存在一起,报票时用同一个 ID: + +```kotlin +HandsFeedback(context, baseUrl, appSlug, clientKey = key).submitReport( + message = "Process exited: ${exit.reason}", + kind = "crash", + extras = exitFields, + submissionId = launch.eventId, // 启动时存下的 HandsNativeCrash.processEventId +) +``` + +后到的一方会合并进第一张票:崩溃类型和分组签名以原生记录为准,退出票的字段一并保留,两边不一致的值记在票元数据的 `crash_merge` 里。若这张票原先被当作"后台被系统结束"自动关闭,原生记录证明是真崩溃后会重新打开。 + +`HandsNativeCrash.uploadPending(...)` 为每条记录返回一个 `NativeCrashUpload`:`UPLOADED`(带 `ticketId`)、`MERGED`(匿名客户端拿不到 `ticketId`)、`FAILED_WILL_RETRY`(记录保留,下次重试)或 `DISCARDED`(记录损坏或超出保留上限)。每条都带 `pid`、`processStartAt`、`processEventId`、`crashAt` 和匹配到的 `exitTimestamp`;0.13.2 之前写下的记录没有进程 ID 和启动时间。 + ### ANR 从 `0.13.0` 起,SDK 在 Android 11 及以上版本(API 30)还会上报 ANR(应用无响应导致的终止)。系统从外部杀死进程,进程内不会有代码运行;下次启动时,SDK 读取带 `REASON_ANR` 的 `ApplicationExitInfo` 条目,并将选中的记录提交为 `kind=crash`、`crash_type=anr` 工单。系统 ANR 线程转储会作为附件,并像 Java 崩溃日志一样通过 R8 映射还原。工单按 `ANR@<主线程的第一个应用堆栈帧>` 分组,因此相同卡死可跨构建聚合,也不会与同一帧上的 Java 异常混合。控制台的崩溃页面可按异常、原生崩溃和 ANR 筛选。 diff --git a/docs/public/zh/public-api-reference.md b/docs/public/zh/public-api-reference.md index 820d2d08..062cdc44 100644 --- a/docs/public/zh/public-api-reference.md +++ b/docs/public/zh/public-api-reference.md @@ -282,7 +282,7 @@ X-Hands-Client-Key: qk_... | 字段 | 必填 | 说明 | |---|---|---| | `message` | 是 | 反馈文本,最多 10,000 个字符。 | -| `submission_id` | 否 | 客户端生成的 UUID,用于幂等重试;同一草稿保持不变。完全相同的重放返回原工单,相同 ID 使用不同内容返回 `409`(见 [`submission_id` 冲突](#submission-id-conflicts))。 | +| `submission_id` | 否 | 客户端生成的 UUID,用于幂等重试;同一草稿保持不变。完全相同的重放返回原工单,相同 ID 使用不同内容返回 `409`(见 [`submission_id` 冲突](#submission-id-conflicts)),下面的崩溃合并除外。 | | `kind` | 否 | `feedback`(默认)、`bug` 或 `crash`。 | | `contact` | 否 | 回复联系方式,例如电子邮件或 Raft 名称。 | | `metadata` | 否 | JSON 字符串:`version_name`、`version_code`、`channel`、`device_id`、`device_model`、`os_version`、`arch`、`locale` 及自定义键。崩溃工单附加 `crash_exception_class` / `crash_top_frame`(分组签名)。QNC2 Android 原生报告增加 `crash_native_frames`(`{ index, offset, soname, build_id, source }`)、`crash_registers`、崩溃线程字段及 `crash_native_images`;服务端符号化要求每帧 BuildId 与构建的 `native-symbols` 文件完全匹配。API 30 及以上报告还可能包含 `crash_exit_*` 元数据和保留的系统跟踪附件。 | @@ -304,6 +304,16 @@ X-Hands-Client-Key: qk_... } ``` +#### 同一 `submission_id` 下的崩溃合并 {#crash-merge} + +同一 `submission_id` 下两份不同的 `crash`/`error` 报告,如果恰好一份是 Android SDK 的原生崩溃记录(`crash_reason: "native_signal"` 且带 `crash_native_frames`),即同一进程的 App 退出票和 SDK 原生票;或两份是同一条原生记录(`crash_process_event_id` 相同)的重发,就合并进第一张票,而不返回 `409`。分类字段(`crash_type`、`crash_reason`、异常类、栈顶)和分组签名以原生一方为准;其他字段两边都保留,落选一方不一致的值和因上限丢弃的附件记在票元数据的 `crash_merge` 里。被当作后台系统结束自动关闭的票,合并后不再是这一类时会重新打开并发崩溃通知。响应为 `200`: + +```json +{ "merged": true, "reopened": true, "attachments_added": 1, "attachments_dropped": 0, "idempotent_replay": false } +``` + +只有拥有该票的受信 reporter 会拿到 `id`。重发同一次合并返回 `idempotent_replay: true`,不做任何改动。`503` 且 `code` 为 `submission_merge_conflict` 表示同一时刻另一次合并改了这张票,用同样内容重试即可。 + #### `submission_id` 冲突 {#submission-id-conflicts} 重复使用 `submission_id` 返回的 `409` 带有稳定的 `code`。请根据 `code` 分支处理,不要依赖 `error` 文本;为兼容旧客户端,`error` 文本保持不变。旧版服务器可能只返回 `error`。 diff --git a/worker/src/routes/feedback.ts b/worker/src/routes/feedback.ts index bacc122f..b864ab4e 100644 --- a/worker/src/routes/feedback.ts +++ b/worker/src/routes/feedback.ts @@ -644,11 +644,18 @@ export async function handlePublicFeedbackSubmit(c: Context<{ Bindings: Env }>) })) : null; + const mergeInput = { + app, kind, clientSubmissionId, metadata, attachmentRows, reporterId, + }; if (existingSubmission && submissionFingerprint) { if ( existingSubmission.submission_fingerprint !== submissionFingerprint && !(exitEventSubmissionId && existingSubmission.reporter_id === (reporterId || null)) ) { + if (canMergeCrashSubmission(existingSubmission, mergeInput)) { + const mergedResponse = await mergeCrashSubmission(c, existingSubmission, mergeInput); + if (mergedResponse) return mergedResponse; + } return submissionPayloadMismatch(c, existingSubmission, reporterId); } return feedbackSubmitResponse(c, app, existingSubmission.id, 200, true); @@ -893,6 +900,10 @@ export async function handlePublicFeedbackSubmit(c: Context<{ Bindings: Env }>) }, 409); } if (existing.submission_fingerprint !== submissionFingerprint && !exitEventSubmissionId) { + if (canMergeCrashSubmission(existing, mergeInput)) { + const mergedResponse = await mergeCrashSubmission(c, existing, mergeInput); + if (mergedResponse) return mergedResponse; + } return submissionPayloadMismatch(c, existing, reporterId); } return feedbackSubmitResponse(c, app, existing.id, 200, true); @@ -927,77 +938,9 @@ export async function handlePublicFeedbackSubmit(c: Context<{ Bindings: Env }>) // spikes. Background system kills skip real-time alerts and are reported via // a once-a-day summary instead. if (!externalBuild && (kind === "crash" || kind === "error") && signature && app.org_id && !backgroundSystemKill) { - const orgId = app.org_id; - const eventPrefix = kind === "crash" ? "crash" : "error"; - const alert = async () => { - const nonFatal = kind === "crash" && isNonFatalCrash(metadata); - const base = { - app_slug: app.slug, - signature, - crash_type: crashTypeOf(metadata), - ...(nonFatal ? { fatal: false } : {}), - ticket_id: ticketId, - message: message.slice(0, 300), - version_name: versionName, - version_code: versionCode, - }; - // A fatal ticket announces its group the first time the signature is seen - // fatally, even if non-fatal tickets came first; a non-fatal ticket only - // when the signature has never been seen at all. - const prior = await c.env.DB.prepare( - `SELECT COUNT(*) AS n FROM feedback_tickets t - WHERE app_id = ?1 AND signature = ?2 AND id != ?3 - ${nonFatal ? "" : `AND NOT (kind = 'crash' AND ${NON_FATAL_CRASH_SQL})`} - AND ${feedbackBuildScopeClause("standard")}`, - ) - .bind(app.id, signature, ticketId) - .first<{ n: number }>(); - if ((prior?.n ?? 0) === 0) { - await emitWebhookEvent(c.env, { - orgId, - appId: app.id, - event: `${eventPrefix}:new_group`, - // A signature is first seen once, so (app, signature) is the - // occurrence. This also makes concurrent submissions that both read - // prior.n === 0 collapse instead of double-notifying. - eventId: `${eventPrefix}:new_group:${nonFatal ? "non_fatal:" : ""}${app.id}:${signature}`, - body: base, - }); - return; - } - // Non-fatal crashes are grouped and announced once, but never counted as a spike. - if (nonFatal) return; - const recent = await c.env.DB.prepare( - `SELECT COUNT(*) AS n FROM feedback_tickets t - WHERE app_id = ?1 AND signature = ?2 AND created_at >= ?3 - AND NOT (kind = 'crash' AND ${NON_FATAL_CRASH_SQL}) - AND ${feedbackBuildScopeClause("standard")}`, - ) - .bind(app.id, signature, now - 60 * 60 * 1000) - .first<{ n: number }>(); - const hourCount = recent?.n ?? 0; - if (hourCount === 10 || hourCount === 50 || hourCount === 100) { - await emitWebhookEvent(c.env, { - orgId, - appId: app.id, - event: `${eventPrefix}:spike`, - // The threshold alone is not enough: this fires only when the hourly - // count is exactly 10/50/100, so a later hour returning to 10 is a - // genuine second outbreak. Without the hour bucket that one collides - // with the earlier key and is silently dropped. - eventId: `${eventPrefix}:spike:${app.id}:${signature}:${Math.floor(now / 3_600_000)}:${hourCount}`, - body: { ...base, count_last_hour: hourCount }, - }); - } - }; - const guarded = alert().catch(() => { - // alerting must never fail the submission + await scheduleCrashAlerts(c, app, app.org_id, { + kind, signature, metadata, ticketId, message, versionName, versionCode, now, }); - try { - c.executionCtx.waitUntil(guarded); - } catch { - await guarded; - } } if (app.org_id && !reporterIntegrationId && !externalBuild && !backgroundSystemKill) { @@ -1103,6 +1046,388 @@ function feedbackNewSubmitResponse( }, 201); } +/** + * Crash alerting: webhooks when a signature is first seen or when it spikes. + * Never fails the caller; runs in the background when an execution context + * exists. + */ +async function scheduleCrashAlerts( + c: Context<{ Bindings: Env }>, + app: FeedbackApp, + orgId: string, + input: { + kind: string; + signature: string; + metadata: Record; + ticketId: string; + message: string; + versionName: string | null; + versionCode: number | null; + now: number; + }, +) { + const { kind, signature, metadata, ticketId, message, versionName, versionCode, now } = input; + const eventPrefix = kind === "crash" ? "crash" : "error"; + const alert = async () => { + const nonFatal = kind === "crash" && isNonFatalCrash(metadata); + const base = { + app_slug: app.slug, + signature, + crash_type: crashTypeOf(metadata), + ...(nonFatal ? { fatal: false } : {}), + ticket_id: ticketId, + message: message.slice(0, 300), + version_name: versionName, + version_code: versionCode, + }; + // A fatal ticket announces its group the first time the signature is seen + // fatally, even if non-fatal tickets came first; a non-fatal ticket only + // when the signature has never been seen at all. + const prior = await c.env.DB.prepare( + `SELECT COUNT(*) AS n FROM feedback_tickets t + WHERE app_id = ?1 AND signature = ?2 AND id != ?3 + ${nonFatal ? "" : `AND NOT (kind = 'crash' AND ${NON_FATAL_CRASH_SQL})`} + AND ${feedbackBuildScopeClause("standard")}`, + ) + .bind(app.id, signature, ticketId) + .first<{ n: number }>(); + if ((prior?.n ?? 0) === 0) { + await emitWebhookEvent(c.env, { + orgId, + appId: app.id, + event: `${eventPrefix}:new_group`, + // A signature is first seen once, so (app, signature) is the + // occurrence. This also makes concurrent submissions that both read + // prior.n === 0 collapse instead of double-notifying. + eventId: `${eventPrefix}:new_group:${nonFatal ? "non_fatal:" : ""}${app.id}:${signature}`, + body: base, + }); + return; + } + // Non-fatal crashes are grouped and announced once, but never counted as a spike. + if (nonFatal) return; + const recent = await c.env.DB.prepare( + `SELECT COUNT(*) AS n FROM feedback_tickets t + WHERE app_id = ?1 AND signature = ?2 AND created_at >= ?3 + AND NOT (kind = 'crash' AND ${NON_FATAL_CRASH_SQL}) + AND ${feedbackBuildScopeClause("standard")}`, + ) + .bind(app.id, signature, now - 60 * 60 * 1000) + .first<{ n: number }>(); + const hourCount = recent?.n ?? 0; + if (hourCount === 10 || hourCount === 50 || hourCount === 100) { + await emitWebhookEvent(c.env, { + orgId, + appId: app.id, + event: `${eventPrefix}:spike`, + // The threshold alone is not enough: this fires only when the hourly + // count is exactly 10/50/100, so a later hour returning to 10 is a + // genuine second outbreak. Without the hour bucket that one collides + // with the earlier key and is silently dropped. + eventId: `${eventPrefix}:spike:${app.id}:${signature}:${Math.floor(now / 3_600_000)}:${hourCount}`, + body: { ...base, count_last_hour: hourCount }, + }); + } + }; + const guarded = alert().catch(() => { + // alerting must never fail the submission + }); + try { + c.executionCtx.waitUntil(guarded); + } catch { + await guarded; + } +} + +type CrashMergeInput = { + app: FeedbackApp; + kind: string; + clientSubmissionId: string | null; + metadata: Record; + attachmentRows: Array<{ + r2Key: string; + filename: string; + contentType: string | null; + sizeBytes: number; + inlineFile?: File; + }>; + reporterId: string; +}; + +const MERGEABLE_KINDS = new Set(["crash", "error"]); + +/** Fields that classify and group a crash; native evidence decides them. */ +const CRASH_CLASSIFICATION_KEYS = [ + "crash_type", + "crash_reason", + "crash_exception_class", + "exception_class", + "crash_top_frame", + "top_frame", + "crash_fatal", +] as const; +const MAX_MERGE_RECORDS = 5; +const MAX_MERGE_CONFLICT_BYTES = 8 * 1024; +/** Room past MAX_ATTACHMENTS kept for a native record and its tombstone. */ +const NATIVE_MERGE_ATTACHMENT_RESERVE = 2; + +function isNativeCrashMetadata(metadata: Record): boolean { + return metadata["crash_reason"] === "native_signal" && metadata["crash_native_frames"] !== undefined; +} + +/** + * Two different crash reports under one explicit client submission_id are one + * event seen from two sides only when exactly one of them is the SDK's native + * crash record (the other being the app's own exit report), or when both are + * the same native record resent. Those merge; derived system-kill ids, every + * other kind and every other pairing keep the strict replay/409 contract. + */ +function canMergeCrashSubmission(existing: FeedbackSubmissionRow, input: CrashMergeInput): boolean { + return Boolean(input.clientSubmissionId) + && MERGEABLE_KINDS.has(existing.kind) + && MERGEABLE_KINDS.has(input.kind) + && existing.reporter_id === (input.reporterId || null); +} + +function sameJson(a: unknown, b: unknown): boolean { + return stableJson(a) === stableJson(b); +} + +/** + * Merge a later crash submission into the ticket that owns its submission_id. + * Returns null when the pair is not one event seen from two sides (see + * canMergeCrashSubmission); the caller then answers 409. + * + * - Native evidence wins classification: whichever side is the native record + * supplies crash_type/reason/exception/top frame, and the ticket's signature + * is recomputed from it. Every other field from both sides is kept. + * - A conflicting value never disappears: the losing side's values are kept in + * the ticket's `crash_merge` metadata, with any attachment dropped at the cap. + * - A ticket that was auto-closed as a background system kill and is no longer + * one is reopened, and its crash alerts fire as for a new crash. + * - Attachments not already on the ticket (same filename and size) are added; + * the native side may exceed the ticket limit by its record and tombstone. + * - Re-sending the same merge changes nothing. + * + * Only a trusted reporter that owns the ticket is told its id; an anonymous + * caller learns that the merge happened, never which ticket it joined. + */ +async function mergeCrashSubmission( + c: Context<{ Bindings: Env }>, + existing: FeedbackSubmissionRow, + input: CrashMergeInput, +): Promise { + const { app } = input; + const now = Date.now(); + const current = await c.env.DB.prepare( + `SELECT metadata_json, status, closure_reason, signature, message, version_name, version_code + FROM feedback_tickets WHERE app_id = ?1 AND id = ?2`, + ).bind(app.id, existing.id).first<{ + metadata_json: string | null; + status: string; + closure_reason: string | null; + signature: string | null; + message: string; + version_name: string | null; + version_code: number | null; + }>(); + if (!current) return null; + let currentMetadata: Record = {}; + try { + const parsed = JSON.parse(current.metadata_json ?? "{}"); + if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) currentMetadata = parsed; + } catch { + // An unreadable stored object is treated as empty. + } + const incoming = Object.fromEntries( + Object.entries(input.metadata).filter(([, value]) => value !== null && value !== undefined), + ); + const existingNative = isNativeCrashMetadata(currentMetadata); + const incomingNative = isNativeCrashMetadata(incoming); + const sameNativeRecord = existingNative && incomingNative + && typeof incoming["crash_process_event_id"] === "string" + && incoming["crash_process_event_id"] === currentMetadata["crash_process_event_id"]; + if (existingNative === incomingNative && !sameNativeRecord) return null; + + // primary wins conflicts; secondary fills what primary lacks. + const nativeIncoming = incomingNative && !existingNative; + const { crash_merge: priorMerges, ...currentFields } = currentMetadata; + const primary = nativeIncoming ? incoming : currentFields; + const secondary = nativeIncoming ? currentFields : incoming; + const merged: Record = { ...secondary, ...primary }; + if (existingNative !== incomingNative) { + for (const key of CRASH_CLASSIFICATION_KEYS) { + if (!(key in primary)) delete merged[key]; + } + } + const conflicts: Record = {}; + for (const [key, value] of Object.entries(secondary)) { + if (key === "crash_merge") continue; + if (key in merged && sameJson(merged[key], value)) continue; + conflicts[key] = value; + } + let conflictJson = JSON.stringify(conflicts); + const conflictsTruncated = conflictJson.length > MAX_MERGE_CONFLICT_BYTES; + if (conflictsTruncated) conflictJson = "{}"; + + // Attachments. + const limit = MAX_ATTACHMENTS + (incomingNative && !existingNative ? NATIVE_MERGE_ATTACHMENT_RESERVE : 0); + const added: string[] = []; + const dropped: string[] = []; + for (const [index, attachment] of input.attachmentRows.entries()) { + const duplicate = await c.env.DB.prepare( + `SELECT 1 AS hit FROM feedback_attachments WHERE ticket_id = ?1 AND filename = ?2 AND size_bytes = ?3`, + ).bind(existing.id, attachment.filename, attachment.sizeBytes).first<{ hit: number }>(); + if (duplicate) continue; + const id = crypto.randomUUID(); + const r2Key = attachment.inlineFile + ? `feedback/${app.id}/${existing.id}/merge-${id.slice(0, 8)}-${index}-${attachment.filename}` + : attachment.r2Key; + if (attachment.inlineFile) { + await c.env.APK_BUCKET.put(r2Key, await attachment.inlineFile.arrayBuffer(), { + httpMetadata: { contentType: attachment.contentType || "application/octet-stream" }, + }); + } + const inserted = await c.env.DB.prepare( + `INSERT INTO feedback_attachments + (id, ticket_id, r2_key, filename, content_type, size_bytes, created_at) + SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7 + WHERE NOT EXISTS ( + SELECT 1 FROM feedback_attachments + WHERE ticket_id = ?2 AND filename = ?4 AND size_bytes = ?6 + ) + AND (SELECT COUNT(*) FROM feedback_attachments WHERE ticket_id = ?2) < ?8 + RETURNING id`, + ).bind(id, existing.id, r2Key, attachment.filename, attachment.contentType, attachment.sizeBytes, now, limit) + .first<{ id: string }>(); + if (inserted) { + added.push(attachment.filename); + } else { + if (attachment.inlineFile) await c.env.APK_BUCKET.delete(r2Key).catch(() => {}); + dropped.push(attachment.filename); + } + } + + const fieldsChanged = !sameJson(merged, currentFields); + const changed = fieldsChanged || added.length > 0 || dropped.length > 0; + const mergeRecords = Array.isArray(priorMerges) ? priorMerges.slice(-(MAX_MERGE_RECORDS - 1)) : []; + const finalMetadata: Record = { ...merged }; + if (changed && !sameNativeRecord) { + mergeRecords.push({ + merged_at: now, + precedence: nativeIncoming ? "incoming_native" : "existing_native", + conflicts: JSON.parse(conflictJson), + ...(conflictsTruncated ? { conflicts_truncated: true } : {}), + ...(dropped.length > 0 ? { dropped_attachments: dropped } : {}), + }); + } + if (mergeRecords.length > 0) finalMetadata["crash_merge"] = mergeRecords; + + const kind = existing.kind; + const signature = crashSignature(finalMetadata); + const wasBackgroundKill = current.signature === BACKGROUND_SYSTEM_KILL_SIGNATURE; + const backgroundKill = isBackgroundSystemKill(finalMetadata); + const nextSignature = backgroundKill ? BACKGROUND_SYSTEM_KILL_SIGNATURE : signature; + const reopen = wasBackgroundKill && !backgroundKill + && current.status === "closed" && current.closure_reason === "not_planned"; + + if (changed) { + const updated = await c.env.DB.prepare( + `UPDATE feedback_tickets + SET metadata_json = ?1, signature = ?2, updated_at = ?3, + status = CASE WHEN ?4 THEN 'open' ELSE status END, + closure_reason = CASE WHEN ?4 THEN NULL ELSE closure_reason END + WHERE app_id = ?5 AND id = ?6 AND metadata_json IS ?7 + RETURNING id`, + ).bind( + JSON.stringify(finalMetadata), + nextSignature, + now, + reopen ? 1 : 0, + app.id, + existing.id, + current.metadata_json, + ).first<{ id: string }>(); + if (!updated) { + // A concurrent merge rewrote the ticket first; the client retries and + // its next attempt merges against the new state. + return c.json({ error: "ticket changed during merge; retry", code: "submission_merge_conflict" }, 503); + } + } + + if (fieldsChanged && finalMetadata["crash_native_frames"] !== undefined && !existingNative) { + const run = async () => { + const first = await c.env.DB.prepare( + `SELECT r2_key FROM feedback_attachments WHERE ticket_id = ?1 ORDER BY created_at, id LIMIT 1`, + ).bind(existing.id).first<{ r2_key: string }>(); + await dispatchSymbolication( + c.env, + { id: app.id, platform: app.platform }, + existing.id, + existing.version_code, + finalMetadata, + first?.r2_key ?? null, + ); + }; + try { + c.executionCtx.waitUntil(run()); + } catch { + run().catch(() => {}); + } + } + + // Alerts follow the merged classification: a new signature (or a ticket that + // stopped being a background kill) is announced as any new crash would be. + // Apps that separate external builds decide that at submission time; a merge + // does not re-derive it, so it stays quiet rather than alert on one. + const alertsAllowed = app.feedback_origin_filter_enabled !== 1; + if ( + alertsAllowed && changed && app.org_id && nextSignature && !backgroundKill + && nextSignature !== current.signature + ) { + await scheduleCrashAlerts(c, app, app.org_id, { + kind, + signature: nextSignature, + metadata: finalMetadata, + ticketId: existing.id, + message: current.message, + versionName: current.version_name, + versionCode: current.version_code, + now, + }); + } + if (alertsAllowed && changed && wasBackgroundKill && !backgroundKill && app.org_id && !existing.reporter_id) { + await emitWebhookEvent(c.env, { + orgId: app.org_id, + appId: app.id, + event: "feedback:new", + eventId: `feedback:new:${existing.id}`, + body: { + ticket_id: existing.id, + app_slug: app.slug, + kind, + message: current.message.slice(0, 500), + version_name: current.version_name, + version_code: current.version_code, + attachments: added.length, + reporter_id: null, + reporter_integration_id: null, + author_actor: null, + }, + }).catch(() => {}); + } + + const disclose = Boolean(input.reporterId) && existing.reporter_id === input.reporterId; + return c.json({ + ...(disclose ? { id: existing.id } : {}), + merged: true, + reopened: reopen, + attachments_added: added.length, + attachments_dropped: dropped.length, + idempotent_replay: !changed, + }, 200); +} + /** * 409 for a submission_id that already created a ticket with a different * fingerprint. Callers must have already verified that the existing ticket @@ -1124,6 +1449,14 @@ function submissionPayloadMismatch( }, 409); } +type FeedbackSubmissionRow = { + id: string; + kind: string; + submission_fingerprint: string | null; + reporter_id: string | null; + version_code: number | null; +}; + async function findFeedbackSubmission( db: D1Database, appId: string, @@ -1131,17 +1464,13 @@ async function findFeedbackSubmission( reporterIntegrationId: string | null, ) { return db.prepare( - `SELECT id, submission_fingerprint, reporter_id + `SELECT id, kind, submission_fingerprint, reporter_id, version_code FROM feedback_tickets WHERE app_id = ?1 AND submission_id = ?2 AND reporter_integration_id IS ?3`, ) .bind(appId, submissionId, reporterIntegrationId) - .first<{ - id: string; - submission_fingerprint: string | null; - reporter_id: string | null; - }>(); + .first(); } async function feedbackSubmitResponse( diff --git a/worker/test/routes.test.ts b/worker/test/routes.test.ts index 33e0b2a1..410cd1f2 100644 --- a/worker/test/routes.test.ts +++ b/worker/test/routes.test.ts @@ -13352,6 +13352,194 @@ describe("quiver public API v2 — scope resolution", () => { expect(tickets?.count).toBe(1); }); + describe("feedback: an app exit report and the SDK native record under one submission_id", () => { + const appExit = { + message: "Process exited: signaled", + metadata: { + crash_type: "system_kill", + crash_reason: "system_kill", + crash_exception_class: "SystemKill", + crash_top_frame: "signaled", + crash_exit_reason: "signaled", + crash_exit_reason_code: 2, + crash_exit_importance: 125, + crash_foreground: false, + crash_recent_foreground: false, + crash_process_id: 4123, + crash_process_event_id: "3f2b9c1e-8d4a-4b6e-9c1f-2a7d5e8b0c34", + battery_level: 80, + }, + file: ["app-exit.txt", [1, 2]] as [string, number[]], + }; + const nativeRecord = { + message: "Native crash: SIGSEGV\nat libraft.so+0x1234", + metadata: { + crash_exception_class: "SIGSEGV", + crash_top_frame: "libraft.so+0x1234", + crash_reason: "native_signal", + crash_native_format: "QNC2", + crash_native_frames: JSON.stringify([{ index: 0, soname: "libraft.so", offset: 4660, build_id: "ab" }]), + crash_process_id: 4123, + crash_process_event_id: "3f2b9c1e-8d4a-4b6e-9c1f-2a7d5e8b0c34", + battery_level: 79, + }, + file: ["1721810000123-4123.qnc", [9, 9, 9]] as [string, number[]], + }; + const submissionId = "3f2b9c1e-8d4a-4b6e-9c1f-2a7d5e8b0c34"; + + const setup = async () => { + const env = makeEnv(); + const putCalls: string[] = []; + env.APK_BUCKET = { + put: async (key: string) => { putCalls.push(key); }, + delete: async () => {}, + get: async () => null, + head: async () => null, + }; + const now = Date.now(); + await env.DB.prepare( + `INSERT INTO webhooks (id, org_id, app_id, url, secret, events_json, enabled, created_at, updated_at) + VALUES ('wh-merge', 'default', 'app-scope', 'https://hooks.example.test/merge', 'sec', ?1, 1, ?2, ?2)`, + ).bind(JSON.stringify(["feedback:new", "crash:new_group"]), now).run(); + const { handlePublicFeedbackSubmit } = await import("../src/routes/feedback"); + const submit = async (report: { message: string; metadata: Record; file?: [string, number[]] }, kind = "crash") => { + const form = new FormData(); + form.set("message", report.message); + form.set("kind", kind); + form.set("submission_id", submissionId); + form.set("metadata", JSON.stringify(report.metadata)); + if (report.file) { + form.append("attachments", new File([new Uint8Array(report.file[1])], report.file[0], { type: "application/octet-stream" })); + } + const pending: Promise[] = []; + const response = await handlePublicFeedbackSubmit({ + env, + executionCtx: { waitUntil: (p: Promise) => { pending.push(p.catch(() => {})); } }, + req: { + param: (name: string) => (name === "slug" ? "scope-app" : ""), + header: (name: string) => (name === "X-Quiver-Client-Key" ? "qk_test" : undefined), + query: () => undefined, + formData: async () => form, + raw: { cf: { clientIp: "203.0.113.72" } }, + }, + json: (data: unknown, status = 200) => new Response(JSON.stringify(data), { status }), + } as any); + await Promise.all(pending); + return response; + }; + const ticket = async () => { + const rows = await env.DB.prepare( + "SELECT id, message, status, closure_reason, signature, metadata_json FROM feedback_tickets WHERE app_id = 'app-scope'", + ).all(); + expect(rows.results).toHaveLength(1); + const row = rows.results[0] as any; + const files = await env.DB.prepare( + "SELECT filename FROM feedback_attachments WHERE ticket_id = ?1 ORDER BY filename", + ).bind(row.id).all(); + return { ...row, metadata: JSON.parse(row.metadata_json), files: (files.results as any[]).map((f) => f.filename) }; + }; + const events = async () => { + const { results } = await env.DB.prepare( + "SELECT payload_json FROM webhook_deliveries WHERE webhook_id = 'wh-merge' ORDER BY created_at, rowid", + ).all(); + return (results as any[]).map((r) => JSON.parse(r.payload_json)).map((b: any) => `${b.event}:${b.payload.signature ?? ""}`); + }; + return { submit, ticket, events, putCalls }; + }; + + const expectNativeWins = (t: any) => { + // Native evidence decides classification and grouping in either order. + expect(t.signature).toBe("SIGSEGV@libraft.so+0x1234"); + expect(t.status).toBe("open"); + expect(t.closure_reason).toBeNull(); + expect(t.metadata.crash_type).toBeUndefined(); + expect(t.metadata.crash_reason).toBe("native_signal"); + expect(t.metadata.crash_exception_class).toBe("SIGSEGV"); + // The exit report's own evidence is kept alongside. + expect(t.metadata.crash_exit_reason).toBe("signaled"); + expect(t.metadata.crash_exit_importance).toBe(125); + expect(t.metadata.crash_native_format).toBe("QNC2"); + expect(t.files).toEqual(["1721810000123-4123.qnc", "app-exit.txt"]); + }; + + it("app first: auto-closed as a background kill, reopened and announced when the native record merges", async () => { + const { submit, ticket, events, putCalls } = await setup(); + const first = await submit(appExit); + expect(first.status).toBe(201); + expect(await responseJson(first)).toMatchObject({ signature: "SystemKill@background", status: "closed" }); + expect(await events()).toEqual([]); + + const merged = await submit(nativeRecord); + expect(merged.status).toBe(200); + // Anonymous callers learn that it merged, never which ticket it joined. + expect(await responseJson(merged)).toEqual({ + merged: true, + reopened: true, + attachments_added: 1, + attachments_dropped: 0, + idempotent_replay: false, + }); + const t = await ticket(); + expectNativeWins(t); + expect(t.message).toBe("Process exited: signaled"); + // Losing values are kept, not dropped. + expect(t.metadata.crash_merge).toHaveLength(1); + expect(t.metadata.crash_merge[0]).toMatchObject({ + precedence: "incoming_native", + conflicts: { + crash_type: "system_kill", + crash_reason: "system_kill", + crash_exception_class: "SystemKill", + crash_top_frame: "signaled", + battery_level: 80, + }, + }); + expect(await events()).toEqual(["crash:new_group:SIGSEGV@libraft.so+0x1234", "feedback:new:"]); + + // Re-sending either side changes nothing more. + expect(await responseJson(await submit(nativeRecord))).toMatchObject({ merged: true, idempotent_replay: true }); + // (the identical first report is a plain replay of its own submission) + expect(await responseJson(await submit(appExit))).toMatchObject({ idempotent_replay: true }); + expect((await ticket()).metadata.crash_merge).toHaveLength(1); + expect(putCalls.filter((key) => key.includes("/merge-"))).toHaveLength(1); + expect(await events()).toHaveLength(2); + }); + + it("native first: the later exit report only adds its evidence", async () => { + const { submit, ticket, events } = await setup(); + const first = await submit(nativeRecord); + expect(first.status).toBe(201); + expect(await responseJson(first)).toMatchObject({ signature: "SIGSEGV@libraft.so+0x1234", status: "open" }); + const before = await events(); + expect(before).toContain("crash:new_group:SIGSEGV@libraft.so+0x1234"); + + const merged = await submit(appExit); + expect(merged.status).toBe(200); + expect(await responseJson(merged)).toMatchObject({ merged: true, reopened: false, attachments_added: 1 }); + const t = await ticket(); + expectNativeWins(t); + expect(t.message).toBe("Native crash: SIGSEGV\nat libraft.so+0x1234"); + expect(t.metadata.crash_merge[0]).toMatchObject({ + precedence: "existing_native", + conflicts: { crash_type: "system_kill", crash_exception_class: "SystemKill", battery_level: 80 }, + }); + // Same ticket, same group: no second announcement. + expect(await events()).toEqual(before); + }); + + it("pairs that are not one event seen from two sides are still rejected", async () => { + const { submit } = await setup(); + expect((await submit(appExit)).status).toBe(201); + // Two different non-native reports. + expect((await submit({ ...appExit, message: "another exit", metadata: { ...appExit.metadata, crash_top_frame: "x" } })).status).toBe(409); + // A non-crash kind. + expect((await submit({ message: "hello", metadata: {} }, "feedback")).status).toBe(409); + // A native record of a different process. + expect((await submit(nativeRecord)).status).toBe(200); + expect((await submit({ ...nativeRecord, metadata: { ...nativeRecord.metadata, crash_process_event_id: "00000000-0000-4000-8000-000000000000", crash_top_frame: "libother.so+0x1" } })).status).toBe(409); + }); + }); + it("feedback: submission_id replays the original ticket and rejects payload conflicts", async () => { const env = makeEnv(); const putCalls: string[] = []; @@ -13491,7 +13679,8 @@ describe("quiver public API v2 — scope resolution", () => { expect(noId.status).toBe(201); const noIdAgain = await submit(kill({ crash_exit_event_id: undefined })); expect(noIdAgain.status).toBe(201); - // An explicit submission_id keeps its own strict replay semantics. + // An explicit submission_id keeps its own strict replay semantics: two + // different exit reports are not one event seen from two sides. const explicitId = "33333333-3333-4333-8333-333333333333"; expect((await submit(kill(), { submissionId: explicitId })).status).toBe(201); expect((await submit(kill({ crash_trim: "complete" }), { submissionId: explicitId })).status).toBe(409); @@ -13896,7 +14085,7 @@ describe("quiver public API v2 — scope resolution", () => { env.DB = { ...dbBeforeSubmissionRace, prepare(sql: string) { - if (!preflightMissed && sql.includes("SELECT id, submission_fingerprint, reporter_id")) { + if (!preflightMissed && sql.includes("SELECT id, kind, submission_fingerprint, reporter_id")) { preflightMissed = true; return { bind: () => ({ first: async () => null }) } as any; } From 1d1106cd9f9e19d98bd97a356fb52a119e8a05e2 Mon Sep 17 00:00:00 2001 From: Volta Date: Tue, 17 Nov 2026 18:48:10 +0800 Subject: [PATCH 2/2] fix(feedback): keep crash merges idempotent at the attachment cap and bounded Co-Authored-By: Claude Opus 5.5 Signed-off-by: Volta --- docs/public/public-api-reference.md | 3 ++- docs/public/zh/public-api-reference.md | 2 +- worker/src/routes/feedback.ts | 29 +++++++++++++++++++++----- worker/test/routes.test.ts | 5 +++++ 4 files changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/public/public-api-reference.md b/docs/public/public-api-reference.md index 0b1a8737..2cc78d75 100644 --- a/docs/public/public-api-reference.md +++ b/docs/public/public-api-reference.md @@ -457,7 +457,8 @@ fire, when the merged report is no longer one. The response is `200`: `id` is included only for a trusted reporter that owns the ticket. Resending the same merge returns `idempotent_replay: true` and changes nothing. A `503` with code `submission_merge_conflict` means another merge changed the ticket at -the same moment; retry with the same body. +the same moment; retry with the same body. After five recorded merges a ticket +accepts no further changing merges (`409`, code `submission_merge_limit`). #### `submission_id` conflicts {#submission-id-conflicts} diff --git a/docs/public/zh/public-api-reference.md b/docs/public/zh/public-api-reference.md index 062cdc44..788303c9 100644 --- a/docs/public/zh/public-api-reference.md +++ b/docs/public/zh/public-api-reference.md @@ -312,7 +312,7 @@ X-Hands-Client-Key: qk_... { "merged": true, "reopened": true, "attachments_added": 1, "attachments_dropped": 0, "idempotent_replay": false } ``` -只有拥有该票的受信 reporter 会拿到 `id`。重发同一次合并返回 `idempotent_replay: true`,不做任何改动。`503` 且 `code` 为 `submission_merge_conflict` 表示同一时刻另一次合并改了这张票,用同样内容重试即可。 +只有拥有该票的受信 reporter 会拿到 `id`。重发同一次合并返回 `idempotent_replay: true`,不做任何改动。`503` 且 `code` 为 `submission_merge_conflict` 表示同一时刻另一次合并改了这张票,用同样内容重试即可。一张票记录满五次合并后,不再接受会改动它的合并(`409`,`code` 为 `submission_merge_limit`)。 #### `submission_id` 冲突 {#submission-id-conflicts} diff --git a/worker/src/routes/feedback.ts b/worker/src/routes/feedback.ts index b864ab4e..085c2047 100644 --- a/worker/src/routes/feedback.ts +++ b/worker/src/routes/feedback.ts @@ -1239,8 +1239,10 @@ async function mergeCrashSubmission( } catch { // An unreadable stored object is treated as empty. } + // crash_merge is server-owned; a client cannot plant or replace it. const incoming = Object.fromEntries( - Object.entries(input.metadata).filter(([, value]) => value !== null && value !== undefined), + Object.entries(input.metadata) + .filter(([key, value]) => key !== "crash_merge" && value !== null && value !== undefined), ); const existingNative = isNativeCrashMetadata(currentMetadata); const incomingNative = isNativeCrashMetadata(incoming); @@ -1279,6 +1281,13 @@ async function mergeCrashSubmission( `SELECT 1 AS hit FROM feedback_attachments WHERE ticket_id = ?1 AND filename = ?2 AND size_bytes = ?3`, ).bind(existing.id, attachment.filename, attachment.sizeBytes).first<{ hit: number }>(); if (duplicate) continue; + const count = await c.env.DB.prepare( + `SELECT COUNT(*) AS n FROM feedback_attachments WHERE ticket_id = ?1`, + ).bind(existing.id).first<{ n: number }>(); + if ((count?.n ?? 0) >= limit) { + dropped.push(attachment.filename); + continue; + } const id = crypto.randomUUID(); const r2Key = attachment.inlineFile ? `feedback/${app.id}/${existing.id}/merge-${id.slice(0, 8)}-${index}-${attachment.filename}` @@ -1308,9 +1317,19 @@ async function mergeCrashSubmission( } } + const priorRecords: Array> = Array.isArray(priorMerges) ? priorMerges : []; + // An attachment already recorded as dropped is not news on a resend. + const priorDropped = new Set(priorRecords.flatMap((record) => + Array.isArray(record?.dropped_attachments) ? record.dropped_attachments as string[] : [])); + const newlyDropped = dropped.filter((name) => !priorDropped.has(name)); const fieldsChanged = !sameJson(merged, currentFields); - const changed = fieldsChanged || added.length > 0 || dropped.length > 0; - const mergeRecords = Array.isArray(priorMerges) ? priorMerges.slice(-(MAX_MERGE_RECORDS - 1)) : []; + const changed = fieldsChanged || added.length > 0 || newlyDropped.length > 0; + if (changed && !sameNativeRecord && priorRecords.length >= MAX_MERGE_RECORDS) { + // One event has two sides; a ticket that keeps changing under merges is + // not that, and a known submission_id must not be an unmetered write path. + return c.json({ error: "submission_id merge limit reached", code: "submission_merge_limit" }, 409); + } + const mergeRecords = priorRecords.slice(-(MAX_MERGE_RECORDS - 1)); const finalMetadata: Record = { ...merged }; if (changed && !sameNativeRecord) { mergeRecords.push({ @@ -1318,7 +1337,7 @@ async function mergeCrashSubmission( precedence: nativeIncoming ? "incoming_native" : "existing_native", conflicts: JSON.parse(conflictJson), ...(conflictsTruncated ? { conflicts_truncated: true } : {}), - ...(dropped.length > 0 ? { dropped_attachments: dropped } : {}), + ...(newlyDropped.length > 0 ? { dropped_attachments: newlyDropped } : {}), }); } if (mergeRecords.length > 0) finalMetadata["crash_merge"] = mergeRecords; @@ -1380,7 +1399,7 @@ async function mergeCrashSubmission( // stopped being a background kill) is announced as any new crash would be. // Apps that separate external builds decide that at submission time; a merge // does not re-derive it, so it stays quiet rather than alert on one. - const alertsAllowed = app.feedback_origin_filter_enabled !== 1; + const alertsAllowed = !(app.platform === "ios" && app.feedback_origin_filter_enabled === 1); if ( alertsAllowed && changed && app.org_id && nextSignature && !backgroundKill && nextSignature !== current.signature diff --git a/worker/test/routes.test.ts b/worker/test/routes.test.ts index 410cd1f2..3165fdbb 100644 --- a/worker/test/routes.test.ts +++ b/worker/test/routes.test.ts @@ -13525,6 +13525,11 @@ describe("quiver public API v2 — scope resolution", () => { }); // Same ticket, same group: no second announcement. expect(await events()).toEqual(before); + + // crash_merge is server-owned: a resend cannot plant or replace it. + const planted = await submit({ ...nativeRecord, metadata: { ...nativeRecord.metadata, crash_merge: "x" } }); + expect(await responseJson(planted)).toMatchObject({ merged: true, idempotent_replay: true }); + expect((await ticket()).metadata.crash_merge).toHaveLength(1); }); it("pairs that are not one event seen from two sides are still rejected", async () => {