Skip to content

feat: AUTO binding by default, and mocks wired out of the box - #13

Merged
maksudur03 merged 1 commit into
mainfrom
feature/default-lan-and-mock-setup
Aug 17, 2026
Merged

maksudur03 merged 1 commit into
mainfrom
feature/default-lan-and-mock-setup

Conversation

@nur-shuvo

Copy link
Copy Markdown
Collaborator

Two defaults changed, aimed at the same first-run complaint: a fresh integration handed back a 127.0.0.1 URL that needed adb forward before it showed anything, and a Mocks screen that could not add a mock.

Binding: AUTO by default

Adds BindingMode.AUTO / BrowserBinding.AUTO and makes them the default for StartRequest.bindingMode and BrowserConfig.binding. AUTO binds a real network interface when the device has one and falls back to loopback when it does not, so a start always yields a working server and the QR code is scannable from another machine with no configuration.

Added as a third mode rather than by re-pointing the default at LAN, because LAN earns its keep by not degrading: a host sharing a connect URL with another device needs NoEligibleNetwork/PermissionRequired back, not a 127.0.0.1 link that works for nobody but itself. Explicit LOOPBACK and LAN behave exactly as before.

BrowserEndpoint.bindingMode never reports AUTO — it reports the socket that actually bound, so the connect URL, QR code, and "LAN MODE — UNENCRYPTED" banner stay truthful. Fallbacks are logged with their reason.

The fallback decision lives in AutoBinding as pure functions, because the real thing needs an API 37+ device or a machine with its interfaces torn down — neither stageable in Robolectric. startLocked leaves the first attempt unmapped until the retry is settled, so a rescued start never drags the runtime through serverFailed() on its way to serverStarted().

This loosens a security default

The dashboard speaks plaintext HTTP, so wherever AUTO reaches the network, headers, tokens, and bodies are readable by anyone who can see that traffic. docs/THREAT_MODEL.md is rewritten around the new default rather than patched.

One consequence worth flagging for review: AUTO never prompts for ACCESS_LOCAL_NETWORK. It treats a missing grant as a reason to bind loopback, not a reason to fail, so on an API 37+ device it settles for 127.0.0.1 until something requests the grant. Hosts wanting the prompt ask for BindingMode.LAN by name — which all three samples still do, keeping that path exercised.

AUTO is a reused name, not a restored feature: the pre-1.0 BindingMode.AUTO came with zero-config auto-start and NSD discovery, both still removed. This one only picks a binding. Called out in the KDoc and docs so nobody assumes the old semantics.

Mocks: wired out of the box

installDevConsole now wires the mock interceptor from an engine the facade publishes to a new MockEngineRegistry at initialize. That registry exists to close a layering gap — sdk:network-okhttp sits below the facade and cannot call DevConsole.mockEngine() — so the separate .addInterceptor(DevConsoleMockInterceptor(DevConsole.mockEngine())) line is no longer needed. Pass mockEngine = null to opt out. The protected build publishes nothing, so a release APK reads null and wires no mock interceptor.

EditingCapabilities.mocks now defaults to true, and DevConsoleConfig seeds EditingCapabilities() instead of readOnly(). A mock rule writes nothing of the host's — it only short-circuits DevConsole's own interceptor — so the read-only posture that protects preferences, databases, and files had nothing to protect here. readOnly() is now spelled out field by field, so it still grants nothing at all, mocks included.

One real regression found and guarded

A host keeping their existing manual DevConsoleMockInterceptor line would have ended up with two in the chain, and a Delay rule whose next action proceeds up the chain would have slept in both passes — silently doubling every simulated latency on upgrade. The second interceptor now detects the first one's request tag and stands down.

Two things for the reviewer to decide

The version number is deliberately unresolved. Under CHANGELOG.md's own policy, adding a constant to a public enum is source-breaking for any host that whens exhaustively over BindingMode/BrowserBinding, and flipping a security default is a behavioural break. That reads as a major, not a minor. The changelog entry sits under ## Unreleased with a note, and SDK_VERSION is left at 1.2.0.

