fix: [SDK-4336] guard IndexedDB Options writes from iOS Safari PWA wedge

[sherwinski]

Description

1 Line Summary

Stops OneSignal.init() from hanging for ~30 minutes on iOS 26 Safari PWAs by capping Options-store readwrite operations with a 1.5s hard timeout and tripping a page-scoped circuit breaker once the wedge is detected.

Note: A bug report (315804) was filed in Webkit upstream to investigate this.

Details

Root cause

On iOS 26 Safari running as a Home-Screen PWA (display: standalone), the navigation back into the app after a successful push subscription leaves the ONE_SIGNAL_SDK_DB IndexedDB in a poisoned state where every readwrite request on the Options object store stalls indefinitely. The IDBRequest is created and goes to pending, but no event ever fires — no success, no error, no transaction complete / abort, no IDBDatabase.onclose. WebKit's internal transaction watchdog only forcibly aborts the wedged transaction after roughly 30 minutes; until then await db.put('Options', ...) never settles.

OneSignal.init() always writes to Options very early — initSaveState writes pageTitle, saveInitOptions writes 7+ entries (webhook URLs, persistNotification, click-handler config, lastPushToken, isPushEnabled, etc.). Without this guard, the very first of those writes blocks init forever and the support team observes "init hanging for 30 minutes, then eventually recovers" — exactly the watchdog timer.

What we ruled out and how:

• NetworkProcess crash family (WebKit bugs 273827 / 277615 / 309386). Those throw UnknownError: Connection to Indexed Database server lost and fire IDBDatabase.onclose. We never see either.
• Process suspension (202705). That throws TransactionInactiveError synchronously. We throw nothing.
• PWA total freeze (211018). All other JS keeps running — timers fire, fetch works, the SW heartbeat keeps ticking — only this one IDBRequest is dead.
• Connection-level wedge. Reads (get, getAll) on the same DB connection still work. readwrite on other stores still works. Closing and re-opening the database returns a fresh IDBDatabase whose first readwrite on Options wedges identically.
• Origin-wide IDB wedge. A diagnostic probe that opened a different IndexedDB name at the same origin and issued a readwrite put completed in 11 ms while the real DB was hung. The wedge is per-database, not origin-wide.

Filed upstream as WebKit bug 315804 ("A readwrite IDBTransaction never fires oncomplete, onerror, or onabort after the user subscribes to web push in an installed PWA") with a link back to this PR for steps on how to reproduce. The source comment in client.ts also references the bug so the workaround can be removed once WebKit ships a fix.

Fix

Three commits, each independently revertable:

1. 81415fdd — fix: fail-fast Options writes. Wrap db.put('Options', ...) and db.delete('Options', ...) with a 1500ms hard timeout. On timeout, log a [SDK-4336] warning and resolve the promise as a no-op so init proceeds. Other stores keep their existing behavior. The values that don't get persisted are session metadata that the SW reads with sensible fallbacks if missing or stale, so push delivery is unaffected.

2. 1ae8abdf — perf: short-circuit after first wedge. Once a single Options readwrite times out we know the store is poisoned for the rest of this page's lifetime. Add a module-scoped optionsWriteWedged flag so the remaining 7 Options writes in initSaveState + saveInitOptions short-circuit immediately instead of each independently paying the 1500ms timeout. Cuts init latency on a wedged page from ~12s to ~1.5s. The flag is page-scoped (resets on navigation), so a subsequent navigation will probe the wedge fresh.

3. 88e4cd59 — chore(preview): repro sandbox (will be reverted before merge). Two-page demo + dev-server hardening that lets a reviewer reproduce the original 30-minute hang on main and confirm this branch resolves it. Detailed testing instructions in a separate PR comment.

A 4th commit (3c41181b) generalizing the timeout to all readwrite stores was tried and reverted (83cbff87) because we couldn't validate it on device — every subsequent on-device repro happened with an empty operation queue. Parked in branch history with the validation steps captured in a Linear comment on SDK-4336.

Systems Affected

• WebSDK
• Backend
• Dashboard

