diff --git a/build.gradle b/build.gradle index 2f18349..a227c4d 100644 --- a/build.gradle +++ b/build.gradle @@ -38,4 +38,8 @@ android { minSdkVersion 26 ndk.abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64' } +} + +dependencies { + testImplementation 'junit:junit:4.13.2' } \ No newline at end of file diff --git a/docs/superpowers/plans/2026-11-20-debug-log-view.md b/docs/superpowers/plans/2026-11-20-debug-log-view.md new file mode 100644 index 0000000..83381fb --- /dev/null +++ b/docs/superpowers/plans/2026-11-20-debug-log-view.md @@ -0,0 +1,525 @@ +# Debug Log View Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add a live debug log view with a post-connect debug toggle and periodic native tunnel statistics, so a connected-but-stalled tunnel can be diagnosed without reconnecting. + +**Architecture:** Extend the existing status fragment with a log buffer and controls, expose a native debug flag through JNI, and emit one compact stats line every 5 seconds from the native tunnel loop through the existing `fprintf` → broadcast path. + +**Tech Stack:** Java 8, Android SDK 35 / minSdk 26, platform widgets, JNI, NDK 27, Gradle 8.7, JUnit 4 for the pure-Java log buffer. + +**Spec:** `docs/superpowers/specs/2026-11-20-debug-log-view-design.md` + +## Global Constraints + +- minSdk 26, compileSdk 35, NDK `27.0.12077973`. +- Java source/target compatibility is 8; use `java.time` and anonymous inner classes consistent with the existing code. +- Debug stats are emitted every 5 seconds, plus once immediately when enabled. +- Log buffer is capped at 500 complete lines. +- No persistence, log files, export/share, logcat capture, per-packet traces, or per-profile verbose setting. +- The tunnel password must never appear in logs. +- `./gradlew build` must pass at the end of every task. +- Native log output must continue to use `fprintf(stderr, ...)` so `common.h` routes it through `android_printf` → `IodineClient.log_callback`. + +## Review Focus + +These are the failure modes most likely to bite a user, beyond what the automated tests cover: + +1. **Toggling Debug mid-tunnel** must not restart, disconnect, or perturb the tunnel; only a volatile logging flag changes. +2. **Rotation and reconnect** must keep the checkbox in sync with the native flag, while a new connection clears the buffer and leaves Debug off. +3. **Copy and Clear at any time**, including with an empty buffer or an open partial line, must not crash or lose the open line unexpectedly. +4. **A stalled tunnel** must keep printing stats while traffic is absent; `last-rx` grows, `tx` keeps increasing, and output continues until the client's 60-second shutdown. +5. **Secrets** must not leak: the copied log may contain the domain/server but never the password. + +Each is verified in the manual checklist in Task 3. This project has no Android +UI or native test harness, so those behaviors are checked on-device; the +pure-logic buffer behaviors are unit-tested in Task 1. + +--- + +## Before Task 1 + +- [ ] Commit the approved spec and this plan: + +```bash +git add docs/superpowers/specs/2026-11-20-debug-log-view-design.md docs/superpowers/plans/2026-11-20-debug-log-view.md +git commit -m "docs: add debug log view design and plan" +``` + +--- + +### Task 1: Timestamped, Capped Log Buffer + +**Files:** +- Modify: `build.gradle` +- Create: `src/main/java/org/xapek/andiodine/LogBuffer.java` +- Create: `src/test/java/org/xapek/andiodine/LogBufferTest.java` + +**Interfaces:** +- Consumes: nothing. +- Produces: + - `public LogBuffer(int maxLines, java.util.function.Supplier timestamp)` + - `public static LogBuffer withLocalTime(int maxLines)` + - `public void append(String chunk)` + - `public String getText()` + - `public void clear()` + - `public int getLineCount()` + +- [ ] **Step 1: Add the JUnit test dependency** + +In `build.gradle`, add a top-level dependencies block after the `android { ... }` block: + +```groovy +dependencies { + testImplementation 'junit:junit:4.13.2' +} +``` + +- [ ] **Step 2: Write the failing LogBuffer test** + +Create `src/test/java/org/xapek/andiodine/LogBufferTest.java`: + +```java +package org.xapek.andiodine; + +import org.junit.Test; + +import java.util.function.Supplier; + +import static org.junit.Assert.assertEquals; + +public class LogBufferTest { + private static final Supplier TS = () -> "12:00:00.000"; + + @Test + public void timestampsCompleteLines() { + LogBuffer buffer = new LogBuffer(10, TS); + buffer.append("hello\n"); + assertEquals("12:00:00.000 hello\n", buffer.getText()); + assertEquals(1, buffer.getLineCount()); + } + + @Test + public void assemblesPartialChunksIntoOneLine() { + LogBuffer buffer = new LogBuffer(10, TS); + buffer.append("Autodetect"); + buffer.append("ing"); + buffer.append(".\n"); + assertEquals("12:00:00.000 Autodetecting.\n", buffer.getText()); + assertEquals(1, buffer.getLineCount()); + } + + @Test + public void splitsMultipleLinesInOneChunk() { + LogBuffer buffer = new LogBuffer(10, TS); + buffer.append("one\ntwo\n"); + assertEquals("12:00:00.000 one\n12:00:00.000 two\n", buffer.getText()); + assertEquals(2, buffer.getLineCount()); + } + + @Test + public void dropsOldestLinesAtCapacity() { + LogBuffer buffer = new LogBuffer(2, TS); + buffer.append("one\n"); + buffer.append("two\n"); + buffer.append("three\n"); + assertEquals("12:00:00.000 two\n12:00:00.000 three\n", buffer.getText()); + assertEquals(2, buffer.getLineCount()); + } + + @Test + public void clearRemovesOpenPartialLine() { + LogBuffer buffer = new LogBuffer(10, TS); + buffer.append("partial"); + buffer.clear(); + assertEquals("", buffer.getText()); + assertEquals(0, buffer.getLineCount()); + } + + @Test + public void openLineAppearsWithoutTrailingNewline() { + LogBuffer buffer = new LogBuffer(10, TS); + buffer.append("partial"); + assertEquals("12:00:00.000 partial", buffer.getText()); + assertEquals(1, buffer.getLineCount()); + } +} +``` + +- [ ] **Step 3: Run the test and verify it fails** + +Run: + +```bash +export ANDROID_HOME=/home/arti/Android/Sdk +./gradlew testDebugUnitTest --tests "org.xapek.andiodine.LogBufferTest" +``` + +Expected: compilation failure, `cannot find symbol: class LogBuffer`. + +- [ ] **Step 4: Implement `LogBuffer`** + +Create `src/main/java/org/xapek/andiodine/LogBuffer.java` with the constructor and factory above, plus: + +- A private `List lines` and a `StringBuilder openLine`. +- `append`: ignore null/empty chunks; on the first character of a line append `timestamp.get() + " "`; add ordinary characters to `openLine`; on `\n`, finalize only if `openLine` has content, then trim oldest lines while `lines.size() > maxLines`. +- `getText`: join every completed line with `"\n"`, each followed by `\n`; append `openLine` without a trailing newline if it has content. +- `clear`: clear both `lines` and `openLine`. +- `getLineCount`: `lines.size()` plus 1 when `openLine` has content. +- `withLocalTime`: use `java.time.LocalTime.now()` and `java.time.format.DateTimeFormatter.ofPattern("HH:mm:ss.SSS")`. +- Reject `maxLines < 1` with `IllegalArgumentException`. + +Do not add Android imports; this class must run in a plain JVM test. + +- [ ] **Step 5: Run the test and verify it passes** + +Run: + +```bash +./gradlew testDebugUnitTest --tests "org.xapek.andiodine.LogBufferTest" +``` + +Expected: `BUILD SUCCESSFUL`, 6 tests passed. + +- [ ] **Step 6: Commit** + +```bash +git add build.gradle src/main/java/org/xapek/andiodine/LogBuffer.java src/test/java/org/xapek/andiodine/LogBufferTest.java +git commit -m "feat: add timestamped capped log buffer" +``` + +--- + +### Task 2: Native Debug Flag, Counters, Stats, and JNI + +**Files:** +- Modify: `jni/iodine/src/client.h` +- Modify: `jni/iodine/src/client.c` +- Modify: `jni/iodine-client.c` +- Modify: `src/main/java/org/xapek/andiodine/IodineClient.java` + +**Interfaces:** +- Consumes: the existing `android_printf` path and native client session. +- Produces: + - `void client_set_debug(int enabled)` + - `int client_get_debug(void)` + - `public static native void IodineClient.setDebug(boolean enabled)` + - `public static native boolean IodineClient.isDebug()` + - Stats lines in the form: + `[stats] elapsed=125s tx=612 rx=608 oos=2 servfail=0 last-rx=1s interval=2 lazy=1 resend=0` + +- [ ] **Step 1: Declare the native debug API** + +In `jni/iodine/src/client.h`, add: + +```c +void client_set_debug(int enabled); +int client_get_debug(void); +``` + +- [ ] **Step 2: Move tunnel counters to file scope and add the debug flag** + +In `jni/iodine/src/client.c`: + +- Add near the other file-scope statics: + +```c +static volatile int debug_stats; +static long debug_tx_queries; +static long packrecv; +static long packrecv_oos; +static long packrecv_servfail; +``` + +- Remove the function-local `static long packrecv`, `packrecv_oos`, and `packrecv_servfail` declarations from `tunnel_dns()`. The existing increments and reads keep working against the file-scope variables. +- In `client_init()`, reset `debug_stats`, `debug_tx_queries`, `packrecv`, `packrecv_oos`, and `packrecv_servfail` to 0. +- In `send_query()`, increment `debug_tx_queries` once per query sent. + +- [ ] **Step 3: Add the getter/setter and stats emitter** + +In `client.c`, add: + +```c +void +client_set_debug(int enabled) +{ + enabled = enabled ? 1 : 0; + if (debug_stats == enabled) + return; + debug_stats = enabled; + fprintf(stderr, "[stats] %s\n", enabled ? "enabled" : "disabled"); +} + +int +client_get_debug(void) +{ + return debug_stats; +} +``` + +In `client_tunnel_cb()`, before the `while` loop, add: + +```c +time_t tunnel_start = time(NULL); +time_t last_stats = 0; +debug_tx_queries = 0; +``` + +Resetting `debug_tx_queries` here makes the stats measure tunnel-phase queries, +not the handshake probes that ran before this loop. + +At the top of the `while` loop, before `select()` is prepared, add: + +```c +if (debug_stats) { + time_t now = time(NULL); + if (last_stats == 0 || now - last_stats >= 5) { + last_stats = now; + fprintf(stderr, + "[stats] elapsed=%lds tx=%ld rx=%ld oos=%ld servfail=%ld " + "last-rx=%lds interval=%d lazy=%d resend=%d\n", + (long)(now - tunnel_start), debug_tx_queries, packrecv, + packrecv_oos, packrecv_servfail, + (long)(now - lastdownstreamtime), selecttimeout, lazymode, + outchunkresent); + } +} +``` + +Use `time(NULL)`; `lastdownstreamtime` is already maintained by the tunnel loop. + +- [ ] **Step 4: Add the JNI methods** + +In `jni/iodine-client.c`, add: + +```c +JNIEXPORT void JNICALL Java_org_xapek_andiodine_IodineClient_setDebug( + JNIEnv *env, jclass klass, jboolean enabled) { + client_set_debug(enabled ? 1 : 0); +} + +JNIEXPORT jboolean JNICALL Java_org_xapek_andiodine_IodineClient_isDebug( + JNIEnv *env, jclass klass) { + return client_get_debug() ? JNI_TRUE : JNI_FALSE; +} +``` + +`client.h` is already included by `jni/iodine-client.c`. + +- [ ] **Step 5: Declare the Java native methods** + +In `src/main/java/org/xapek/andiodine/IodineClient.java`, add next to the other native declarations: + +```java +public static native void setDebug(boolean enabled); + +public static native boolean isDebug(); +``` + +- [ ] **Step 6: Build and verify the JNI symbols** + +Run: + +```bash +export ANDROID_HOME=/home/arti/Android/Sdk +./gradlew assembleDebug +LIB=$(find build -name 'libiodine-client.so' | head -1) +nm -D "$LIB" | grep -E 'Java_org_xapek_andiodine_IodineClient_(setDebug|isDebug)' +``` + +Expected: build succeeds and both symbols appear, each on +`Java_org_xapek_andiodine_IodineClient_setDebug` and +`Java_org_xapek_andiodine_IodineClient_isDebug`. + +- [ ] **Step 7: Commit** + +```bash +git add jni/iodine/src/client.h jni/iodine/src/client.c jni/iodine-client.c src/main/java/org/xapek/andiodine/IodineClient.java +git commit -m "feat: add native debug stats flag and JNI hooks" +``` + +--- + +### Task 3: Status Screen Controls and Log Integration + +**Files:** +- Modify: `src/main/res/layout/fragment_status.xml` +- Modify: `src/main/java/org/xapek/andiodine/FragmentStatus.java` +- Modify: `src/main/res/values/strings.xml` +- Modify: `src/main/res/values-de/strings.xml` +- Modify: `src/main/res/values-nl/strings.xml` + +**Interfaces:** +- Consumes: + - `LogBuffer.withLocalTime(500)`, `append`, `getText`, `clear` + - `IodineClient.setDebug(boolean)`, `IodineClient.isDebug()` +- Produces: the user-visible debug view; no later tasks depend on it. + +- [ ] **Step 1: Add the strings** + +In `src/main/res/values/strings.xml`: + +```xml +Debug +Auto-scroll +Copy +Clear +Log copied +``` + +Add German equivalents to `values-de/strings.xml`: +`Debug`, `Autom. scrollen`, `Kopieren`, `Leeren`, `Log kopiert`. + +Add Dutch equivalents to `values-nl/strings.xml`: +`Debug`, `Automatisch scrollen`, `Kopiëren`, `Wissen`, `Log gekopieerd`. + +- [ ] **Step 2: Add the controls to the layout** + +In `fragment_status.xml`, keep the existing `status_message` `TextView`, then insert +two horizontal rows before the inner `LinearLayout` that contains the +`ScrollView` and Close button: + +```xml + + + + + + + + + +