The API surface is additive. apiDump is in the diff. The 2- and 3-argument installDevConsole / DevConsoleOkHttp.install overloads are still emitted via @JvmOverloads, so Java call sites and existing bytecode are unaffected; Kotlin callers relying on default arguments should recompile, since the synthetic $default signature changed.

Verification

./gradlew build ktlintCheck detekt apiCheck                       # green
./gradlew :samples:*:verifyDevConsoleProtectedArtifacts --rerun   # green, all three

The protected-artifact check was force-re-run on all three samples specifically because this PR adds a :sdk:mocks dependency to sdk:network-okhttp — the release APKs carry no full runtime.

Two flakes surfaced during verification, both unrelated to this change and both passing on isolated re-run: CrashPolicyGatingTest (a 200 ms thread-state poll) and DevConsoleKtorModuleTest (a 3-minute coroutine timeout under --rerun-tasks load, in a module this PR does not touch). Separately, the nine gradle-plugin functional tests fail identically on a stashed clean tree — pre-existing in this environment, not introduced here.

Tests added

  • AutoBindingTest — the fallback decision, including the failures loopback cannot rescue
  • PlatformFacadeProviderAutoBindingTest — that startLocked consults it, and AUTO never surfaces as a bound mode
  • MockEngineRegistryTest / MockEnginePublishingTest — publish/replace/clear, and that a disabled MOCKS category still publishes a passthrough engine
  • DevConsoleOkHttpMockInstallTest — real calls through MockWebServer: a served mock the upstream never sees, untouched passthrough with no matching rule, and the double-Delay guard

Updated to pin the new contract: FocusedConfigurationTest, DevConsoleContractTest, PlatformFacadeProviderMoreScreenBindingTest, FullFacadeTest.

Docs

README, THREAT_MODEL, LAN_PERMISSION_AND_TROUBLESHOOTING, FAQ_TROUBLESHOOTING, COMPOSER_AND_MOCKS, DATA_INSPECTORS_AND_EXPORTS, and a new "Upgrading from 1.2.0" section in MIGRATION.

🤖 Generated with Claude Code

Two defaults changed, aimed at the same first-run complaint: a fresh
integration handed back a 127.0.0.1 URL that needed `adb forward` before
it showed anything, and a Mocks screen that could not add a mock.

Binding: add BindingMode.AUTO / BrowserBinding.AUTO and make them the
default. AUTO binds a real interface when the device has one and falls
back to loopback when it does not, so a start always yields a working
server. Added as a third mode rather than by re-pointing the default at
LAN, because LAN earns its keep by *not* degrading -- a host sharing a
connect URL with another device needs NoEligibleNetwork/PermissionRequired
back, not a 127.0.0.1 link that works for nobody but itself. The fallback
decision lives in AutoBinding as pure functions, since the real thing
needs an API 37+ device or a machine with its interfaces down.

This loosens a security default: the dashboard speaks plaintext HTTP, so
AUTO exposes headers, tokens, and bodies to anyone who can see the
traffic. THREAT_MODEL.md is rewritten around the new default rather than
patched. AUTO also never prompts for ACCESS_LOCAL_NETWORK -- it settles
for loopback instead -- so hosts wanting the prompt ask for LAN by name,
which all three samples still do.

Mocks: installDevConsole now wires the mock interceptor from an engine the
facade publishes to the new MockEngineRegistry at initialize, closing a
layering gap (sdk:network-okhttp sits below the facade and cannot call
DevConsole.mockEngine()). EditingCapabilities.mocks defaults to true --
a mock rule writes nothing of the host's, it only short-circuits
DevConsole's own interceptor -- while readOnly() still grants nothing.

Guards a real upgrade regression: a host keeping its manual
DevConsoleMockInterceptor would have had two in the chain, and a Delay
rule would have slept in both passes. The second one now stands down.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@maksudur03
maksudur03 merged commit a2e1f70 into main Aug 17, 2026
1 of 2 checks passed
@nur-shuvo
nur-shuvo deleted the feature/default-lan-and-mock-setup branch August 18, 2026 16:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants