Skip to content

Layer 3: the database gateway for isolated plugins (#94) - #97

Merged
samifouad merged 9 commits into
mainfrom
claude/layer3-db-94
Nov 12, 2026
Merged

samifouad merged 9 commits into
mainfrom
claude/layer3-db-94

Conversation

@samifouad

@samifouad samifouad commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

An isolated plugin's $wpdb now works: in its child, $wpdb is a gateway to the php-fpm worker. The worker runs each query on its real connection, under layer 2's own check, charged to the plugin. Two commits:

  1. Layer 2 fix. The UTF-8 bug, found while building the gateway, is fixed in its own commit (details below).
  2. The gateway.

closes #94 (part of #53)

Design

What crosses the wire. The existing request socket and frames carry it:

  • Child → worker: a Q\n<sql> frame (ext/layer3/src/gateway.rs). The child sends it in place of the answer the worker is waiting for, either to the plugin's load or to a call.
  • Worker → child: one PHP-serialized frame per query, holding:
    • ret, error (becomes last_error);
    • keys + rows (rows as value lists);
    • cols (column names);
    • num_rows;
    • affected (for a write);
    • insert_id (for an INSERT/REPLACE).
  • The worker then goes back to waiting.
  • The hello gains the worker's $wpdb facts: charset, collate, db_version() and db_server_info(). It carries no host, user, password or database name.

Where layer 2's checks run. Layer 2 runs in the worker, through the same functions as for a plugin that isn't isolated:

  1. The extension reads the frame and first applies layer 3's own admission (gateway::admit):
    • the dbQueries cap;
    • 16 MiB of text at most;
    • the text must be UTF-8;
    • the text must not name max_statement_time or max_execution_time.
  2. The stand-in takes the text (securecore_layer3_db_begin) and runs $wpdb->query($sql) on the real connection.
  3. While it runs, attribution::db_caller treats the stand-in's own frames as plugin:<slug> (layer3::gateway_component). Those frames are compiled under securecore-layer3:<slug>, a name only the extension uses.
  4. So db::check gives the plugin the same verdict and writes the same line as for that plugin's own $wpdb->query().
  5. The test compares the lines. The sorted set from the isolated run is byte-identical to the set from the same page with the plugin unisolated:
    layer2 enforce plugin:sc-l3db mysqli_query core-table select wp_users
    layer2 enforce plugin:sc-l3db mysqli_query server-file select -
    layer2 enforce plugin:sc-l3db mysqli_query table select wp_sc_l3_neighbour_data
    

The child never picks the attribution. The slug is the key of the channel the worker opened; nothing in a query frame names a plugin. Other plugins' query filters run as they always do, and any SQL they run is charged to them, not to the isolated plugin.

The child side. helper.php's connectionless $wpdb overrides query(): it applies the plugin's own query filters, then goes through the gateway. Everything else is wpdb's own code on top of that:

  • get_results, get_row, get_var, get_col;
  • insert, update, delete, replace;
  • prepare, dbDelta, get_charset_collate, transients.

_real_escape escapes byte for byte as mysqli_real_escape_string does on utf8mb4, so the worker gets the same text the plugin would send unisolated.

Caps (layer3.limits, added to the schema):

cap default what it does
dbQueries 1000 per request and plugin; logged once per request
dbResultBytes 4 MiB, at most 16 MiB per answer
timeoutMs as before now also covers the call's queries

For time, the stand-in sets SET SESSION max_statement_time (MariaDB) or max_execution_time (MySQL) to the call's remaining time, once per call that queries. Afterwards it restores the session's own value, which it reads once per request. A child past its deadline is killed as before.

Transactions. If a child dies with a transaction open (START/BEGIN/autocommit=0), the worker rolls it back and logs a line. Without that, core's later writes in the request would join the open transaction and be lost at disconnect.

Layer 2 bug fixed (commit 1)

db::check read the SQL argument with Zval::str(), which gives up when the text isn't valid UTF-8. On that path the handler ran the query unchecked. So one \xff byte, even inside a comment, skipped layer 2 on every route for a non-isolated plugin.

Proven on main's extension:

mysqli_query($dbh, "SELECT user_login, user_pass FROM wp_users /* \xff */ LIMIT 1")

ran (not-utf8-direct is BLOCKED (got 'OK')). It now reads the text lossily: an invalid byte is never ASCII, so the statement's structure is what the server sees. The gateway refuses text that isn't UTF-8 outright.

Evidence

All on [xps], project scl3db; the microVM run used project scl3dbmvm.

gate result
docker build --target check (clippy -D warnings + cargo test, whole workspace) rc=0
test/ext-config.sh all passed
test/ext-layer3.sh all ext-layer3 checks passed (163 ok)
test/ext-attribution.sh, ext-enforce, ext-vault, ext-db, ext-hosts, ext-layer1 rc=0 each
test/ext-microvm.sh (KVM, jailed Firecracker guest, kernel from bench/microvm/kernel.sh) all ext-microvm checks passed; the probe's isolated child runs in the guest
scripts/ext-build.sh 8.3 nts rc=0
scripts/guest-build.sh, test/release-check.sh 8.3 nts, test/promote-check.sh rc=0 each (release check: all passed; promote check: all passed)

Clippy line, from the check target: clippy --workspace --all-targets -D warnings, clean (rc=0).

What ext-layer3 now proves (new fixture test/ext/layer3-plugin/sc-l3db.php, isolated):

  • Own table and every method. It creates its own table with dbDelta, then OKs for insert, get_row (quotes, a backslash, a newline and a NUL round-trip), get_row(ARRAY_A), update (rows_affected), replace, insert_id, get_var, get_col, get_results (+OBJECT_K, num_rows), get_col_info('name'), a rolled-back transaction, delete, a bad query's last_error, and transients.
  • Its own option persists. It keeps a counter in its own option, and the counter grows across requests and lands in the site's database. The plugin's table row is read back from MariaDB.
  • It reads options. A site option, both at load and in a call; and blogname from the snapshot.
  • Layer 2's refusals hold. A core table without a grant, a refused statement (LOAD_FILE) and another plugin's table are each refused, with last_error from layer 2. The lines are identical to the unisolated run.
  • Layer 3's own refusals are logged: SQL that isn't UTF-8, and a change to the time cap.
  • The caps trip:
    • 59 of 80 queries ran under dbQueries 60 (the load used one), logged once;
    • a 300 KB answer is refused under dbResultBytes 65536;
    • SELECT SLEEP(5) is cut at 1.59 s (timeoutMs 1500) and no longer runs on the server.
  • Transactions. A child killed mid-transaction: the worker rolls back, and another plugin's later update_option in the same request commits.
  • No secrets in the child:
    • getenv(), $_ENV and /proc/<pid>/environ are empty, and DB_PASSWORD is undefined;
    • a scan of 43,753,472 bytes of the child's heap, stack and anonymous memory, taken while it ran the call, finds the DB password 0 times and a salt 0 times (control: "WordPress" found);
    • the scan runs from outside, as root with CAP_SYS_PTRACE in the container (test/ext/layer3-memscan.php), because a layer 3 child isn't dumpable after its uid change.
  • Revert checks within the suite:
    • with layer 2 off, the refused queries run through the gateway;
    • unisolated, nothing caps the queries: 80/80 ran, the 300 KB answer came back, and the sleep held the page for 5 s;
    • the same memory scan of the worker finds the password 4 times.

Revert proofs

  • The new test against main's extension (its own stack scl3dbmain; the new cap keys are dropped from the config, because main's parser rejects them): 46 FAIL. Every gateway case is BLOCKED, the layer 2 lines don't appear, no cap trips, the sleep finishes, and not-utf8-direct runs (the layer 2 bug). Sample:
    FAIL db: dbdelta is OK (got 'BLOCKED')
    FAIL db: its own option persisted from one request (child) to the next (got '0', want '1')
    FAIL layer 2's lines for the isolated plugin are the unisolated plugin's (0a1,3 > ...core-table... > ...server-file... > ...table...)
    FAIL caps: the query cap stopped the loop (ran '0')
    FAIL unisolated: SQL that isn't UTF-8, straight to mysqli: not-utf8-direct is BLOCKED (got 'OK')
    
  • The stand-in's rollback disabled (this branch, one line): 2 FAIL, exactly the transaction checks:
    FAIL transactions: the worker rolled back what the dead child left open
    FAIL transactions: a later write in the same request (another plugin's) committed, not swallowed by the open transaction (got '', want 'm…')
    

Cost per query

[sc_l3db_time] runs a one-row get_row(prepare(…)) 50 times, measured in the plugin, and takes the median of 7 pages. Isolated it costs ~316 µs. In a quiet run the same query cost ~155 µs unisolated, so the gateway adds about +160 µs per query. The unisolated figure swung to 551 µs in a second run while other builds shared the box, so the delta is rough. A call that queries also adds two SET SESSION statements. It isn't tuned yet: column names are fetched for every SELECT, and rows cross PHP-serialized.

Covered / not covered

Covered:

  • the $wpdb methods above, prefix and the table properties, dbDelta, transactions;
  • queries at load and in calls;
  • gelada (host) and the microVM guest.

Not covered (in ext/README.md "Not yet"):

  • Column metadata other than names.
  • Escaping assumes backslash escapes: a server whose global sql_mode has NO_BACKSLASH_ESCAPES would differ.
  • A plugin's own mysqli/PDO connection still fails in the child, because it has no network.
  • An isolated plugin's query filter doesn't see its own queries in the worker: a re-entered call passes through, with a line.
  • Behaviour change: core code in the child that queries for the plugin (for example get_option() of a core option missing from the snapshot) is charged to the plugin, not to core, because the child can't prove which of its frames are core's. Unisolated, the same call would be core's.
  • securecore_layer3_db_reply and its siblings are PHP functions, so a non-isolated plugin in the worker could forge an answer to an isolated child. It can't run SQL as that plugin: the stand-in only runs text the child sent.

Out of scope, still in #53's "not yet" list: request state, objects across the socket, salted pluggables and mail, outbound HTTP.

-claude

The database handler read the SQL argument as UTF-8 and ran the query
unchecked when it wasn't, so one invalid byte anywhere in a query (a
comment is enough) skipped layer 2 for every route. Read it with the
invalid bytes replaced: such a byte is never ASCII, so the statement's
structure reads as the server reads it.
An isolated plugin's $wpdb in its child is a gateway to the php-fpm
worker: each query crosses the request socket as a Q frame while the
worker waits for the plugin's load or a call, and the stand-in runs it
on the worker's real connection with $wpdb->query(). While it does,
the stand-in's frames are the plugin, so layer 2's own caller rule
charges the query to it exactly as unisolated: same check, same
verdict, same audit line. The child holds no connection and no
credential; the slug comes from the channel, never from the child.

