Skip to content

[Website] Serve single byte ranges from WP Cloud PHP - #4507

Merged
adamziel merged 1 commit into
trunkfrom
codex/wp-cloud-byte-ranges
Oct 23, 2026
Merged

adamziel merged 1 commit into
trunkfrom
codex/wp-cloud-byte-ranges

Conversation

@adamziel

@adamziel adamziel commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Let PHP-served static files answer a single byte range with HTTP 206, so interrupted PHP runtime downloads can resume instead of starting over. Playground's retry code sends Range: bytes=<offset>- and requires a 206 response.

Supports bounded ranges (bytes=100-199) and open-ended ranges (bytes=100-). An end beyond the file is clamped. A supported range with no valid bytes returns 416 and the file size.

Multiple ranges, suffix ranges, unknown units, unrecognized syntax, and requests with If-Range get the normal full response. HEAD ignores Range and returns the full content length without a body. No multipart response or validator matching is added. Ignoring Range is allowed by the HTTP specification.

Full transfers still use readfile(). Partial transfers seek to the requested offset and stream only those bytes. Existing path checks, redirects, MIME/cache headers, and native PHP handling stay in place.

This is extracted from #4468 and goes below it in the stack. It changes no hostname routing or deployment file layout.

Testing

CI checks the responses through a real local PHP server, including exact bytes, bounded/open-ended ranges, clamping, unsatisfiable ranges, full-response fallback, HEAD, and empty files.

For a manual check, request a static file with Range: bytes=1-3 and verify 206 with three bytes. Repeat with two ranges and verify a full 200 response. A HEAD request should report the full size without a body.

Summary by CodeRabbit

  • New Features
    • Static-file downloads now support single byte-range requests, allowing clients to resume downloads. Valid ranges return partial content; ranges beyond the file return an error response.
    • Unsupported or multiple ranges receive the full file response. HEAD requests continue to return headers without a response body.
  • Documentation
    • Added details on supported range requests and how to run the HTTP behavior tests.

@coderabbitai

coderabbitai Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 89781adc-f921-43c1-ae18-7200364f9a34
📥 Commits

Reviewing files that changed from the base of the PR and between b34b487 and 2a81232.

📒 Files selected for processing: 6
  • .github/workflows/ci.yml
  • AGENTS.md
  • packages/playground/website-deployment/README.md
  • packages/playground/website-deployment/custom-redirects-lib.php
  • packages/playground/website-deployment/test-static-file-ranges.mjs
  • packages/playground/website/project.json

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

📝 Walkthrough

PHP-served static files now support selected byte-range responses. The change adds an HTTP integration test for range handling and connects it to the website Nx target and CI workflow.

Changes: Static File Range Responses

Layer / File(s) Summary
Static response handling
packages/playground/website-deployment/custom-redirects-lib.php
Static non-PHP GET and HEAD requests now use a helper that sets response headers and serves full, partial, or unsatisfied-range responses.
Range contract test and CI wiring
packages/playground/website-deployment/test-static-file-ranges.mjs, packages/playground/website/project.json, .github/workflows/ci.yml, AGENTS.md, packages/playground/website-deployment/README.md
A PHP-server integration test checks range handling, fallback responses, and request methods. The website Nx target and CI workflow run the test. Documentation describes the response behavior and test requirements.

Priority: ➖ Normal

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant playground_handle_request
  participant playground_serve_static_file
  participant StaticFile
  Client->>playground_handle_request: Send static-file request
  playground_handle_request->>playground_serve_static_file: Pass non-PHP file path
  playground_serve_static_file->>StaticFile: Read full file or requested byte range
  playground_serve_static_file-->>Client: Return response with status and headers
Loading

Suggested reviewers: ashfame

Merge Risk: ⚪ Minimal · up to 2a812

