Skip to content

README.md

Latest commit

 

History

History
32 lines (19 loc) · 6.72 KB

README.md

File metadata and controls

32 lines (19 loc) · 6.72 KB
Raw

Cloudflare Runtime Gate

This candidate integration for wp-codebox#1838 runs WordPress through PHP-WASM and Playground in Cloudflare Workers.

Runtime Architecture

The entry Worker executes PHP-WASM and WordPress. The named WordPressStateCoordinator Durable Object remains lightweight: it serializes a bounded lease and atomically promotes the current canonical R2 pointer with token, base-revision, and version checks. It never imports or instantiates PHP-WASM. State reads query the coordinator directly; every request that can observe canonical WordPress state acquires a lease first.

On cold start, the entry Worker uses the acquired pointer to rebuild PHP-WASM's disposable SQLite index from canonical MDI Markdown and JSON files. A missing pointer materializes the packaged canonical MDI seed and boots one PHP-WASM primary runtime. The build-time PHP CLI generator creates that archive from wordpress-install-seed.sqlite through MDI's public bootstrap_existing_cache() API, validates its pinned MDI revision and input digest, and never packages SQLite. The runtime updates siteurl and home through WordPress APIs using the request origin and sets the admin password from WORDPRESS_ADMIN_PASSWORD; only WordPress's password hash is canonical. Bootstrap persists and CAS-promotes this mutation before serving the next request.

Canonical browser, health, and mutation boots require the separately managed WORDPRESS_AUTH_SECRET Worker secret. The entry Worker derives the eight WordPress auth keys and salts from that secret with a versioned, site-scoped (default) SHA-256 domain separator before wp-load.php. It never logs, persists, or returns the secret or derived values. Configure it independently from the bootstrap password with wrangler secret put WORDPRESS_AUTH_SECRET --config packages/runtime-cloudflare/wrangler.jsonc; rotating WORDPRESS_ADMIN_PASSWORD does not rotate authentication salts or invalidate sessions.

After each mutating HTTP request, the entry runtime invokes MDI's explicit request-boundary flush, collects canonical files, stores immutable content-addressed R2 objects and a revision manifest, then commits the new pointer through the held lease. GET, HEAD, and asset requests release without promotion. Failed requests abort their leases; stale leases recover by token/version/expiry checks. The entry isolate can cache one runtime only for the exact acquired pointer revision and exits it after promotion or when another isolate advances the pointer. It does not persist SQLite. Existing manifests are reused when canonical file hashes have not changed.

The same revision transaction persists bounded user-managed files under wp-content/plugins, themes, languages, and mu-plugins. Runtime-owned MDI, SQLite integration, and Codebox adapter files remain reconstructable artifacts and are excluded. Unchanged bundled-theme files are omitted by release hash, while modified files become canonical overrides. Public canonical plugin and theme assets serve directly from revision-addressed R2 cache entries before the immutable release corpus. Nonce-protected wp-admin GET actions such as plugin activation are classified as mutations so their filesystem and MDI option changes commit atomically. Existing revisions without wpContent remain valid.

The Worker forwards browser cookies directly to Playground and disables Playground's internal cookie store, preventing an empty per-isolate store from replacing a valid browser session after cold restart.

The bundled MDI source is pinned to immutable commit 2a8ee7f6a46e1d64b4606f1ee3c97e14032dc96c from MDI PR #139. The bundle generator, worker provenance, and source-contract test use the same revision.

WordPress server files, browser assets, and pinned runtime dependencies are separate deployment artifacts, never Worker-module imports. generate:cloudflare-wordpress-runtime-corpus emits a deterministic server ZIP containing only isWordPressRuntimeFile() entries, one concatenated browser-asset blob containing the complete supported wp-admin, wp-includes, and bundled-theme surface, and the pinned SQLite integration ZIP. Checked-in manifests record content-addressed R2 keys, hashes, budgets, provenance, and each browser asset's exact byte range. Cold boot validates and streams the server ZIP into PHP MEMFS while loading SQLite integration from R2. Browser requests use one bounded R2 range read, validate the selected bytes, and populate an immutable artifact-versioned Worker cache. Runtime requests never fetch WordPress or SQLite integration release archives from third-party origins.

Canonical Cloudflare boots patch only the assembled PHP MEMFS copy of /wordpress/wp-settings.php after the R2 WordPress corpus is materialized and before WordPress executes. The disabled-cron scheduling policy requires exactly one canonical do_action( 'init' ); needle and fails closed otherwise. When DISABLE_WP_CRON is true, it removes only core's wp_cron, wp_schedule_delete_old_privacy_export_files, and wp_schedule_update_checks callbacks through public remove_action() before executing the original init call once. This prevents browser requests from recreating cron work that cannot execute in the PHP-WASM/MDI shutdown path. Durable cron execution belongs to a separate explicit queue or scheduled-Worker contract.

Verification

  1. Run npm run generate:cloudflare-canonical-mdi-seed and npm run generate:cloudflare-wordpress-runtime-corpus to regenerate deterministic runtime artifacts and manifests.
  2. Run npm run provision:cloudflare-wordpress-runtime-corpus -- --local --persist-to <directory> to verify and upload all exact content-addressed artifacts into isolated local R2 storage. For an authorized deployment, run the provisioner with --remote and require every upload to succeed before deploying the Worker that imports their manifests.
  3. Run npm run test:cloudflare-runtime for routing, canonical-state, artifact validation, source contract, and TypeScript coverage.
  4. Run npm run cloudflare:dry-run to compile the Worker without creating Cloudflare resources.
  5. Run npm run cloudflare:local-gate for isolated local workerd evidence. It generates and provisions all artifacts before workerd starts, then injects stable test-only admin-password and auth-secret values, uploads and activates a real plugin ZIP, verifies that plugin's REST route before and after Worker restart, and covers login, authenticated REST publication, media, public rendering, representative frontend/admin/editor assets, PHP diagnostics, session recovery, and a fresh login after restart.

This document describes local candidate verification only. It does not claim remote deployment.