The worker admits each query first: dbQueries per request, size,
UTF-8, and no change to the statement time cap. dbResultBytes caps an
answer; the call's remaining timeoutMs caps each statement on the
server (max_statement_time / max_execution_time). A transaction left
open by a child that dies is rolled back.

Tests: ext-layer3 gets a database probe (dbDelta table, every $wpdb
method, own options, layer 2's refusals with the unisolated lines, the
caps, the child's memory and environment scanned for the DB password)
and ext-microvm runs it in the guest.
- Transactions: after every exchange that queried, however it ended, the
  stand-in reads the connection's state from the server (@@autocommit,
  @@in_transaction or innodb_trx) instead of parsing SQL, and rolls back
  and restores autocommit when the plugin left either changed. A normal
  return no longer leaves core's later writes in the plugin's transaction.
- dbResultBytes is applied while the rows are copied, not after the whole
  answer is serialized; the worker's copies are freed on a refusal.
- The child gets the server error's code and text with the database name,
  user and host taken out.
- The statement time cap is re-set to the time left before a query when
  the last setting is over 50 ms old. MySQL's SELECT-only limit is #99.
- A unit test that read_frame refuses an oversized length prefix before
  allocating.
…ounds the worker's memory; strip only the database name from errors
@samifouad

Copy link
Copy Markdown
Member Author