The range-serving change is ready for normal merge checks. No actionable failure in the supported download or fallback behavior was established.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (4 skipped: 4… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title "[Website] Serve single byte ranges from WP Cloud PHP" matches the main change. The PR adds PHP-served static-file support for single bytes=start-end range requests, returning 206 for valid …
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.
Full details: Title check

Explanation

The title "[Website] Serve single byte ranges from WP Cloud PHP" matches the main change. The PR adds PHP-served static-file support for single bytes=start-end range requests, returning 206 for valid ranges and 416 for unsatisfiable ones, so the title names the primary feature. It is specific and concise, and it does not describe unrelated work. The title omits the HEAD handling, the test additions, and the documentation, which is acceptable because the title need not cover every detail.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ 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
  • Autofix · 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 added this pull request to stack #4508 October 23, 2026 15:04
@adamziel
adamziel merged commit 92736f3 into trunk Oct 23, 2026
235 of 239 checks passed
@adamziel
adamziel deleted the codex/wp-cloud-byte-ranges branch October 23, 2026 16:52
adamziel added a commit that referenced this pull request Oct 26, 2026
…#4468)

#4511 added the `?reprint` opt-in and is merged. This PR adds the WP
Cloud host rule and deployment wiring on trunk. It uses the single-range
static-file responses merged in #4507.

Keep the app, Dock, PHP runtime, and storage on
`playground.wordpress.net`. With `?reprint`, render WordPress on
`wpsandbox.wordpress.net`. Without the flag, WordPress stays on the app
domain.

```text
playground.wordpress.net       address bar, app, trusted PHP runtime
└── wpsandbox.wordpress.net    WordPress iframe, only with ?reprint
```

## Request handling

All host and path rules live in the existing
`packages/playground/website-deployment/custom-redirects-lib.php`,
reached through `playground_handle_request()`. Only the configured
WordPress host (`wpsandbox.wordpress.net` in production) takes an early
path that serves the `wordpress-sandbox/` subdirectory. Other hosts
continue through the existing app logic. There is no separate router or
parallel app handler.

- The **app host** keeps the existing request handler: rewrites,
conditional and unconditional redirects, directory indexes, MIME types,
custom headers, cache exceptions, HEAD handling, and native PHP
environment setup. There is no replacement app handler or new app-side
PHP allowlist.
- The **WordPress host** serves existing files only from the built
`wordpress-sandbox/` directory. It contains the small request-helper
page and service-worker/thumbnail-worker loaders. Missing files and
paths escaping the directory return 404. No app redirects or native PHP
endpoints run on this host. WordPress pages come from its browser
service worker.

```text
files/
├── index.html, remote.html, api.html, assets/, ...
└── wordpress-sandbox/
    ├── wordpress-bridge.html
    ├── sw.js
    └── assets/<hashed-thumbnail-worker>.js
```

The build writes app-origin URLs into those small files once. PHP serves
their bytes without constructing JavaScript or rewriting HTML for each
request. The worker filename comes from Vite's source-file mapping, so
there is no PHP list of hashed filenames or query-based exception for
arbitrary JavaScript files.

Both hosts use the same app-host bundles, PHP binaries, and WordPress
downloads. Assets allow cross-origin loading and HTTP caching.
Static-file transfers use the range support from #4507. Existing app
cache exceptions remain, including no-store for the app/API entry pages
and identity encoding for static ZIP archives. Sandbox bootstrap
responses use `private, no-store`.

Existing external iframe and SDK embeds keep working without a referrer
or new URL parameters.

## Normal deployment

The website deployment workflow sets the two origins once:

```yaml
PLAYGROUND_APP_ORIGIN: https://playground.wordpress.net
VITE_WORDPRESS_SITE_URL: https://wpsandbox.wordpress.net
```

Vite uses `VITE_WORDPRESS_SITE_URL` for the browser's sandbox selection
and `PLAYGROUND_APP_ORIGIN` for the sandbox files' shared-script URLs.
The SSH step passes those same values to `apply-update.sh`. That one
script checks the origins, installs the release, replaces the entry, and
purges the edge cache. There is no second installer script. The entry
records the sandbox origin; the PHP library and deployment script do not
hardcode production domains. Request headers and query parameters cannot
change the configuration.

`apply-update.sh` installs the setup as follows:

1. Check that the required build entry files exist. Check both public
hosts and direct access to a harmless private-path probe. Refuse
activation if private URLs are readable or a service-worker URL
redirects.
2. Put the complete build and request library under
`/srv/htdocs/.playground-releases/release.<random>/`.
3. Back up the old public entry and move old public build files outside
`htdocs`. Otherwise Nginx could serve them on the WordPress host before
PHP checks the hostname. A failed file move stops activation.
4. Replace `custom-redirects.php` in one rename. It calls the existing
library with that release's build path. Retain previous private releases
and entry files for rollback, then purge the WP Cloud edge cache.

Personal WP keeps its existing entry, file layout, and separate
deployment script. Native PHP endpoint credentials still come from WP
Cloud persistent data.

## Before activation

Both names must map to the same WP Cloud site, with valid TLS and
`canonicalize_aliases=false`. Nginx must deny direct access to
`.playground-releases`, including encoded paths. PHP cannot create that
deny rule; the deployment script checks for HTTP 403 through both hosts
before putting the build there.

The first deployment moves the old public build and can briefly
interrupt requests. Later deployments retain the previous private
release. The deployment guide covers verification, rollback, and
removing obsolete backups.

## Limits

The separate-origin protections apply only to sessions started with
`?reprint`. Ordinary sessions still run WordPress on the app origin and
can access its OPFS and CacheStorage, including data used by opted-in
sessions. Reopening a saved clone without the flag returns its WordPress
code to the app origin.

WordPress cannot directly read an existing parent document or its OPFS,
or call its connected PHP API. It can still embed a **fresh** app/API
document and connect to that document. That path to saved storage
remains unresolved. This is not complete protection for saved files or
native directory handles. Running Playgrounds still share one WordPress
origin, without per-site HTTP authorization.

## Testing

The contract test builds the real sandbox directory, runs the complete
`apply-update.sh` in a temporary directory, and tests the installed PHP
entry. Public probes and the cache-purge API are stubbed. The preview
and upgrade-test servers also serve the built sandbox directory, so the
browser suite exercises that file-serving path. Checks use alternate
configured hostnames and cover invalid origin settings, incomplete
uploads, failed private-path/redirect probes, failed old-file moves,
sandbox restrictions and symlink/traversal rejection, existing redirects
(including referrer-based redirects), directory/index handling,
set-aside files, the plugin-proxy rewrite and persistent-data setup,
native PHP HEAD behavior, custom cache/agent-cluster/archive headers,
shared-asset headers, integration with #4507's static-file sender,
HEAD/OPTIONS, release switching, and rollback files. These tests do not
prove the live Nginx or TLS configuration.

Follow the deployment guide to check both HTTPS hosts and blocked
private URLs. Save a post, switch saved sites, open a database tool, try
a disposable local folder, and test an unchanged no-referrer embed.
Confirm WordPress cannot read or alter a private OPFS file created by
the parent.
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