Prod and Beta apps cannot run concurrently on iOS: second app shows white screen until the other is killed (local server port collision on localhost:12280)

[abroa01]

Bug

Production MIEAuth and MIEAuth Beta cannot run concurrently on the same device. If one app is open (or suspended in the background), launching the other shows a white screen / stuck state. The only workaround is to kill one app before using the other.

Steps to reproduce

1. Install both the production app and the beta app on the same iOS device.
2. Open app A, let it load, then send it to the background (do not kill it).
3. Open app B.

Expected: App B loads normally.
Actual: App B shows a white/stuck screen. Killing app A and relaunching app B fixes it.

Environment

• Platform: iOS (Android appears unaffected — see analysis below)
• Both apps built from the same repository (prod: org.mieweb.opensource / com.mieweb.mieauth, beta: org.mieweb.os.dev)

---

Root-cause analysis to follow in comments.

[abroa01]

Root-cause analysis

TL;DR: Both apps run an in-app HTTP server bound to the same fixed TCP port (localhost:12280). iOS shares the loopback network namespace across apps, so whichever app binds the port first wins; the second app's local server fails to start and its WKWebView has nothing to load → white screen.

Evidence

1. The port is derived from the Meteor project ID, which both flavors share.

Meteor's Cordova builder computes the local web server port deterministically from the project ID in .meteor/.id. Prod and Beta are built from the same repository (the CI workflows only sed-patch the bundle id/name in mobile-config.js — see .github/workflows/deploy-development.yml and deploy-production.yml), so both apps end up with the identical port. From the generated .meteor/local/cordova-build/config.xml:

<content src="http://localhost:12280/"/>
<preference name="hostname" value="localhost:12280"/>

2. On iOS the plugin binds a real TCP socket to that port.

cordova-plugin-meteor-webapp/src/ios/WebAppLocalServer.swift starts a GCDWebServer on the port parsed from the start page URL:

// In all other cases, we use a listening port that has been set during build
let port = URLComponents(string: viewController.startPage)?.port
...
GCDWebServerOption_Port: NSNumber(value: localServerPort as UInt),
GCDWebServerOption_AutomaticallySuspendInBackground: false]

Note AutomaticallySuspendInBackground: false — the backgrounded app keeps the socket bound while suspended, which is exactly why the collision persists until the first app is fully killed.

3. The failure mode matches the symptom.

In pluginInitialize():

do {
  try startLocalServer()
} catch {
  NSLog("Could not start local server: \(error)")
  return
}

The error is only logged; the WKWebView is then pointed at http://localhost:12280, which is being served by the other app's bundle — or, depending on auth-token mismatch/timing, serves nothing usable → white/stuck screen. (Each app's server requires a per-app cdvToken query auth, so the second app can't even piggyback on the first app's server.)

4. Why Android is unaffected.

src/android/WebAppLocalServer.java uses androidx.webkit.WebViewAssetLoader — in-process request interception with no TCP socket at all — so there is no port to collide on Android.

Why killing one app fixes it

Killing the foreground/background app releases the bound socket; the next launch of the other app successfully binds 12280 and boots normally.

Fix options

1. Give the beta a different port (recommended, minimal): in the beta CI patch step, also override the port. The plugin honors a WebAppLocalServerPort preference (WebAppLocalServer.swift reads it before falling back to the start-page port), but the start page URL/hostname in config.xml must match. The cleanest lever is patching the port Meteor computes — e.g. set App.setPreference("WebAppLocalServerPort", "12281", "ios") for beta builds and verify the generated <content src> follows, or patch .meteor/.id for beta builds so Meteor derives a different port (side effect: different HCP appId, which is arguably correct for a separate app).
2. Fallback-to-random-port in the plugin (upstream fix): catch the bind failure and retry with port 0 (GCDWebServer assigns a free port; the plugin already updates viewController.startPage with the assigned port after start).
3. Migrate iOS to a scheme handler / asset loader like Android (largest change, upstream).

Option 1 is the low-risk immediate fix we control entirely in this repo's CI.

[abroa01]

TODO — Issue #468: Prod/Beta iOS local-server port collision

Prod MIEAuth and MIEAuth Beta cannot run concurrently on the same iOS device: the second app shows a white/stuck screen until the other is killed.
Tracking: #468

Root cause (confirmed)

• Meteor derives the Cordova local web server port by hashing the project ID in .meteor/.id into the 12000–12999 range.
• Prod and Beta are built from the same repository → same project ID (jp4aul86o9am.wjvst2vahkih) → same port 12280 in both apps. CI only patches the bundle ID/app name in mobile-config.js, never the project ID.
• Generated .meteor/local/cordova-build/config.xml confirms:

  <content src="http://localhost:12280/"/>
  <preference name="hostname" value="localhost:12280"/>

• On iOS, cordova-plugin-meteor-webapp (WebAppLocalServer.swift) binds a real GCDWebServer TCP socket on that port with GCDWebServerOption_AutomaticallySuspendInBackground: false — a backgrounded app keeps the port bound.
• The second app's startLocalServer() throws; the error is only NSLog'd, and its WKWebView points at http://localhost:12280 served by the other app (rejected by per-app cdvToken auth) → white screen.
• Killing one app releases the socket, which is why the other then loads fine.

Why this doesn't affect all Meteor apps

• Unrelated Meteor apps have different .meteor/.id values → different hashed ports (~0.1% accidental collision chance per pair). The randomization exists precisely so different Meteor apps coexist.
• The design just doesn't account for two flavors of the same project installed side by side — our exact case.
• Android is unaffected: the plugin uses in-process androidx.webkit.WebViewAssetLoader — no TCP socket, no port to collide.

Fix options

1. [Recommended] Distinct port for beta builds — patch the beta CI (deploy-development.yml iOS job) to override the port (e.g. WebAppLocalServerPort preference and/or ensure the generated <content src>/hostname follow), or give beta builds a different .meteor/.id (side effect: separate HCP identity, arguably correct for a separate app). Low risk, fully in-repo.
2. Upstream plugin fix: on bind failure, retry with port 0 (GCDWebServer assigns a free port; plugin already rewrites startPage with the assigned port).
3. Upstream migration: move iOS to a WKURLSchemeHandler/asset-loader model like Android (largest change).

Task list

• Decide port-override mechanism for beta (preference patch vs distinct .meteor/.id in CI)
• Implement in .github/workflows/deploy-development.yml (iOS beta job)
• Verify generated config.xml in the beta build shows the new port (content src + hostname)
• Ship beta via TestFlight/Play internal and confirm prod + beta run concurrently on one iOS device
• Confirm hot code push still works on beta after the change
• (Optional) File upstream issue/PR against cordova-plugin-meteor-webapp for the bind-failure fallback
• Close Prod and Beta apps cannot run concurrently on iOS: second app shows white screen until the other is killed (local server port collision on localhost:12280) #468 with verification notes