Review fixes

Commits e79572d and 22e43c0. Merges only; 3aa4b88 is untouched.

finding fix test (fails on f355a4a, passes now)
HIGH: an open transaction captures core's later writes. It was only rolled back when the child died, and the check parsed the SQL text. After every exchange that queried, however it ended, the stand-in asks the server for the connection's real state: @@autocommit + @@in_transaction on MariaDB, or information_schema.innodb_trx for CONNECTION_ID() on MySQL. If the plugin left a transaction open or autocommit off, it does ROLLBACK, then SET autocommit = 1, and logs layer3 plugin:<slug> left a transaction open on the worker's connection: rolled back[, autocommit restored]. transaction_effect() and its parsing are gone. A db unit test confirms layer 2 refuses XA START/XA BEGIN to a component, so an XA transaction can't be left open. [sc_l3db_txn_open] (/* hidden */ START TRANSACTION) and [sc_l3db_autocommit_off] (SET autocommit = FALSE): both write and return normally. Core's later update_option in the same request commits. Before the fix: core's later write in the same request committed (got <previous mark>) for both.
dbResultBytes applied after the full buffer and serialize The stand-in runs the query the way $wpdb->query() does (the worker's query filters, then mysqli_query() on $wpdb's connection, so layer 2 sees the same route and text and writes the same lines). But it reads the result unbuffered (MYSQLI_USE_RESULT) and counts bytes row by row. Past the cap it drains the rest unread and refuses the answer cleanly. [sc_l3db_huge]: 40 rows of 1 MiB against a 64 KiB cap. The page renders with a 200, the answer is refused, and the worker's peak memory is 7.8 MB. Before the fix: 500, Allowed memory size of 134217728 bytes exhausted … class-wpdb.php.
Raw last_error leaks the database name and user The child gets [errno] text, with the database name stripped where the server names it ('db.table', `db`, 'db') and 'user'@'host' replaced by '<user>'@'<host>'. Layer 2/3 refusals pass through unchanged. [sc_l3db_err] now reads [1146] Table 'wp_sc_l3db_nope' doesn't exist. Before the fix: Table 'wordpress.wp_sc_l3db_nope' …. The user@host pattern isn't exercised by a test: I couldn't make this stack produce that error.
Weak time cap: set once per pump, MySQL SELECT-only, checked after the fact Before each query, the cap is re-set to the time actually left, whenever the last setting is more than 50 ms old, so a statement overruns by at most 50 ms on MariaDB. For MySQL I documented the limit and filed #99 rather than build a watchdog. #99 recommends a watchdog using MYSQLI_ASYNC + KILL QUERY; the repo has no NEEDS TRIAGE label, so the issue is unlabelled. [sc_l3db_sleeps]: two SLEEP(1) in a 1500 ms call end at 1.59 s. Before the fix: 2.10 s.
Frame size Already bounded: read_frame rejects a length over MAX_FRAME (32 MiB) from the 4-byte header, before allocating. MAX_SQL (16 MiB) applies after that. No code change needed. New unit test an_oversized_frame_is_refused_from_its_header (headers of MAX_FRAME + 1 and u32::MAX, plus a writer refusing to send one).

