Skip to content

Build your personal knowledge base with Trilium Notes

feat(mobile): answer Android local API requests natively instead of via the service worker

Elian Doran45d66b30bcd9
diff --git a/.claude/skills/developing-capacitor-mobile/SKILL.md b/.claude/skills/developing-capacitor-mobile/SKILL.md
index 721d4ea504..6509b38e83 100644
--- a/.claude/skills/developing-capacitor-mobile/SKILL.md
+++ b/.claude/skills/developing-capacitor-mobile/SKILL.md
@@ -1,6 +1,6 @@
---
name: developing-capacitor-mobile
-description: Use when working on the Trilium mobile app (`apps/mobile`, Capacitor for Android/iOS) or on the standalone code paths that only run inside it — request routing on `capacitor://` vs `https://localhost`, the iOS fetch/XHR/image/stylesheet interceptors, the Android native streaming HTTP proxy (`TriliumWebViewClient`), the `NativeHttpHandler` sync transport, downloads and exports (the WebView saves none itself — `capacitor_download.ts` writes them and opens the share sheet), `MainActivity`/`ViewController` WebView tweaks (edge-to-edge, keyboard), `isMobileApp()` gating in the client, adding a Capacitor plugin, or the mobile CI/nightly builds. Also load it when reviewing a diff that touches these files, so working iOS-only code is not flagged as dead.
+description: Use when working on the Trilium mobile app (`apps/mobile`, Capacitor for Android/iOS) or on the standalone code paths that only run inside it — request routing on `capacitor://` vs `https://localhost`, the iOS fetch/XHR/image/stylesheet interceptors, the Android request bridge (`TriliumRequestBridge`, which replaces the service worker there), the Android native streaming HTTP proxy (`TriliumWebViewClient`), the `NativeHttpHandler` sync transport, downloads and exports (the WebView saves none itself — `capacitor_download.ts` writes them and opens the share sheet), `MainActivity`/`ViewController` WebView tweaks (edge-to-edge, keyboard), `isMobileApp()` gating in the client, adding a Capacitor plugin, or the mobile CI/nightly builds. Also load it when reviewing a diff that touches these files, so working iOS-only code is not flagged as dead.
---
# Developing the Capacitor mobile app
@@ -12,16 +12,18 @@ Key files:
```
apps/mobile/capacitor.config.json # appId org.triliumnotes.trilium, androidScheme https, hostname localhost, plugins
apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/
- MainActivity.java # installs TriliumWebViewClient + TriliumFileSink, edge-to-edge + insets, system bars
- TriliumWebViewClient.java # streaming same-origin HTTP proxy for the sync worker (Android only)
+ MainActivity.java # installs TriliumRequestBridge, TriliumWebViewClient, TriliumFileSink; edge-to-edge + insets, system bars
+ TriliumRequestBridge.java # answers local API requests from the page's worker in place of a service worker (Android only)
+ TriliumWebViewClient.java # routes local API requests to TriliumRequestBridge; streaming HTTP proxy for the sync worker
TriliumFileSink.java # binary file-write channel (WebMessageListener + ArrayBuffer, Android only)
apps/mobile/ios/App/App/ViewController.swift # keyboard handling: pins outer scroll, drives --tn-keyboard-gap
-apps/standalone/src/main.ts # boot: registers native HTTP handler if `Capacitor` in window; iOS interceptors
+apps/standalone/src/main.ts # boot: registers native HTTP handler if `Capacitor` in window; iOS interceptors or Android request bridge
+apps/standalone/src/android-request-bridge.ts # page side of TriliumRequestBridge: localFetch() → head + chunk frames
apps/standalone/src/ios-interceptors.ts # fetch / XHR / <img> / stylesheet interceptors, iOS only
apps/standalone/src/services/capacitor_http_handler.ts # NativeHttpHandler: Android proxy probe + CapacitorHttp fallback
apps/standalone/src/services/capacitor_download.ts # saveUrlToDevice(): fetch → Filesystem cache → share sheet
apps/standalone/src/local-bridge.ts # LOCAL_API_PREFIXES, localFetch(), registerNativeHttpHandler()
-apps/standalone/src/sw.ts # service worker routing (Android + web); guards for capacitor:// and the native proxy
+apps/standalone/src/sw.ts # service worker routing (web; Android only on a WebView without message listeners)
apps/client/src/services/utils.ts # isMobileApp() — running inside the native wrapper
.github/workflows/mobile.yml, .github/actions/build-mobile # APK + iOS simulator builds, nightly signing
```
@@ -34,7 +36,7 @@ The client's `/api`, `/sync`, `/bootstrap`, `/search` requests (`LOCAL_API_PREFI
What still leaves the page — engine-initiated loads (`<img src="api/images/…">`, `@font-face`, themes), `upload()`/`chunked_upload.ts`, the LLM stream — is where the platforms diverge, because their WebViews resolve `*Scheme: "https"` differently:
-- **Android** — `androidScheme: "https"` works, the app runs at `https://localhost`, a real secure origin, so the **service worker** (`sw.ts`) intercepts those requests and forwards them to the worker — the same path as the web build.
+- **Android** — the app runs at `https://localhost` and registers **no service worker**. `TriliumWebViewClient.shouldInterceptRequest` sees every request the engine issues, whichever subsystem issued it, and hands local API paths to **`TriliumRequestBridge`**. That bridge calls `window.__triliumNativeRequest()`, `android-request-bridge.ts` answers from `localFetch()`, and the reply comes back over the injected `window.triliumRequestBridge` WebMessageListener: a JSON `head`, then the body as ArrayBuffer frames (4-byte request id + bytes; base64 `chunk` messages on a WebView without ArrayBuffer messages), then `end`/`error`. The IO thread blocks until the head arrives (270 s cap, as in `sw.ts`), then the body streams through a queue-backed `InputStream`. `main.ts` takes this path when `triliumRequestBridge` is on `window`; a WebView without `WEB_MESSAGE_LISTENER` never gets it, so it falls back to the service worker.
- **iOS** — the app runs at **`capacitor://localhost`**, and WebKit refuses to register a service worker on a non-HTTP(S) origin. `main.ts` therefore installs **in-page interceptors** (`installIosInterceptors()`, gated on `location.protocol === "capacitor:"`), one per way a request can leave the page: `window.fetch`, `XMLHttpRequest` (jQuery `$.ajax` never touches fetch), `<img src="api/images/…">` (the image loader issues its own requests) and CSS-initiated loads (`@font-face url()` in injected styles, custom themes via `<link href="api/…">`). Each rewrites a local-API request into `localFetch()`.
Consequences that keep tripping people up:
@@ -42,6 +44,9 @@ Consequences that keep tripping people up:
- **`iosScheme: "https"` is a no-op — do not re-add it.** Capacitor rejects it: `CAPInstanceDescriptor.normalize()` checks `WKWebView.handlesURLScheme(scheme) == false`, and WKWebView reserves `http`/`https`, so the scheme resets to `capacitor`. The config line only implies an https origin that never exists on iOS.
- **Do not delete the iOS interceptor path as "dead code"**, and do not gate anything on "there is always a service worker". A reviewer assuming `iosScheme: https` ⇒ https origin will wrongly flag it.
- A **new way for the page to issue a request** (a new element type loading `api/…`, a `new Worker` fetching, `EventSource`, `sendBeacon`) needs a fourth/fifth interceptor in `ios-interceptors.ts`, or it will silently 404 on iOS while working everywhere else. Test it in `ios-interceptors.spec.ts`.
+- **The Android bridge answers GET and HEAD only.** `shouldInterceptRequest` exposes no request body, so any other method gets a 405 with `x-trilium-bridge-error`. A request with a body has to go through `standaloneApi.localFetch` (as `server.ts`'s `ajax()` does); a raw `fetch`/`$.ajax` POST to `api/` fails on Android.
+- **`WebResourceResponse` rejects 3xx statuses**, so `android-request-bridge.ts` turns a redirect (the share pages issue them) into a 200 page with a `<meta http-equiv="refresh">`. The Java prefix list in `TriliumRequestBridge.handles()` must match `isLocalApiRequest()` in `local-bridge.ts`, including the `/share` rule.
+- **A service worker registered by an older build still controls the page.** Its fetches never reach `shouldInterceptRequest`, and with no `attachServiceWorkerBridge()` nothing answers them. Clearing the app's data or reinstalling removes it.
- `sw.ts` has a defensive `self.location.protocol === "capacitor:"` guard and must **let `/_trilium_native_http/` requests fall through** to the WebView (see below); keep both when editing its fetch handler.
- Image blob URLs created by the interceptor are revoked (`5332cee3fb`); if you add another `URL.createObjectURL`, revoke it.
@@ -70,7 +75,7 @@ worker never sees and where no server exists.
So the page does the saving: `open.download()` (`apps/client/src/services/open.ts`) routes through
`window.standaloneApi.save.saveUrl()` when that exists, which `main.ts` defines only inside the shell.
-`capacitor_download.ts` fetches the URL — still routed to the worker by the service worker on Android
+`capacitor_download.ts` fetches the URL — still routed to the worker by `TriliumRequestBridge` on Android
and the interceptors on iOS — writes it into `Directory.Cache` and hands the file to the system share
sheet.
@@ -119,7 +124,7 @@ sheet.
## Native shells
-- **Android `MainActivity`**: sets `TriliumWebViewClient`, draws edge-to-edge with transparent system bars, forwards window insets to the WebView (so the client can pad for the status/navigation bars) and re-applies system bar appearance on configuration change. Nightly and debug builds get a distinct `applicationId` suffix (`.nightly`, `.debug`) and launcher icon so they install side by side (`android/app/build.gradle`).
+- **Android `MainActivity`**: installs `TriliumRequestBridge` and sets `TriliumWebViewClient`, draws edge-to-edge with transparent system bars, forwards window insets to the WebView (so the client can pad for the status/navigation bars) and re-applies system bar appearance on configuration change. Nightly and debug builds get a distinct `applicationId` suffix (`.nightly`, `.debug`) and launcher icon so they install side by side (`android/app/build.gradle`).
- **iOS `ViewController`**: the layout is `body { position: fixed; height: 100vh }` with an inner scrolling container, so WKWebView's reflexive scroll-to-focused-element would drag the toolbar off-screen; the controller pins the outer scroll offset while the keyboard animates and samples the keyboard's top edge every frame into the `--tn-keyboard-gap` CSS variable so the editor toolbar follows an interactive swipe-dismiss. `Keyboard.resize: "native"` in the config is part of the same contract. Change the keyboard/toolbar CSS on the client and this controller together.
- `limitsNavigationsToAppBoundDomains: true` on iOS.
@@ -187,7 +192,8 @@ pnpm --filter standalone test ios-interceptors # iOS interceptors
pnpm --filter standalone test capacitor_http_handler # Android proxy probe / plugin fallback
pnpm --filter standalone test capacitor_download # chunked base64 write, filename parsing, share sheet
pnpm --filter standalone test sw # service-worker routing incl. capacitor:// guard
-pnpm --filter standalone test main # boot wiring (native handler registered, interceptors installed on capacitor:)
+pnpm --filter standalone test android-request-bridge # Android request bridge: framing, base64 fallback, redirects
+pnpm --filter standalone test main # boot wiring (native handler, iOS interceptors, Android bridge instead of the SW)
```
Simulate the platform in a spec by stubbing `location.protocol` / `window.Capacitor` (`getPlatform`, `isNativePlatform`, `Plugins.CapacitorHttp`) — see the existing specs for the fixtures. Native Java/Swift has no test harness in the repo; keep logic there minimal and mirror the protocol on the JS side where it is testable.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3c0cf320cc..b802237a8d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -148,7 +148,7 @@ Shared components live in `apps/client/src/widgets/react/` — **always** reuse
`apps/standalone` runs the client on the page and `@triliumnext/core` — plain JS — in a dedicated Web Worker over `@sqlite.org/sqlite-wasm` persisted in OPFS; a Web Lock elects the one tab that owns the database, which answers its own API calls straight from the worker (`standaloneApi.localFetch`); the service worker forwards other tabs' calls to it and covers what the page still requests. Every core provider has a browser twin in `apps/standalone/src/lightweight/` — **a new provider or Node import in core breaks this build first.** Load the **`developing-standalone` skill** before touching `sw.ts`, `main.ts`, `local-server-worker.ts`, `lightweight/*` or `vite.config.mts`.
### Mobile (Capacitor) app
-`apps/mobile` wraps the standalone WASM build in a Capacitor WebView — no network backend. Its one tab always owns the worker, so the client answers most API calls in-page; what still leaves it (images, fonts, uploads) goes through the service worker on Android, at `https://localhost`, and through `apps/standalone/src/ios-interceptors.ts` on iOS, at `capacitor://localhost`, where no service worker can register. **`iosScheme: "https"` is a no-op and must not be re-added, and the iOS interceptor path is not dead code.** Load the **`developing-capacitor-mobile` skill** before touching `apps/mobile`, `ios-interceptors.ts`, `capacitor_http_handler.ts` or the `capacitor:` branches of `sw.ts`/`main.ts`.
+`apps/mobile` wraps the standalone WASM build in a Capacitor WebView — no network backend. Its one tab always owns the worker, so the client answers most API calls in-page; what still leaves it (images, fonts, uploads) goes through `TriliumRequestBridge` on Android, at `https://localhost`, where `shouldInterceptRequest` replaces the service worker and answers GET/HEAD only, and through `apps/standalone/src/ios-interceptors.ts` on iOS, at `capacitor://localhost`, where no service worker can register. **`iosScheme: "https"` is a no-op and must not be re-added, and the iOS interceptor path is not dead code.** Load the **`developing-capacitor-mobile` skill** before touching `apps/mobile`, `ios-interceptors.ts`, `android-request-bridge.ts`, `capacitor_http_handler.ts` or the `capacitor:` branches of `sw.ts`/`main.ts`.
### PDF viewer
PDF notes render in Mozilla's PDF.js viewer plus Trilium's code from `packages/pdfjs-viewer`, which every app serves from the built `dist` — **rebuild it (`pnpm --filter @triliumnext/pdfjs-viewer build`) after every viewer change**, since no `*:start` script does; load the **`developing-pdf-viewer` skill** before touching the viewer, `Pdf.tsx` or the PDF sidebar panels.
diff --git a/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/MainActivity.java b/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/MainActivity.java
index a267f6633b..dfc55eb38b 100644
--- a/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/MainActivity.java
+++ b/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/MainActivity.java
@@ -20,8 +20,10 @@ public class MainActivity extends BridgeActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
- // Streaming HTTP proxy for the sync worker (see TriliumWebViewClient).
- getBridge().setWebViewClient(new TriliumWebViewClient(getBridge()));
+ // Local API requests answered by the page's SQLite worker (see TriliumRequestBridge),
+ // and the streaming HTTP proxy for the sync worker (see TriliumWebViewClient).
+ TriliumRequestBridge requestBridge = TriliumRequestBridge.install(getBridge());
+ getBridge().setWebViewClient(new TriliumWebViewClient(getBridge(), requestBridge));
// Binary write channel for downloads and backups (see TriliumFileSink).
TriliumFileSink.install(getBridge());
enableEdgeToEdge();
diff --git a/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumRequestBridge.java b/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumRequestBridge.java
new file mode 100644
index 0000000000..a6491c9712
--- /dev/null
+++ b/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumRequestBridge.java
@@ -0,0 +1,442 @@
+package org.triliumnotes.trilium;
+
+import android.net.Uri;
+import android.os.Handler;
+import android.os.Looper;
+import android.util.Base64;
+import android.util.Log;
+import android.webkit.WebResourceRequest;
+import android.webkit.WebResourceResponse;
+import android.webkit.WebView;
+
+import androidx.webkit.WebMessageCompat;
+import androidx.webkit.WebViewCompat;
+import androidx.webkit.WebViewFeature;
+
+import com.getcapacitor.Bridge;
+import com.getcapacitor.WebViewListener;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * Answers the page's local API requests ({@code /api/}, {@code /bootstrap}, …) from the in-page
+ * SQLite worker, in place of a service worker.
+ *
+ * <p>{@link #handle} runs on a WebView IO thread: it hands the request to the page through
+ * {@code window.__triliumNativeRequest()} and blocks until the head of the reply arrives. The
+ * body then streams into the WebView through a {@link ChunkStream}. The page replies over the
+ * {@code window.triliumRequestBridge} message channel; the protocol is described in
+ * {@code apps/standalone/src/android-request-bridge.ts}.
+ *
+ * <p>Requests intercepted before the page announces {@code ready} are queued, and a new page
+ * fails whatever the previous one left unanswered.
+ */
+public final class TriliumRequestBridge {
+
+ private static final String TAG = "TriliumRequestBridge";
+ private static final String JS_OBJECT_NAME = "triliumRequestBridge";
+
+ /** Must match {@code isLocalApiRequest()} in {@code apps/standalone/src/local-bridge.ts}. */
+ private static final String[] LOCAL_PREFIXES = { "/bootstrap", "/api/", "/sync/", "/search/", "/custom/" };
+
+ /**
+ * Matches the service worker's limit in {@code sw.ts}: the worker can be inside a long
+ * synchronous stretch (a VACUUM of a large database) before it answers.
+ */
+ private static final long HEAD_TIMEOUT_MS = 270_000;
+
+ private static final int FRAME_HEADER_SIZE = 4;
+
+ private final Bridge bridge;
+ private final boolean binaryChunks;
+ private final Handler mainHandler = new Handler(Looper.getMainLooper());
+ private final AtomicInteger nextId = new AtomicInteger();
+ private final Map<Integer, PendingRequest> pending = new ConcurrentHashMap<>();
+
+ /** Guards {@link #pageReady} and {@link #queuedIds}. */
+ private final Object readyLock = new Object();
+ private boolean pageReady;
+ private final List<Integer> queuedIds = new ArrayList<>();
+
+ private TriliumRequestBridge(Bridge bridge, boolean binaryChunks) {
+ this.bridge = bridge;
+ this.binaryChunks = binaryChunks;
+ }
+
+ /**
+ * Injects {@code window.triliumRequestBridge} into pages of the app origin. Returns null when
+ * the WebView has no message listeners; the object is then never injected, and the page
+ * registers its service worker instead.
+ */
+ public static TriliumRequestBridge install(Bridge bridge) {
+ if (!WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) {
+ Log.i(TAG, "WebMessage listeners are unavailable; local requests stay on the service worker");
+ return null;
+ }
+
+ TriliumRequestBridge requestBridge = new TriliumRequestBridge(
+ bridge, WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_ARRAY_BUFFER));
+ WebViewCompat.addWebMessageListener(
+ bridge.getWebView(),
+ JS_OBJECT_NAME,
+ bridge.getAllowedOriginRules(),
+ (view, message, sourceOrigin, isMainFrame, replyProxy) -> {
+ if (isMainFrame) {
+ requestBridge.onMessage(message);
+ }
+ }
+ );
+ bridge.addWebViewListener(new WebViewListener() {
+ @Override
+ public void onPageStarted(WebView webView) {
+ requestBridge.onPageStarted();
+ }
+ });
+ return requestBridge;
+ }
+
+ /** Whether the request is for a local API path on the app's own origin. */
+ public boolean handles(Uri uri) {
+ String path = uri.getPath();
+ if (path == null
+ || !bridge.getScheme().equals(uri.getScheme())
+ || !bridge.getHost().equals(uri.getHost())) {
+ return false;
+ }
+ if (path.equals("/share") || (path.startsWith("/share/") && !path.startsWith("/share/assets/"))) {
+ return true;
+ }
+ for (String prefix : LOCAL_PREFIXES) {
+ if (path.startsWith(prefix)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /** Answers a request {@link #handles} accepted. Blocks the calling WebView IO thread. */
+ public WebResourceResponse handle(WebResourceRequest request) {
+ String method = request.getMethod() == null ? "GET" : request.getMethod().toUpperCase(Locale.ROOT);
+ if (!"GET".equals(method) && !"HEAD".equals(method)) {
+ // shouldInterceptRequest exposes no request body; the page sends these through
+ // standaloneApi.localFetch instead.
+ return errorResponse(405, "Method Not Allowed",
+ method + " cannot be answered natively: the request body is not available");
+ }
+
+ int id = nextId.incrementAndGet();
+ PendingRequest pendingRequest = new PendingRequest();
+ try {
+ JSONObject payload = new JSONObject()
+ .put("id", id)
+ .put("method", method)
+ .put("url", request.getUrl().toString())
+ .put("headers", new JSONObject(request.getRequestHeaders()))
+ .put("binary", binaryChunks);
+ // U+2028 and U+2029 are valid in JSON strings but end a line in JavaScript source.
+ String json = payload.toString().replace("\u2028", "\\u2028").replace("\u2029", "\\u2029");
+ pendingRequest.script =
+ "window.__triliumNativeRequest ? (window.__triliumNativeRequest(" + json + "), true) : false";
+ } catch (JSONException e) {
+ return errorResponse(500, "Internal Error", "Cannot encode the request: " + e.getMessage());
+ }
+
+ pending.put(id, pendingRequest);
+ synchronized (readyLock) {
+ if (pageReady) {
+ mainHandler.post(() -> dispatch(id, pendingRequest));
+ } else {
+ queuedIds.add(id);
+ }
+ }
+
+ try {
+ if (!pendingRequest.headReceived.await(HEAD_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+ pending.remove(id);
+ return errorResponse(504, "Gateway Timeout", "The local worker did not answer in time");
+ }
+ } catch (InterruptedException e) {
+ pending.remove(id);
+ Thread.currentThread().interrupt();
+ return errorResponse(503, "Service Unavailable", "Interrupted while waiting for the local worker");
+ }
+
+ if (pendingRequest.headError != null) {
+ return errorResponse(502, "Bad Gateway", pendingRequest.headError);
+ }
+ return buildResponse(pendingRequest);
+ }
+
+ private void onPageStarted() {
+ synchronized (readyLock) {
+ pageReady = false;
+ queuedIds.clear();
+ }
+ Iterator<PendingRequest> iterator = pending.values().iterator();
+ while (iterator.hasNext()) {
+ iterator.next().fail("The page reloaded before answering");
+ iterator.remove();
+ }
+ }
+
+ private void onMessage(WebMessageCompat message) {
+ if (message.getType() == WebMessageCompat.TYPE_ARRAY_BUFFER) {
+ byte[] frame = message.getArrayBuffer();
+ if (frame.length < FRAME_HEADER_SIZE) {
+ return;
+ }
+ PendingRequest pendingRequest = pending.get(ByteBuffer.wrap(frame).getInt());
+ if (pendingRequest != null) {
+ pendingRequest.body.append(Arrays.copyOfRange(frame, FRAME_HEADER_SIZE, frame.length));
+ }
+ return;
+ }
+
+ try {
+ JSONObject parsed = new JSONObject(message.getData());
+ String type = parsed.getString("type");
+ if ("ready".equals(type)) {
+ onPageReady();
+ return;
+ }
+
+ int id = parsed.getInt("id");
+ PendingRequest pendingRequest = pending.get(id);
+ if (pendingRequest == null) {
+ return;
+ }
+ switch (type) {
+ case "head":
+ pendingRequest.receiveHead(parsed.getInt("status"), toHeaderMap(parsed.optJSONObject("headers")));
+ break;
+ case "chunk":
+ pendingRequest.body.append(Base64.decode(parsed.getString("data"), Base64.DEFAULT));
+ break;
+ case "end":
+ pending.remove(id);
+ pendingRequest.body.finish();
+ break;
+ case "error":
+ pending.remove(id);
+ pendingRequest.fail(parsed.optString("message", "The local request failed"));
+ break;
+ default:
+ Log.w(TAG, "Unknown message type: " + type);
+ }
+ } catch (JSONException e) {
+ Log.w(TAG, "Malformed message from the page", e);
+ }
+ }
+
+ private void onPageReady() {
+ List<Integer> ids;
+ synchronized (readyLock) {
+ pageReady = true;
+ ids = new ArrayList<>(queuedIds);
+ queuedIds.clear();
+ }
+ for (int id : ids) {
+ PendingRequest pendingRequest = pending.get(id);
+ if (pendingRequest != null) {
+ dispatch(id, pendingRequest);
+ }
+ }
+ }
+
+ /** Hands a request to the page. Runs on the UI thread, which evaluateJavascript requires. */
+ private void dispatch(int id, PendingRequest pendingRequest) {
+ bridge.getWebView().evaluateJavascript(pendingRequest.script, result -> {
+ if (!"true".equals(result)) {
+ failRequest(id, "The page has no request handler");
+ }
+ });
+ }
+
+ private void failRequest(int id, String message) {
+ PendingRequest pendingRequest = pending.remove(id);
+ if (pendingRequest != null) {
+ pendingRequest.fail(message);
+ }
+ }
+
+ private static WebResourceResponse buildResponse(PendingRequest request) {
+ Map<String, String> headers = new HashMap<>();
+ String mimeType = "application/octet-stream";
+ String encoding = null;
+ for (Map.Entry<String, String> header : request.headers.entrySet()) {
+ String name = header.getKey().toLowerCase(Locale.ROOT);
+ if ("content-length".equals(name) || "content-encoding".equals(name)) {
+ // The stream carries exactly the decoded bytes the page sent.
+ continue;
+ }
+ if ("content-type".equals(name)) {
+ String[] parts = header.getValue().split(";");
+ mimeType = parts[0].trim();
+ for (int i = 1; i < parts.length; i++) {
+ String part = parts[i].trim();
+ if (part.toLowerCase(Locale.ROOT).startsWith("charset=")) {
+ encoding = part.substring("charset=".length()).trim();
+ }
+ }
+ }
+ headers.put(header.getKey(), header.getValue());
+ }
+
+ int status = request.status;
+ if (status < 100 || status > 599 || (status >= 300 && status < 400)) {
+ // WebResourceResponse rejects these; the page turns redirects into a 200 already.
+ return errorResponse(502, "Bad Gateway", "The local worker answered with status " + status);
+ }
+ return new WebResourceResponse(mimeType, encoding, status, reasonPhrase(status), headers, request.body);
+ }
+
+ /** WebResourceResponse requires a non-empty reason phrase. */
+ private static String reasonPhrase(int status) {
+ switch (status) {
+ case 200: return "OK";
+ case 201: return "Created";
+ case 204: return "No Content";
+ case 206: return "Partial Content";
+ case 400: return "Bad Request";
+ case 401: return "Unauthorized";
+ case 403: return "Forbidden";
+ case 404: return "Not Found";
+ case 500: return "Internal Server Error";
+ case 503: return "Service Unavailable";
+ default: return "Status " + status;
+ }
+ }
+
+ private static WebResourceResponse errorResponse(int status, String reason, String message) {
+ Log.w(TAG, message);
+ Map<String, String> headers = new HashMap<>();
+ headers.put("x-trilium-bridge-error", message.replaceAll("[^\\x20-\\x7e]", " "));
+ return new WebResourceResponse("text/plain", "utf-8", status, reason, headers,
+ new ByteArrayInputStream(message.getBytes(StandardCharsets.UTF_8)));
+ }
+
+ private static Map<String, String> toHeaderMap(JSONObject json) {
+ Map<String, String> headers = new HashMap<>();
+ if (json == null) {
+ return headers;
+ }
+ Iterator<String> names = json.keys();
+ while (names.hasNext()) {
+ String name = names.next();
+ headers.put(name, json.optString(name));
+ }
+ return headers;
+ }
+
+ /** One intercepted request, from dispatch until the page sends {@code end} or {@code error}. */
+ private static final class PendingRequest {
+ final CountDownLatch headReceived = new CountDownLatch(1);
+ final ChunkStream body = new ChunkStream();
+ String script;
+ volatile int status;
+ volatile Map<String, String> headers;
+ volatile String headError;
+
+ void receiveHead(int status, Map<String, String> headers) {
+ this.status = status;
+ this.headers = headers;
+ headReceived.countDown();
+ }
+
+ void fail(String message) {
+ if (headReceived.getCount() > 0) {
+ headError = message;
+ headReceived.countDown();
+ }
+ body.fail(message);
+ }
+ }
+
+ /** The response body as the page sends it: a queue of chunks the WebView drains. */
+ private static final class ChunkStream extends InputStream {
+ private static final byte[] END = new byte[0];
+
+ private final LinkedBlockingQueue<byte[]> chunks = new LinkedBlockingQueue<>();
+ private volatile String error;
+ private byte[] current;
+ private int position;
+ private boolean finished;
+
+ void append(byte[] chunk) {
+ if (chunk.length > 0) {
+ chunks.add(chunk);
+ }
+ }
+
+ void finish() {
+ chunks.add(END);
+ }
+
+ void fail(String message) {
+ error = message;
+ chunks.add(END);
+ }
+
+ @Override
+ public int read() throws IOException {
+ byte[] single = new byte[1];
+ int read = read(single, 0, 1);
+ return read == -1 ? -1 : single[0] & 0xff;
+ }
+
+ @Override
+ public int read(byte[] buffer, int offset, int length) throws IOException {
+ if (length == 0) {
+ return 0;
+ }
+ while (current == null || position >= current.length) {
+ if (finished) {
+ return -1;
+ }
+ try {
+ current = chunks.take();
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ throw new IOException("Interrupted while reading the local response", e);
+ }
+ position = 0;
+ if (current == END) {
+ finished = true;
+ if (error != null) {
+ throw new IOException(error);
+ }
+ return -1;
+ }
+ }
+ int count = Math.min(length, current.length - position);
+ System.arraycopy(current, position, buffer, offset, count);
+ position += count;
+ return count;
+ }
+
+ @Override
+ public void close() {
+ chunks.clear();
+ finished = true;
+ }
+ }
+}
diff --git a/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumWebViewClient.java b/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumWebViewClient.java
index 69e77a75c5..fe05b9a0bf 100644
--- a/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumWebViewClient.java
+++ b/apps/mobile/android/app/src/main/java/org/triliumnotes/trilium/TriliumWebViewClient.java
@@ -61,13 +61,21 @@ public class TriliumWebViewClient extends BridgeWebViewClient {
// dead connection cannot pin a WebView IO thread forever.
private static final int READ_TIMEOUT_MS = 600_000;
- public TriliumWebViewClient(Bridge bridge) {
+ /** Null when the WebView cannot host it; the page then uses its service worker. */
+ private final TriliumRequestBridge requestBridge;
+
+ public TriliumWebViewClient(Bridge bridge, TriliumRequestBridge requestBridge) {
super(bridge);
+ this.requestBridge = requestBridge;
}
@Override
public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
Uri uri = request.getUrl();
+ if (requestBridge != null && requestBridge.handles(uri)) {
+ return requestBridge.handle(request);
+ }
+
String path = uri.getPath();
if (path == null || !path.startsWith(INTERCEPT_PREFIX)) {
return super.shouldInterceptRequest(view, request);
diff --git a/apps/standalone/src/android-request-bridge.spec.ts b/apps/standalone/src/android-request-bridge.spec.ts
new file mode 100644
index 0000000000..4554b21540
--- /dev/null
+++ b/apps/standalone/src/android-request-bridge.spec.ts
@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { installAndroidRequestBridge } from "./android-request-bridge.js";
+
+const mocks = vi.hoisted(() => ({
+ localFetch: vi.fn()
+}));
+
+vi.mock("./local-bridge.js", () => ({
+ localFetch: (request: Request) => mocks.localFetch(request),
+ isLocalApiRequest: (url: URL) => url.pathname.startsWith("/api/") || url.pathname.startsWith("/share/")
+}));
+
+interface BridgeWindow {
+ triliumRequestBridge?: { postMessage: ReturnType<typeof vi.fn> };
+ __triliumNativeRequest?: (request: Record<string, unknown>) => void;
+}
+
+const bridgeWindow = window as unknown as BridgeWindow;
+let postMessage: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+ mocks.localFetch.mockReset();
+ postMessage = vi.fn();
+ bridgeWindow.triliumRequestBridge = { postMessage };
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+ delete bridgeWindow.triliumRequestBridge;
+ delete bridgeWindow.__triliumNativeRequest;
+ vi.restoreAllMocks();
+});
+
+/** Installs the bridge, forwards one request, and returns every message the page sent back. */
+async function forward(request: Record<string, unknown>) {
+ installAndroidRequestBridge();
+ postMessage.mockClear();
+ bridgeWindow.__triliumNativeRequest?.({
+ method: "GET",
+ headers: {},
+ binary: true,
+ ...request
+ });
+ await vi.waitFor(() => {
+ const last = postMessage.mock.calls.at(-1)?.[0];
+ expect(typeof last === "string" && /"type":"(end|error)"/.test(last)).toBe(true);
+ });
+ return postMessage.mock.calls.map(([message]) =>
+ typeof message === "string" ? JSON.parse(message) : message as ArrayBuffer);
+}
+
+describe("installAndroidRequestBridge", () => {
+ it("does nothing without the native channel, and announces readiness with it", () => {
+ delete bridgeWindow.triliumRequestBridge;
+ installAndroidRequestBridge();
+ expect(bridgeWindow.__triliumNativeRequest).toBeUndefined();
+
+ bridgeWindow.triliumRequestBridge = { postMessage };
+ installAndroidRequestBridge();
+ expect(bridgeWindow.__triliumNativeRequest).toBeTypeOf("function");
+ expect(postMessage).toHaveBeenCalledWith(JSON.stringify({ type: "ready" }));
+ });
+
+ it("answers from localFetch with a head, id-framed binary chunks and an end", async () => {
+ // Two chunks' worth plus a remainder, so the split and the framing both show.
+ const body = new Uint8Array(256 * 1024 * 2 + 3).map((_, i) => i % 251);
+ mocks.localFetch.mockResolvedValue(new Response(body, {
+ status: 206,
+ headers: { "content-type": "image/png" }
+ }));
+
+ const messages = await forward({ id: 7, url: "https://localhost/api/images/x", headers: { range: "bytes=0-" } });
+
+ const request = mocks.localFetch.mock.calls[0][0] as Request;
+ expect(request.url).toBe("https://localhost/api/images/x");
+ expect(request.method).toBe("GET");
+ expect(request.headers.get("range")).toBe("bytes=0-");
+
+ expect(messages[0]).toEqual({ type: "head", id: 7, status: 206, headers: { "content-type": "image/png" } });
+ const frames = messages.slice(1, -1) as ArrayBuffer[];
+ expect(frames.map((frame) => frame.byteLength)).toEqual([4 + 256 * 1024, 4 + 256 * 1024, 4 + 3]);
+ for (const frame of frames) {
+ expect(new DataView(frame).getUint32(0)).toBe(7);
+ }
+ const received = new Uint8Array(frames.flatMap((frame) => [...new Uint8Array(frame, 4)]));
+ expect(received).toEqual(body);
+ expect(messages.at(-1)).toEqual({ type: "end", id: 7 });
+ });
+
+ it("sends base64 chunks when the WebView cannot carry ArrayBuffers, and none for an empty body", async () => {
+ mocks.localFetch.mockResolvedValue(new Response("hello"));
+ const messages = await forward({ id: 3, url: "https://localhost/api/notes", binary: false });
+ expect(messages.slice(1)).toEqual([
+ { type: "chunk", id: 3, data: btoa("hello") },
+ { type: "end", id: 3 }
+ ]);
+
+ mocks.localFetch.mockResolvedValue(new Response(null, { status: 204 }));
+ const empty = await forward({ id: 4, url: "https://localhost/api/notes" });
+ expect(empty.map((message) => (message as { type: string }).type)).toEqual(["head", "end"]);
+ });
+
+ it("turns a redirect into a page that navigates, since WebResourceResponse rejects 3xx", async () => {
+ mocks.localFetch.mockResolvedValue(new Response(null, {
+ status: 302,
+ headers: { location: "../share/?a=1&b=\"2\"" }
+ }));
+ const messages = await forward({ id: 1, url: "https://localhost/share/x", binary: false });
+
+ expect(messages[0]).toEqual({
+ type: "head", id: 1, status: 200, headers: { "content-type": "text/html; charset=utf-8" }
+ });
+ const html = atob((messages[1] as { data: string }).data);
+ expect(html).toBe("<!DOCTYPE html><meta http-equiv=\"refresh\" content=\"0;url=../share/?a=1&amp;b=&quot;2&quot;\">");
+ });
+
+ it("reports an error for a path the worker does not serve, and for a failed localFetch", async () => {
+ const unrouted = await forward({ id: 5, url: "https://localhost/assets/app.js" });
+ expect(unrouted).toEqual([{ type: "error", id: 5, message: "Path is not routed to the local worker: /assets/app.js" }]);
+ expect(mocks.localFetch).not.toHaveBeenCalled();
+
+ mocks.localFetch.mockRejectedValue(new Error("worker gone"));
+ const failed = await forward({ id: 6, url: "https://localhost/api/notes" });
+ expect(failed).toEqual([{ type: "error", id: 6, message: "worker gone" }]);
+ });
+});
diff --git a/apps/standalone/src/android-request-bridge.ts b/apps/standalone/src/android-request-bridge.ts
new file mode 100644
index 0000000000..02ad2ba28f
--- /dev/null
+++ b/apps/standalone/src/android-request-bridge.ts
@@ -0,0 +1,115 @@
+import { isLocalApiRequest, localFetch } from "./local-bridge.js";
+import { toBase64 } from "./services/capacitor_download.js";
+
+/**
+ * Page side of `TriliumRequestBridge.java`, which answers local API requests in the Android shell
+ * in place of the service worker.
+ *
+ * `WebViewClient.shouldInterceptRequest` sees every request the WebView issues, whichever part of
+ * the engine issued it (`fetch`, XHR, `<img>`, `@font-face`, iframes, media). For a local API path
+ * the native side calls `window.__triliumNativeRequest()`, this module answers it from
+ * `localFetch()`, and the reply travels back over the `window.triliumRequestBridge` message
+ * channel:
+ *
+ * - `{"type":"head","id","status","headers"}`, then the body as ArrayBuffer frames, each a 4-byte
+ * big-endian request id followed by the bytes — or, when the WebView cannot carry ArrayBuffers,
+ * `{"type":"chunk","id","data"}` with the bytes in base64.
+ * - `{"type":"end","id"}` once the body is complete, or `{"type":"error","id","message"}`.
+ *
+ * `shouldInterceptRequest` exposes no request body, so the native side forwards only GET and HEAD.
+ */
+export function installAndroidRequestBridge() {
+ const bridgeWindow = window as RequestBridgeWindow;
+ const channel = bridgeWindow.triliumRequestBridge;
+ if (!channel) {
+ return;
+ }
+
+ bridgeWindow.__triliumNativeRequest = (request) => {
+ void answer(channel, request);
+ };
+ // The native side holds every request it intercepted until this arrives.
+ channel.postMessage(JSON.stringify({ type: "ready" }));
+}
+
+/** Request forwarded by `TriliumRequestBridge.java`. */
+interface NativeRequest {
+ id: number;
+ method: string;
+ url: string;
+ headers: Record<string, string>;
+ /** Whether the WebView carries ArrayBuffer messages; base64 chunks are sent otherwise. */
+ binary: boolean;
+}
+
+interface RequestChannel {
+ postMessage(message: string | ArrayBuffer): void;
+}
+
+interface RequestBridgeWindow {
+ triliumRequestBridge?: RequestChannel;
+ __triliumNativeRequest?: (request: NativeRequest) => void;
+}
+
+/** Bounds each message, so no single bridge crossing holds a whole attachment. */
+const CHUNK_SIZE = 256 * 1024;
+
+const FRAME_HEADER_SIZE = 4;
+
+async function answer(channel: RequestChannel, request: NativeRequest) {
+ const send = (message: Record<string, unknown>) =>
+ channel.postMessage(JSON.stringify({ ...message, id: request.id }));
+
+ try {
+ const url = new URL(request.url, location.href);
+ if (!isLocalApiRequest(url)) {
+ // The prefix list in TriliumRequestBridge.java must match `isLocalApiRequest()`.
+ throw new Error(`Path is not routed to the local worker: ${url.pathname}`);
+ }
+
+ const response = toNativeResponse(await localFetch(new Request(url.href, {
+ method: request.method,
+ headers: request.headers
+ })));
+ const body = new Uint8Array(await response.arrayBuffer());
+
+ send({ type: "head", status: response.status, headers: Object.fromEntries(response.headers) });
+ for (let offset = 0; offset < body.length; offset += CHUNK_SIZE) {
+ const chunk = body.subarray(offset, offset + CHUNK_SIZE);
+ if (request.binary) {
+ channel.postMessage(frame(request.id, chunk));
+ } else {
+ send({ type: "chunk", data: toBase64(chunk) });
+ }
+ }
+ send({ type: "end" });
+ } catch (err) {
+ console.warn("[RequestBridge] Local request failed", request.url, err);
+ send({ type: "error", message: err instanceof Error ? err.message : String(err) });
+ }
+}
+
+/**
+ * `WebResourceResponse` rejects 3xx statuses, so a redirect (the share pages issue them) becomes a
+ * page that navigates to its target. A relative target resolves against the request URL, as it
+ * would for a real redirect.
+ */
+function toNativeResponse(response: Response): Response {
+ const location = response.headers.get("location");
+ if (response.status < 300 || response.status >= 400 || !location) {
+ return response;
+ }
+
+ const target = location.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+ return new Response(`<!DOCTYPE html><meta http-equiv="refresh" content="0;url=${target}">`, {
+ status: 200,
+ headers: { "content-type": "text/html; charset=utf-8" }
+ });
+}
+
+function frame(id: number, chunk: Uint8Array): ArrayBuffer {
+ const buffer = new ArrayBuffer(FRAME_HEADER_SIZE + chunk.length);
+ new DataView(buffer).setUint32(0, id);
+ new Uint8Array(buffer, FRAME_HEADER_SIZE).set(chunk);
+ return buffer;
+}
diff --git a/apps/standalone/src/main.spec.ts b/apps/standalone/src/main.spec.ts
index 1e51e768e2..21b141b662 100644
--- a/apps/standalone/src/main.spec.ts
+++ b/apps/standalone/src/main.spec.ts
@@ -10,7 +10,8 @@ const mocks = vi.hoisted(() => ({
localFetch: vi.fn(),
capacitorHttpHandler: vi.fn(),
saveUrlToDevice: vi.fn(),
- requestSecurityChange: vi.fn()
+ requestSecurityChange: vi.fn(),
+ installAndroidRequestBridge: vi.fn()
}));
// Whether this tab wins the database lock. Only the leader may start a worker;
@@ -36,6 +37,7 @@ vi.mock("./leader_election.js", () => ({
}));
vi.mock("./services/capacitor_http_handler.js", () => ({ capacitorHttpHandler: mocks.capacitorHttpHandler }));
vi.mock("./services/capacitor_download.js", () => ({ saveUrlToDevice: mocks.saveUrlToDevice }));
+vi.mock("./android-request-bridge.js", () => ({ installAndroidRequestBridge: mocks.installAndroidRequestBridge }));
// Avoid pulling the entire client bundle when loadScripts() runs.
vi.mock("../../client/src/index.js", () => ({}));
@@ -182,6 +184,23 @@ describe("bootstrap", () => {
await vi.waitFor(() => expect(win.standaloneApi?.save?.saveUrl).toBe(mocks.saveUrlToDevice));
});
+ it("answers through the Android request bridge without a SW when the shell injects it", async () => {
+ const sw: ServiceWorkerLike = { controller: null, register: vi.fn(), ready: Promise.resolve() };
+ setServiceWorker(sw);
+ const win = window as unknown as { triliumRequestBridge?: unknown };
+ win.triliumRequestBridge = {};
+ try {
+ await runBootstrap();
+ await vi.waitFor(() => expect(mocks.installAndroidRequestBridge).toHaveBeenCalled());
+ expect(mocks.startLocalServerWorker).toHaveBeenCalled();
+ expect(mocks.attachServiceWorkerBridge).not.toHaveBeenCalled();
+ expect(sw.register).not.toHaveBeenCalled();
+ expect(document.body.innerHTML).toBe("");
+ } finally {
+ delete win.triliumRequestBridge;
+ }
+ });
+
it("registers and waits for the SW, then loads scripts once it controls", async () => {
const sw: ServiceWorkerLike = { controller: null, register: vi.fn(), ready: Promise.resolve() };
// The SW takes control once registration completes (after the first check).
diff --git a/apps/standalone/src/main.ts b/apps/standalone/src/main.ts
index d95809650f..8c2637f89a 100644
--- a/apps/standalone/src/main.ts
+++ b/apps/standalone/src/main.ts
@@ -129,10 +129,14 @@ async function bootstrap() {
// iOS Capacitor loads on the capacitor:// scheme, where WebKit rejects
// service worker registration. Fall back to in-page request interceptors
- // that route API calls straight to the local SQLite worker; everywhere
- // else (Android https, web) the service worker handles this.
+ // that route API calls straight to the local SQLite worker. The Android
+ // shell answers them natively (TriliumRequestBridge.java) and injects
+ // `triliumRequestBridge` to say so; on the web the service worker does.
if (location.protocol === "capacitor:") {
installIosInterceptors();
+ } else if ("triliumRequestBridge" in window) {
+ const { installAndroidRequestBridge } = await import("./android-request-bridge.js");
+ installAndroidRequestBridge();
} else {
attachServiceWorkerBridge();
await waitForServiceWorkerControl();
diff --git a/apps/standalone/src/services/capacitor_download.ts b/apps/standalone/src/services/capacitor_download.ts
index 1009aabc93..843e1a8310 100644
--- a/apps/standalone/src/services/capacitor_download.ts
+++ b/apps/standalone/src/services/capacitor_download.ts
@@ -497,7 +497,7 @@ function take(parts: Uint8Array[], size: number): Uint8Array {
* overflows the call stack. The crypto provider's `encodeBase64` is not reachable from here: it
* lives in the worker, and this runs on the page.
*/
-function toBase64(bytes: Uint8Array): string {
+export function toBase64(bytes: Uint8Array): string {
const native = (bytes as Uint8Array & { toBase64?: () => string }).toBase64;
if (typeof native === "function") {
return native.call(bytes);