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..2cc78d75 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,31 @@ 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. After five recorded merges a ticket +accepts no further changing merges (`409`, code `submission_merge_limit`). + #### `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..788303c9 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` 表示同一时刻另一次合并改了这张票,用同样内容重试即可。一张票记录满五次合并后,不再接受会改动它的合并(`409`,`code` 为 `submission_merge_limit`)。 + #### `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..085c2047 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,407 @@ 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. + } + // crash_merge is server-owned; a client cannot plant or replace it. + const incoming = Object.fromEntries( + Object.entries(input.metadata) + .filter(([key, value]) => key !== "crash_merge" && 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 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}` + : 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 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 || 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({ + merged_at: now, + precedence: nativeIncoming ? "incoming_native" : "existing_native", + conflicts: JSON.parse(conflictJson), + ...(conflictsTruncated ? { conflicts_truncated: true } : {}), + ...(newlyDropped.length > 0 ? { dropped_attachments: newlyDropped } : {}), + }); + } + 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.platform === "ios" && 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 +1468,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 +1483,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..3165fdbb 100644 --- a/worker/test/routes.test.ts +++ b/worker/test/routes.test.ts @@ -13352,6 +13352,199 @@ 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); + + // 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 () => { + 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 +13684,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 +14090,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; }