Revert run. The new ext-layer3.sh against f355a4a's extension (stack scl3dbprev): 14 FAIL, covering all four behaviour findings above, with nothing else failing.

Gates (on [xps], under the lock):

gate result
--target check (clippy -D warnings + cargo test, whole workspace) rc=0
ext-config rc=0
ext-layer3 all passed, 183 ok
ext-attribution, ext-enforce, ext-vault, ext-db, ext-hosts, ext-layer1 rc=0 each
ext-microvm (KVM guest) all passed; the probe's reads and writes go through the gateway in the guest
ext-build 8.3 nts, guest-build, release-check 8.3 nts, promote-check rc=0 each

Cost. One query now costs ~325 µs isolated against ~153 µs unisolated: about +170 µs.

Behaviour change: drop-ins. Gateway queries no longer go through $wpdb->query() itself, so the worker's $wpdb->num_queries, SAVEQUERIES and a db.php drop-in's own routing don't see them. They still use $wpdb's connection and the worker's query filters. This is documented in ext/README.md.

-claude

…ver mirrored, a session SET allowlist, ROLLBACK AND NO CHAIN, the MySQL rollback, a per-row result cost, cleanup in finally
@samifouad

Copy link
Copy Markdown
Member Author

Verification fixes (round 2)

Commits ff3da44 and 2ad8d66 (the second is a test-only fix), on top of 22e43c0. Merges only.