Validation

Tests

Info

• Full suite: 512/512 pass, lint clean, formatter clean.
• The fix path is exercised by the existing client.test.ts round-trip tests (every Options write goes through the new wrapper, so all 12 client tests are effectively also covering the timeout path's happy case).
• On-device verification on iPhone running iOS 26.4 (logs11.txt → logs14.txt in the chat): pre-fix init hung indefinitely; post-fix init completes within ~1.5s on the wedged navigation, with a [SDK-4336] db.put(Options) timed out … Tripping circuit breaker warning and 7 follow-up db.put(Options) skipped warnings, then internalInit → SW handshake → sessionInit proceed normally.
• I haven't added a unit test specifically for the timeout path because the existing client.test.ts uses fake-indexeddb which doesn't reproduce the WebKit-specific wedge — a synthetic timeout test would only verify the timer plumbing, which is straightforward enough that the on-device evidence is more meaningful.

Checklist

• All the automated tests pass or I explained why that is not possible
• I have personally tested this on my machine or explained why that is not possible
• I have included test coverage for these changes or explained why they are not needed

Programming Checklist

Interfaces:

• Don't use default export
• New interfaces are in model files

Functions:

• Don't use default export
• All function signatures have return types
• Helpers should not access any data but rather be given the data to operate on.

Typescript:

• No Typescript warnings
• Avoid silencing null/undefined warnings with the exclamation point

Other:

• Iteration: refrain from using elem of array syntax. Prefer forEach or use map
• Avoid using global OneSignal accessor for context if possible.

Screenshots

Info

N/A — runtime correctness fix, no UI changes. See on-device console logs in the SDK-4336 Linear ticket and chat history.

Checklist

• I have included screenshots/recordings of the intended results or explained why they are not needed

---

Related Tickets

SDK-4336

[sherwinski]

Testing instructions for reviewers

The third commit (88e4cd59 chore(preview): add iOS PWA repro sandbox) is included specifically so you can reproduce the bug end-to-end on a real iOS device. It will be reverted before merge — please don't ship it.

You'll need:

• A real iOS device running iOS 26.x (the bug doesn't surface in the iOS Simulator's WebKit). Mine: iPhone running iOS 26.4.
• An ngrok / Cloudflare tunnel account so the iOS device can reach your dev machine's HTTPS server.
• A OneSignal app whose Site URL matches the tunnel host you'll be using, with a custom service-worker integration pointing to push/onesignal/OneSignalSDKWorker.js. (A pre-existing app pointing to https://localhost:4000 will not work — Apple/iOS Web Push enforces an exact origin match against your tunnel host. Easiest path: create a fresh disposable test app in the dashboard.)

One-time setup

# Repo
git checkout sherwin/sdk-4336

# Build the dev SDK against your tunnel host so the iOS device fetches assets
# from the right origin. Replace the value with your own ngrok host.
BUILD_ORIGIN=<your-tunnel-host>.ngrok-free.app NO_DEV_PORT=true vp run build:dev-prod

# In two separate terminals:
SDK_ENV=dev vp dev --filter @onesignal/preview     # serves on https://localhost:4001
ngrok http https://localhost:4001                  # exposes that to the public

Reproduce the bug on main (control)

To confirm the bug is real before validating the fix:

git checkout main
# Repeat the build + dev server commands above against the same tunnel host

1. On the iPhone, open https://<your-tunnel-host>.ngrok-free.app/pageA.html?app_id=<APP_ID> in Safari.
2. Tap the Share icon → Add to Home Screen → Add. The web inspector won't follow it once installed; that's fine, we don't need it for the control.
3. Open the installed PWA from the Home Screen.
4. Tap Go to Page B → tap Go to Page A → tap Register → accept the system prompt.
5. Tap Go to Page B → tap Go to Page A.
6. Page A's body should still appear, but OneSignal.init() will not complete. If you switch your Mac to Safari → Develop → [device name] → [the PWA's web view] before tapping that final Page A link, you'll see the console freeze with no OneSignal initialized (Nms) log line. Leave it for ~30 minutes and it will eventually resume by itself — that's the WebKit watchdog firing.

