turnloop-mysql 0.1.0-beta.2

Pull-driven sans-I/O MySQL client protocol
Documentation

turnloop-mysql

A sans-I/O MySQL v10 client, built on mysql_common handshake/auth/value packets. No sockets, filesystem access, threads, implicit clocks, timers or entropy reads in the default sans-I/O feature set. The crate forbids unsafe. TLS and entropy are explicit requests.

Getting started on turnloop

Enable turnloop-mysql = { version = "0.1.0-alpha.2", features = ["turnloop"] } and use the asynchronous module: Connection::connect, query, prepare/execute, begin and Pool::acquire. The default feature set remains sans-I/O. The adapter reuses turnloop-io; the host owns LocalExecutor and calls turn. Spawn local futures through its handle and keep their JoinHandles until completion.

cargo run -p turnloop-mysql --features turnloop --example turnloop

The complete example connects to 127.0.0.1:3306 by default; TURNLOOP_DB_ADDR overrides that development endpoint. All operations take an absolute turnloop_io::Instant deadline, shared across authentication, I/O and retries. Callbacks borrow row/reply storage; copy values only when retaining them. Dropping a pending operation closes its transport before a pool can reuse it.

For TLS, set the protocol's TLS mode and provide turnloop_tls::asynchronous::ClientTls with the trust configuration, verified server name and current Unix seconds. Certificates are verified; a requested TLS upgrade without a configuration fails. Native TCP and WASI 0.2 sockets share the same driver. Browser raw TCP is unavailable; Windows accepts a host-provided Backend until the repository's production IOCP provider is integrated.

Pool::new uses pool::Config with mysql2 queue/max/idle policy. Leases own their connection until drop, and never return unfinished transactions to the pool. begin returns a transaction guard with explicit commit/rollback; dropping an unfinished guard closes its connection. Multi-statements require Config::multiple_statements; callbacks receive every result set. Full caching_sha2 RSA authentication obtains fresh OAEP entropy from the TLS provider.

Host contract

Construct Config and Connection, connect transport in the host, then feed plaintext into receive. Pull next_event until None; Progress means a control packet was consumed and polling should continue. Write output, acknowledging only successfully written bytes via consume_output. When it returns true, an event is ready without further input: call next_event immediately. COM_STMT_CLOSE and COM_QUIT get no server reply, so that acknowledgement is their only wakeup; a completion-driven host needs no timer for them. Borrowed outputs/events remain valid until the next mutable call. Preserve the output borrow through write completion or copy into a reusable host transport buffer.

At UpgradeTls, flush the SSLRequest, verify and finish TLS in the host, and call tls_established. For caching_sha2 full authentication on plaintext transport, the core requests the server key. RsaSeedNeeded asks the host for 20 fresh cryptographically random bytes; rsa_seed performs nonce XOR and OAEP-SHA1 using those bytes. Never reuse a seed. Fast caching auth, TLS password auth, mysql_native_password, and auth switches are handled explicitly. There is no arbitrary authentication-plugin callback or multi-factor flow.

Provide absolute deadlines; schedule next_timeout and call handle_timeout(now). The host supplies mysql2's default 10-second connect deadline; Config does not read a clock. On EOF/TLS failure or a parsing error, call abort(error) and drain events. A parsing error is terminal; never continue the byte stream after it. Each accepted command yields exactly one Completed; server Error, Ok and Eof events are informational. Close emits one Closed. Command rejection accepts no token. There are no callbacks from this core.

MySQL permits one active command. Busy calls return backpressure; can_accept() reports that exact admission decision up front (the command methods call it themselves), so a host queue never copies the rule. The adapter queues commands in JS submission order. This prevents unsynchronized packet sequence resets. COM_QUERY supports multiple result sets (multiple statements are opt-in); EOF negotiation deliberately selects legacy EOF, which MySQL 9.6 supports. Ok is a real OK packet (affected_rows, last_insert_id, warnings, status); Eof ends a result set's rows and carries only warnings and status, so a host need not track whether a result set is open to read either one.

Prepare emits parameter/column metadata and a Statement ID. Execute accepts mysql_common Value parameters and emits binary rows. Reset/close statements, ping, quit, reset_connection and change_user are commands. Successful reset and changeUser invalidate statement IDs. COM_STMT_CLOSE completes after its bytes are acknowledged because the server sends no response. There is no SQL-keyed LRU/automatic prepare helper or COM_STMT_SEND_LONG_DATA API yet; large parameters use packet continuation within the configured buffer bound. Transactions use START TRANSACTION/COMMIT/ROLLBACK; status flags track the server state.

LOCAL INFILE is disabled by default and aborts an unsolicited request without reading a file or returning file data. When enabled, LocalInfile lends the requested filename to the host. The host decides whether/how to source bytes, then calls local_infile_data and local_infile_finish; the final empty packet terminates input. To reject an enabled request safely, abort the connection.

Compression negotiates CLIENT_COMPRESS. Plain and compressed framing handle 24-bit lengths, sequence wrapping, continuation and exact-boundary empty frames. The outer zlib encoder/decoder states are retained for the connection; upstream's per-frame zlib construction did not satisfy this lane's allocation contract. The encoder is never reset either — each frame is a full-flushed segment wrapped in its own RFC 1950 header, final block and Adler-32 (src/zlib.rs), because resetting a deflate state reallocates its LZ buffer on wasm32. Zstd and MariaDB extensions are out of scope.