finding fix test (fails on 22e43c0, passes now)
1. A mirrored query filter fools the state check; the state read fails open Bookkeeping: the state read, the time cap, the rollback and SET autocommit go straight to mysqli_query() on the exchange's connection, with no filters. An unreadable state counts as open and is rolled back.
SQL-shaping hooks are never mirrored (gateway::shapes_sql, unit-tested), with a line saying so: query, dbdelta_*, incompatible_sql_modes, posts_*, post_limits*, *_clauses, *_pre_query, found_*_query, comment_feed_*, getarchives_*, get_terms_fields/_orderby, get_meta_sql, get_date_sql, split_the_query. I took the list from a grep of WP 7.1's apply_filters calls.
The fixture's own query filter answers any @@in_transaction read with SELECT 1, 0. [sc_l3db_txo] leaves a transaction open behind a comment. Before the fix: no rollback, and core's later write was lost. Now: rolled back, the write commits, and hook query not mirrored is logged.
2. completion_type chains the ROLLBACK; session SETs persist Rollback: ROLLBACK AND NO CHAIN, then the state is re-read. If it still isn't clean, the worker reconnects ($wpdb->close() + db_connect). sqlparser can't parse NO RELEASE, so it would log unparseable on every exchange. RELEASE can only come from a completion_type, and the gateway now refuses any change to that.
Session SET allowlist (gateway::allowed_set): SET NAMES / SET CHARACTER SET to the connection's own charset (optionally COLLATE one of its collations), SET [SESSION] group_concat_max_len = <n>, and SET [SESSION] sql_big_selects = 1|ON.
Refused: every other SET, also behind a comment (autocommit, completion_type, sql_select_limit, transaction_read_only, sql_mode, time_zone, SET TRANSACTION, SET @@…, several assignments at once), plus COMMIT/ROLLBACK AND CHAIN or RELEASE.
Chain: [sc_l3db_chain] tries completion_type = 'CHAIN' then leaves a transaction open. Before: the set was accepted, the rollback chained, core's write was lost. Now: refused and rolled back, and core's write commits.
Session: [sc_l3db_session] gets 3 allowed and 10 refused. Core's next query sees sql_select_limit, completion_type, transaction_read_only, autocommit, time_zone and sql_mode unchanged, and its LIMIT 5 returns 5 rows. Before, core saw 2|CHAIN|1|0|+05:00|…TRADITIONAL….
3. The MySQL state check doesn't work On MySQL only @@autocommit is read. Whenever autocommit was on before the plugin's first query, the worker runs ROLLBACK AND NO CHAIN plus SET autocommit = 1 unconditionally after the exchange, which is a no-op when nothing is open. Documented in ext/README.md. No MySQL leg (not built). The test stack is MariaDB-only: the compose files, db_exec via the mariadb client, max_statement_time, @@in_transaction. Making ext-config + ext-layer3 parametric over the database didn't fit this budget. The MySQL branch is unchanged-risk code with no live test; worth a follow-up with #99.
4. db.php drop-ins Covered by 1: the exchange captures $wpdb->dbh once and uses it for the plugin's queries and all bookkeeping. If dbh isn't a mysqli (SQLite drop-in), each query is refused with the worker's $wpdb has no mysqli connection (a db.php drop-in such as SQLite)…. Documented. No live test: the stack has no SQLite drop-in.
5. The result cap undercounts small rows Each row counts 200 bytes, plus 16 per value, plus the value's text. [sc_l3db_tiny]: 1,000,000 one-byte rows under a 4 MiB cap are refused cleanly, worker peak 10.5 MB. Before the fix the peak was 63.2 MB. The 40 MiB result: peak 11.0 MB.
6. An exception skips the cleanup The pump loop is in try/finally. The new securecore_layer3_db_end() always pops the slug from GATEWAY. If a query's answer never went back to the child, it ends the channel (kills the child) with exchange aborted. Then the state check and rollback run. [sc_l3db_throw]: a worker-side query filter throws during the plugin's query with a transaction open. Before: no cleanup, core's write lost. Now: exchange aborted is logged, the transaction is rolled back, the write commits, and the exception reaches the page's own catch.