Verify the fix

git checkout sherwin/sdk-4336
# Rebuild against the same tunnel host
BUILD_ORIGIN=<your-tunnel-host>.ngrok-free.app NO_DEV_PORT=true vp run build:dev-prod

Reset state on the device (delete the PWA from Home Screen and reinstall, or in Safari → Settings → Advanced → Website Data → remove the tunnel host's data), then run the same 6-step sequence above.

On the final B → A navigation you should see, in roughly this order:

[Log]    !!!! [SDK-4336 PAGE A] OneSignal initialize
[Debug]  init()
...
[Warning] [SDK-4336] db.put(Options) timed out after 1500ms; IndexedDB Options
          store is wedged (likely iOS Safari PWA after push subscription).
          Tripping circuit breaker; subsequent Options writes on this page
          will be skipped immediately.
[Info]    Set pageTitle to be 'OneSignalWeb'.
[Warning] [SDK-4336] db.put(Options) skipped; Options store is known wedged
          for this page.    (× 7-ish times)
[Debug]   internalInit()
[Info]    Checking SW version...
[Debug]   sessionInit()
[Log]     !!!! [SDK-4336 PAGE A] OneSignal initialized (~1500ms)

The total init time on the wedged navigation should be ~1.5s instead of indefinite. No Ops in progress runaway loop, no exceptions, push delivery still works.

What I confirmed on my device

• Pre-fix: init never completed in 30+ minutes of waiting.
• Post-fix (81415fdd only): init completes after ~12s (8 separate Options writes each timing out individually).
• Post-fix (81415fdd + 1ae8abdf): init completes after ~1.5s (one timeout, the rest short-circuit). This is the shipped behavior.

Captured logs are in the SDK-4336 Linear ticket if you want to compare to your own run.

Pre-merge

Before merging, please drop the sandbox commit:

git rebase -i origin/main      # drop 88e4cd59
git push --force-with-lease

The remaining commits (81415fdd, 1ae8abdf) are the only ones that need to ship.

[sherwinski]

Note: we'll also roll back the [SDK-4336]... logs before merging.

[sherwinski]

@claude review

[fadi-george]

How'd you settle on this value?

[sherwinski]

Just by tinkering with it and trying to find a balance between letting it hang too long and letting a non-poisoned state operate normally. We can increase it, since either way it will be a lot better than the current ~30 min it takes to resolve itself.

[fadi-george]

So what happens if it does fail, do operations just linger?

[sherwinski]

On timeout we resolve the wrapper promise with undefined and trip the breaker, so the JS caller proceeds. The underlying IDBRequest itself isn't cancellable — it stays queued in WebKit's transaction queue and eventually settles (~30 min later, when the OS watchdog aborts the wedged transaction). By then the page is usually unloaded. Our op().then(...) handler has an if (settled) return; guard, so the eventual settlement is a no-op for us — no unhandled rejection, no late state mutation. Net effect on the page: zero; one zombie IDB request lingers on the WebKit-internal side until the OS reaps it.

[fadi-george]

avoid overusing logs, they bloat sdk size

[fadi-george]

isnt key always string

[fadi-george]

maybe dont need this log

[fadi-george]

could do to optimize for bundle size:

function guardOptionsWrite<T>(
  storeName: IDBStoreName,
  label: string,
  op: () => Promise<T>,
): Promise<T | undefined> {
  if (storeName !== 'Options') return op();
  if (optionsWriteWedged) {
    return Promise.resolve(undefined);
  }
  let timer: ReturnType<typeof setTimeout>;
  const timeout = new Promise<undefined>((resolve) => {
    timer = setTimeout(() => {
      optionsWriteWedged = true;
      Log._warn(`db.${label} timed out`);
      resolve(undefined);
    }, OPTIONS_WRITE_TIMEOUT_MS);
  });
  return Promise.race([op(), timeout]).finally(() => clearTimeout(timer));
}

[fadi-george]

would fadi/sdk-4336-options-write-timeout be enough?