mysql2 conversions and hooks

Row iterators return borrowed bytes or mysql_common numeric/calendar scalars. Each value is validated and decoded once, as the iterator reaches it (the last one also rejects trailing bytes); the first error ends the row. Such an error is a parsing error: abort the connection. types::decode implements a default conversion policy. Column retains names, original names/table/schema, flags, charset, length, decimals and wire type; every Row also carries its columns' ColumnTypeInfo (type, flags, charset, decimals) via Row::columns and Row::typed, so a host can implement its own policy per MySQL column type without reimplementing value decoding.

MySQL type Default policy / host action
integer, FLOAT, DOUBLE Number; TINYINT(1) remains numeric
BIGINT Number by default; support_big_numbers preserves unsafe-range values as strings; big_number_strings forces strings when enabled
DECIMAL/NEWDECIMAL exact string; decimal_numbers opts into f64
DATE/DATETIME/TIMESTAMP explicit Date request with raw text/calendar components; date_strings formats strings; truncate_fraction_to_decimals cuts binary-protocol fractions to the column's decimals like mysql2
TIME string, including negative and >24-hour values (by column type, even though its charset is 63)
JSON explicit host JSON parse request; json_strings returns raw text
BIT Buffer bytes
GEOMETRY explicit Geometry request with the SRID+WKB bytes; the host builds mysql2's objects
BLOB/other string types with binary charset 63 Buffer bytes
text UTF-8 string; other character sets require host decoding
NULL Null

The host selects timezone, creates JS Date (including zero-date/invalid-Date behavior), parses JSON and materializes row objects or rowsAsArray tuples. The protocol preserves microseconds; JS Date loses sub-millisecond precision. typeCast can inspect Column and RawValue in the event-dispatch layer and invoke types::decode for next(). Callback invocation, field.string/buffer single-use semantics and building field.geometry objects are adapter work, not core callbacks. Per-type dateStrings arrays are not implemented (only the boolean option). BIGINT inside JSON is still host policy. This is documented surface support, not a drop-in mysql2 API.

ServerError preserves errno, sql_state and sql_message. code() maps Perry's common observed server errors and several auth/connection codes; unknown numbers return None, preserving errno. Full mysql2 error-name registry parity is a gap. URI parsing, named placeholders, query formatting/escaping, endpoint/socket options, custom charsets, promise/callback order and TLS options belong to the adapter. .query does not interpolate parameters; use prepare/execute for the Perry bound parameter path. Existing Perry DECIMAL conversion is lossy and is not reproduced by the default policy.

Pool, memory and verification

The pool is lazy and bounded, queues waiters FIFO and reuses idle clients LIFO. It implements waitForConnections, queueLimit, maxIdle, idleTimeout, release, connection failures, generation-checked leases and end. Connect/Close are host requests; report completion back before a slot can be reused. Event emitters, nextTick/promise scheduling, auto-release query wrappers and graceful transport close are adapter work. PG-style min/uses/lifetime limits are optional extras.

Packet/TX/RX/metadata/serialization buffers are reused. Numeric and borrowed-byte rows and warmed query/ping commands allocate nothing. Tests count 1,000 warmed plain and compressed commands; row tests exercise a 512-byte value generated by the independent mysql_common compressed encoder. Authentication, RSA arithmetic, new statement registration, pool capacity growth and owned result conversion allocate. Compression state is allocated once at negotiation and retained.

Run cargo test -p turnloop-mysql; real server tests are ignored by default and assert required fixture variables if selected. From the workspace:

TURNLOOP_SQL_SERVER=mysql python3 scripts/test-servers.py run cargo test -p turnloop-mysql --test server -- --ignored

The private fixture script starts/stops only its own instances and keeps files under .tools. MySQL 9.6 cannot authenticate mysql_native_password users: that plugin was removed in 9.0, so a separate private 8.4 fixture is needed for that real-server case. See the root report for actual verification and open gaps.

Browser builds export a host-supplied Instant::from_duration(ticks); native and WASI builds reexport std::time::Instant. Use one monotonic epoch per connection and pool. Map the browser core loop’s Instant through as_duration/from_duration. The protocol never calls performance.now or std Instant::now. Browser runtime execution is not yet verified; only target compilation has run.

Getting started on turnloop

Enable the turnloop feature and construct asynchronous::AsyncConnection::new with a connected turnloop::AsyncIo (TCP/pipe) or turnloop_tls::TlsStream and this crate's sans-I/O Connection. Submit commands through core_mut(), then next(&executor_handle, |event| { /* consume the event */ Ok(()) }).await. Callbacks finish consuming borrowed rows before the next event. Authentication, entropy and TLS-upgrade requests are explicit events; acknowledge them through the core. For an upgrade, into_parts preserves the stream, core and unread bytes. Apply turnloop_io::deadline using the core's next deadline. Dropping a pending drive future closes the stream and aborts the core; terminal core events remain available for draining. See turnloop-io for the shared adapter ownership pattern.