Revert run: the new ext-layer3.sh against 22e43c0's extension gives 22 FAIL, all in the new cases above.

Gates on [xps], under the lock:

gate result
check (clippy -D warnings + cargo test, workspace) rc=0
ext-config rc=0
ext-layer3 all passed, 215 ok
ext-microvm all passed
ext-attribution, ext-enforce, ext-vault, ext-db, ext-hosts, ext-layer1 rc=0 each
ext-build, guest-build, release-check, promote-check rc=0 each (all release checks passed)

Cost: about +127 µs per query (288 µs isolated, 160 µs unisolated).

-claude

@samifouad

Copy link
Copy Markdown
Member Author

After merging main into the branch (3f426c2, d6bd2d1). #88's test/lib/target.sh now runs ext-layer3 on both targets, as CI does.

run result
SC_TARGET=docker all ext-layer3 checks passed, 215 ok
SC_TARGET=microvm 199 ok, with my database cases running in the guest
--target check after the merge rc=0

Two new checks are n/a on the microVM target: the memory scans of the child and the worker, because the scan reads /proc in the php container. That is why test/lib/na-expected.txt changes from layer3 4 to 6. Before that change, the microVM run's only FAIL was this count.

CI after one check: the ext cell passed, guest reproducibility passed, and the microVM job was pending.

-claude

@samifouad

Copy link
Copy Markdown
Member Author

Commit 2ce853f: the gateway refuses on MySQL for now.

The worker reads db_server_info() once per request, with the hello, and checks it with gateway::is_mariadb. If the server isn't MariaDB, every isolated plugin's query fails closed, with one line per request:

layer3 plugin:<slug> database refused: the database gateway supports MariaDB only for now (#99)

Why: on MySQL, START TRANSACTION leaves @@autocommit unchanged, so the unconditional ROLLBACK could end a transaction core itself opened around the call. #99's body now covers this and lists what lifting the refusal needs.

Tests: a new unit test, the_gateway_is_mariadb_only_for_now, covers the detection (MariaDB strings, including the 5.5.5- prefix; MySQL / Percona / TiDB / empty strings) and the refusal path (the reason text, and logged once per request).

Runs:

  • CI, one check: the ext cell (which runs the Rust check, clippy -D warnings + cargo test) passed; guest reproducibility passed; the microVM job is pending.
  • [xps], docker target: ext-config passed. ext-layer3 didn't finish: xps went offline on the tailnet while it ran, after ~40 ok and no FAIL so far. I have no full xps result for this commit.

-claude

@samifouad
samifouad merged commit 0dabc02 into main Nov 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Layer 3: database access for isolated plugins (the $wpdb gateway)

1 participant