[WEP] Wails v3 Mobile Support (Android)#5500
Conversation
WalkthroughThis PR introduces a formal proposal document for Wails v3 Android support. The proposal outlines a Tri-Bridge architecture combining a Go runtime layer via ChangesWails v3 Android Mobile Architecture Proposal
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (2)
v3/wep/proposals/wails-mobile/proposal.md (2)
12-31: ⚡ Quick winConsider adding security considerations section.
The proposal's Detailed Design section covers asset serving, WebView hosting, and plugin architecture, but doesn't address security implications such as:
- WebView sandboxing and JavaScript bridge security
- Asset serving origin validation to prevent unauthorized access
- Plugin permission model and privilege escalation risks
- Input validation for JS → Go → Java call chain
Consider adding a "Security Considerations" section to the proposal addressing these concerns, especially since this introduces a new attack surface for mobile applications.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@v3/wep/proposals/wails-mobile/proposal.md` around lines 12 - 31, Add a "Security Considerations" section to the proposal that addresses WebView and bridge hardening (e.g., restrict JavaScript bridges and origin checks for Wails.CallGo in wails.js), asset-serving validation when using embed.FS and intercepting URLs (ensure origin/host whitelist for WailsWebViewActivity), EventBus and NativeCallHandler authorization/validation to prevent unauthorized event injection, and a plugin permission model with least-privilege rules and input validation for the JS→Go→Java call chain (validate and sanitize arguments before invoking native plugins).
65-66: 💤 Low valueConsider project sustainability with single maintainer.
The maintenance plan identifies a single maintainer (
@its-ernest) for the Android implementation. For a critical feature like mobile support, consider:
- Identifying a co-maintainer or backup maintainer
- Documenting a knowledge transfer plan
- Establishing a succession plan if the primary maintainer becomes unavailable
This helps ensure long-term sustainability of the Android mobile support.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@v3/wep/proposals/wails-mobile/proposal.md` around lines 65 - 66, Update the "Maintenance Plan" section to address single-maintainer risk: add a co-maintainer or designated backup (name or role), outline a concise knowledge transfer plan (documentation, walkthroughs, and handoff checklist) and include a succession plan describing how responsibility will be transferred if the primary maintainer (`@its-ernest`) becomes unavailable; make these additions under the existing "Maintenance Plan" heading and reference following Wails v3 coding standards and documentation responsibilities.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@v3/wep/proposals/wails-mobile/proposal.md`:
- Around line 30-31: The proposal currently names the frontend bridge API as
Wails.CallGo(method, ...args) but the runtime actually exposes
window.wails.invoke(msg); update the proposal to reconcile these: either (A)
explicitly state that Wails.CallGo is a higher-level wrapper implemented on top
of window.wails.invoke (describe mapping: Wails.CallGo serializes method+args
into the invoke message and forwards to window.wails.invoke), or (B) replace all
references to Wails.CallGo with the concrete runtime API window.wails.invoke and
document the required message shape and helper patterns; reference the symbols
Wails.CallGo and window.wails.invoke so readers can find the implementation
and/or wrapper code.
- Around line 40-41: Clarify the toolchain paragraph to accurately state that
using -buildmode=c-shared requires CGO and gomobile for cross-compiling Go into
Android artifacts but does not necessarily require the full Android NDK/Android
Studio for all workflows (explain when the NDK is only needed, e.g., for native
C/C++ code or custom toolchains), and add a one-line introduction of the wailsm
CLI (e.g., "wailsm: a CLI helper that automates gomobile setup and AAR
generation") so readers understand it automates gomobile and Android packaging;
update the sentence that currently reads "Requires Android SDK/NDK" to mention
CGO/-buildmode=c-shared and conditional NDK need, and insert the wailsm
description next to the gomobile mention.
- Line 6: The markdown heading "Summary" is using an h3 ("### Summary") which
skips h2 after the document title; change the heading marker for the "Summary"
heading to h2 by replacing "### Summary" with "## Summary" in the proposal.md so
the heading hierarchy is correct.
- Line 4: Update the proposal creation date line that currently reads
"**Created:** 2026-05-26" to a date that matches or predates the PR creation
date (e.g., "2026-05-23"); locate the literal string "**Created:** 2026-05-26"
in proposal.md and replace it with the corrected date.
- Around line 15-18: The proposal's mention that EventBus "supports polling from
the native side to push events to JavaScript" is ambiguous against the "Battery
Efficiency First" principle; update the proposal to explicitly state whether
EventBus uses continuous polling or an event-driven low-wakeup model and, if
polling is used, add a mitigation strategy: implement batching/coalescing,
adaptive intervals with exponential backoff, idle-disablement and explicit wake
triggers, and a max-poll frequency cap; edit the EventBus section (EventBus) to
document the exact behavior, the algorithms/parameters for backoff and batching,
and a short justification cross-referencing the Android battery-efficiency
guideline so reviewers can verify it meets the principle.
- Around line 25-28: The Plugin Architecture section is inaccurate: update the
text to reflect that v3 uses a thin Java-to-Go JNI bridge rather than Java-side
feature plugins by default—mention the exact JS→Java→Go call chain
(WailsJSBridge.invoke → WailsBridge.handleMessage → nativeHandleMessage) and
asset handling via nativeServeAsset, and reference the JNI exports implemented
in v3/pkg/application/application_android.go and the JS/Java wiring in
v3/examples/android/.../WailsJSBridge, WailsBridge, MainActivity; alternatively,
if you intend a Java plugin layer, add concrete references showing where Java
plugins are defined/registered and how Go dispatches to them (file/class names
and dispatch functions) so the proposal matches the v3 reference implementation.
- Around line 20-23: Update the proposal to use the exact domain used by the
Android implementation: change any occurrences of "https://wails.local" to
"https://wails.localhost/" and note that
WebViewAssetLoader.Builder#setDomain("wails.localhost") and the base URL
construction must match; explicitly state that assets are served in-process via
WebViewAssetLoader/PathHandler for requests to https://wails.localhost/*
(same-origin, no external network) and that WailsWebViewActivity should
intercept only those requests while any request that falls through must be
treated as potential DNS/TLS/network exposure; keep the NativeCallHandler
description but add this security clarification.
---
Nitpick comments:
In `@v3/wep/proposals/wails-mobile/proposal.md`:
- Around line 12-31: Add a "Security Considerations" section to the proposal
that addresses WebView and bridge hardening (e.g., restrict JavaScript bridges
and origin checks for Wails.CallGo in wails.js), asset-serving validation when
using embed.FS and intercepting URLs (ensure origin/host whitelist for
WailsWebViewActivity), EventBus and NativeCallHandler authorization/validation
to prevent unauthorized event injection, and a plugin permission model with
least-privilege rules and input validation for the JS→Go→Java call chain
(validate and sanitize arguments before invoking native plugins).
- Around line 65-66: Update the "Maintenance Plan" section to address
single-maintainer risk: add a co-maintainer or designated backup (name or role),
outline a concise knowledge transfer plan (documentation, walkthroughs, and
handoff checklist) and include a succession plan describing how responsibility
will be transferred if the primary maintainer (`@its-ernest`) becomes unavailable;
make these additions under the existing "Maintenance Plan" heading and reference
following Wails v3 coding standards and documentation responsibilities.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 737f2ac7-9a04-4c90-b88d-1419bc05cdfd
📒 Files selected for processing (1)
v3/wep/proposals/wails-mobile/proposal.md
| # WEP: Wails v3 Mobile Support (Android) | ||
|
|
||
| **Author:** Ernest ([@its-ernest](https://github.com/its-ernest)) | ||
| **Created:** 2026-05-26 |
There was a problem hiding this comment.
Correct the proposal creation date.
The document shows a creation date of "2026-05-26", but the PR was created on "2026-05-23". The proposal date should match or predate the PR creation date.
📅 Proposed fix
-**Created:** 2026-05-26
+**Created:** 2026-05-23📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Created:** 2026-05-26 | |
| **Created:** 2026-05-23 |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@v3/wep/proposals/wails-mobile/proposal.md` at line 4, Update the proposal
creation date line that currently reads "**Created:** 2026-05-26" to a date that
matches or predates the PR creation date (e.g., "2026-05-23"); locate the
literal string "**Created:** 2026-05-26" in proposal.md and replace it with the
corrected date.
| **Author:** Ernest ([@its-ernest](https://github.com/its-ernest)) | ||
| **Created:** 2026-05-26 | ||
|
|
||
| ### Summary |
There was a problem hiding this comment.
Fix markdown heading level.
The heading level jumps from h1 (line 1) to h3 (line 6), skipping h2. Use ## Summary instead of ### Summary to maintain proper heading hierarchy.
📝 Proposed fix
-### Summary
+## Summary📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Summary | |
| ## Summary |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 6-6: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@v3/wep/proposals/wails-mobile/proposal.md` at line 6, The markdown heading
"Summary" is using an h3 ("### Summary") which skips h2 after the document
title; change the heading marker for the "Summary" heading to h2 by replacing
"### Summary" with "## Summary" in the proposal.md so the heading hierarchy is
correct.
| 1. **Core Go Runtime (Mobile Core):** | ||
| * A mobile-compatible subset of the Wails v3 runtime. | ||
| * Uses `gomobile bind` to generate an AAR for Android. | ||
| * Implements an `EventBus` that supports polling from the native side to push events to JavaScript. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for EventBus implementation patterns in the codebase to verify the polling design
rg -n --type=go -C3 'EventBus|polling' --glob '!vendor/**'Repository: wailsapp/wails
Length of output: 1655
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# 1) Show the proposal lines in question
echo "---- proposal.md (around lines 10-25) ----"
nl -ba v3/wep/proposals/wails-mobile/proposal.md | sed -n '10,30p'
# 2) Show the battery efficiency principle line
echo "---- ANDROID_ARCHITECTURE.md (around lines 20-45) ----"
nl -ba v3/ANDROID_ARCHITECTURE.md | sed -n '20,45p'
# 3) Search for EventBus / polling usage beyond Go-only
echo "---- repo search for EventBus ----"
rg -n --glob '!vendor/**' --glob '!**/node_modules/**' 'EventBus' .
echo "---- repo search for polling (md/go) ----"
rg -n --glob '!vendor/**' --glob '!**/node_modules/**' 'polling' .Repository: wailsapp/wails
Length of output: 162
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "---- proposal.md (lines 12-22) ----"
awk 'NR>=12 && NR<=22 {printf "%d:%s\n", NR, $0}' v3/wep/proposals/wails-mobile/proposal.md || true
echo "---- ANDROID_ARCHITECTURE.md (lines 25-40) ----"
awk 'NR>=25 && NR<=40 {printf "%d:%s\n", NR, $0}' v3/ANDROID_ARCHITECTURE.md || true
echo "---- repo search for EventBus (any filetype) ----"
rg -n --glob '!vendor/**' --glob '!**/node_modules/**' 'EventBus' .
echo "---- repo search for polling word (any filetype) ----"
rg -n --glob '!vendor/**' --glob '!**/node_modules/**' 'polling' .Repository: wailsapp/wails
Length of output: 11971
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "---- proposal.md (lines 14-25, more context) ----"
awk 'NR>=14 && NR<=28 {printf "%d:%s\n", NR, $0}' v3/wep/proposals/wails-mobile/proposal.md
echo "---- docs architecture EventBus section (guides/architecture.mdx) ----"
awk 'NR>=60 && NR<=130 {printf "%d:%s\n", NR, $0}' docs/src/content/docs/guides/architecture.mdx
echo "---- docs architecture concept diagram context (concepts/architecture.mdx, EN not searched) ----"
# show a small window around the first EventBus diagram occurrence in zh-cn file as representative
awk 'NR>=190 && NR<=270 {printf "%d:%s\n", NR, $0}' docs/src/content/docs/zh-cn/concepts/architecture.mdx | head -n 120Repository: wailsapp/wails
Length of output: 4403
Clarify/justify native-side “polling” EventBus vs the battery-efficiency principle
The proposal says it “implements an EventBus that supports polling from the native side to push events to JavaScript” (v3/wep/proposals/wails-mobile/proposal.md:15-18), but the Android design principle is “Battery Efficiency First” (v3/ANDROID_ARCHITECTURE.md:31). Clarify whether this is continuous polling or an event-driven/low-wakeup approach (e.g., batching, adaptive intervals/backoff, coalescing, and disabling when idle); if true polling is required, document the mitigation strategy to avoid battery drain.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@v3/wep/proposals/wails-mobile/proposal.md` around lines 15 - 18, The
proposal's mention that EventBus "supports polling from the native side to push
events to JavaScript" is ambiguous against the "Battery Efficiency First"
principle; update the proposal to explicitly state whether EventBus uses
continuous polling or an event-driven low-wakeup model and, if polling is used,
add a mitigation strategy: implement batching/coalescing, adaptive intervals
with exponential backoff, idle-disablement and explicit wake triggers, and a
max-poll frequency cap; edit the EventBus section (EventBus) to document the
exact behavior, the algorithms/parameters for backoff and batching, and a short
justification cross-referencing the Android battery-efficiency guideline so
reviewers can verify it meets the principle.
| 4. **Frontend Bridge (`wails.js`):** | ||
| * A simplified contract providing `Wails.CallGo(method, ...args)` and `Wails.on(event, callback)`. |
There was a problem hiding this comment.
Reconcile frontend bridge API naming with actual implementation.
The proposal describes Wails.CallGo(method, ...args) as the frontend API, but the existing v3 Android runtime (see context snippet from v3/internal/runtime/desktop/@wailsio/runtime/src/system.ts:30) uses window.wails.invoke(msg) for Android WebView communication. Please clarify:
- Is
Wails.CallGoa proposed higher-level wrapper aroundwindow.wails.invoke? - Or should the proposal document the actual API contract used by the runtime?
Consistent API documentation will help developers understand the integration surface.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@v3/wep/proposals/wails-mobile/proposal.md` around lines 30 - 31, The proposal
currently names the frontend bridge API as Wails.CallGo(method, ...args) but the
runtime actually exposes window.wails.invoke(msg); update the proposal to
reconcile these: either (A) explicitly state that Wails.CallGo is a higher-level
wrapper implemented on top of window.wails.invoke (describe mapping:
Wails.CallGo serializes method+args into the invoke message and forwards to
window.wails.invoke), or (B) replace all references to Wails.CallGo with the
concrete runtime API window.wails.invoke and document the required message shape
and helper patterns; reference the symbols Wails.CallGo and window.wails.invoke
so readers can find the implementation and/or wrapper code.
|
@its-ernest Thanks for putting this together. As you know, there was existing code for Android support which I've tidied up and pushed. I'm still happy to discuss the points you've made here though as to why we should use gomobile etc. It would be good to reframe this as an improvement to the existing approach if you're up for it? |
2 participants
Description
LINK TO REPO: https://github.com/its-ernest/wails-mobile
The
wails-mobileproject already implemented a working prototype of the bridge and plugin system(For third-party Go packages to extend the capabilities for biometircs, camera, other hardware, deep native integrations, without writing a single JNI, just pure Java/Kotlin and Go wrappepr)Summary by CodeRabbit