Skip to content

[PHP] Retain current OPFS mounts across PHP runtime rotation - #4389

Merged
adamziel merged 2 commits into
trunkfrom
codex/opfs-current-runtime-mounts
Oct 7, 2026
Merged

adamziel merged 2 commits into
trunkfrom
codex/opfs-current-runtime-mounts

Conversation

@adamziel

@adamziel adamziel commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

Avoid calling an already-unmounted mount's cleanup again after PHP replaces its runtime.

Background

For a storage mount at /wordpress:

  1. The caller mounts storage and keeps the returned unmount() function.
  2. PHP replaces its runtime. It unmounts the old storage mount, then mounts the same storage again with a new cleanup function.
  3. The caller invokes its saved unmount(). Previously, this called the old mount's cleanup a second time. It could leave the current mount active while removing it from PHP's mount tracking.

This change

The saved unmount() now looks up the current mount and runs its cleanup. It follows replacements made with the same mount handler. If a different handler later mounts something at the same path, the saved function leaves that mount alone. After a successful unmount, further calls do nothing.

Explicit OPFS flushes also use the current mount's journal after runtime replacement. The replacement journal is registered only after its initial copy succeeds, so a failed setup leaves another save possible. Failed OPFS writes preserve the original error even if stream cleanup also fails.

Includes tests for runtime replacement, repeated unmount calls, a different mount at the same path, setup failures, and quota errors.

PR 5 extracted from #4373. Targets trunk directly; no dependency on the other split PRs.

Testing

Save a Playground locally, replace its PHP runtime, edit a file, flush, and reopen it. Check that the edit persists. Call the saved unmount() twice and check that cleanup runs only for the current mount, once.

Summary by CodeRabbit

  • Bug Fixes
    • Mounts now clean up correctly when replaced or mounted again, without an outdated unmount action detaching the replacement.
    • Failed OPFS writes now preserve the original error while attempting safe cleanup, even if cleanup also fails.
    • OPFS mounts can be retried after setup failures. Replacement journals are used for flushing only after their initial copy completes, preventing incomplete data from being exposed.

@coderabbitai

coderabbitai Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 417ef061-1acb-4e2f-940c-c89d95ace462
📥 Commits

Reviewing files that changed from the base of the PR and between 9b9afad and f290263.

📒 Files selected for processing (1)
  • packages/php-wasm/universal/src/lib/php.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • packages/php-wasm/universal/src/lib/php.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.


📝 Walkthrough

Walkthrough

The change updates PHP mount teardown, OPFS writer cleanup, and worker endpoint mount tracking. Tests cover handler replacement, write and cleanup failures, failed mount retries, and runtime rotation.

Changes

OPFS mount lifecycle

Layer / File(s) Summary
PHP mount handle lifecycle
packages/php-wasm/universal/src/lib/php.ts, packages/php-wasm/universal/src/lib/php.spec.ts
The returned unmount function acts on the current mount at the path only when its handler matches the original handler. Tests cover repeated unmount calls and replacement handlers.
OPFS write failure cleanup
packages/php-wasm/web/src/lib/directory-handle-mount.ts, packages/php-wasm/web/src/lib/directory-handle-mount.spec.ts
Failed truncation or writing triggers abort when available, or close otherwise. Cleanup errors are ignored, and the original error is rethrown. Successful writes close the writer.
Worker endpoint mount tracking
packages/playground/remote/src/lib/playground-worker-endpoint.ts, packages/playground/remote/src/lib/playground-worker-endpoint.spec.ts
The endpoint tracks a mount only after its handler succeeds and clears stored tracking when mounting fails. Tests cover retries, runtime rotation, and replacement journal availability during copying.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant PlaygroundWorkerEndpoint
  participant PHP
  participant OPFSMountHandler
  PlaygroundWorkerEndpoint->>PHP: Pass wrapped handler to PHP.mount
  PHP->>PlaygroundWorkerEndpoint: Invoke wrapped handler during mount
  PlaygroundWorkerEndpoint->>OPFSMountHandler: Run handler after clearing mount tracking
  alt Handler succeeds
    OPFSMountHandler-->>PlaygroundWorkerEndpoint: Return from handler
    PlaygroundWorkerEndpoint->>PlaygroundWorkerEndpoint: Track replacement mount
  else Handler fails
    OPFSMountHandler-->>PlaygroundWorkerEndpoint: Throw mount error
    PlaygroundWorkerEndpoint->>PlaygroundWorkerEndpoint: Remove stored unmount callback
  end
Loading

Merge Risk: ⚪ Minimal · up to f2902

The mount lifecycle change is mergeable after normal checks; no concrete remaining failure was identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 6 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: retaining current OPFS mounts across PHP runtime rotation.
  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@adamziel
adamziel merged commit 544f7f9 into trunk Oct 7, 2026
@adamziel
adamziel deleted the codex/opfs-current-runtime-mounts branch October 7, 2026 11:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant