diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8816035..c762264 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -48,3 +48,47 @@ jobs: - name: Check against MSRV run: cargo +1.81 check --workspace --all-targets --locked + + - name: Check the wasm crate for wasm32 against MSRV + run: | + rustup target add wasm32-unknown-unknown --toolchain 1.81 + cargo +1.81 check -p ch-core-wasm --target wasm32-unknown-unknown --locked + + wasm: + name: wasm32 build + JS tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - name: Install pinned Rust toolchain and the wasm32 target + run: | + rustup show + rustup target add wasm32-unknown-unknown + + - name: Cache cargo build + uses: Swatinem/rust-cache@v2 + + - name: Core without the zstd feature (clippy + test) + run: | + cargo clippy -p ch-core-rs --no-default-features --all-targets -- -D warnings + cargo test -p ch-core-rs --no-default-features + + - name: Clippy for wasm32 (deny warnings) + run: cargo clippy -p ch-core-wasm --target wasm32-unknown-unknown -- -D warnings + + - name: Build the .wasm + run: crates/ch-core-wasm/scripts/build.sh + + - name: Size budget (1 MiB uncompressed) + run: | + size=$(stat -c %s crates/ch-core-wasm/dist/ch_core_wasm.wasm) + echo "ch_core_wasm.wasm: $size bytes" + test "$size" -le 1048576 + + - uses: actions/setup-node@v5 + with: + node-version: 22 + + - name: JS glue tests + working-directory: crates/ch-core-wasm + run: npm test diff --git a/AGENTS.md b/AGENTS.md index 60c47a7..0082f45 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,11 +55,19 @@ These are the reasons the crate exists. Do not erode them. ### Workspace The repo is a Cargo workspace. The root package is `ch-core-rs`. A second -crate, `crates/ch-tcp-proto`, is the sans-I/O TCP protocol engine. Its only -runtime dependency is `ch-core-rs` by path. Core's invariants apply to it as -well: no panics on untrusted input, the same MSRV (`rust-version = "1.81"`), -and the dependency policy below. Run checks with -`--workspace` so both crates are covered. +crate, `crates/ch-tcp-proto`, is the sans-I/O TCP protocol engine. A third, +`crates/ch-core-wasm`, compiles core to WebAssembly behind a small C ABI with +hand-written JS glue. Both depend only on `ch-core-rs` by path. Core's +invariants apply to them as well: no panics on untrusted input, the same MSRV +(`rust-version = "1.81"`), and the dependency policy below. Run checks with +`--workspace` so every crate is covered. + +`ch-core-wasm` is not a language binding in the sense above. It exposes core's +columnar buffers through a C ABI, which is a public contract documented in +`crates/ch-core-wasm/ABI.md`. Keep it columnar: no row building and no client +methods, which belong in clickhouse-js. Results are copied out of linear +memory, never handed to JS as views. Bump `ABI_VERSION` for any breaking ABI +change. It builds core without the C `zstd` feature. ### Dependencies diff --git a/CHANGELOG.md b/CHANGELOG.md index 4950009..79d9a65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,21 @@ version; patch releases remain backward compatible. ## Unreleased +- New workspace crate `ch-core-wasm`: core compiled to WebAssembly behind a + small, versioned C ABI (`crates/ch-core-wasm/ABI.md`), with hand-written JS + glue for Node.js and browsers. It decodes Native bodies into column buffers, + streams decode, and encodes column buffers back to Native. Results are + copied out of wasm memory, never returned as views. It has no dependencies + beyond core and is not published yet. +- ZSTD frame support is now the default `zstd` cargo feature. With + `default-features = false` the crate is pure Rust, which the wasm32 build + needs, and ZSTD frames return `CompressionError::UnsupportedCodec`. Default + builds are unchanged. +- Fix `encode_block` on 32-bit targets: a huge row count for zero-width + `Nothing` or `Tuple()` columns wrapped the output size and returned a + truncated block. Zero-width, `Bool`, null-map and `QBit` output is now + reserved with a checked size, and a block that cannot be allocated returns + the new `EncodeError::OutputTooLarge` instead of panicking. - `decode_binary_value` and `encode_binary_value` handle an `Array` or `Map` run of zero-width `Tuple()` values in constant time per tuple node instead of once per element. Before, a small nested value such as diff --git a/CODEC_CONTRACT.md b/CODEC_CONTRACT.md index 3c68f47..5eb7e3d 100644 --- a/CODEC_CONTRACT.md +++ b/CODEC_CONTRACT.md @@ -117,7 +117,8 @@ They accept plaintext Native bytes independently of revision or type layout and write payloads directly after the reserved header, avoiding a separate payload copy. LZ4 block coding is hand-written safe Rust, checksums use `cityhash-rs::cityhash_102_128`, and ZSTD decode uses the `zstd` crate over -libzstd. ZSTD grows the output `Vec` by exactly the claimed plaintext size, +libzstd. ZSTD is the default `zstd` cargo feature. Without it, a ZSTD frame +returns `CompressionError::UnsupportedCodec { method: 0x90 }`. ZSTD grows the output `Vec` by exactly the claimed plaintext size, zero-filled, and libzstd decodes into that slice with a reused per-thread context, so it never writes past the claim. A payload libzstd rejects, including invalid trailing bytes and output larger than the claim, returns diff --git a/Cargo.lock b/Cargo.lock index aaa71ce..dea3fe0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -29,6 +29,13 @@ dependencies = [ "zstd", ] +[[package]] +name = "ch-core-wasm" +version = "0.1.0" +dependencies = [ + "ch-core-rs", +] + [[package]] name = "ch-tcp-proto" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 75787f7..7dd4321 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] -members = ["crates/ch-tcp-proto"] -default-members = [".", "crates/ch-tcp-proto"] +members = ["crates/ch-tcp-proto", "crates/ch-core-wasm"] +default-members = [".", "crates/ch-tcp-proto", "crates/ch-core-wasm"] resolver = "2" # Agent worktrees under .claude/worktrees are full checkouts with their own # root manifest. Exclude them so Cargo does not treat them as members. @@ -26,8 +26,14 @@ publish = false cityhash-rs = "1.0.1" # Builds libzstd from source, so a C compiler is needed at build time. Its cc # build dependency pulls in jobserver. jobserver 0.1.35 requires Rust 1.85, so -# Cargo.lock holds 0.1.34 and the MSRV CI job checks with --locked. -zstd = { version = "0.14", default-features = false } +# Cargo.lock holds 0.1.34 and the MSRV CI job checks with --locked. Optional +# behind the default `zstd` feature so a pure-Rust build, such as the wasm32 +# one, can leave out the C code. Without it, ZSTD frames are rejected as +# `CompressionError::UnsupportedCodec`. +zstd = { version = "0.14", default-features = false, optional = true } + +[features] +default = ["zstd"] # Test and bench only, never linked into the library. liblz4 (through the # safe `lz4` wrapper over `lz4-sys`) is the reference implementation for the @@ -42,3 +48,12 @@ harness = false [[bench]] name = "block_scanner" harness = false + +# Release profile for the .wasm (`--profile wasm-release`), kept separate so +# it does not change the release and bench builds of the other crates. +[profile.wasm-release] +inherits = "release" +lto = true +codegen-units = 1 +panic = "abort" +strip = "debuginfo" diff --git a/INTEGRATING.md b/INTEGRATING.md index 8131d2c..54c9299 100644 --- a/INTEGRATING.md +++ b/INTEGRATING.md @@ -66,7 +66,9 @@ to obtain typed columnar buffers. - Runtime dependencies are `cityhash-rs` for CityHash128 and the `zstd` crate for ZSTD frames. LZ4 is hand-written. `zstd` builds libzstd from C source, so - building this crate needs a C compiler. + building this crate needs a C compiler. ZSTD sits behind the default `zstd` + feature. With `default-features = false` the crate is pure Rust and ZSTD + frames return `CompressionError::UnsupportedCodec`. - A crate building on Rust 1.81 must pin jobserver after a fresh lockfile, because 0.1.35 needs Rust 1.85: `cargo update -p jobserver --precise 0.1.34`. - It is downstream agnostic. The core owns binary decoding and the shared columnar model. It does not build host-language objects or make language-specific policy decisions. diff --git a/README.md b/README.md index e1d89f4..c3b1b80 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,8 @@ Implemented: - Decode ClickHouse compression frames with LZ4, ZSTD, or NONE and verify CityHash128 1.0.2 checksums. Encode LZ4 frames for inserts. LZ4 is hand-written; CityHash128 uses `cityhash-rs` and ZSTD uses the `zstd` crate, - which builds libzstd from C source, so a C compiler is needed to build. + which builds libzstd from C source, so a C compiler is needed to build. ZSTD + is the default `zstd` feature; turn it off for a pure-Rust build. Not implemented yet: @@ -224,7 +225,9 @@ The root package remains `ch-core-rs`. The workspace also contains Its current scope is the revision-54460 handshake, Ping/Pong, SELECT and INSERT with optional compression, Native byte output and query metadata events. -The engine depends on core. +The engine depends on core. [`ch-core-wasm`](crates/ch-core-wasm/README.md) +compiles core to WebAssembly behind a small C ABI, with JS glue for Node.js and +browsers. - `src/schema.rs` - ClickHouse logical type model. - `src/column.rs` - Arrow-compatible physical column buffers. diff --git a/crates/ch-core-wasm/.gitignore b/crates/ch-core-wasm/.gitignore new file mode 100644 index 0000000..3d2bc62 --- /dev/null +++ b/crates/ch-core-wasm/.gitignore @@ -0,0 +1,2 @@ +/dist/ +/node_modules/ diff --git a/crates/ch-core-wasm/ABI.md b/crates/ch-core-wasm/ABI.md new file mode 100644 index 0000000..b10f3b5 --- /dev/null +++ b/crates/ch-core-wasm/ABI.md @@ -0,0 +1,188 @@ +# ch-core-wasm C ABI + +This is the public contract of `ch_core_wasm.wasm`. The JS glue in `js/` is +one host. Any WebAssembly host can call the same exports. Treat every name, +signature, error code, descriptor field and ownership rule below as API. + +ABI version: **1**, returned by `chw_abi_version()`. A host must check it at +load time and refuse a version it does not know. Any breaking change to this +document bumps the version. Adding a new export or a new optional descriptor +field does not. + +## Module + +- Target `wasm32-unknown-unknown`, built with + `cargo build -p ch-core-wasm --target wasm32-unknown-unknown`. A workspace + wide wasm32 build is not supported: other members turn core's C `zstd` + feature back on. Pointers and lengths are 32-bit. A host + that reads them as signed `i32`, as JS does, must convert them to unsigned. +- No imports. The module exports `memory` plus the functions below. +- Single threaded. Calls must not overlap. +- The module does not panic on malformed input. A bug that does panic traps + with `unreachable`, after which the instance is unusable and must be + replaced. + +## Memory rules + +These rules are the reason the ABI looks the way it does. + +1. **Linear memory can grow during any call.** Growth replaces the host's + view of memory. In JS it detaches the old `memory.buffer`, and every + TypedArray over it becomes empty. Addresses stay the same. A host must + re-read the memory buffer after every call before it touches memory. +2. **Input is borrowed.** The host allocates with `chw_alloc`, writes its + bytes, passes `(ptr, len)`, and frees with `chw_free` after the call + returns. No call keeps a pointer to its input. Input must not point into + memory the module owns, such as a result buffer or the last-error message, + because the call may change or free it. +3. **Output is owned by a result handle.** A result's JSON descriptor and every + buffer it references stay valid until `chw_result_free`. After that the + memory is reused. +4. **Copy out, then free.** A host copies whatever it needs out of linear + memory before calling `chw_result_free`, and before any call that could + reuse the memory. The JS glue copies every buffer into a JS-owned TypedArray + and never returns a view into linear memory, so results survive growth, + frees and later calls. + +## Errors + +A call that fails returns `0` (or a null pointer) and records an error. A call +that returns a result handle clears it on success. + +| Export | Returns | +| --- | --- | +| `chw_last_error_code() -> u32` | `0` none, `1` InvalidArg, `2` GenericFailure, `3` OutOfMemory | +| `chw_last_error_ptr() -> *const u8` | UTF-8 message, valid until the next call that records or clears an error | +| `chw_last_error_len() -> usize` | message byte length | + +- **InvalidArg**: the input can never succeed, however many bytes arrive. This + covers corrupt framing, unsupported types, invalid encode input, a bad + handle, and lifecycle misuse such as pushing after finish. +- **GenericFailure**: an I/O-shaped failure, such as a truncated final block in + `chw_stream_finish`. +- **OutOfMemory**: `chw_alloc` could not allocate. + +## Handles + +Results and streams are `u32` handles, never raw pointers. `0` is never a +valid handle. A handle carries a slot index in its low 20 bits and a +generation in its high 12 bits. Freeing bumps the generation, so a freed +handle stays invalid after its slot is reused, until that one slot has been +reused 4096 times. A stale, freed, forged or wrong-kind handle is an +`InvalidArg` error, never undefined behavior. At most about one million +handles can be live at once. + +## Exports + +### Version and memory + +| Export | Meaning | +| --- | --- | +| `chw_abi_version() -> u32` | The ABI version. | +| `chw_alloc(len) -> *mut u8` | `len` bytes, 8-byte aligned. Null and `OutOfMemory` on failure. `len = 0` returns a dangling non-null pointer that must not be read or written. | +| `chw_free(ptr, len)` | Free a `chw_alloc(len)` block. `len` must match. Freeing twice or freeing a pointer `chw_alloc` did not return is undefined behavior, as with C `free`. `len = 0` is a no-op. | + +### Results + +| Export | Meaning | +| --- | --- | +| `chw_result_json_ptr(result) -> *const u8` | The result's UTF-8 JSON descriptor. Null for a bad handle. | +| `chw_result_json_len(result) -> usize` | Descriptor byte length. `0` for a bad handle. | +| `chw_result_free(result) -> u32` | Free the result and every buffer it references. `1`, or `0` for a bad handle. | + +### Decode + +| Export | Descriptor | +| --- | --- | +| `chw_decode(ptr, len) -> result` | A complete HTTP `FORMAT Native` body -> `{ rowCount, columnNames, columnTypes, chunks: [{ rowCount, columns }] }`. An empty body is an empty result with no schema. | +| `chw_decode_binary_value(ptr, len) -> result` | One SharedVariant or JSON shared-data cell -> `{ type, column }` with a one-row column. | +| `chw_describe_type(ptr, len) -> result` | A UTF-8 ClickHouse type string -> `{ type, kind, nullable, ...metadata, ...children }`. Children are nested descriptions under `element`, `key`, `value`, `dictionary`, `fields` or `variants`. JSON `typedPaths` entries are descriptions with an added `path`. | + +The input is a bare HTTP Native body at protocol revision 0, with no TCP +framing and no compression frames. This build of core leaves out the C +`zstd` feature. + +### Streaming decode + +| Export | Meaning | +| --- | --- | +| `chw_stream_new() -> stream` | A decoder for one HTTP response body. | +| `chw_stream_push(stream, ptr, len) -> result` | Append bytes. The result describes every block now complete, in the decode shape plus `bufferedBytes`. | +| `chw_stream_finish(stream) -> result` | Drain the tail. Fails with GenericFailure on a truncated final block. Callable once. | +| `chw_stream_row_count(stream) -> u64` | Rows emitted so far. A `u64`, an `i64` in wasm, a BigInt in JS, because a long export can pass `u32::MAX`. | +| `chw_stream_buffered_bytes(stream) -> usize` | Bytes held for an incomplete block. | +| `chw_stream_free(stream) -> u32` | `1`, or `0` for a bad handle. | + +Zero-row blocks contribute the schema but are left out of `chunks`. A failed +decode step poisons the stream, and every later push or finish fails with +InvalidArg. Lifecycle misuse, such as a push after finish, fails without +poisoning. The two lookups return `0` for a bad handle and record +InvalidArg. On success they clear the last error, so `chw_last_error_code` +tells a real `0` from a failure. + +### Encode + +| Export | Meaning | +| --- | --- | +| `chw_encode(desc_ptr, desc_len, data_ptr, data_len) -> result` | Encode one Native block for `INSERT ... FORMAT Native`. The result descriptor is `{ bytes }`. | + +`desc` is a UTF-8 JSON block `{ rowCount, columns: [...] }` in the shape of +one decoded chunk, so a decoded chunk can be passed straight back. Its buffers +are references into `data` (see below). Each column needs `name` and `type`. +The `type` string is authoritative and `kind` is ignored. The core encoder +validates every structural invariant before writing a byte. A block too large +to allocate, for example billions of zero-width `Nothing` rows, fails with +InvalidArg. + +## Descriptors + +Descriptors are UTF-8 JSON. They carry per-column metadata only, never +per-row values, so parsing them costs little next to the buffers. + +### Buffer references + +- **In results**: `{"$b": [ptr, byteLength, dtype]}`, an absolute address in + linear memory owned by the result. `dtype` is one of `i8 u8 i16 u16 i32 u32 + i64 u64 f32 f64` and names the element type. Buffers are little-endian. +- **In encode input**: `{"$b": [offset, byteLength]}`, a range of the `data` + argument. The element type follows from the column's `type`, and + `byteLength` must be a multiple of its width. + +No other object in a descriptor has a `$b` key. + +### Column objects + +Every column has `kind` (the physical layout), `type` (the ClickHouse type +string) where known, and `name` at the top level of a chunk. A nullable column +also has `validity`, an Arrow-style bitmap with bit 1 = valid. + +| `kind` | Fields | +| --- | --- | +| `Int8` ... `UInt64`, `Float32`, `Float64` | `values` | +| `Date`, `Date32`, `DateTime`, `DateTime64`, `Time`, `Time64`, `Interval` | `values`; `timezone` and `precision` where the type has them | +| `Enum8`, `Enum16` | `values`, `enumValues: [[name, value], ...]` | +| `IPv4` | `values` (u32) | +| `BFloat16` | `values` (u8, two bytes per row) | +| `Bool` | `bitmap`, `length` | +| `Nothing` | `length` | +| `String` | `offsets` (i32), `data` (u8) | +| `FixedString`, `UUID`, `IPv6`, `Int128`, `UInt128`, `Int256`, `UInt256` | `data`, `width` | +| `Decimal` | `data`, `width`, `precision`, `scale` | +| `AggregateFunction` | `offsets` (i64), `data` | +| `LowCardinality` | `indices` (i32), `dictionary` (column) | +| `Array` | `offsets` (i64), `values` (column) | +| `Tuple` | `length`, `names` (string or null each), `fields` (columns) | +| `Map` | `offsets` (i64), `keys`, `values` (columns) | +| `QBit` | `dimension`, `values` (column) | +| `Variant` | `discriminators` (u8, 255 = NULL), `offsets` (i32, row index within its alternative), `variants` (columns) | +| `Dynamic` | `typeIds` (u32, 0xFFFFFFFF = NULL), `offsets` (i32), `children` (typed columns, or a `SharedVariant` String-shaped column of binary cells) | +| `JSON` | `format: "text"` with `text` (String column), or `format: "structured"` with `length`, `typedPaths`, `dynamicPaths` (`[{ path, column }]`), `sharedOffsets` (i64), `sharedPaths`, `sharedValues` (String columns) | + +Name-only types (Nullable, SimpleAggregateFunction, the geo types, Nested) +use the layout of the type they stand for. `type` keeps the original name. + +## Out of scope + +The ABI is columnar on purpose. Turning columns into rows, mapping values to +host types (BigInt, Date, Decimal strings), and client methods such as +`insertNative` or `queryNativeRows` belong in the client, not here. diff --git a/crates/ch-core-wasm/Cargo.toml b/crates/ch-core-wasm/Cargo.toml new file mode 100644 index 0000000..e696f93 --- /dev/null +++ b/crates/ch-core-wasm/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "ch-core-wasm" +version = "0.1.0" +edition = "2021" +rust-version = "1.81" +description = "C ABI over ch-core-rs for WebAssembly hosts, with JS glue for Node.js and browsers" +license = "Apache-2.0" +repository = "https://github.com/ClickHouse/ch-core-rs" +publish = false + +[lib] +# cdylib is the .wasm. rlib lets `cargo test` run the ABI natively. +crate-type = ["cdylib", "rlib"] + +[dependencies] +# Without the default `zstd` feature: libzstd is C, which a wasm32 build would +# need clang and llvm-ar to compile. This crate decodes plain HTTP Native +# bodies, which carry no compression frames. +ch-core-rs = { path = "../..", default-features = false } diff --git a/crates/ch-core-wasm/README.md b/crates/ch-core-wasm/README.md new file mode 100644 index 0000000..effc1ca --- /dev/null +++ b/crates/ch-core-wasm/README.md @@ -0,0 +1,71 @@ +# ch-core-wasm + +`ch-core-rs` compiled to WebAssembly: one `.wasm` file with a small C ABI and +no imports, plus hand-written JS glue for Node.js, browsers, Deno and Bun. + +- **Columnar only.** Decode Native bytes into typed column buffers, and encode + column buffers into Native bytes. Turning columns into rows and the client + methods (`insertNative`, `queryNativeRows`, `queryNativeColumns`) live in + clickhouse-js. +- **Results are copies.** Every buffer is copied once out of wasm memory into a + JS-owned TypedArray, then freed on the Rust side. Nothing returned is a view + into wasm memory, so memory growth cannot empty or corrupt a result. +- **The C ABI is a contract**, versioned and documented in [ABI.md](ABI.md). + The glue checks the version at load time. +- **No dependencies** beyond core. Core is built without its C `zstd` feature, + so the build needs only the Rust `wasm32-unknown-unknown` target. + +## Build and test + +```sh +rustup target add wasm32-unknown-unknown +npm run build # -> dist/ch_core_wasm.wasm (runs wasm-opt if it is on PATH) +npm test # JS glue against the committed server fixtures +cargo test -p ch-core-wasm # the ABI, natively on the host +``` + +`npm test` also runs a live-server suite when `CLICKHOUSE_URL` is set, for +example `CLICKHOUSE_URL=http://localhost:8123 npm test`. It reads about 55 +types from the server and checks that each re-encodes to identical bytes. + +## Use + +```js +import { NativeStreamDecoder, encodeNative } from 'ch-core-wasm' // web: await init() first + +const res = await fetch(url, { method: 'POST', body: 'SELECT number AS n FROM numbers(1e6) FORMAT Native' }) +const decoder = new NativeStreamDecoder() +for await (const piece of res.body) { + for (const chunk of decoder.push(piece).chunks) { + chunk.columns[0].values // BigUint64Array, one per Native block + } +} +decoder.finish() +decoder.free() + +// A decoded chunk, or any block in the same shape, encodes back to Native. +const body = encodeNative({ + rowCount: 2, + columns: [{ name: 'id', type: 'UInt64', values: new BigUint64Array([13n, 79n]) }], +}) +``` + +The entry points are `decodeNativeColumns`, `NativeStreamDecoder`, +`encodeNative`, `describeType` (the core's type parser) and +`decodeBinaryValue` (one Dynamic or JSON shared cell). Column shapes are listed +in [ABI.md](ABI.md#column-objects) and typed in `js/index.d.ts`. Errors are +`CodecError`s with `code` `'InvalidArg'`, `'GenericFailure'` or `'OutOfMemory'`. + +## Layout + +```text +src/lib.rs C ABI exports, handle table, errors +src/decode.rs decoded columns -> descriptor JSON with buffer references +src/encode.rs descriptor JSON + data blob -> columns -> Native bytes +src/describe.rs chw_describe_type +src/json.rs minimal JSON writer and parser for descriptors +js/core.mjs glue: copy in, copy out, errors, stream decoder +js/node.mjs Node entry (ready on import) +js/web.mjs browser entry (await init()) +test/ node:test suites +``` diff --git a/crates/ch-core-wasm/js/core.mjs b/crates/ch-core-wasm/js/core.mjs new file mode 100644 index 0000000..309ee20 --- /dev/null +++ b/crates/ch-core-wasm/js/core.mjs @@ -0,0 +1,220 @@ +// JS glue over the ch-core-wasm C ABI (see ../ABI.md). Runtime-agnostic: the +// Node and web entries instantiate the module and pass its exports here. +// +// Memory rule: nothing this module returns is a view into wasm memory. Every +// buffer in a result is copied into a JS-owned TypedArray, then the result is +// freed on the Rust side. Any call into the module may grow its memory, which +// detaches the old `memory.buffer`, so the buffer is re-read after every call. + +/** The C ABI version this glue speaks. */ +export const ABI_VERSION = 1 + +const CODES = { 1: 'InvalidArg', 2: 'GenericFailure', 3: 'OutOfMemory' } + +const CTORS = { + i8: Int8Array, + u8: Uint8Array, + i16: Int16Array, + u16: Uint16Array, + i32: Int32Array, + u32: Uint32Array, + i64: BigInt64Array, + u64: BigUint64Array, + f32: Float32Array, + f64: Float64Array, +} + +const utf8Decoder = new TextDecoder('utf-8') +const utf8Encoder = new TextEncoder() + +/** An error raised by the codec. `code` is 'InvalidArg', 'GenericFailure' or 'OutOfMemory'. */ +export class CodecError extends Error { + constructor(code, message) { + super(message) + this.name = 'CodecError' + this.code = code + } +} + +const asBytes = (input) => { + if (input instanceof Uint8Array) return input + if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength) + if (input instanceof ArrayBuffer) return new Uint8Array(input) + throw new TypeError('expected a Uint8Array, ArrayBuffer or ArrayBuffer view') +} + +/** + * Wrap the exports of an instantiated ch-core-wasm module. + * Throws if the module speaks a different ABI version than this glue. + */ +export function bindExports(x) { + const abi = x.chw_abi_version() + if (abi !== ABI_VERSION) { + throw new Error(`ch-core-wasm: the .wasm speaks ABI ${abi}, this glue expects ${ABI_VERSION}`) + } + // wasm returns i32; pointers and lengths are unsigned. + const u32 = (n) => n >>> 0 + const memory = () => x.memory.buffer + + function lastError() { + const code = x.chw_last_error_code() + const ptr = u32(x.chw_last_error_ptr()) + const len = u32(x.chw_last_error_len()) + const message = len ? utf8Decoder.decode(new Uint8Array(memory(), ptr, len)) : 'unknown error' + return new CodecError(CODES[code] ?? 'GenericFailure', message) + } + + function alloc(len) { + const ptr = u32(x.chw_alloc(len)) + if (len > 0 && ptr === 0) throw lastError() + return ptr + } + + /** Copy `input` into wasm memory for the duration of `fn(ptr, len)`. */ + function withInput(input, fn) { + const bytes = asBytes(input) + const ptr = alloc(bytes.byteLength) + try { + new Uint8Array(memory(), ptr, bytes.byteLength).set(bytes) + return fn(ptr, bytes.byteLength) + } finally { + x.chw_free(ptr, bytes.byteLength) + } + } + + /** Read a result, copy every referenced buffer out, then free the result. */ + function take(handle) { + if (handle === 0) throw lastError() + try { + const ptr = u32(x.chw_result_json_ptr(handle)) + const len = u32(x.chw_result_json_len(handle)) + // No calls into the module between here and the end of JSON.parse, so + // `buf` stays attached for the whole copy. + const buf = memory() + const text = utf8Decoder.decode(new Uint8Array(buf, ptr, len)) + return JSON.parse(text, (_key, v) => { + if (v !== null && typeof v === 'object' && Array.isArray(v.$b)) { + const [p, n, dtype] = v.$b + return new CTORS[dtype](buf.slice(p, p + n)) + } + return v + }) + } finally { + x.chw_result_free(handle) + } + } + + /** + * Decode a complete `FORMAT Native` body into + * `{ rowCount, columnNames, columnTypes, chunks: [{ rowCount, columns }] }`. + */ + function decodeNativeColumns(bytes) { + return withInput(bytes, (ptr, len) => take(x.chw_decode(ptr, len))) + } + + /** Decode one SharedVariant / JSON shared-data cell into `{ type, column }`. */ + function decodeBinaryValue(bytes) { + return withInput(bytes, (ptr, len) => take(x.chw_decode_binary_value(ptr, len))) + } + + /** Parse a ClickHouse type string with the core's parser. */ + function describeType(type) { + return withInput(utf8Encoder.encode(type), (ptr, len) => take(x.chw_describe_type(ptr, len))) + } + + /** + * Encode one block `{ rowCount, columns: [{ name, type, ...buffers }] }`, + * the shape of one decoded chunk, into Native bytes for + * `INSERT ... FORMAT Native`. Concatenate blocks for a multi-block body. + */ + function encodeNative(block) { + // Pack every TypedArray into one data blob at 8-byte aligned offsets and + // replace it in the descriptor with a reference to its range. + const parts = [] + let size = 0 + const desc = JSON.stringify(block, function (key, v) { + // Read the raw property: JSON.stringify has already applied toJSON, which + // turns a Node Buffer into { type, data } before the replacer sees it. + const raw = this[key] + if (ArrayBuffer.isView(raw)) { + const off = Math.ceil(size / 8) * 8 + parts.push([off, raw]) + size = off + raw.byteLength + return { $b: [off, raw.byteLength] } + } + return v + }) + const descBytes = utf8Encoder.encode(desc) + const dataPtr = alloc(size) + let descPtr = 0 + try { + descPtr = alloc(descBytes.byteLength) + const mem = new Uint8Array(memory()) + mem.set(descBytes, descPtr) + for (const [off, v] of parts) { + mem.set(new Uint8Array(v.buffer, v.byteOffset, v.byteLength), dataPtr + off) + } + return take(x.chw_encode(descPtr, descBytes.byteLength, dataPtr, size)).bytes + } finally { + x.chw_free(dataPtr, size) + if (descPtr) x.chw_free(descPtr, descBytes.byteLength) + } + } + + // A decoder dropped without free() releases its Rust state when collected. + const streams = new FinalizationRegistry((handle) => x.chw_stream_free(handle)) + + /** + * Incremental Native decoder for HTTP response streams. `push` returns + * every block that is now complete; `finish` drains the tail and fails on a + * truncated final block. After any error the decoder is poisoned. + */ + class NativeStreamDecoder { + #handle + + constructor() { + this.#handle = x.chw_stream_new() + streams.register(this, this.#handle, this) + } + + #live() { + if (!this.#handle) throw new CodecError('InvalidArg', 'NativeStreamDecoder was freed') + return this.#handle + } + + push(bytes) { + const h = this.#live() + return withInput(bytes, (ptr, len) => take(x.chw_stream_push(h, ptr, len))) + } + + finish() { + return take(x.chw_stream_finish(this.#live())) + } + + /** Rows emitted so far. A u64 in the ABI, exact here up to 2^53. */ + get rowCount() { + return Number(BigInt.asUintN(64, x.chw_stream_row_count(this.#live()))) + } + + get bufferedBytes() { + return u32(x.chw_stream_buffered_bytes(this.#live())) + } + + /** Release the decoder's state now instead of at garbage collection. */ + free() { + if (!this.#handle) return + streams.unregister(this) + x.chw_stream_free(this.#handle) + this.#handle = 0 + } + } + + return { + abiVersion: abi, + decodeNativeColumns, + decodeBinaryValue, + describeType, + encodeNative, + NativeStreamDecoder, + } +} diff --git a/crates/ch-core-wasm/js/index.d.ts b/crates/ch-core-wasm/js/index.d.ts new file mode 100644 index 0000000..6c064d3 --- /dev/null +++ b/crates/ch-core-wasm/js/index.d.ts @@ -0,0 +1,76 @@ +// Types for both entries (Node and web). Column objects are columnar: every +// buffer is a JS-owned TypedArray copied out of wasm memory, never a view. + +/** The C ABI version this glue speaks. */ +export const ABI_VERSION: number + +export class CodecError extends Error { + readonly code: 'InvalidArg' | 'GenericFailure' | 'OutOfMemory' +} + +/** + * One decoded column. `kind` is the physical layout and selects which + * buffers are present (see README.md); `type` is the ClickHouse type string. + * Nullable columns carry an Arrow-style `validity` bitmap (bit 1 = valid). + */ +export interface Column { + kind: string + type?: string + name?: string + validity?: Uint8Array + values?: ArrayBufferView | Column + offsets?: Int32Array | BigInt64Array + data?: Uint8Array + [field: string]: unknown +} + +export interface Chunk { + rowCount: number + columns: Column[] +} + +export interface DecodeResult { + rowCount: number + columnNames: string[] + columnTypes: string[] + chunks: Chunk[] +} + +export interface StreamResult extends DecodeResult { + bufferedBytes: number +} + +export interface TypeDescription { + type: string + kind: string + nullable: boolean + [field: string]: unknown +} + +type Bytes = Uint8Array | ArrayBuffer | ArrayBufferView + +/** Resolves once the module is ready. A no-op on Node. */ +export function init(source?: string | URL | Response | BufferSource | WebAssembly.Module): Promise + +/** Decode a complete `FORMAT Native` body. An empty body is an empty result. */ +export function decodeNativeColumns(bytes: Bytes): DecodeResult + +/** Decode one SharedVariant or JSON shared-data cell into a one-row column. */ +export function decodeBinaryValue(bytes: Bytes): { type: string; column: Column } + +/** Parse a ClickHouse type string with the core's parser. */ +export function describeType(type: string): TypeDescription + +/** Encode one block, in the shape of a decoded chunk, into Native bytes. */ +export function encodeNative(block: { rowCount: number; columns: Column[] }): Uint8Array + +/** Incremental decoder for HTTP response bodies. Poisoned after any error. */ +export class NativeStreamDecoder { + constructor() + push(bytes: Bytes): StreamResult + finish(): StreamResult + readonly rowCount: number + readonly bufferedBytes: number + /** Release the decoder now instead of at garbage collection. */ + free(): void +} diff --git a/crates/ch-core-wasm/js/node.mjs b/crates/ch-core-wasm/js/node.mjs new file mode 100644 index 0000000..5a9f512 --- /dev/null +++ b/crates/ch-core-wasm/js/node.mjs @@ -0,0 +1,14 @@ +// Node.js entry: the module is compiled and instantiated synchronously on +// import, from dist/ch_core_wasm.wasm next to this package. +import { readFileSync } from 'node:fs' +import { bindExports } from './core.mjs' + +const bytes = readFileSync(new URL('../dist/ch_core_wasm.wasm', import.meta.url)) +const { exports } = new WebAssembly.Instance(new WebAssembly.Module(bytes), {}) +const api = bindExports(exports) + +export { ABI_VERSION, CodecError } from './core.mjs' +export const { decodeNativeColumns, decodeBinaryValue, describeType, encodeNative, NativeStreamDecoder } = api + +/** No-op on Node, where the module is ready on import. Present for parity with the web entry. */ +export async function init() {} diff --git a/crates/ch-core-wasm/js/web.mjs b/crates/ch-core-wasm/js/web.mjs new file mode 100644 index 0000000..45b08bf --- /dev/null +++ b/crates/ch-core-wasm/js/web.mjs @@ -0,0 +1,64 @@ +// Browser, Deno and Bun entry. Call `await init()` once before anything else. +// By default `init()` fetches dist/ch_core_wasm.wasm relative to this module; +// pass a URL, Response, BufferSource or WebAssembly.Module to load it from +// elsewhere. +import { bindExports, CodecError } from './core.mjs' + +export { ABI_VERSION, CodecError } from './core.mjs' + +let api +let ready + +async function instantiate(source) { + if (source instanceof WebAssembly.Module) return WebAssembly.instantiate(source, {}) + if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) { + return (await WebAssembly.instantiate(source, {})).instance + } + const response = await (typeof source === 'string' || source instanceof URL ? fetch(source) : source) + if (!response.ok) throw new Error(`ch-core-wasm: fetching the .wasm failed with HTTP ${response.status}`) + if (typeof WebAssembly.instantiateStreaming === 'function') { + try { + return (await WebAssembly.instantiateStreaming(response.clone(), {})).instance + } catch { + // Served without `application/wasm`: fall back to a buffered compile. + } + } + return (await WebAssembly.instantiate(await response.arrayBuffer(), {})).instance +} + +export function init(source = new URL('../dist/ch_core_wasm.wasm', import.meta.url)) { + ready ??= instantiate(source).then( + (instance) => { + api = bindExports(instance.exports) + }, + (err) => { + // Let a later init() retry instead of keeping the failure forever. + ready = undefined + throw err + }, + ) + return ready +} + +const loaded = () => { + if (!api) throw new CodecError('InvalidArg', 'ch-core-wasm is not initialized; await init() first') + return api +} + +export const decodeNativeColumns = (bytes) => loaded().decodeNativeColumns(bytes) +export const decodeBinaryValue = (bytes) => loaded().decodeBinaryValue(bytes) +export const describeType = (type) => loaded().describeType(type) +export const encodeNative = (block) => loaded().encodeNative(block) + +/** See `NativeStreamDecoder` in core.mjs. Requires `init()` first. */ +export class NativeStreamDecoder { + constructor() { + return new (loaded().NativeStreamDecoder)() + } + + // The constructor returns the bound class's instance, so make instanceof + // recognize those. + static [Symbol.hasInstance](value) { + return api !== undefined && value instanceof api.NativeStreamDecoder + } +} diff --git a/crates/ch-core-wasm/package.json b/crates/ch-core-wasm/package.json new file mode 100644 index 0000000..7103d3e --- /dev/null +++ b/crates/ch-core-wasm/package.json @@ -0,0 +1,24 @@ +{ + "name": "ch-core-wasm", + "version": "0.1.0", + "private": true, + "description": "ch-core-rs (ClickHouse FORMAT Native codec) compiled to WebAssembly, with JS glue over its C ABI", + "license": "Apache-2.0", + "type": "module", + "exports": { + ".": { + "types": "./js/index.d.ts", + "node": "./js/node.mjs", + "default": "./js/web.mjs" + } + }, + "types": "./js/index.d.ts", + "files": ["js", "dist", "ABI.md"], + "scripts": { + "build": "./scripts/build.sh", + "test": "node --test test/*.test.mjs" + }, + "engines": { + "node": ">=18" + } +} diff --git a/crates/ch-core-wasm/scripts/build.sh b/crates/ch-core-wasm/scripts/build.sh new file mode 100755 index 0000000..e9abce7 --- /dev/null +++ b/crates/ch-core-wasm/scripts/build.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Build the .wasm into dist/. Needs the wasm32-unknown-unknown target: +# rustup target add wasm32-unknown-unknown +# Runs wasm-opt (binaryen) as well when it is on PATH. +set -euo pipefail +crate="$(cd "$(dirname "$0")/.." && pwd)" +root="$(cd "$crate/../.." && pwd)" + +cargo build --manifest-path "$root/Cargo.toml" -p ch-core-wasm \ + --target wasm32-unknown-unknown --profile wasm-release +mkdir -p "$crate/dist" +out="$crate/dist/ch_core_wasm.wasm" +cp "$root/target/wasm32-unknown-unknown/wasm-release/ch_core_wasm.wasm" "$out" + +if command -v wasm-opt >/dev/null 2>&1; then + wasm-opt -O3 --enable-bulk-memory --enable-nontrapping-float-to-int \ + --enable-sign-ext --enable-mutable-globals "$out" -o "$out" +fi +ls -l "$out" diff --git a/crates/ch-core-wasm/src/decode.rs b/crates/ch-core-wasm/src/decode.rs new file mode 100644 index 0000000..7b609e2 --- /dev/null +++ b/crates/ch-core-wasm/src/decode.rs @@ -0,0 +1,512 @@ +//! Decoded columns -> descriptor JSON with buffer references. +//! +//! Every buffer is written as `{"$b":[ptr,byteLength,"dtype"]}`, where `ptr` +//! points at the decoded `Vec` inside the [`Output`] that owns it. Nothing is +//! copied here. The JS glue copies each referenced range out of linear memory +//! once, then frees the output (see `ABI.md`). +//! +//! The descriptor shape is the column-object shape the JS side returns: every +//! column has `kind` (the physical layout) and, when known, `type` (the full +//! ClickHouse type string). A nullable column carries an Arrow-style packed +//! `validity` bitmap (bit 1 = valid). Nested kinds carry their children as +//! further column objects. + +use std::borrow::Cow; +use std::sync::Arc; + +use ch_core_rs::batch::ColBatch; +use ch_core_rs::column::{ + Column, DynamicChild, DynamicColumn, JsonBody, Utf8Column, VariantColumn, +}; +use ch_core_rs::native::decode::{low_cardinality_dict_value_type, parse_ch_type}; +use ch_core_rs::schema::ChType; + +use crate::json::Writer; +use crate::{Error, Output}; + +/// An element type that crosses the ABI as a typed buffer. +pub(crate) trait Elem: Copy { + /// The `dtype` tag the JS glue maps to a TypedArray constructor. + const DTYPE: &'static str; + const SIZE: usize; + /// Read one little-endian element from exactly `SIZE` bytes. + fn from_le(bytes: &[u8]) -> Self; +} + +macro_rules! elem { + ($($t:ty => $tag:literal),* $(,)?) => {$( + impl Elem for $t { + const DTYPE: &'static str = $tag; + const SIZE: usize = std::mem::size_of::<$t>(); + #[inline] + fn from_le(bytes: &[u8]) -> Self { + let mut raw = [0u8; std::mem::size_of::<$t>()]; + raw.copy_from_slice(bytes); + <$t>::from_le_bytes(raw) + } + } + )*}; +} + +elem!( + i8 => "i8", u8 => "u8", i16 => "i16", u16 => "u16", i32 => "i32", u32 => "u32", + i64 => "i64", u64 => "u64", f32 => "f32", f64 => "f64", +); + +/// Strip name-only decorations (Nullable, SimpleAggregateFunction, geo +/// aliases, Geometry, Nested) down to the type that determines the column's +/// physical layout. Uses the core's single expansion point so this never +/// drifts from the decoder. `LowCardinality` is kept: it maps to its own +/// dictionary column. +pub(crate) fn physical(ty: &ChType) -> Cow<'_, ChType> { + let mut t: Cow<'_, ChType> = Cow::Borrowed(ty); + loop { + let next = match t.as_ref() { + ChType::Nullable(inner) => Some(inner.as_ref().clone()), + other => other.physical_delegate(), + }; + match next { + Some(n) => t = Cow::Owned(n), + None => return t, + } + } +} + +/// Builds one result descriptor. Derived buffers that do not exist in the +/// decoded columns, such as Variant offsets, are kept in `derived` so their +/// pointers stay valid for the life of the [`Output`]. +#[derive(Default)] +pub(crate) struct Describer { + pub(crate) w: Writer, + derived: Vec>, +} + +impl Describer { + /// Wrap the descriptor and everything its pointers refer to. + pub(crate) fn into_output(self, batches: Vec>, columns: Vec) -> Output { + Output { + json: self.w.finish(), + batches, + columns, + bytes: self.derived, + } + } + + /// Write a buffer reference to `values` as the value of `key`. + /// + /// The caller must move whatever owns `values` into the [`Output`] + /// built from this describer. Moving a `Vec` does not move its heap + /// allocation, so the pointer stays valid. + pub(crate) fn buf(&mut self, key: &str, values: &[T]) { + self.raw_buf( + key, + values.as_ptr() as usize, + std::mem::size_of_val(values), + T::DTYPE, + ); + } + + fn raw_buf(&mut self, key: &str, ptr: usize, len: usize, dtype: &str) { + self.w.key(key); + self.w.begin_object(); + self.w.key("$b"); + self.w.begin_array(); + self.w.uint(ptr as u64); + self.w.uint(len as u64); + self.w.string(dtype); + self.w.end_array(); + self.w.end_object(); + } + + /// Keep a derived buffer alive and reference it. + fn derived_buf(&mut self, key: &str, values: Vec) { + self.raw_buf(key, values.as_ptr() as usize, values.len(), T::DTYPE); + self.derived.push(values); + } + + // ----------------------------------------------------------------------- + // Results + // ----------------------------------------------------------------------- + + /// `{ rowCount, columnNames, columnTypes, chunks: [{ rowCount, columns }] ...` + /// The caller closes the object, so the stream path can append fields. + pub(crate) fn begin_result<'a>( + &mut self, + row_count: usize, + names: &[String], + types: &[String], + chunks: impl IntoIterator, + ) -> Result<(), Error> { + let w = &mut self.w; + w.begin_object(); + w.field_uint("rowCount", row_count as u64); + w.key("columnNames"); + w.begin_array(); + for n in names { + w.string(n); + } + w.end_array(); + w.key("columnTypes"); + w.begin_array(); + for t in types { + w.string(t); + } + w.end_array(); + self.w.key("chunks"); + self.w.begin_array(); + for chunk in chunks { + self.chunk(chunk)?; + } + self.w.end_array(); + Ok(()) + } + + fn chunk(&mut self, batch: &ColBatch) -> Result<(), Error> { + if batch.schema.fields.len() != batch.num_columns() { + return Err(Error::generic(format!( + "decoded block is inconsistent: {} schema fields but {} columns", + batch.schema.fields.len(), + batch.num_columns() + ))); + } + self.w.begin_object(); + self.w.field_uint("rowCount", batch.num_rows as u64); + self.w.key("columns"); + self.w.begin_array(); + for (field, col) in batch.schema.fields.iter().zip(&batch.columns) { + self.column(col, Some(&field.ch_type), Some(&field.name))?; + } + self.w.end_array(); + self.w.end_object(); + Ok(()) + } + + // ----------------------------------------------------------------------- + // Columns + // ----------------------------------------------------------------------- + + /// Write one column object. + pub(crate) fn column( + &mut self, + col: &Column, + ty: Option<&ChType>, + name: Option<&str>, + ) -> Result<(), Error> { + self.w.begin_object(); + if let Some(n) = name { + self.w.field_str("name", n); + } + if let Some(t) = ty { + self.w.field_str("type", &t.to_string()); + } + let phys = ty.map(physical); + let phys = phys.as_deref(); + self.type_metadata(phys); + + macro_rules! values { + ($kind:literal, $c:expr) => {{ + self.w.field_str("kind", $kind); + self.buf("values", &$c.values); + }}; + } + + match col { + Column::Nothing(c) => { + self.w.field_str("kind", "Nothing"); + self.w.field_uint("length", c.len as u64); + } + Column::Bool(c) => { + self.w.field_str("kind", "Bool"); + self.w.field_uint("length", c.len as u64); + self.buf("bitmap", &c.bitmap); + } + Column::Int8(c) => values!("Int8", c), + Column::Int16(c) => values!("Int16", c), + Column::Int32(c) => values!("Int32", c), + Column::Int64(c) => values!("Int64", c), + Column::UInt8(c) => values!("UInt8", c), + Column::UInt16(c) => values!("UInt16", c), + Column::UInt32(c) => values!("UInt32", c), + Column::UInt64(c) => values!("UInt64", c), + Column::Float32(c) => values!("Float32", c), + Column::Float64(c) => values!("Float64", c), + Column::BFloat16(c) => { + // Raw little-endian 16-bit words: the top half of an f32. + self.w.field_str("kind", "BFloat16"); + self.buf("values", c.values.as_flattened()); + } + Column::QBit(c) => { + self.w.field_str("kind", "QBit"); + self.w.field_uint("dimension", c.dimension as u64); + let elem = match phys { + Some(ChType::QBit { element_type, .. }) => { + parse_ch_type(&element_type.to_string()) + } + _ => None, + }; + self.w.key("values"); + self.column(&c.values, elem.as_ref(), None)?; + } + Column::Date(c) => values!("Date", c), + Column::Date32(c) => values!("Date32", c), + Column::DateTime(c) => values!("DateTime", c), + Column::DateTime64(c) => values!("DateTime64", c), + Column::Time(c) => values!("Time", c), + Column::Time64(c) => values!("Time64", c), + Column::Interval(c) => values!("Interval", c), + Column::Utf8(c) => self.utf8_body("String", c), + Column::AggregateState(c) => { + self.w.field_str("kind", "AggregateFunction"); + self.buf("offsets", &c.offsets); + self.buf("data", &c.data); + } + Column::FixedBinary(c) => self.fixed("FixedString", &c.data, c.width), + Column::Ipv4(c) => values!("IPv4", c), + Column::Ipv6(c) => self.fixed("IPv6", &c.data, c.width), + Column::Uuid(c) => self.fixed("UUID", &c.data, c.width), + Column::Enum8(c) => values!("Enum8", c), + Column::Enum16(c) => values!("Enum16", c), + Column::Decimal(c) => { + self.fixed("Decimal", &c.data, c.width); + self.w.field_uint("precision", u64::from(c.precision)); + self.w.field_uint("scale", u64::from(c.scale)); + } + Column::Int128(c) => self.fixed("Int128", &c.data, c.width), + Column::UInt128(c) => self.fixed("UInt128", &c.data, c.width), + Column::Int256(c) => self.fixed("Int256", &c.data, c.width), + Column::UInt256(c) => self.fixed("UInt256", &c.data, c.width), + Column::Dictionary(c) => { + self.w.field_str("kind", "LowCardinality"); + self.buf("indices", &c.indices); + let dict_ty = match phys { + Some(ChType::LowCardinality(inner)) => { + Some(low_cardinality_dict_value_type(inner).1.clone()) + } + _ => None, + }; + self.w.key("dictionary"); + self.column(&c.values, dict_ty.as_ref(), None)?; + } + Column::Array(c) => { + self.w.field_str("kind", "Array"); + self.buf("offsets", &c.offsets); + let elem = match phys { + Some(ChType::Array(e)) => Some(e.as_ref()), + _ => None, + }; + self.w.key("values"); + self.column(&c.values, elem, None)?; + } + Column::Tuple(c) => { + self.w.field_str("kind", "Tuple"); + self.w.field_uint("length", c.len as u64); + let elems = match phys { + Some(ChType::Tuple(e)) if e.len() == c.fields.len() => Some(e), + _ => None, + }; + self.w.key("names"); + self.w.begin_array(); + for i in 0..c.fields.len() { + match elems.and_then(|e| e[i].0.as_deref()) { + Some(n) => self.w.string(n), + None => self.w.null(), + } + } + self.w.end_array(); + self.w.key("fields"); + self.w.begin_array(); + for (i, f) in c.fields.iter().enumerate() { + self.column(f, elems.map(|e| &e[i].1), None)?; + } + self.w.end_array(); + } + Column::Map(c) => { + self.w.field_str("kind", "Map"); + self.buf("offsets", &c.offsets); + let Column::Tuple(entries) = c.entries.as_ref() else { + return Err(Error::invalid("Map entries are not a Tuple")); + }; + if entries.fields.len() != 2 { + return Err(Error::invalid("Map entries must have 2 fields")); + } + let (kty, vty) = match phys { + Some(ChType::Map(k, v)) => (Some(k.as_ref()), Some(v.as_ref())), + _ => (None, None), + }; + self.w.key("keys"); + self.column(&entries.fields[0], kty, None)?; + self.w.key("values"); + self.column(&entries.fields[1], vty, None)?; + } + Column::Variant(c) => self.variant(c, phys)?, + Column::Dynamic(c) => self.dynamic(c)?, + Column::Json(c) => { + self.w.field_str("kind", "JSON"); + match &c.body { + JsonBody::Text(s) => { + self.w.field_str("format", "text"); + self.w.key("text"); + self.utf8_object(s, None); + } + JsonBody::Structured(s) => { + self.w.field_str("format", "structured"); + self.w.field_uint("length", s.len as u64); + let declared = match phys { + Some(ChType::Json { typed_paths, .. }) => Some(typed_paths), + _ => None, + }; + self.w.key("typedPaths"); + self.w.begin_array(); + for (path, col) in &s.typed { + let pty = declared + .and_then(|d| d.iter().find(|(p, _)| p == path)) + .map(|(_, t)| t); + self.w.begin_object(); + self.w.field_str("path", path); + self.w.key("column"); + self.column(col, pty, None)?; + self.w.end_object(); + } + self.w.end_array(); + self.w.key("dynamicPaths"); + self.w.begin_array(); + for (path, col) in &s.dynamic { + self.w.begin_object(); + self.w.field_str("path", path); + self.w.key("column"); + self.w.begin_object(); + self.dynamic(col)?; + self.w.end_object(); + self.w.end_object(); + } + self.w.end_array(); + self.buf("sharedOffsets", &s.shared_offsets); + self.w.key("sharedPaths"); + self.utf8_object(&s.shared_paths, None); + self.w.key("sharedValues"); + self.utf8_object(&s.shared_values, None); + } + } + } + } + + if let Some(validity) = col.validity() { + self.buf("validity", validity.as_bytes()); + } + self.w.end_object(); + Ok(()) + } + + /// The `kind`, `offsets` and `data` fields of a String-shaped column. + fn utf8_body(&mut self, kind: &str, c: &Utf8Column) { + self.w.field_str("kind", kind); + self.buf("offsets", &c.offsets); + self.buf("data", &c.data); + } + + /// A standalone String-shaped column object, used for JSON text, JSON + /// shared data and the Dynamic `SharedVariant` child. + fn utf8_object(&mut self, c: &Utf8Column, kind: Option<&str>) { + self.w.begin_object(); + self.utf8_body(kind.unwrap_or("String"), c); + if let Some(v) = &c.validity { + self.buf("validity", v.as_bytes()); + } + self.w.end_object(); + } + + fn fixed(&mut self, kind: &str, data: &[u8], width: usize) { + self.w.field_str("kind", kind); + self.w.field_uint("width", width as u64); + self.buf("data", data); + } + + /// Type metadata a binding needs to turn raw wire values into host values. + fn type_metadata(&mut self, ty: Option<&ChType>) { + match ty { + Some(ChType::DateTime { timezone: Some(tz) }) => self.w.field_str("timezone", tz), + Some(ChType::DateTime64 { + precision, + timezone, + }) => { + self.w.field_uint("precision", u64::from(*precision)); + if let Some(tz) = timezone { + self.w.field_str("timezone", tz); + } + } + Some(ChType::Time64 { precision }) => { + self.w.field_uint("precision", u64::from(*precision)) + } + Some(ChType::Enum8 { variants }) => { + self.enum_values(variants.iter().map(|(n, v)| (n, i64::from(*v)))) + } + Some(ChType::Enum16 { variants }) => { + self.enum_values(variants.iter().map(|(n, v)| (n, i64::from(*v)))) + } + _ => {} + } + } + + pub(crate) fn enum_values<'a>(&mut self, variants: impl Iterator) { + self.w.key("enumValues"); + self.w.begin_array(); + for (name, v) in variants { + self.w.begin_array(); + self.w.string(name); + self.w.int(v); + self.w.end_array(); + } + self.w.end_array(); + } + + /// Variant: per-row global discriminators (255 = NULL), per-row offsets + /// into the selected alternative, and one compact child column per + /// alternative. Offsets are derived here from the discriminators so JS + /// does not need to understand the two-level Arrow union layout used past + /// 127 alternatives. + fn variant(&mut self, c: &VariantColumn, ty: Option<&ChType>) -> Result<(), Error> { + self.w.field_str("kind", "Variant"); + let alts = match ty { + Some(ChType::Variant(a)) if a.len() == c.variants.len() => Some(a), + _ => None, + }; + let mut seen = [0i32; 256]; + let mut offsets = Vec::with_capacity(c.discriminators.len() * 4); + for &d in &c.discriminators { + let slot = &mut seen[usize::from(d)]; + offsets.extend_from_slice(&slot.to_le_bytes()); + *slot += 1; + } + self.buf("discriminators", &c.discriminators); + self.derived_buf::("offsets", offsets); + self.w.key("variants"); + self.w.begin_array(); + for (i, v) in c.variants.iter().enumerate() { + self.column(v, alts.map(|a| &a[i]), None)?; + } + self.w.end_array(); + Ok(()) + } + + /// Dynamic: per-row `typeIds` (index into `children`, 0xFFFFFFFF = NULL) + /// and dense `offsets` into that child. Each child is either a typed column + /// or the `SharedVariant` overflow, whose cells are binary-encoded values + /// for `chw_decode_binary_value`. + fn dynamic(&mut self, c: &DynamicColumn) -> Result<(), Error> { + self.w.field_str("kind", "Dynamic"); + self.buf("typeIds", &c.type_ids); + self.buf("offsets", &c.offsets); + self.w.key("children"); + self.w.begin_array(); + for child in &c.children { + match child { + DynamicChild::Typed { ch_type, values } => { + self.column(values, Some(ch_type), None)? + } + DynamicChild::Shared(values) => self.utf8_object(values, Some("SharedVariant")), + } + } + self.w.end_array(); + Ok(()) + } +} diff --git a/crates/ch-core-wasm/src/describe.rs b/crates/ch-core-wasm/src/describe.rs new file mode 100644 index 0000000..d8face0 --- /dev/null +++ b/crates/ch-core-wasm/src/describe.rs @@ -0,0 +1,172 @@ +//! `chw_describe_type`: the core's type parser, exposed so a JS binding can +//! lay out column buffers for a ClickHouse type without a second parser. + +use ch_core_rs::native::decode::{low_cardinality_dict_value_type, parse_ch_type}; +use ch_core_rs::schema::ChType; + +use crate::decode::{physical, Describer}; + +/// Write `{ type, kind, nullable, ...metadata, ...children }` for `ty`, where +/// `kind` is the column-object kind the decoder emits for that type. Name-only +/// aliases (geo types, Nested, SimpleAggregateFunction) resolve to their +/// physical layout. Types the core cannot encode report `kind: "Unsupported"`. +pub(crate) fn describe(d: &mut Describer, ty: &ChType) { + d.w.begin_object(); + describe_fields(d, ty); + d.w.end_object(); +} + +/// The fields of [`describe`] without the enclosing braces. +fn describe_fields(d: &mut Describer, ty: &ChType) { + let w = &mut d.w; + w.field_str("type", &ty.to_string()); + let phys = physical(ty); + let nullable = matches!(ty, ChType::Nullable(_)) + || matches!(phys.as_ref(), ChType::LowCardinality(i) if low_cardinality_dict_value_type(i).0); + w.key("nullable"); + w.bool(nullable); + let kind = match phys.as_ref() { + ChType::Nothing => "Nothing", + ChType::Bool => "Bool", + ChType::Int8 => "Int8", + ChType::Int16 => "Int16", + ChType::Int32 => "Int32", + ChType::Int64 => "Int64", + ChType::UInt8 => "UInt8", + ChType::UInt16 => "UInt16", + ChType::UInt32 => "UInt32", + ChType::UInt64 => "UInt64", + ChType::Float32 => "Float32", + ChType::Float64 => "Float64", + ChType::BFloat16 => "BFloat16", + ChType::QBit { + element_type, + dimension, + } => { + d.w.field_uint("dimension", *dimension as u64); + if let Some(e) = parse_ch_type(&element_type.to_string()) { + d.w.key("element"); + describe(d, &e); + } + "QBit" + } + ChType::Date => "Date", + ChType::Date32 => "Date32", + ChType::DateTime { timezone } => { + if let Some(tz) = timezone { + d.w.field_str("timezone", tz); + } + "DateTime" + } + ChType::DateTime64 { + precision, + timezone, + } => { + d.w.field_uint("precision", u64::from(*precision)); + if let Some(tz) = timezone { + d.w.field_str("timezone", tz); + } + "DateTime64" + } + ChType::Time => "Time", + ChType::Time64 { precision } => { + d.w.field_uint("precision", u64::from(*precision)); + "Time64" + } + ChType::Interval(_) => "Interval", + ChType::String => "String", + ChType::FixedString(n) => { + d.w.field_uint("width", *n as u64); + "FixedString" + } + ChType::Uuid => "UUID", + ChType::Ipv4 => "IPv4", + ChType::Ipv6 => "IPv6", + ChType::Enum8 { variants } => { + d.enum_values(variants.iter().map(|(n, v)| (n, i64::from(*v)))); + "Enum8" + } + ChType::Enum16 { variants } => { + d.enum_values(variants.iter().map(|(n, v)| (n, i64::from(*v)))); + "Enum16" + } + ChType::Decimal { + precision, + scale, + bits, + } => { + d.w.field_uint("precision", u64::from(*precision)); + d.w.field_uint("scale", u64::from(*scale)); + d.w.field_uint("width", u64::from(*bits / 8)); + "Decimal" + } + ChType::Int128 => "Int128", + ChType::UInt128 => "UInt128", + ChType::Int256 => "Int256", + ChType::UInt256 => "UInt256", + ChType::LowCardinality(inner) => { + d.w.key("dictionary"); + describe(d, low_cardinality_dict_value_type(inner).1); + "LowCardinality" + } + ChType::Array(e) => { + d.w.key("element"); + describe(d, e); + "Array" + } + ChType::Tuple(elems) => { + d.w.key("names"); + d.w.begin_array(); + for (n, _) in elems { + match n { + Some(n) => d.w.string(n), + None => d.w.null(), + } + } + d.w.end_array(); + d.w.key("fields"); + d.w.begin_array(); + for (_, t) in elems { + describe(d, t); + } + d.w.end_array(); + "Tuple" + } + ChType::Map(k, v) => { + d.w.key("key"); + describe(d, k); + d.w.key("value"); + describe(d, v); + "Map" + } + ChType::Variant(alts) => { + d.w.key("variants"); + d.w.begin_array(); + for t in alts { + describe(d, t); + } + d.w.end_array(); + "Variant" + } + ChType::Dynamic { max_types } => { + d.w.field_uint("maxTypes", u64::from(*max_types)); + "Dynamic" + } + ChType::Json { typed_paths, .. } => { + d.w.key("typedPaths"); + d.w.begin_array(); + // Each entry is the path's type description plus its `path`. + for (p, t) in typed_paths { + d.w.begin_object(); + d.w.field_str("path", p); + describe_fields(d, t); + d.w.end_object(); + } + d.w.end_array(); + "JSON" + } + ChType::AggregateFunction { .. } => "AggregateFunction", + _ => "Unsupported", + }; + d.w.field_str("kind", kind); +} diff --git a/crates/ch-core-wasm/src/encode.rs b/crates/ch-core-wasm/src/encode.rs new file mode 100644 index 0000000..d5111e0 --- /dev/null +++ b/crates/ch-core-wasm/src/encode.rs @@ -0,0 +1,479 @@ +//! Descriptor JSON + data blob -> core `Column`s -> Native bytes (the INSERT +//! path). +//! +//! The input is the same column-object shape the decoder produces, so a +//! decoded chunk can be passed straight back. Each column's ClickHouse `type` +//! string is authoritative: the core parses it and it drives which buffers are +//! read. `kind` is ignored. A buffer is `{"$b":[offset,byteLength]}`, a range +//! of the data blob passed next to the descriptor, and is copied into the +//! column's `Vec` here. +//! +//! The core's encoder validates every structural invariant (lengths, offsets, +//! dictionary indices, null placement, Variant/Dynamic routing) before writing +//! a byte, so this layer only checks what it needs to build the columns. + +use ch_core_rs::batch::ColBatch; +use ch_core_rs::bitmap::Bitmap; +use ch_core_rs::column::{ + AggregateStateColumn, ArrayColumn, BoolColumn, Column, DecimalColumn, DictionaryColumn, + DynamicChild, DynamicColumn, FixedBinaryColumn, JsonColumn, MapColumn, NothingColumn, + PrimitiveColumn, QBitColumn, StructuredJson, TupleColumn, Utf8Column, VariantColumn, +}; +use ch_core_rs::native::decode::{low_cardinality_dict_value_type, parse_ch_type}; +use ch_core_rs::native::encode::{encode_block, EncodeOptions}; +use ch_core_rs::schema::{ChType, Field, Schema}; + +use crate::decode::{physical, Elem}; +use crate::json::Value; +use crate::Error; + +type R = Result; + +fn bad(path: &str, msg: impl AsRef) -> Error { + Error::invalid(format!("column {path}: {}", msg.as_ref())) +} + +/// Encode input: the parsed descriptor and the blob its buffers point into. +struct Input<'a> { + data: &'a [u8], +} + +impl Input<'_> { + /// The blob range a `{"$b":[offset,byteLength]}` reference names. + fn range(&self, v: Option<&Value>, key: &str, path: &str) -> R<&[u8]> { + let r = v + .and_then(|v| v.get("$b")) + .and_then(Value::as_array) + .ok_or_else(|| bad(path, format!("expected '{key}' to be a typed array")))?; + let (off, len) = match r { + [off, len, ..] => (off.as_usize(), len.as_usize()), + _ => (None, None), + }; + let (Some(off), Some(len)) = (off, len) else { + return Err(bad( + path, + format!("'{key}' has a malformed buffer reference"), + )); + }; + off.checked_add(len) + .and_then(|end| self.data.get(off..end)) + .ok_or_else(|| bad(path, format!("'{key}' points outside the data buffer"))) + } + + /// Copy a required typed-array field into a `Vec`. + fn buf(&self, obj: &Value, key: &str, path: &str) -> R> { + self.buf_of(obj.get(key), key, path) + } + + fn buf_of(&self, v: Option<&Value>, key: &str, path: &str) -> R> { + let bytes = self.range(v, key, path)?; + if bytes.len() % T::SIZE != 0 { + return Err(bad( + path, + format!("'{key}' length is not a multiple of {} bytes", T::SIZE), + )); + } + Ok(bytes.chunks_exact(T::SIZE).map(T::from_le).collect()) + } + + /// Byte length of a typed-array field, for sizing a dictionary. + fn byte_len(&self, obj: &Value, key: &str) -> Option { + self.range(obj.get(key), key, "").ok().map(<[u8]>::len) + } +} + +fn array<'v>(obj: &'v Value, key: &str, path: &str) -> R<&'v [Value]> { + obj.get(key) + .and_then(Value::as_array) + .ok_or_else(|| bad(path, format!("expected '{key}' to be an array"))) +} + +fn str_field<'v>(obj: &'v Value, key: &str) -> Option<&'v str> { + obj.get(key).and_then(Value::as_str) +} + +fn type_of(obj: &Value, path: &str) -> R { + let s = str_field(obj, "type").ok_or_else(|| bad(path, "missing ClickHouse 'type' string"))?; + parse_ch_type(s).ok_or_else(|| bad(path, format!("cannot parse type '{s}'"))) +} + +/// Length implied by an Arrow-style offsets buffer (its last entry). +fn last_offset(offsets: &[i64], path: &str) -> R { + let last = *offsets + .last() + .ok_or_else(|| bad(path, "offsets must not be empty"))?; + usize::try_from(last).map_err(|_| bad(path, "negative offset")) +} + +/// Rows routed to each child by a discriminator or type-id buffer. +fn counts>(ids: &[T], null: u64, n: usize) -> Vec { + let mut c = vec![0usize; n]; + for &id in ids { + let id: u64 = id.into(); + if id != null { + if let Some(slot) = usize::try_from(id).ok().and_then(|i| c.get_mut(i)) { + *slot += 1; + } + } + } + c +} + +/// Element width of the primitive types `build` reads from a `values` buffer. +fn primitive_width(ty: &ChType) -> Option { + Some(match ty { + ChType::Int8 | ChType::UInt8 | ChType::Enum8 { .. } => 1, + ChType::Int16 | ChType::UInt16 | ChType::Date | ChType::Enum16 { .. } => 2, + ChType::Int32 + | ChType::UInt32 + | ChType::Float32 + | ChType::Date32 + | ChType::DateTime { .. } + | ChType::Time + | ChType::Ipv4 => 4, + ChType::Int64 + | ChType::UInt64 + | ChType::Float64 + | ChType::DateTime64 { .. } + | ChType::Time64 { .. } + | ChType::Interval(_) => 8, + _ => return None, + }) +} + +/// Attach a validity bitmap to the column variants that carry one. +fn attach_validity(col: &mut Column, bm: Bitmap, path: &str) -> R<()> { + let slot = match col { + Column::Nothing(c) => &mut c.validity, + Column::Bool(c) => &mut c.validity, + Column::Int8(c) | Column::Enum8(c) => &mut c.validity, + Column::Int16(c) | Column::Enum16(c) => &mut c.validity, + Column::Int32(c) | Column::Date32(c) | Column::Time(c) => &mut c.validity, + Column::Int64(c) | Column::DateTime64(c) | Column::Time64(c) | Column::Interval(c) => { + &mut c.validity + } + Column::UInt8(c) => &mut c.validity, + Column::UInt16(c) | Column::Date(c) => &mut c.validity, + Column::UInt32(c) | Column::DateTime(c) | Column::Ipv4(c) => &mut c.validity, + Column::UInt64(c) => &mut c.validity, + Column::Float32(c) => &mut c.validity, + Column::Float64(c) => &mut c.validity, + Column::BFloat16(c) => &mut c.validity, + Column::QBit(c) => &mut c.validity, + Column::Utf8(c) => &mut c.validity, + Column::FixedBinary(c) + | Column::Ipv6(c) + | Column::Uuid(c) + | Column::Int128(c) + | Column::UInt128(c) + | Column::Int256(c) + | Column::UInt256(c) => &mut c.validity, + Column::Decimal(c) => &mut c.validity, + Column::Dictionary(c) => &mut c.validity, + Column::Tuple(c) => &mut c.validity, + Column::Json(c) => &mut c.validity, + _ => return Err(bad(path, "this type cannot carry a validity bitmap")), + }; + *slot = Some(bm); + Ok(()) +} + +impl Input<'_> { + /// Build one core `Column` of `len` rows from a column object. + fn column(&self, obj: Option<&Value>, ty: &ChType, len: usize, path: &str) -> R { + let obj = match obj { + Some(o @ Value::Object(_)) => o, + _ => return Err(bad(path, "expected a column object")), + }; + let phys = physical(ty); + let mut col = self.build(obj, phys.as_ref(), len, path)?; + if let Some(v) = obj.get("validity") { + let bytes: Vec = self.buf_of(Some(v), "validity", path)?; + if bytes.len() < len.div_ceil(8) { + return Err(bad(path, "validity bitmap is shorter than the row count")); + } + attach_validity(&mut col, Bitmap::from_raw(bytes, len), path)?; + } + Ok(col) + } + + fn utf8(&self, obj: Option<&Value>, path: &str) -> R { + let obj = obj.ok_or_else(|| bad(path, "expected a String column object"))?; + Ok(Utf8Column::new( + self.buf(obj, "offsets", path)?, + self.buf(obj, "data", path)?, + )) + } + + fn build(&self, obj: &Value, ty: &ChType, len: usize, path: &str) -> R { + macro_rules! prim { + ($Var:ident) => { + Column::$Var(PrimitiveColumn::new(self.buf(obj, "values", path)?)) + }; + } + let fixed = |width: usize| -> R { + Ok(FixedBinaryColumn::new(self.buf(obj, "data", path)?, width)) + }; + Ok(match ty { + ChType::Nothing => Column::Nothing(NothingColumn::new(len)), + ChType::Bool => Column::Bool(BoolColumn { + bitmap: self.buf(obj, "bitmap", path)?, + len, + validity: None, + }), + ChType::Int8 => prim!(Int8), + ChType::Int16 => prim!(Int16), + ChType::Int32 => prim!(Int32), + ChType::Int64 => prim!(Int64), + ChType::UInt8 => prim!(UInt8), + ChType::UInt16 => prim!(UInt16), + ChType::UInt32 => prim!(UInt32), + ChType::UInt64 => prim!(UInt64), + ChType::Float32 => prim!(Float32), + ChType::Float64 => prim!(Float64), + ChType::BFloat16 => { + let raw: Vec = self.buf(obj, "values", path)?; + if raw.len() % 2 != 0 { + return Err(bad(path, "BFloat16 values must be 2 bytes per row")); + } + Column::BFloat16(PrimitiveColumn::new( + raw.chunks_exact(2).map(|c| [c[0], c[1]]).collect(), + )) + } + ChType::QBit { + element_type, + dimension, + } => { + let elem = parse_ch_type(&element_type.to_string()) + .ok_or_else(|| bad(path, "bad QBit element type"))?; + let n = len + .checked_mul(*dimension) + .ok_or_else(|| bad(path, "QBit size overflows"))?; + let values = self.column(obj.get("values"), &elem, n, path)?; + Column::QBit(QBitColumn::new(values, *dimension)) + } + ChType::Date => prim!(Date), + ChType::Date32 => prim!(Date32), + ChType::DateTime { .. } => prim!(DateTime), + ChType::DateTime64 { .. } => prim!(DateTime64), + ChType::Time => prim!(Time), + ChType::Time64 { .. } => prim!(Time64), + ChType::Interval(_) => prim!(Interval), + ChType::String => Column::Utf8(self.utf8(Some(obj), path)?), + ChType::FixedString(n) => Column::FixedBinary(fixed(*n)?), + ChType::Uuid => Column::Uuid(fixed(16)?), + ChType::Ipv4 => prim!(Ipv4), + ChType::Ipv6 => Column::Ipv6(fixed(16)?), + ChType::Enum8 { .. } => prim!(Enum8), + ChType::Enum16 { .. } => prim!(Enum16), + ChType::Decimal { + precision, + scale, + bits, + } => Column::Decimal(DecimalColumn::new( + self.buf(obj, "data", path)?, + *bits as usize / 8, + *precision, + *scale, + )), + ChType::Int128 => Column::Int128(fixed(16)?), + ChType::UInt128 => Column::UInt128(fixed(16)?), + ChType::Int256 => Column::Int256(fixed(32)?), + ChType::UInt256 => Column::UInt256(fixed(32)?), + ChType::LowCardinality(inner) => { + let indices = self.buf(obj, "indices", path)?; + let dict_ty = low_cardinality_dict_value_type(inner).1.clone(); + let dict = obj.get("dictionary"); + let n = dict + .and_then(|d| self.dictionary_len(d, &dict_ty)) + .ok_or_else(|| bad(path, "cannot determine dictionary size"))?; + let values = self.column(dict, &dict_ty, n, &format!("{path}.dictionary"))?; + Column::Dictionary(DictionaryColumn::new(indices, values)) + } + ChType::Array(elem) => { + let offsets = self.buf(obj, "offsets", path)?; + let n = last_offset(&offsets, path)?; + let values = self.column(obj.get("values"), elem, n, &format!("{path}[]"))?; + Column::Array(ArrayColumn::new(offsets, values)) + } + ChType::Tuple(elems) => { + let fields = array(obj, "fields", path)?; + if fields.len() != elems.len() { + return Err(bad(path, "Tuple field count does not match its type")); + } + let cols = elems + .iter() + .zip(fields) + .enumerate() + .map(|(i, ((name, t), f))| { + let p = match name { + Some(n) => format!("{path}.{n}"), + None => format!("{path}.{}", i + 1), + }; + self.column(Some(f), t, len, &p) + }) + .collect::>>()?; + Column::Tuple(TupleColumn::new(cols, len)) + } + ChType::Map(k, v) => { + let offsets = self.buf(obj, "offsets", path)?; + let n = last_offset(&offsets, path)?; + let keys = self.column(obj.get("keys"), k, n, &format!("{path}.keys"))?; + let vals = self.column(obj.get("values"), v, n, &format!("{path}.values"))?; + Column::Map(MapColumn::new( + offsets, + Column::Tuple(TupleColumn::new(vec![keys, vals], n)), + )) + } + ChType::Variant(alts) => { + let disc: Vec = self.buf(obj, "discriminators", path)?; + let js_alts = array(obj, "variants", path)?; + if js_alts.len() != alts.len() { + return Err(bad( + path, + "Variant alternative count does not match its type", + )); + } + let c = counts(&disc, 255, alts.len()); + let variants = alts + .iter() + .zip(js_alts) + .zip(c) + .map(|((t, v), n)| self.column(Some(v), t, n, &format!("{path}<{t}>"))) + .collect::>>()?; + Column::Variant( + VariantColumn::try_new(&disc, variants) + .map_err(|e| bad(path, e.to_string()))?, + ) + } + ChType::Dynamic { .. } => Column::Dynamic(self.dynamic(obj, path)?), + ChType::Json { typed_paths, .. } => { + let body = if str_field(obj, "format") == Some("structured") { + JsonColumn::structured(self.structured_json(obj, typed_paths, len, path)?) + } else { + JsonColumn::text(self.utf8(obj.get("text"), path)?) + }; + Column::Json(body) + } + ChType::AggregateFunction { .. } => Column::AggregateState(AggregateStateColumn::new( + self.buf(obj, "offsets", path)?, + self.buf(obj, "data", path)?, + )), + other => { + return Err(bad( + path, + format!("type {other} is not supported for encode"), + )) + } + }) + } + + /// Row count of a dictionary column object, read from its own buffers. + fn dictionary_len(&self, dict: &Value, ty: &ChType) -> Option { + let phys = physical(ty); + let n = |key: &str, width: usize| self.byte_len(dict, key).map(|b| b / width.max(1)); + match phys.as_ref() { + ChType::String => n("offsets", 4).map(|o| o.saturating_sub(1)), + ChType::FixedString(w) => n("data", *w), + ChType::Uuid | ChType::Ipv6 | ChType::Int128 | ChType::UInt128 => n("data", 16), + ChType::Int256 | ChType::UInt256 => n("data", 32), + ChType::Decimal { bits, .. } => n("data", *bits as usize / 8), + ChType::BFloat16 => n("values", 2), + other => primitive_width(other).and_then(|w| n("values", w)), + } + } + + fn dynamic(&self, obj: &Value, path: &str) -> R { + let type_ids: Vec = self.buf(obj, "typeIds", path)?; + let js_children = array(obj, "children", path)?; + let c = counts(&type_ids, u64::from(u32::MAX), js_children.len()); + let mut children = Vec::with_capacity(c.len()); + for (child, n) in js_children.iter().zip(c) { + if str_field(child, "kind") == Some("SharedVariant") { + children.push(DynamicChild::Shared(self.utf8(Some(child), path)?)); + } else { + let ty = type_of(child, path)?; + let p = format!("{path}<{ty}>"); + let values = self.column(Some(child), &ty, n, &p)?; + children.push(DynamicChild::Typed { + ch_type: ty, + values, + }); + } + } + DynamicColumn::try_new(&type_ids, children).map_err(|e| bad(path, e.to_string())) + } + + fn structured_json( + &self, + obj: &Value, + declared: &[(String, ChType)], + len: usize, + path: &str, + ) -> R { + let mut typed = Vec::new(); + for entry in array(obj, "typedPaths", path)? { + let p = str_field(entry, "path").unwrap_or_default(); + let ty = declared + .iter() + .find(|(d, _)| d == p) + .map(|(_, t)| t) + .ok_or_else(|| bad(path, format!("'{p}' is not a declared typed path")))?; + typed.push(( + p.to_owned(), + self.column(entry.get("column"), ty, len, &format!("{path}.{p}"))?, + )); + } + let mut dynamic_paths = Vec::new(); + for entry in array(obj, "dynamicPaths", path)? { + let p = str_field(entry, "path").unwrap_or_default(); + let sub = format!("{path}.{p}"); + let col = entry + .get("column") + .ok_or_else(|| bad(&sub, "expected a column object"))?; + dynamic_paths.push((p.to_owned(), self.dynamic(col, &sub)?)); + } + StructuredJson::try_new( + typed, + dynamic_paths, + self.buf(obj, "sharedOffsets", path)?, + self.utf8(obj.get("sharedPaths"), path)?, + self.utf8(obj.get("sharedValues"), path)?, + len, + ) + .map_err(|e| bad(path, e.to_string())) + } +} + +/// Encode one Native block for HTTP `INSERT ... FORMAT Native`. +/// +/// `block` is `{ rowCount, columns: [{ name, type, ...buffers }] }`, the shape +/// one decoded chunk has. Returns the block's bytes. Concatenate blocks for a +/// multi-block body. +pub(crate) fn encode_native(block: &Value, data: &[u8]) -> R> { + let input = Input { data }; + let rows = block + .get("rowCount") + .and_then(Value::as_usize) + .ok_or_else(|| Error::invalid("block.rowCount must be a non-negative integer"))?; + let js_cols = array(block, "columns", "block")?; + let mut fields = Vec::with_capacity(js_cols.len()); + let mut columns = Vec::with_capacity(js_cols.len()); + for (i, c) in js_cols.iter().enumerate() { + let name = str_field(c, "name") + .ok_or_else(|| Error::invalid(format!("column #{i} has no 'name'")))? + .to_owned(); + let ty = type_of(c, &name)?; + columns.push(input.column(Some(c), &ty, rows, &name)?); + fields.push(Field { name, ch_type: ty }); + } + // Not `ColBatch::new`: it debug-asserts that every column has `rows` rows, + // and this input is untrusted. `encode_block` validates that and every + // other invariant and returns an error instead. + let batch = ColBatch { + schema: Schema::new(fields), + columns, + num_rows: rows, + }; + encode_block(&batch, &EncodeOptions::default()).map_err(|e| Error::invalid(e.to_string())) +} diff --git a/crates/ch-core-wasm/src/json.rs b/crates/ch-core-wasm/src/json.rs new file mode 100644 index 0000000..c3f9701 --- /dev/null +++ b/crates/ch-core-wasm/src/json.rs @@ -0,0 +1,478 @@ +//! Minimal JSON for the descriptors that cross the C ABI. +//! +//! Results leave the module as a JSON descriptor whose buffers are references +//! into linear memory, and encode input arrives the same way. The descriptor +//! carries per-column metadata only, never per-row data, so a small hand-written +//! writer and parser are enough and keep the crate free of dependencies. + +use std::fmt::Write as _; + +// --------------------------------------------------------------------------- +// Writer +// --------------------------------------------------------------------------- + +/// Streaming JSON writer. Callers are responsible for balanced +/// `begin_*`/`end_*` calls and for writing a key before every object value. +#[derive(Default)] +pub(crate) struct Writer { + out: String, + /// True when the next key or value needs a leading comma. + comma: bool, +} + +impl Writer { + pub(crate) fn finish(self) -> String { + self.out + } + + fn sep(&mut self) { + if self.comma { + self.out.push(','); + } + } + + pub(crate) fn begin_object(&mut self) { + self.sep(); + self.out.push('{'); + self.comma = false; + } + + pub(crate) fn end_object(&mut self) { + self.out.push('}'); + self.comma = true; + } + + pub(crate) fn begin_array(&mut self) { + self.sep(); + self.out.push('['); + self.comma = false; + } + + pub(crate) fn end_array(&mut self) { + self.out.push(']'); + self.comma = true; + } + + pub(crate) fn key(&mut self, key: &str) { + self.sep(); + write_escaped(&mut self.out, key); + self.out.push(':'); + self.comma = false; + } + + pub(crate) fn string(&mut self, value: &str) { + self.sep(); + write_escaped(&mut self.out, value); + self.comma = true; + } + + /// Unsigned integer. Every value written here is a length, a count, a + /// pointer or a small type parameter, all far below 2^53, so JS reads them + /// exactly. + pub(crate) fn uint(&mut self, value: u64) { + self.sep(); + let _ = write!(self.out, "{value}"); + self.comma = true; + } + + pub(crate) fn int(&mut self, value: i64) { + self.sep(); + let _ = write!(self.out, "{value}"); + self.comma = true; + } + + pub(crate) fn bool(&mut self, value: bool) { + self.sep(); + self.out.push_str(if value { "true" } else { "false" }); + self.comma = true; + } + + pub(crate) fn null(&mut self) { + self.sep(); + self.out.push_str("null"); + self.comma = true; + } + + pub(crate) fn field_str(&mut self, key: &str, value: &str) { + self.key(key); + self.string(value); + } + + pub(crate) fn field_uint(&mut self, key: &str, value: u64) { + self.key(key); + self.uint(value); + } +} + +fn write_escaped(out: &mut String, s: &str) { + out.push('"'); + for c in s.chars() { + match c { + '"' => out.push_str("\\\""), + '\\' => out.push_str("\\\\"), + '\n' => out.push_str("\\n"), + '\r' => out.push_str("\\r"), + '\t' => out.push_str("\\t"), + c if (c as u32) < 0x20 => { + let _ = write!(out, "\\u{:04x}", c as u32); + } + c => out.push(c), + } + } + out.push('"'); +} + +// --------------------------------------------------------------------------- +// Parser +// --------------------------------------------------------------------------- + +/// Parsed JSON value. Objects keep their keys in order as a list, which is +/// enough for the few keys a column descriptor has. +#[derive(Debug, Clone, PartialEq)] +pub(crate) enum Value { + Null, + Bool(bool), + Number(f64), + String(String), + Array(Vec), + Object(Vec<(String, Value)>), +} + +impl Value { + /// Look up `key` on an object. Missing keys, `null` values and non-objects + /// all read as `None`. + pub(crate) fn get(&self, key: &str) -> Option<&Value> { + match self { + Value::Object(fields) => fields + .iter() + .find(|(k, _)| k == key) + .map(|(_, v)| v) + .filter(|v| !matches!(v, Value::Null)), + _ => None, + } + } + + pub(crate) fn as_str(&self) -> Option<&str> { + match self { + Value::String(s) => Some(s), + _ => None, + } + } + + pub(crate) fn as_array(&self) -> Option<&[Value]> { + match self { + Value::Array(items) => Some(items), + _ => None, + } + } + + /// A non-negative integer that fits in `usize`. + pub(crate) fn as_usize(&self) -> Option { + match self { + // Below 2^53 every integer is exact, so the cast loses nothing. + Value::Number(n) if *n >= 0.0 && n.fract() == 0.0 && *n < 9_007_199_254_740_992.0 => { + usize::try_from(*n as u64).ok() + } + _ => None, + } + } +} + +/// Nesting limit. Column trees are a handful of levels deep; the limit keeps +/// a hostile descriptor from exhausting the stack. +const MAX_DEPTH: usize = 128; + +/// Parse one JSON document. Trailing non-whitespace is an error. +pub(crate) fn parse(bytes: &[u8]) -> Result { + let text = std::str::from_utf8(bytes).map_err(|_| "descriptor is not valid UTF-8")?; + let mut p = Parser { + s: text.as_bytes(), + pos: 0, + }; + let v = p.value(0)?; + p.ws(); + if p.pos != p.s.len() { + return Err(p.err("trailing characters")); + } + Ok(v) +} + +struct Parser<'a> { + s: &'a [u8], + pos: usize, +} + +impl Parser<'_> { + fn err(&self, msg: &str) -> String { + format!("invalid descriptor JSON at byte {}: {msg}", self.pos) + } + + fn ws(&mut self) { + while let Some(b' ' | b'\t' | b'\n' | b'\r') = self.s.get(self.pos) { + self.pos += 1; + } + } + + fn eat(&mut self, lit: &[u8]) -> bool { + if self.s[self.pos..].starts_with(lit) { + self.pos += lit.len(); + true + } else { + false + } + } + + fn value(&mut self, depth: usize) -> Result { + if depth > MAX_DEPTH { + return Err(self.err("nesting too deep")); + } + self.ws(); + match self.s.get(self.pos) { + Some(b'{') => self.object(depth), + Some(b'[') => self.array(depth), + Some(b'"') => self.string().map(Value::String), + Some(b'-' | b'0'..=b'9') => self.number(), + Some(_) if self.eat(b"null") => Ok(Value::Null), + Some(_) if self.eat(b"true") => Ok(Value::Bool(true)), + Some(_) if self.eat(b"false") => Ok(Value::Bool(false)), + Some(_) => Err(self.err("unexpected character")), + None => Err(self.err("unexpected end")), + } + } + + fn object(&mut self, depth: usize) -> Result { + self.pos += 1; + let mut fields = Vec::new(); + self.ws(); + if self.eat(b"}") { + return Ok(Value::Object(fields)); + } + loop { + self.ws(); + if self.s.get(self.pos) != Some(&b'"') { + return Err(self.err("expected a key")); + } + let key = self.string()?; + self.ws(); + if !self.eat(b":") { + return Err(self.err("expected ':'")); + } + let value = self.value(depth + 1)?; + fields.push((key, value)); + self.ws(); + if self.eat(b",") { + continue; + } + if self.eat(b"}") { + return Ok(Value::Object(fields)); + } + return Err(self.err("expected ',' or '}'")); + } + } + + fn array(&mut self, depth: usize) -> Result { + self.pos += 1; + let mut items = Vec::new(); + self.ws(); + if self.eat(b"]") { + return Ok(Value::Array(items)); + } + loop { + items.push(self.value(depth + 1)?); + self.ws(); + if self.eat(b",") { + continue; + } + if self.eat(b"]") { + return Ok(Value::Array(items)); + } + return Err(self.err("expected ',' or ']'")); + } + } + + fn number(&mut self) -> Result { + let start = self.pos; + while let Some(b'-' | b'+' | b'.' | b'e' | b'E' | b'0'..=b'9') = self.s.get(self.pos) { + self.pos += 1; + } + // The slice is ASCII by construction, so it is valid UTF-8. + std::str::from_utf8(&self.s[start..self.pos]) + .ok() + .and_then(|t| t.parse::().ok()) + .filter(|n| n.is_finite()) + .map(Value::Number) + .ok_or_else(|| self.err("invalid number")) + } + + fn hex4(&mut self) -> Result { + let digits = self + .s + .get(self.pos..self.pos + 4) + .ok_or_else(|| self.err("truncated \\u escape"))?; + let mut v = 0u32; + for &d in digits { + let n = (d as char) + .to_digit(16) + .ok_or_else(|| self.err("invalid \\u escape"))?; + v = v * 16 + n; + } + self.pos += 4; + Ok(v) + } + + fn string(&mut self) -> Result { + self.pos += 1; + let mut out = String::new(); + loop { + let start = self.pos; + while let Some(&b) = self.s.get(self.pos) { + if b == b'"' || b == b'\\' || b < 0x20 { + break; + } + self.pos += 1; + } + // `start..pos` stops before an ASCII byte or the end, so it never + // splits a UTF-8 sequence of the already-validated input. + out.push_str(std::str::from_utf8(&self.s[start..self.pos]).unwrap_or_default()); + match self.s.get(self.pos) { + Some(b'"') => { + self.pos += 1; + return Ok(out); + } + Some(b'\\') => { + self.pos += 1; + let esc = *self + .s + .get(self.pos) + .ok_or_else(|| self.err("truncated escape"))?; + self.pos += 1; + match esc { + b'"' => out.push('"'), + b'\\' => out.push('\\'), + b'/' => out.push('/'), + b'b' => out.push('\u{8}'), + b'f' => out.push('\u{c}'), + b'n' => out.push('\n'), + b'r' => out.push('\r'), + b't' => out.push('\t'), + b'u' => { + let hi = self.hex4()?; + let code = if (0xD800..0xDC00).contains(&hi) { + if !self.eat(b"\\u") { + return Err(self.err("unpaired surrogate")); + } + let lo = self.hex4()?; + if !(0xDC00..0xE000).contains(&lo) { + return Err(self.err("unpaired surrogate")); + } + 0x10000 + ((hi - 0xD800) << 10) + (lo - 0xDC00) + } else { + hi + }; + out.push( + char::from_u32(code) + .ok_or_else(|| self.err("invalid code point"))?, + ); + } + _ => return Err(self.err("invalid escape")), + } + } + Some(_) => return Err(self.err("control character in string")), + None => return Err(self.err("unterminated string")), + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn writer_escapes_and_separates() { + let mut w = Writer::default(); + w.begin_object(); + w.field_str("name", "a\"b\\c\n\u{1}é"); + w.key("list"); + w.begin_array(); + w.uint(13); + w.int(-79); + w.bool(true); + w.null(); + w.begin_object(); + w.end_object(); + w.end_array(); + w.end_object(); + let out = w.finish(); + assert_eq!( + out, + r#"{"name":"a\"b\\c\n\u0001é","list":[13,-79,true,null,{}]}"# + ); + let parsed = parse(out.as_bytes()).unwrap(); + assert_eq!( + parsed.get("name").and_then(Value::as_str), + Some("a\"b\\c\n\u{1}é") + ); + } + + #[test] + fn parser_reads_nested_values_and_escapes() { + let v = parse( + br#" {"a": [1, 2.5, -3e2], "s": "\u00e9\ud83d\ude00\/", "n": null, "t": false} "#, + ) + .unwrap(); + assert_eq!( + v.get("a").and_then(Value::as_array).map(|a| a.len()), + Some(3) + ); + assert_eq!(v.get("s").and_then(Value::as_str), Some("é😀/")); + assert_eq!(v.get("n"), None); + assert_eq!(v.get("t"), Some(&Value::Bool(false))); + assert_eq!(v.get("missing"), None); + } + + #[test] + fn parser_rejects_malformed_input_without_panicking() { + let bad: &[&[u8]] = &[ + b"", + b"{", + b"[1,", + b"{\"a\" 1}", + b"{\"a\":1,}", + b"\"unterminated", + b"\"bad \\x escape\"", + b"\"\\ud83d\"", + b"\"\\u12\"", + b"1 2", + b"nul", + b"--1", + b"\xff", + b"\"tab\tinside\"", + ]; + for input in bad { + assert!( + parse(input).is_err(), + "{:?}", + String::from_utf8_lossy(input) + ); + } + } + + #[test] + fn parser_limits_depth() { + let deep = "[".repeat(MAX_DEPTH + 2) + &"]".repeat(MAX_DEPTH + 2); + assert!(parse(deep.as_bytes()).is_err()); + let ok = "[".repeat(MAX_DEPTH) + &"]".repeat(MAX_DEPTH); + assert!(parse(ok.as_bytes()).is_ok()); + } + + #[test] + fn as_usize_rejects_fractions_and_negatives() { + assert_eq!(Value::Number(13.0).as_usize(), Some(13)); + assert_eq!(Value::Number(-1.0).as_usize(), None); + assert_eq!(Value::Number(1.5).as_usize(), None); + assert_eq!(Value::String("13".into()).as_usize(), None); + assert_eq!(Value::Number(2f64.powi(64)).as_usize(), None); + assert_eq!(Value::Number(2f64.powi(53)).as_usize(), None); + } +} diff --git a/crates/ch-core-wasm/src/lib.rs b/crates/ch-core-wasm/src/lib.rs new file mode 100644 index 0000000..0e872f1 --- /dev/null +++ b/crates/ch-core-wasm/src/lib.rs @@ -0,0 +1,699 @@ +//! C ABI over `ch-core-rs` for WebAssembly hosts. +//! +//! This crate compiles to one `.wasm` file with a small C ABI and no runtime +//! dependencies. The hand-written JS glue in `js/` drives it from Node.js and +//! browsers, and any other WebAssembly host can call the same exports. The ABI +//! is a public contract, documented in `ABI.md`; bump [`ABI_VERSION`] for any +//! breaking change to it. +//! +//! The ABI stays columnar. It decodes Native bytes into column buffers and +//! encodes column buffers into Native bytes. Turning columns into rows or +//! host values belongs to the binding, not here. +//! +//! Memory model in short: +//! +//! - Input: the host allocates with [`chw_alloc`], writes the bytes, passes +//! `(ptr, len)`, and frees with [`chw_free`] after the call returns. Calls +//! only borrow their input. +//! - Output: calls that produce data return a result handle. Its descriptor +//! (UTF-8 JSON) and every buffer the descriptor references stay valid until +//! [`chw_result_free`]. Any call into the module may grow linear memory, so +//! the host must re-read the memory buffer after each call and must copy +//! data out before freeing the result. The JS glue copies every buffer once +//! and never hands out views into linear memory. +//! - Errors: a call that fails returns 0 (or a null pointer) and records a +//! code and message, read with [`chw_last_error_code`] and friends. + +use std::alloc::Layout; +use std::cell::RefCell; +use std::ptr::NonNull; +use std::sync::Arc; + +use ch_core_rs::batch::ColBatch; +use ch_core_rs::column::Column; +use ch_core_rs::native::binary_value::{decode_binary_value, read_binary_type_prefix}; +use ch_core_rs::native::decode::{decode_all_bytes, parse_ch_type, DecodeError, DecodeOptions}; +use ch_core_rs::native::stream_decoder::StreamDecoder; + +mod decode; +mod describe; +mod encode; +mod json; + +use decode::Describer; + +/// Version of the C ABI described in `ABI.md`. Hosts check it at load time. +pub const ABI_VERSION: u32 = 1; + +// --------------------------------------------------------------------------- +// Errors +// --------------------------------------------------------------------------- + +/// Error codes returned by [`chw_last_error_code`]. Numeric values are part +/// of the ABI. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u32)] +pub enum ErrorCode { + /// No error recorded. + None = 0, + /// The input can never succeed, however many bytes arrive: unsupported + /// type, corrupt framing, invalid layout, a bad handle, or lifecycle misuse + /// such as pushing after finish. + InvalidArg = 1, + /// An I/O-shaped failure, such as a truncated final block in + /// [`chw_stream_finish`]. + GenericFailure = 2, + /// [`chw_alloc`] could not allocate. + OutOfMemory = 3, +} + +#[derive(Debug)] +pub(crate) struct Error { + code: ErrorCode, + message: String, +} + +impl Error { + pub(crate) fn invalid(message: impl Into) -> Self { + Self { + code: ErrorCode::InvalidArg, + message: message.into(), + } + } + + pub(crate) fn generic(message: impl Into) -> Self { + Self { + code: ErrorCode::GenericFailure, + message: message.into(), + } + } +} + +impl From for Error { + fn from(e: DecodeError) -> Self { + let code = match &e { + DecodeError::Io(io) if io.kind() != std::io::ErrorKind::InvalidData => { + ErrorCode::GenericFailure + } + _ => ErrorCode::InvalidArg, + }; + Self { + code, + message: e.to_string(), + } + } +} + +// --------------------------------------------------------------------------- +// Module state +// --------------------------------------------------------------------------- + +/// A finished result: the descriptor plus everything its buffer references +/// point into. Only `json` is read after construction. The other fields own +/// the referenced buffers and exist to keep them alive until the result is +/// freed. +pub(crate) struct Output { + json: String, + #[allow(dead_code)] + batches: Vec>, + #[allow(dead_code)] + columns: Vec, + bytes: Vec>, +} + +enum Slot { + Free, + /// A stream taken out of its slot for the length of one push or finish. + Busy, + Stream(Box), + Output(Box), +} + +struct Entry { + /// Bumped each time the slot is freed, so an old handle to a reused slot + /// no longer matches. + generation: u32, + slot: Slot, +} + +#[derive(Default)] +struct State { + entries: Vec, + free: Vec, + last_error: Option, +} + +/// A handle is `generation << INDEX_BITS | (index + 1)`. The low bits are +/// never zero, so `0` stays free to mean failure. The generation makes a +/// freed handle stale even after its slot is reused, until the 12-bit counter +/// wraps after 4096 reuses of that one slot. +const INDEX_BITS: u32 = 20; +const INDEX_MASK: u32 = (1 << INDEX_BITS) - 1; +const GENERATION_MASK: u32 = u32::MAX >> INDEX_BITS; + +thread_local! { + // wasm32-unknown-unknown is single threaded, so this is one global table. + // Handles index it, which keeps a stale or forged handle from ever + // becoming a wild pointer: a bad handle is an `InvalidArg` error. + static STATE: RefCell = RefCell::default(); +} + +fn with_state(f: impl FnOnce(&mut State) -> T) -> T { + STATE.with(|s| f(&mut s.borrow_mut())) +} + +impl State { + fn insert(&mut self, slot: Slot) -> Result { + let index = match self.free.pop() { + Some(i) => { + self.entries[i].slot = slot; + i + } + None if self.entries.len() < INDEX_MASK as usize => { + self.entries.push(Entry { + generation: 0, + slot, + }); + self.entries.len() - 1 + } + None => return Err(Error::invalid("too many live handles")), + }; + Ok(self.entries[index].generation << INDEX_BITS | (index as u32 + 1)) + } + + /// The live slot `h` names, or `None` for a zero, stale or forged handle. + fn slot(&mut self, h: u32) -> Option<&mut Slot> { + let index = ((h & INDEX_MASK) as usize).checked_sub(1)?; + let entry = self.entries.get_mut(index)?; + if entry.generation != h >> INDEX_BITS || matches!(entry.slot, Slot::Free) { + return None; + } + Some(&mut entry.slot) + } + + fn remove(&mut self, h: u32) -> Option { + let taken = std::mem::replace(self.slot(h)?, Slot::Free); + let index = (h & INDEX_MASK) as usize - 1; + let entry = &mut self.entries[index]; + entry.generation = (entry.generation + 1) & GENERATION_MASK; + self.free.push(index); + Some(taken) + } + + fn output(&mut self, h: u32) -> Option<&Output> { + match self.slot(h)? { + Slot::Output(o) => Some(o), + _ => None, + } + } +} + +/// Record `e` as the last error and return the failure value. +fn fail(e: Error) -> T { + with_state(|s| s.last_error = Some(e)); + T::default() +} + +/// Store a successful output and return its handle, or record the error. +fn finish(r: Result) -> u32 { + let stored = r.and_then(|out| with_state(|s| s.insert(Slot::Output(Box::new(out))))); + match stored { + Ok(h) => { + with_state(|s| s.last_error = None); + h + } + Err(e) => fail(e), + } +} + +/// Borrow `len` bytes at `ptr` for the duration of one call. +/// +/// # Safety +/// +/// `ptr` must be valid for reads of `len` bytes for the returned lifetime, +/// which callers bound to the current ABI call, and must not alias memory the +/// module owns and may change or free during the call. In practice it is a +/// `chw_alloc` block. A zero `len` ignores `ptr`. +unsafe fn input<'a>(ptr: *const u8, len: usize) -> Result<&'a [u8], Error> { + if len == 0 { + return Ok(&[]); + } + if ptr.is_null() { + return Err(Error::invalid("null pointer with a non-zero length")); + } + // Safety: non-null, and the caller guarantees `len` readable bytes that + // stay untouched for the duration of this call (see `ABI.md`). + Ok(unsafe { std::slice::from_raw_parts(ptr, len) }) +} + +fn options() -> DecodeOptions { + // protocol_revision 0: a bare HTTP `FORMAT Native` body with no TCP framing. + DecodeOptions::default() +} + +// --------------------------------------------------------------------------- +// Version, memory, errors +// --------------------------------------------------------------------------- + +/// The C ABI version, [`ABI_VERSION`]. +#[no_mangle] +pub extern "C" fn chw_abi_version() -> u32 { + ABI_VERSION +} + +/// Alignment of every [`chw_alloc`] block, enough for any column element. +const ALLOC_ALIGN: usize = 8; + +/// Allocate `len` bytes, 8-byte aligned, for the host to write input into. +/// Returns null and records `OutOfMemory` on failure. A zero `len` returns a +/// non-null dangling pointer that must not be read or written. +#[no_mangle] +pub extern "C" fn chw_alloc(len: usize) -> *mut u8 { + if len == 0 { + return NonNull::::dangling().as_ptr().cast(); + } + let Ok(layout) = Layout::from_size_align(len, ALLOC_ALIGN) else { + return fail_null(ErrorCode::OutOfMemory, len); + }; + // Safety: `layout` has a non-zero size, checked above. + let ptr = unsafe { std::alloc::alloc(layout) }; + if ptr.is_null() { + return fail_null(ErrorCode::OutOfMemory, len); + } + ptr +} + +fn fail_null(code: ErrorCode, len: usize) -> *mut u8 { + with_state(|s| { + s.last_error = Some(Error { + code, + message: format!("could not allocate {len} bytes"), + }) + }); + std::ptr::null_mut() +} + +/// Free a block from [`chw_alloc`]. +/// +/// # Safety +/// +/// `ptr` must come from `chw_alloc(len)` with the same `len` and must not have +/// been freed already. Freeing a zero-length block is a no-op. +#[no_mangle] +pub unsafe extern "C" fn chw_free(ptr: *mut u8, len: usize) { + if len == 0 || ptr.is_null() { + return; + } + // Safety: the caller passes a pointer from `chw_alloc(len)`, which + // allocated it with exactly this layout, and has not freed it yet. + unsafe { std::alloc::dealloc(ptr, Layout::from_size_align_unchecked(len, ALLOC_ALIGN)) } +} + +/// Code of the last recorded error, `0` if none. A successful call that +/// returns a result handle clears it. +#[no_mangle] +pub extern "C" fn chw_last_error_code() -> u32 { + with_state(|s| s.last_error.as_ref().map_or(0, |e| e.code as u32)) +} + +/// Pointer to the last error's UTF-8 message. Valid until the next call that +/// records or clears an error. +#[no_mangle] +pub extern "C" fn chw_last_error_ptr() -> *const u8 { + with_state(|s| { + s.last_error + .as_ref() + .map_or(std::ptr::null(), |e| e.message.as_ptr()) + }) +} + +/// Byte length of the last error's message, `0` if none. +#[no_mangle] +pub extern "C" fn chw_last_error_len() -> usize { + with_state(|s| s.last_error.as_ref().map_or(0, |e| e.message.len())) +} + +// --------------------------------------------------------------------------- +// Results +// --------------------------------------------------------------------------- + +/// Pointer to a result's UTF-8 JSON descriptor, or null for a bad handle. +#[no_mangle] +pub extern "C" fn chw_result_json_ptr(result: u32) -> *const u8 { + with_state(|s| { + s.output(result) + .map_or(std::ptr::null(), |o| o.json.as_ptr()) + }) +} + +/// Byte length of a result's JSON descriptor, `0` for a bad handle. +#[no_mangle] +pub extern "C" fn chw_result_json_len(result: u32) -> usize { + with_state(|s| s.output(result).map_or(0, |o| o.json.len())) +} + +/// Free a result and every buffer its descriptor references. Returns 1, or +/// 0 with `InvalidArg` for a bad or already-freed handle. +#[no_mangle] +pub extern "C" fn chw_result_free(result: u32) -> u32 { + let freed = with_state(|s| match s.slot(result) { + Some(Slot::Output(_)) => s.remove(result).is_some(), + _ => false, + }); + if freed { + 1 + } else { + fail(Error::invalid(format!( + "{result} is not a live result handle" + ))) + } +} + +// --------------------------------------------------------------------------- +// Decode +// --------------------------------------------------------------------------- + +/// Decode a complete `FORMAT Native` body into a result whose descriptor is +/// `{ rowCount, columnNames, columnTypes, chunks: [{ rowCount, columns }] }`. +/// An empty body is a valid empty result with no schema. Returns 0 on error. +/// +/// # Safety +/// +/// `ptr` must be valid for reads of `len` bytes for the duration of the call. +#[no_mangle] +pub unsafe extern "C" fn chw_decode(ptr: *const u8, len: usize) -> u32 { + // Safety: forwarded caller contract. + finish(unsafe { input(ptr, len) }.and_then(decode_body)) +} + +fn decode_body(buf: &[u8]) -> Result { + let mut d = Describer::default(); + if buf.is_empty() { + // Empty SELECT over HTTP: no bytes, no schema. + d.begin_result(0, &[], &[], [])?; + d.w.end_object(); + return Ok(d.into_output(Vec::new(), Vec::new())); + } + let batch = decode_all_bytes(buf, &options())?; + let names: Vec = batch.schema.fields.iter().map(|f| f.name.clone()).collect(); + let types: Vec = batch + .schema + .fields + .iter() + .map(|f| f.ch_type.to_string()) + .collect(); + d.begin_result( + batch.num_rows(), + &names, + &types, + batch.chunks.iter().map(Arc::as_ref), + )?; + d.w.end_object(); + Ok(d.into_output(batch.chunks, Vec::new())) +} + +/// Decode one `SharedVariant` or JSON shared-data cell, a binary type +/// descriptor followed by one `serializeBinary` value, into a result whose +/// descriptor is `{ type, column }` with a one-row column. Returns 0 on error. +/// +/// # Safety +/// +/// `ptr` must be valid for reads of `len` bytes for the duration of the call. +#[no_mangle] +pub unsafe extern "C" fn chw_decode_binary_value(ptr: *const u8, len: usize) -> u32 { + // Safety: forwarded caller contract. + finish(unsafe { input(ptr, len) }.and_then(|bytes| { + let (ty, used) = + read_binary_type_prefix(bytes).map_err(|e| Error::invalid(e.to_string()))?; + let col = + decode_binary_value(&ty, &bytes[used..]).map_err(|e| Error::invalid(e.to_string()))?; + let mut d = Describer::default(); + d.w.begin_object(); + d.w.field_str("type", &ty.to_string()); + d.w.key("column"); + d.column(&col, Some(&ty), None)?; + d.w.end_object(); + Ok(d.into_output(Vec::new(), vec![col])) + })) +} + +/// Parse a ClickHouse type string with the core's parser. The result's +/// descriptor is `{ type, kind, nullable, ...metadata, ...children }`. +/// Returns 0 on error. +/// +/// # Safety +/// +/// `ptr` must be valid for reads of `len` bytes for the duration of the call. +#[no_mangle] +pub unsafe extern "C" fn chw_describe_type(ptr: *const u8, len: usize) -> u32 { + // Safety: forwarded caller contract. + finish(unsafe { input(ptr, len) }.and_then(|bytes| { + let name = + std::str::from_utf8(bytes).map_err(|_| Error::invalid("type is not valid UTF-8"))?; + let ty = parse_ch_type(name) + .ok_or_else(|| Error::invalid(format!("cannot parse type '{name}'")))?; + let mut d = Describer::default(); + describe::describe(&mut d, &ty); + Ok(d.into_output(Vec::new(), Vec::new())) + })) +} + +// --------------------------------------------------------------------------- +// Streaming decode +// --------------------------------------------------------------------------- + +/// Incremental decoder state behind a stream handle. +struct Stream { + decoder: StreamDecoder, + column_names: Option>, + column_types: Option>, + /// `u64` so a long export cannot wrap a 32-bit `usize` on wasm32. + row_count: u64, + finished: bool, + errored: bool, +} + +impl Stream { + fn check_usable(&self) -> Result<(), Error> { + if self.errored { + return Err(Error::invalid( + "decoder failed previously; create a new stream", + )); + } + Ok(()) + } + + /// Run one decode step. Any failure in it poisons the stream: the decoder + /// may have consumed bytes, or handed over blocks that are then lost, so + /// continuing would silently drop rows. Lifecycle misuse is checked before + /// this and leaves the stream as it was. + fn poison_on_error( + &mut self, + step: impl FnOnce(&mut Self) -> Result, + ) -> Result { + let r = step(self); + if r.is_err() { + self.errored = true; + } + r + } + + /// Describe newly completed blocks. Zero-row blocks contribute the schema + /// but are omitted from `chunks`. + fn emit(&mut self, batches: Vec) -> Result { + if self.column_names.is_none() { + if let Some(first) = batches.first() { + let f = &first.schema.fields; + self.column_names = Some(f.iter().map(|f| f.name.clone()).collect()); + self.column_types = Some(f.iter().map(|f| f.ch_type.to_string()).collect()); + } + } + let batches: Vec> = batches + .into_iter() + .filter(|b| b.num_rows > 0) + .map(Arc::new) + .collect(); + let rows: usize = batches.iter().map(|b| b.num_rows).sum(); + let mut d = Describer::default(); + d.begin_result( + rows, + self.column_names.as_deref().unwrap_or(&[]), + self.column_types.as_deref().unwrap_or(&[]), + batches.iter().map(Arc::as_ref), + )?; + d.w.field_uint("bufferedBytes", self.decoder.buffered_bytes() as u64); + d.w.end_object(); + self.row_count = self.row_count.saturating_add(rows as u64); + Ok(d.into_output(batches, Vec::new())) + } +} + +/// Create a streaming decoder for an HTTP `FORMAT Native` response body. +/// Free it with [`chw_stream_free`]. +#[no_mangle] +pub extern "C" fn chw_stream_new() -> u32 { + let stream = Stream { + decoder: StreamDecoder::new(options()), + column_names: None, + column_types: None, + row_count: 0, + finished: false, + errored: false, + }; + match with_state(|s| s.insert(Slot::Stream(Box::new(stream)))) { + Ok(h) => h, + Err(e) => fail(e), + } +} + +/// Run `f` on a live stream, then store its output. +fn with_stream(h: u32, f: impl FnOnce(&mut Stream) -> Result) -> u32 { + // The stream is taken out of the table while `f` runs so storing the + // output does not need a second borrow of the table. + let Some(Slot::Stream(mut stream)) = with_state(|s| match s.slot(h) { + Some(slot @ Slot::Stream(_)) => Some(std::mem::replace(slot, Slot::Busy)), + _ => None, + }) else { + return fail(Error::invalid(format!("{h} is not a live stream handle"))); + }; + let r = f(&mut stream); + with_state(|s| { + if let Some(slot) = s.slot(h) { + *slot = Slot::Stream(stream); + } + }); + finish(r) +} + +/// Append bytes to a stream. The result describes every block that is now +/// complete, plus `bufferedBytes`. After any error the stream is poisoned and +/// every later push or finish fails. Returns 0 on error. +/// +/// # Safety +/// +/// `ptr` must be valid for reads of `len` bytes for the duration of the call. +#[no_mangle] +pub unsafe extern "C" fn chw_stream_push(stream: u32, ptr: *const u8, len: usize) -> u32 { + // Safety: forwarded caller contract. + let bytes = match unsafe { input(ptr, len) } { + Ok(b) => b, + Err(e) => return fail(e), + }; + with_stream(stream, |s| { + s.check_usable()?; + if s.finished { + return Err(Error::invalid("cannot push after finish")); + } + s.poison_on_error(|s| { + let batches = s.decoder.feed(bytes)?; + s.emit(batches) + }) + }) +} + +/// Drain the stream's tail. Fails on a truncated final block. Can be called +/// once. Returns 0 on error. +#[no_mangle] +pub extern "C" fn chw_stream_finish(stream: u32) -> u32 { + with_stream(stream, |s| { + s.check_usable()?; + if s.finished { + return Err(Error::invalid("finish called more than once")); + } + s.finished = true; + // A zero-byte body is a legitimate empty result: ClickHouse's HTTP + // interface writes no header block for a SELECT that returns no rows, + // so the schema stays unknown. + s.poison_on_error(|s| { + let batches = s.decoder.finish()?; + s.emit(batches) + }) + }) +} + +/// Read a field of a live stream. A bad handle returns 0 and records +/// `InvalidArg`. Success clears the last error, so a 0 result can be told +/// apart from a failure by [`chw_last_error_code`]. +fn stream_field(h: u32, f: impl FnOnce(&Stream) -> T) -> T { + let value = with_state(|s| { + let value = match s.slot(h) { + Some(Slot::Stream(st)) => Some(f(st)), + _ => None, + }; + if value.is_some() { + s.last_error = None; + } + value + }); + value.unwrap_or_else(|| fail(Error::invalid(format!("{h} is not a live stream handle")))) +} + +/// Rows emitted by the stream so far, as a `u64`, which can pass `u32::MAX` +/// on a long export. +#[no_mangle] +pub extern "C" fn chw_stream_row_count(stream: u32) -> u64 { + stream_field(stream, |st| st.row_count) +} + +/// Bytes the stream holds for an incomplete block. +#[no_mangle] +pub extern "C" fn chw_stream_buffered_bytes(stream: u32) -> usize { + stream_field(stream, |st| st.decoder.buffered_bytes()) +} + +/// Free a stream. Returns 1, or 0 with `InvalidArg` for a bad handle. +#[no_mangle] +pub extern "C" fn chw_stream_free(stream: u32) -> u32 { + let freed = with_state(|s| match s.slot(stream) { + Some(Slot::Stream(_)) => s.remove(stream).is_some(), + _ => false, + }); + if freed { + 1 + } else { + fail(Error::invalid(format!( + "{stream} is not a live stream handle" + ))) + } +} + +// --------------------------------------------------------------------------- +// Encode +// --------------------------------------------------------------------------- + +/// Encode one Native block for `INSERT ... FORMAT Native`. +/// +/// `desc` is the UTF-8 JSON block descriptor `{ rowCount, columns }`, in the +/// shape of one decoded chunk, whose buffers are `{"$b":[offset,byteLength]}` +/// ranges of `data`. The result's descriptor is `{ bytes }`, a reference to +/// the encoded block. Returns 0 on error. +/// +/// # Safety +/// +/// `desc_ptr` and `data_ptr` must be valid for reads of `desc_len` and +/// `data_len` bytes for the duration of the call. +#[no_mangle] +pub unsafe extern "C" fn chw_encode( + desc_ptr: *const u8, + desc_len: usize, + data_ptr: *const u8, + data_len: usize, +) -> u32 { + // Safety: forwarded caller contract. + let inputs = + unsafe { input(desc_ptr, desc_len).and_then(|d| Ok((d, input(data_ptr, data_len)?))) }; + finish(inputs.and_then(|(desc, data)| { + let block = json::parse(desc).map_err(Error::invalid)?; + let bytes = encode::encode_native(&block, data)?; + let mut d = Describer::default(); + d.w.begin_object(); + d.buf("bytes", &bytes); + d.w.end_object(); + let mut out = d.into_output(Vec::new(), Vec::new()); + out.bytes.push(bytes); + Ok(out) + })) +} + +#[cfg(test)] +mod tests; diff --git a/crates/ch-core-wasm/src/tests.rs b/crates/ch-core-wasm/src/tests.rs new file mode 100644 index 0000000..75bf759 --- /dev/null +++ b/crates/ch-core-wasm/src/tests.rs @@ -0,0 +1,428 @@ +//! Native tests of the C ABI. They call the exported functions directly on the +//! host target and act as the host would: read the descriptor, copy every +//! referenced buffer out, then free the result. + +use super::*; +use crate::json::{self, Value, Writer}; + +const ALL_TYPES: &[u8] = include_bytes!("../../../tests/fixtures/all_types_rev0.native"); +const MULTI_BLOCK: &[u8] = include_bytes!("../../../tests/fixtures/multi_block_rev0.native"); +/// Captured with the server's flattened Dynamic/JSON serialization, which +/// the core decodes but does not write, so it cannot re-encode identically. +const JSON_FLATTENED: &[u8] = include_bytes!("../../../tests/fixtures/json_flattened_rev0.native"); + +/// Rev-0 fixtures in the server's default serialization. +const REV0_FIXTURES: &[(&str, &[u8])] = &[ + ("all_types", ALL_TYPES), + ("multi_block", MULTI_BLOCK), + ( + "json_mixed_rows", + include_bytes!("../../../tests/fixtures/json_mixed_rows_rev0.native"), + ), + ( + "json_multipart", + include_bytes!("../../../tests/fixtures/json_multipart_rev0.native"), + ), + ( + "json_shared", + include_bytes!("../../../tests/fixtures/json_shared_rev0.native"), + ), + ( + "json_string", + include_bytes!("../../../tests/fixtures/json_string_rev0.native"), + ), + ( + "zero_width_dynamic", + include_bytes!("../../../tests/fixtures/zero_width_dynamic_rev0.native"), + ), +]; + +fn last_error() -> (u32, String) { + let code = chw_last_error_code(); + let len = chw_last_error_len(); + let msg = if len == 0 { + String::new() + } else { + // Safety: the module reports `len` readable bytes at this pointer, + // valid until the next call that records or clears an error. + let bytes = unsafe { std::slice::from_raw_parts(chw_last_error_ptr(), len) }; + String::from_utf8(bytes.to_vec()).unwrap() + }; + (code, msg) +} + +/// Read a result's descriptor, resolve every `{"$b":[ptr,len,dtype]}` into +/// an owned copy of the bytes, and free the result. +fn take(result: u32) -> Value { + assert_ne!(result, 0, "call failed: {:?}", last_error()); + let len = chw_result_json_len(result); + // Safety: the result is live and reports `len` bytes of descriptor. + let raw = unsafe { std::slice::from_raw_parts(chw_result_json_ptr(result), len) }; + let mut v = json::parse(raw).unwrap(); + copy_out(&mut v); + assert_eq!(chw_result_free(result), 1); + v +} + +/// Owned copy of a buffer, standing in for a JS TypedArray. +fn bytes_value(bytes: Vec) -> Value { + Value::Object(vec![( + "$bytes".into(), + Value::Array(bytes.into_iter().map(|b| Value::Number(b.into())).collect()), + )]) +} + +fn copy_out(v: &mut Value) { + if let Some([ptr, len, _dtype]) = v.get("$b").and_then(Value::as_array) { + let (ptr, len) = (ptr.as_usize().unwrap(), len.as_usize().unwrap()); + let bytes = if len == 0 { + Vec::new() + } else { + // Safety: the result that owns this buffer is still live; `take` + // frees it only after every reference has been copied out. + unsafe { std::slice::from_raw_parts(ptr as *const u8, len) }.to_vec() + }; + *v = bytes_value(bytes); + return; + } + match v { + Value::Array(items) => items.iter_mut().for_each(copy_out), + Value::Object(fields) => fields.iter_mut().for_each(|(_, f)| copy_out(f)), + _ => {} + } +} + +fn owned_bytes(v: &Value) -> Option> { + let items = v.get("$bytes")?.as_array()?; + Some(items.iter().map(|b| b.as_usize().unwrap() as u8).collect()) +} + +/// Serialize a column tree for `chw_encode`, packing every copied buffer into +/// one data blob at 8-byte aligned offsets, as the JS glue does. +fn write_value(w: &mut Writer, v: &Value, data: &mut Vec) { + if let Some(bytes) = owned_bytes(v) { + let off = data.len().next_multiple_of(8); + data.resize(off, 0); + data.extend_from_slice(&bytes); + w.begin_object(); + w.key("$b"); + w.begin_array(); + w.uint(off as u64); + w.uint(bytes.len() as u64); + w.end_array(); + w.end_object(); + return; + } + match v { + Value::Null => w.null(), + Value::Bool(b) => w.bool(*b), + Value::Number(n) => w.int(*n as i64), + Value::String(s) => w.string(s), + Value::Array(items) => { + w.begin_array(); + for i in items { + write_value(w, i, data); + } + w.end_array(); + } + Value::Object(fields) => { + w.begin_object(); + for (k, f) in fields { + w.key(k); + write_value(w, f, data); + } + w.end_object(); + } + } +} + +fn call_encode(block: &Value) -> Result, (u32, String)> { + let mut w = Writer::default(); + let mut data = Vec::new(); + write_value(&mut w, block, &mut data); + let desc = w.finish(); + // Safety: both slices outlive the call. + let h = unsafe { chw_encode(desc.as_ptr(), desc.len(), data.as_ptr(), data.len()) }; + if h == 0 { + return Err(last_error()); + } + Ok(owned_bytes(take(h).get("bytes").unwrap()).unwrap()) +} + +fn decode(bytes: &[u8]) -> Value { + // Safety: `bytes` outlives the call. + take(unsafe { chw_decode(bytes.as_ptr(), bytes.len()) }) +} + +#[test] +fn abi_version_is_exported() { + assert_eq!(chw_abi_version(), ABI_VERSION); +} + +#[test] +fn every_rev0_fixture_reencodes_byte_identically() { + for (name, bytes) in REV0_FIXTURES { + let decoded = decode(bytes); + let mut again = Vec::new(); + for chunk in decoded.get("chunks").and_then(Value::as_array).unwrap() { + again.extend(call_encode(chunk).unwrap_or_else(|e| panic!("{name}: {e:?}"))); + } + assert!(again == *bytes, "{name}: re-encoded bytes differ"); + } +} + +#[test] +fn flattened_json_decodes_and_reencodes_or_errors_cleanly() { + let decoded = decode(JSON_FLATTENED); + let chunks = decoded.get("chunks").and_then(Value::as_array).unwrap(); + for chunk in chunks { + let kind = chunk.get("columns").and_then(Value::as_array).unwrap()[0].get("kind"); + assert_eq!(kind.and_then(Value::as_str), Some("JSON")); + match call_encode(chunk) { + // Re-encoded in the default shape, which decodes to the same rows. + Ok(bytes) => assert_eq!(decode(&bytes).get("rowCount"), chunk.get("rowCount")), + // The flattened shape can carry more dynamic paths than the + // declared limit allows in the default shape. The encoder rejects + // that with an error, not a panic. + Err((code, _)) => assert_eq!(code, ErrorCode::InvalidArg as u32), + } + } +} + +#[test] +fn decode_reports_schema_and_chunks() { + let v = decode(MULTI_BLOCK); + let chunks = v.get("chunks").and_then(Value::as_array).unwrap(); + assert!(chunks.len() > 1, "fixture has several blocks"); + let rows: usize = chunks + .iter() + .map(|c| c.get("rowCount").and_then(Value::as_usize).unwrap()) + .sum(); + assert_eq!(v.get("rowCount").and_then(Value::as_usize), Some(rows)); + let names = v.get("columnNames").and_then(Value::as_array).unwrap(); + let types = v.get("columnTypes").and_then(Value::as_array).unwrap(); + assert_eq!(names.len(), types.len()); + let first = &chunks[0].get("columns").and_then(Value::as_array).unwrap()[0]; + assert_eq!(first.get("name"), Some(&names[0])); + assert_eq!(first.get("type"), Some(&types[0])); +} + +#[test] +fn empty_body_is_an_empty_result() { + let v = decode(&[]); + assert_eq!(v.get("rowCount").and_then(Value::as_usize), Some(0)); + assert_eq!(v.get("chunks").and_then(Value::as_array), Some(&[][..])); +} + +#[test] +fn garbage_input_records_an_error_and_the_module_keeps_working() { + let garbage = [1u8, 1, 1, b'x', 3, b'F', b'o', b'o']; + // Safety: `garbage` outlives the call. + let h = unsafe { chw_decode(garbage.as_ptr(), garbage.len()) }; + assert_eq!(h, 0); + let (code, msg) = last_error(); + assert_eq!(code, ErrorCode::InvalidArg as u32); + assert!(!msg.is_empty()); + decode(ALL_TYPES); + assert_eq!(chw_last_error_code(), 0, "success clears the error"); +} + +#[test] +fn stream_matches_buffered_decode_at_every_split() { + let whole = decode(MULTI_BLOCK); + for split in [1, 7, MULTI_BLOCK.len() / 2] { + let s = chw_stream_new(); + let mut chunks = Vec::new(); + for piece in MULTI_BLOCK.chunks(split) { + // Safety: `piece` outlives the call. + let out = take(unsafe { chw_stream_push(s, piece.as_ptr(), piece.len()) }); + chunks.extend( + out.get("chunks") + .and_then(Value::as_array) + .unwrap() + .to_vec(), + ); + } + let out = take(chw_stream_finish(s)); + chunks.extend( + out.get("chunks") + .and_then(Value::as_array) + .unwrap() + .to_vec(), + ); + assert_eq!( + chunks, + whole.get("chunks").and_then(Value::as_array).unwrap() + ); + assert_eq!( + chw_stream_row_count(s), + whole.get("rowCount").and_then(Value::as_usize).unwrap() as u64 + ); + assert_eq!(chw_stream_free(s), 1); + } +} + +#[test] +fn stream_lifecycle_errors() { + // One column `x UInt8`, one row with value 7. + let block = [1u8, 1, 1, b'x', 5, b'U', b'I', b'n', b't', b'8', 7]; + let s = chw_stream_new(); + // Safety: `block` outlives the call. + take(unsafe { chw_stream_push(s, block.as_ptr(), block.len()) }); + take(chw_stream_finish(s)); + // Safety: `block` outlives the call. + assert_eq!( + unsafe { chw_stream_push(s, block.as_ptr(), block.len()) }, + 0 + ); + assert!(last_error().1.contains("after finish")); + assert_eq!(chw_stream_finish(s), 0); + assert!(last_error().1.contains("more than once")); + assert_eq!(chw_stream_free(s), 1); + assert_eq!(chw_stream_free(s), 0, "double free is an error, not UB"); + assert_eq!(chw_stream_finish(s), 0); +} + +#[test] +fn truncated_stream_fails_in_finish_and_poisons() { + let s = chw_stream_new(); + let part = &MULTI_BLOCK[..MULTI_BLOCK.len() - 3]; + // Safety: `part` outlives the call. + take(unsafe { chw_stream_push(s, part.as_ptr(), part.len()) }); + assert_eq!(chw_stream_finish(s), 0); + assert_eq!(last_error().0, ErrorCode::GenericFailure as u32); + // Safety: `part` outlives the call. + assert_eq!(unsafe { chw_stream_push(s, part.as_ptr(), part.len()) }, 0); + assert!(last_error().1.contains("create a new stream")); + chw_stream_free(s); +} + +#[test] +fn handles_are_checked() { + assert_eq!(chw_result_free(0), 0); + assert_eq!(chw_result_free(u32::MAX), 0); + assert_eq!(chw_result_json_len(u32::MAX), 0); + let s = chw_stream_new(); + assert_eq!(chw_result_free(s), 0, "a stream is not a result"); + assert_eq!(chw_stream_free(s), 1); + // Safety: `MULTI_BLOCK` outlives the call. + let r = unsafe { chw_decode(MULTI_BLOCK.as_ptr(), MULTI_BLOCK.len()) }; + assert_eq!(chw_stream_free(r), 0, "a result is not a stream"); + assert_eq!(chw_result_free(r), 1); +} + +#[test] +fn alloc_and_free_round_trip() { + let p = chw_alloc(13); + assert!(!p.is_null()); + assert_eq!(p as usize % ALLOC_ALIGN, 0); + // Safety: `p` is a fresh 13-byte block from `chw_alloc(13)`. + unsafe { + p.write_bytes(79, 13); + chw_free(p, 13); + } + let empty = chw_alloc(0); + assert!(!empty.is_null()); + // Safety: freeing a zero-length block is a documented no-op. + unsafe { chw_free(empty, 0) }; +} + +#[test] +fn describe_type_resolves_aliases_and_metadata() { + let name = "Array(Nullable(DateTime64(3, 'UTC')))"; + // Safety: `name` outlives the call. + let v = take(unsafe { chw_describe_type(name.as_ptr(), name.len()) }); + assert_eq!(v.get("kind").and_then(Value::as_str), Some("Array")); + let elem = v.get("element").unwrap(); + assert_eq!(elem.get("kind").and_then(Value::as_str), Some("DateTime64")); + assert_eq!(elem.get("nullable"), Some(&Value::Bool(true))); + assert_eq!(elem.get("precision").and_then(Value::as_usize), Some(3)); + assert_eq!(elem.get("timezone").and_then(Value::as_str), Some("UTC")); + + let bad = "NotAType("; + // Safety: `bad` outlives the call. + assert_eq!(unsafe { chw_describe_type(bad.as_ptr(), bad.len()) }, 0); + assert_eq!(last_error().0, ErrorCode::InvalidArg as u32); +} + +#[test] +fn encode_rejects_bad_descriptors_without_panicking() { + let cases: &[(&str, &[u8])] = &[ + ("not json", b""), + ("{", b""), + (r#"{"rowCount":-1,"columns":[]}"#, b""), + (r#"{"rowCount":1,"columns":[{"type":"UInt8"}]}"#, b""), + ( + r#"{"rowCount":1,"columns":[{"name":"x","type":"UInt8","values":{"$b":[0,8]}}]}"#, + &[7], + ), + ( + r#"{"rowCount":1,"columns":[{"name":"x","type":"UInt16","values":{"$b":[0,3]}}]}"#, + &[1, 2, 3], + ), + ( + r#"{"rowCount":1,"columns":[{"name":"x","type":"UInt8","values":{"$b":[18446744073709551615,1]}}]}"#, + &[7], + ), + ( + r#"{"rowCount":2,"columns":[{"name":"x","type":"UInt8","values":{"$b":[0,1]}}]}"#, + &[7], + ), + ( + r#"{"rowCount":1,"columns":[{"name":"x","type":"Array(UInt8)","offsets":{"$b":[0,8]},"values":{"$b":[0,0]}}]}"#, + &[0xff; 8], + ), + ]; + for (desc, data) in cases { + // Safety: both slices outlive the call. + let h = unsafe { chw_encode(desc.as_ptr(), desc.len(), data.as_ptr(), data.len()) }; + assert_eq!(h, 0, "{desc}"); + assert_eq!(last_error().0, ErrorCode::InvalidArg as u32, "{desc}"); + } +} + +#[test] +fn encode_one_column_block() { + let desc = r#"{"rowCount":1,"columns":[{"name":"x","type":"UInt8","values":{"$b":[0,1]}}]}"#; + // Safety: both slices outlive the call. + let h = unsafe { chw_encode(desc.as_ptr(), desc.len(), [7u8].as_ptr(), 1) }; + let bytes = owned_bytes(take(h).get("bytes").unwrap()).unwrap(); + assert_eq!(bytes, [1, 1, 1, b'x', 5, b'U', b'I', b'n', b't', b'8', 7]); +} + +#[test] +fn a_freed_handle_stays_stale_after_its_slot_is_reused() { + // Safety: `MULTI_BLOCK` outlives both calls. + let first = unsafe { chw_decode(MULTI_BLOCK.as_ptr(), MULTI_BLOCK.len()) }; + assert_eq!(chw_result_free(first), 1); + // Safety: as above. + let second = unsafe { chw_decode(MULTI_BLOCK.as_ptr(), MULTI_BLOCK.len()) }; + assert_eq!( + first & INDEX_MASK, + second & INDEX_MASK, + "the slot was reused" + ); + assert_ne!(first, second); + assert_eq!( + chw_result_free(first), + 0, + "the old handle does not free the new result" + ); + assert_eq!(chw_result_json_len(first), 0); + assert!(chw_result_json_len(second) > 0); + take(second); +} + +#[test] +fn stream_lookups_report_bad_handles() { + assert_eq!(chw_stream_row_count(0), 0); + assert_eq!(chw_last_error_code(), ErrorCode::InvalidArg as u32); + let s = chw_stream_new(); + assert_eq!(chw_stream_buffered_bytes(s), 0); + assert_eq!( + chw_last_error_code(), + 0, + "a successful lookup clears the error" + ); + chw_stream_free(s); +} diff --git a/crates/ch-core-wasm/test/glue.test.mjs b/crates/ch-core-wasm/test/glue.test.mjs new file mode 100644 index 0000000..9d5188f --- /dev/null +++ b/crates/ch-core-wasm/test/glue.test.mjs @@ -0,0 +1,201 @@ +// End-to-end tests of the JS glue over the real .wasm, against committed +// server fixtures. Run `npm run build` first. No ClickHouse server needed. +import { test } from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { bindExports, ABI_VERSION } from '../js/core.mjs' +import { + decodeNativeColumns, + describeType, + encodeNative, + NativeStreamDecoder, + CodecError, +} from '../js/node.mjs' + +const fixture = (name) => new Uint8Array(readFileSync(new URL(`../../../tests/fixtures/${name}`, import.meta.url))) +const ALL_TYPES = fixture('all_types_rev0.native') +const MULTI_BLOCK = fixture('multi_block_rev0.native') +// Rev-0 fixtures in the server's default serialization. json_flattened is +// left out: the core decodes that shape but does not write it. +const REV0 = [ + 'all_types_rev0.native', + 'multi_block_rev0.native', + 'json_mixed_rows_rev0.native', + 'json_multipart_rev0.native', + 'json_shared_rev0.native', + 'json_string_rev0.native', + 'zero_width_dynamic_rev0.native', +] + +const concat = (parts) => { + const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)) + let o = 0 + for (const p of parts) { + out.set(p, o) + o += p.length + } + return out +} + +/** Every TypedArray reachable from `v`. */ +function* typedArrays(v) { + if (ArrayBuffer.isView(v)) yield v + else if (Array.isArray(v)) for (const i of v) yield* typedArrays(i) + else if (v && typeof v === 'object') for (const i of Object.values(v)) yield* typedArrays(i) +} + +function instance() { + const bytes = readFileSync(new URL('../dist/ch_core_wasm.wasm', import.meta.url)) + const { exports } = new WebAssembly.Instance(new WebAssembly.Module(bytes), {}) + return { exports, api: bindExports(exports) } +} + +test('the .wasm speaks the ABI version the glue expects', () => { + const { exports } = instance() + assert.equal(exports.chw_abi_version(), ABI_VERSION) + assert.throws(() => bindExports({ ...exports, chw_abi_version: () => ABI_VERSION + 1 }), /ABI/) +}) + +for (const name of REV0) { + test(`decode -> encode is byte-identical: ${name}`, () => { + const bytes = fixture(name) + const decoded = decodeNativeColumns(bytes) + assert.ok(decoded.chunks.length > 0) + assert.deepEqual(concat(decoded.chunks.map(encodeNative)), bytes) + }) +} + +test('results are JS-owned copies that survive memory growth', () => { + const { exports, api } = instance() + const decoded = api.decodeNativeColumns(ALL_TYPES) + const arrays = [...typedArrays(decoded)] + assert.ok(arrays.length > 100) + const before = arrays.map((a) => Buffer.from(a.buffer, a.byteOffset, a.byteLength).toString('hex')) + for (const a of arrays) assert.notEqual(a.buffer, exports.memory.buffer, 'no views into wasm memory') + + // Force memory.grow(), which detaches the old ArrayBuffer, then reuse the + // freed memory by decoding again. + const old = exports.memory.buffer + const big = 64 * 1024 * 1024 + const p = exports.chw_alloc(big) >>> 0 + assert.notEqual(p, 0) + exports.chw_free(p, big) + assert.equal(old.byteLength, 0, 'growth detached the old buffer') + api.decodeNativeColumns(ALL_TYPES) + + const after = arrays.map((a) => Buffer.from(a.buffer, a.byteOffset, a.byteLength).toString('hex')) + assert.deepEqual(after, before) + assert.deepEqual(concat(decoded.chunks.map(api.encodeNative)), ALL_TYPES) +}) + +test('typed buffers use the matching TypedArray per kind', () => { + const cols = Object.fromEntries(decodeNativeColumns(ALL_TYPES).chunks[0].columns.map((c) => [c.name, c])) + const byKind = {} + for (const c of Object.values(cols)) byKind[c.kind] ??= c + assert.ok(byKind.Int64.values instanceof BigInt64Array) + assert.ok(byKind.UInt64.values instanceof BigUint64Array) + assert.ok(byKind.Float64.values instanceof Float64Array) + assert.ok(byKind.String.offsets instanceof Int32Array) + assert.ok(byKind.String.data instanceof Uint8Array) + assert.ok(byKind.Array.offsets instanceof BigInt64Array) +}) + +test('streaming matches the buffered decode at any split', () => { + const whole = decodeNativeColumns(MULTI_BLOCK) + for (const step of [1, 7, MULTI_BLOCK.length]) { + const d = new NativeStreamDecoder() + const chunks = [] + for (let i = 0; i < MULTI_BLOCK.length; i += step) { + chunks.push(...d.push(MULTI_BLOCK.subarray(i, i + step)).chunks) + } + const last = d.finish() + chunks.push(...last.chunks) + assert.deepEqual(chunks, whole.chunks) + assert.deepEqual(last.columnNames, whole.columnNames) + assert.equal(d.rowCount, whole.rowCount) + assert.equal(d.bufferedBytes, 0) + d.free() + d.free() + assert.throws(() => d.push(MULTI_BLOCK), /freed/) + } +}) + +test('empty body is an empty result', () => { + const r = decodeNativeColumns(new Uint8Array()) + assert.deepEqual(r, { rowCount: 0, columnNames: [], columnTypes: [], chunks: [] }) + const d = new NativeStreamDecoder() + assert.equal(d.push(new Uint8Array()).rowCount, 0) + assert.deepEqual(d.finish().chunks, []) + d.free() +}) + +test('errors carry codes and the module keeps working', () => { + assert.throws( + () => decodeNativeColumns(new Uint8Array([1, 1, 1, 120, 3, 70, 111, 111])), + (e) => e instanceof CodecError && e.code === 'InvalidArg', + ) + const d = new NativeStreamDecoder() + d.push(MULTI_BLOCK.subarray(0, MULTI_BLOCK.length - 3)) + assert.throws(() => d.finish(), { code: 'GenericFailure' }) + assert.throws(() => d.push(MULTI_BLOCK), /create a new stream/) + d.free() + + const once = new NativeStreamDecoder() + once.push(new Uint8Array([1, 1, 1, 120, 5, 85, 73, 110, 116, 56, 7])) // x UInt8 = 7 + once.finish() + assert.throws(() => once.push(new Uint8Array([0])), /after finish/) + assert.throws(() => once.finish(), /more than once/) + once.free() + + assert.throws(() => encodeNative({ rowCount: 2, columns: [{ name: 'x', type: 'UInt8', values: new Uint8Array([7]) }] }), { + code: 'InvalidArg', + }) + assert.equal(decodeNativeColumns(ALL_TYPES).chunks[0].columns.length, 116) +}) + +test('zero-width rows past the 32-bit address space fail instead of wrapping', () => { + // On wasm32 the encoder's output size once wrapped here, returning a + // truncated block. Native tests cannot see this: they run on 64 bits. + for (const type of ['Nothing', 'Tuple()']) { + const column = type === 'Nothing' ? { name: 'z', type } : { name: 'z', type, fields: [] } + assert.throws(() => encodeNative({ rowCount: 2 ** 32 - 1, columns: [column] }), { code: 'InvalidArg' }) + } + const arr = { name: 'a', type: 'Array(Nothing)', offsets: new BigInt64Array([0n, 3_000_000_000n]), values: {} } + assert.throws(() => encodeNative({ rowCount: 1, columns: [arr] }), { code: 'InvalidArg' }) + assert.equal(decodeNativeColumns(ALL_TYPES).chunks[0].columns.length, 116, 'module still works') +}) + +test('encode accepts Node Buffers like any other TypedArray', () => { + const bytes = encodeNative({ rowCount: 2, columns: [{ name: 'x', type: 'UInt8', values: Buffer.from([13, 79]) }] }) + assert.deepEqual(decodeNativeColumns(bytes).chunks[0].columns[0].values, new Uint8Array([13, 79])) +}) + +test('encode takes plain TypedArrays', () => { + const bytes = encodeNative({ + rowCount: 2, + columns: [ + { name: 'id', type: 'UInt64', values: new BigUint64Array([13n, 79n]) }, + { + name: 'user', + type: 'Nullable(String)', + offsets: new Int32Array([0, 6, 6]), + data: new TextEncoder().encode('user_1'), + validity: new Uint8Array([0b01]), + }, + ], + }) + const [chunk] = decodeNativeColumns(bytes).chunks + assert.deepEqual(chunk.columns[0].values, new BigUint64Array([13n, 79n])) + assert.deepEqual(chunk.columns[1].validity, new Uint8Array([0b01])) + assert.equal(new TextDecoder().decode(chunk.columns[1].data), 'user_1') +}) + +test('describeType exposes the core type parser', () => { + const t = describeType("Map(LowCardinality(String), Array(Nullable(Decimal(18, 4))))") + assert.equal(t.kind, 'Map') + assert.equal(t.key.kind, 'LowCardinality') + assert.equal(t.value.element.kind, 'Decimal') + assert.equal(t.value.element.nullable, true) + assert.equal(t.value.element.scale, 4) + assert.throws(() => describeType('NotAType('), { code: 'InvalidArg' }) +}) diff --git a/crates/ch-core-wasm/test/live.test.mjs b/crates/ch-core-wasm/test/live.test.mjs new file mode 100644 index 0000000..8e3fd75 --- /dev/null +++ b/crates/ch-core-wasm/test/live.test.mjs @@ -0,0 +1,136 @@ +// Optional live-server coverage, skipped unless CLICKHOUSE_URL is set +// (CLICKHOUSE_USER and CLICKHOUSE_PASSWORD optional). Every type is read from +// a real server as FORMAT Native and must re-encode to the same bytes. +import { test } from 'node:test' +import assert from 'node:assert/strict' +import { decodeNativeColumns, encodeNative, NativeStreamDecoder } from '../js/node.mjs' + +const URL_ = process.env.CLICKHOUSE_URL +const skip = URL_ ? false : 'set CLICKHOUSE_URL to run against a live server' +const AUTH = `Basic ${btoa(`${process.env.CLICKHOUSE_USER ?? 'default'}:${process.env.CLICKHOUSE_PASSWORD ?? ''}`)}` + +const TYPE_SETTINGS = { + allow_experimental_variant_type: '1', + allow_experimental_dynamic_type: '1', + allow_experimental_json_type: '1', + allow_experimental_qbit_type: '1', + allow_experimental_bfloat16_type: '1', + enable_time_time64_type: '1', + allow_suspicious_low_cardinality_types: '1', +} + +async function query(sql, settings = {}) { + const url = new URL(URL_) + for (const [k, v] of Object.entries({ ...TYPE_SETTINGS, ...settings })) url.searchParams.set(k, v) + const res = await fetch(url, { method: 'POST', body: `${sql}\nFORMAT Native`, headers: { Authorization: AUTH } }) + if (!res.ok) throw new Error(`ClickHouse ${res.status}: ${await res.text()}`) + return res +} + +const nativeBytes = async (sql, settings) => new Uint8Array(await (await query(sql, settings)).arrayBuffer()) + +const concat = (parts) => { + const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)) + let o = 0 + for (const p of parts) (out.set(p, o), (o += p.length)) + return out +} + +// [label, SQL expression, (optional) query settings] +const CASES = [ + ['Bool', 'true'], + ['Int8', 'toInt8(-128)'], + ['Int16', 'toInt16(-32768)'], + ['Int32', 'toInt32(-2147483648)'], + ['Int64', 'toInt64(-9223372036854775808)'], + ['UInt8', 'toUInt8(255)'], + ['UInt16', 'toUInt16(65535)'], + ['UInt32', 'toUInt32(4294967295)'], + ['UInt64', 'toUInt64(18446744073709551615)'], + ['Int128', "toInt128('-170141183460469231731687303715884105728')"], + ['UInt128', "toUInt128('340282366920938463463374607431768211455')"], + ['Int256', "toInt256('-12345678901234567890123456789012345678901234567890')"], + ['UInt256', "toUInt256('115792089237316195423570985008687907853269984665640564039457584007913129639935')"], + ['Float32', 'toFloat32(1.5)'], + ['Float64', 'toFloat64(-0.125)'], + ['BFloat16', 'toBFloat16(1.5)'], + ['String', "'héllo, 世界'"], + ['FixedString', "toFixedString('ab', 4)"], + ['Date', "toDate('2024-02-29')"], + ['Date32', "toDate32('1900-01-01')"], + ['DateTime', "toDateTime('2024-01-02 03:04:05', 'UTC')"], + ['DateTime64(9)', "toDateTime64('2024-01-02 03:04:05.123456789', 9, 'UTC')"], + ['Time', "toTime('12:34:56')"], + ['Time64(3)', "toTime64('12:34:56.789', 3)"], + ['IntervalDay', 'toIntervalDay(5)'], + ['Decimal32', 'toDecimal32(-3.14, 2)'], + ['Decimal256', "toDecimal256('12345678901234567890.123456789', 9)"], + ['UUID', "toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0')"], + ['IPv4', "toIPv4('192.168.1.254')"], + ['IPv6', "toIPv6('2001:db8:0:0:1:0:0:1')"], + ['Enum8', "CAST('b', 'Enum8(\\'a\\' = -1, \\'b\\' = 2)')"], + ['Enum16', "CAST('z', 'Enum16(\\'y\\' = 1000, \\'z\\' = -1000)')"], + ['Nullable', "if(number = 1, NULL, toNullable('x'))"], + ['Nothing', 'NULL'], + ['LowCardinality', "toLowCardinality(toString(number % 2))"], + ['LowCardinality(Nullable)', "CAST(if(number = 1, NULL, 'lc'), 'LowCardinality(Nullable(String))')"], + ['Array(Nullable)', '[1, NULL, 3]'], + ['Array(Array)', "[['a'], [], ['b', 'c']]"], + ['Tuple named', "CAST((1, 'x'), 'Tuple(id UInt8, name String)')"], + ['Nullable(Tuple)', "CAST(if(number = 1, NULL, tuple(7)), 'Nullable(Tuple(a UInt8))')"], + ['Map(String, Nullable)', "map('x', NULL, 'y', toNullable(7))"], + ['Variant', "CAST(if(number = 0, 'hi', if(number = 1, NULL, toUInt64(13))), 'Variant(String, UInt64)')"], + ['Dynamic', "CAST(if(number = 0, toInt32(7), if(number = 1, NULL, 'str')), 'Dynamic')"], + ['Dynamic array', "CAST([1, 2], 'Dynamic')"], + ['Dynamic shared', "CAST(toInt16(5), 'Dynamic(max_types=0)')"], + ['JSON', `CAST('{"a": 1, "b": {"c": "x", "d": [1, 2]}}', 'JSON')`], + ['JSON typed path', `CAST('{"a": 1, "s": "str"}', 'JSON(a UInt8)')`], + ['JSON shared data', `CAST('{"a": 1, "b": 2}', 'JSON(max_dynamic_paths=0)')`], + ['JSON as string', `CAST('{"a": 1}', 'JSON')`, { output_format_native_write_json_as_string: '1' }], + ['QBit', "CAST([1., 2., 3.], 'QBit(Float32, 3)')"], + ['Point', "CAST((1.5, 2.5), 'Point')"], + ['Ring', "CAST([(0, 0), (1, 1)], 'Ring')"], + ['SimpleAggregateFunction', "CAST(5, 'SimpleAggregateFunction(sum, UInt64)')"], + ['Nested', "CAST([(1, 'a')], 'Nested(id UInt8, s String)')"], +] + +for (const [label, expr, settings] of CASES) { + test(`live re-encode: ${label}`, { skip }, async () => { + const bytes = await nativeBytes(`SELECT ${expr} AS v FROM numbers(3)`, settings) + const decoded = decodeNativeColumns(bytes) + assert.equal(decoded.rowCount, 3) + assert.deepEqual(concat(decoded.chunks.map(encodeNative)), bytes) + }) +} + +test('live stream: 1M rows across many blocks and pushes', { skip }, async () => { + const res = await query('SELECT number AS n, toString(number) AS s FROM numbers(1000000)') + const d = new NativeStreamDecoder() + let sum = 0n + let blocks = 0 + const consume = (out) => { + blocks += out.chunks.length + for (const c of out.chunks) for (const v of c.columns[0].values) sum += v + } + for await (const piece of res.body) consume(d.push(piece)) + consume(d.finish()) + assert.equal(d.rowCount, 1_000_000) + assert.equal(sum, (999_999n * 1_000_000n) / 2n) + assert.ok(blocks > 1) + d.free() +}) + +test('live stream: a mid-stream server exception fails the decode', { skip }, async () => { + const res = await query("SELECT throwIf(number = 300000, 'boom') AS x FROM numbers(1000000)", { + max_block_size: '10000', + http_write_exception_in_output_format: '0', + }) + const d = new NativeStreamDecoder() + let before = 0 + await assert.rejects(async () => { + for await (const piece of res.body) before += d.push(piece).rowCount + d.finish() + }) + assert.ok(before > 0) + d.free() +}) diff --git a/src/compression/mod.rs b/src/compression/mod.rs index 9733166..aa4aca4 100644 --- a/src/compression/mod.rs +++ b/src/compression/mod.rs @@ -54,6 +54,7 @@ use std::borrow::Cow; mod cityhash; mod lz4; +#[cfg(feature = "zstd")] mod zstd; use cityhash::city_hash128; @@ -339,7 +340,9 @@ struct BlockHeader { /// decoder returns for it: [`CompressionError::Lz4Malformed`] for LZ4, /// [`CompressionError::InvalidUncompressedSize`] for ZSTD, and /// [`CompressionError::SizeMismatch`] for NONE, whose payload length must equal -/// the plaintext size. The returned sizes remain untrusted declarations. +/// the plaintext size. Without the `zstd` feature a ZSTD frame returns +/// [`CompressionError::UnsupportedCodec`]. The returned sizes remain untrusted +/// declarations. pub fn frame_header(data: &[u8]) -> Result { let header = parse_frame_prefix(data)?; check_expansion( @@ -382,7 +385,7 @@ fn parse_frame_prefix(data: &[u8]) -> Result { uncompressed_size: plaintext_size, }); } - if method != METHOD_NONE && method != METHOD_LZ4 && method != METHOD_ZSTD { + if !is_supported_method(method) { return Err(CompressionError::UnsupportedCodec { method }); } @@ -393,6 +396,13 @@ fn parse_frame_prefix(data: &[u8]) -> Result { }) } +/// Whether this build decodes `method`. ZSTD needs the `zstd` feature. +fn is_supported_method(method: u8) -> bool { + method == METHOD_NONE + || method == METHOD_LZ4 + || (cfg!(feature = "zstd") && method == METHOD_ZSTD) +} + /// Reject a plaintext size that a `payload_len`-byte payload of `method` cannot /// decode to, with the same error the decoder returns. fn check_expansion( @@ -406,6 +416,7 @@ fn check_expansion( actual: payload_len, }), METHOD_LZ4 => lz4::check_claim(payload_len, plaintext_size), + #[cfg(feature = "zstd")] METHOD_ZSTD => zstd::check_claim(payload_len, plaintext_size), _ => Ok(()), } @@ -510,6 +521,7 @@ pub fn decompress_frame( Cow::Borrowed(payload) } METHOD_LZ4 => Cow::Owned(lz4::decompress_block(payload, header.uncompressed_size)?), + #[cfg(feature = "zstd")] METHOD_ZSTD => Cow::Owned(zstd::decompress_block(payload, header.uncompressed_size)?), other => return Err(CompressionError::UnsupportedCodec { method: other }), }; @@ -557,6 +569,7 @@ pub fn decompress_frame_into( } } METHOD_LZ4 => lz4::decompress_block_into(payload, header.uncompressed_size, out), + #[cfg(feature = "zstd")] METHOD_ZSTD => zstd::decompress_block_into(payload, header.uncompressed_size, out), other => Err(CompressionError::UnsupportedCodec { method: other }), }; @@ -918,7 +931,6 @@ mod tests { let payload = 1u32; let compressed = HEADER_SIZE as u32 + payload; let lz4_max = 255 + 24; - let zstd_max = 32 * 1024; assert!(frame_header(&prefix(METHOD_LZ4, compressed, lz4_max)).is_ok()); assert_eq!( @@ -930,13 +942,17 @@ mod tests { Err(CompressionError::Lz4Malformed) ); - assert!(frame_header(&prefix(METHOD_ZSTD, compressed, zstd_max)).is_ok()); - assert_eq!( - frame_header(&prefix(METHOD_ZSTD, compressed, zstd_max + 1)), - Err(CompressionError::InvalidUncompressedSize { - uncompressed_size: zstd_max + 1 - }) - ); + #[cfg(feature = "zstd")] + { + let zstd_max = 32 * 1024; + assert!(frame_header(&prefix(METHOD_ZSTD, compressed, zstd_max)).is_ok()); + assert_eq!( + frame_header(&prefix(METHOD_ZSTD, compressed, zstd_max + 1)), + Err(CompressionError::InvalidUncompressedSize { + uncompressed_size: zstd_max + 1 + }) + ); + } assert!(frame_header(&prefix(METHOD_NONE, compressed, payload)).is_ok()); assert_eq!( @@ -1173,6 +1189,35 @@ mod tests { )); } + #[cfg(not(feature = "zstd"))] + #[test] + fn zstd_without_the_feature_is_an_unsupported_codec() { + let block = frame_block(METHOD_ZSTD, 4, b"not decoded"); + assert_eq!( + frame_header(&block), + Err(CompressionError::UnsupportedCodec { + method: METHOD_ZSTD + }) + ); + let err = decompress_frame(&block, ChecksumMode::Verify).unwrap_err(); + assert_eq!( + err, + CompressionError::UnsupportedCodec { + method: METHOD_ZSTD + } + ); + let mut out = b"keep me".to_vec(); + let err = decompress_frame_into(&block, ChecksumMode::Verify, &mut out).unwrap_err(); + assert_eq!( + err, + CompressionError::UnsupportedCodec { + method: METHOD_ZSTD + } + ); + assert_eq!(out, b"keep me"); + } + + #[cfg(feature = "zstd")] #[test] fn zstd_roundtrips_and_appends() { let raw = b"ZSTD compressed Native bytes, user_1 and user_2"; @@ -1189,6 +1234,7 @@ mod tests { assert_eq!(out, [b"prefix:".as_slice(), raw].concat()); } + #[cfg(feature = "zstd")] #[test] fn zstd_accepts_concatenated_frames() { let first = b"first half, "; @@ -1217,6 +1263,7 @@ mod tests { } } + #[cfg(feature = "zstd")] #[test] fn zstd_malformed_payloads_roll_back_with_exact_errors() { let raw = b"ZSTD compressed Native bytes"; @@ -1237,6 +1284,7 @@ mod tests { } } + #[cfg(feature = "zstd")] #[test] fn zstd_wrong_size_rolls_back_with_exact_errors() { let raw = b"ZSTD compressed Native bytes"; @@ -1269,6 +1317,7 @@ mod tests { assert!(matches!(err, CompressionError::ZstdMalformed), "{err:?}"); } + #[cfg(feature = "zstd")] #[test] fn zstd_oversized_claim_fails_before_reserving() { // A tiny frame with a valid checksum that claims the full 1 GiB. diff --git a/src/native/encode/mod.rs b/src/native/encode/mod.rs index 2e733e5..efdd9d1 100644 --- a/src/native/encode/mod.rs +++ b/src/native/encode/mod.rs @@ -106,6 +106,13 @@ pub enum EncodeError { /// The batch is internally inconsistent: the column count does not match the /// schema field count, or a column's length does not match `num_rows`. InconsistentBatch { detail: String }, + /// The encoded block would not fit in memory. Zero-width columns + /// (`Nothing`, `Tuple()`) and bit-packed ones (`Bool`, null maps, `QBit`) + /// write more bytes than their buffers hold, so a large row count can ask + /// for more output than the address space allows, notably on 32-bit + /// targets such as wasm32. Carries the extra byte count requested, or + /// `usize::MAX` when even that overflowed. + OutputTooLarge { additional: usize }, } impl std::fmt::Display for EncodeError { @@ -124,6 +131,9 @@ impl std::fmt::Display for EncodeError { EncodeError::InconsistentBatch { detail } => { write!(f, "inconsistent batch: {detail}") } + EncodeError::OutputTooLarge { additional } => { + write!(f, "cannot allocate {additional} more bytes of Native output") + } } } } @@ -854,7 +864,7 @@ fn encode_column_values( return Err(column_error(field, ch_type)); } let value_type = if let ChType::Nullable(inner) = ch_type { - encode_null_map(buf, column); + encode_null_map(buf, column)?; inner.as_ref() } else { ch_type @@ -1120,6 +1130,7 @@ fn encode_tuple_data( options: &EncodeOptions, ) -> Result<(), EncodeError> { if elements.is_empty() { + reserve_output(buf, col.len)?; buf.resize(buf.len() + col.len, b'0'); return Ok(()); } @@ -1270,9 +1281,9 @@ fn encode_array_data( /// time (the same shape as [`encode_bool_data`] and the inverse of /// [`crate::bitmap::Bitmap::from_ch_null_map`]), so the per-row `index / 8` and /// `index % 8` recompute is amortized to one shift per bit. -fn encode_null_map(buf: &mut Vec, column: &Column) { +fn encode_null_map(buf: &mut Vec, column: &Column) -> Result<(), EncodeError> { let num_rows = column.len(); - buf.reserve(num_rows); + reserve_output(buf, num_rows)?; match column.validity() { None => buf.resize(buf.len() + num_rows, 0x00), Some(validity) => { @@ -1293,6 +1304,17 @@ fn encode_null_map(buf: &mut Vec, column: &Column) { } } } + Ok(()) +} + +/// Reserve `additional` more output bytes, or fail with +/// [`EncodeError::OutputTooLarge`]. Used where the byte count comes from a row +/// count rather than from an existing buffer. `try_reserve` rejects a +/// `buf.len() + additional` that overflows, so after it succeeds that sum is +/// in range and a following `resize` cannot wrap. +fn reserve_output(buf: &mut Vec, additional: usize) -> Result<(), EncodeError> { + buf.try_reserve(additional) + .map_err(|_| EncodeError::OutputTooLarge { additional }) } /// Encode one column's value body (no header, no null map) into `buf`. @@ -1318,9 +1340,10 @@ fn encode_column_body( // ASCII '0' placeholder byte per row. The decoder accepts arbitrary // placeholder values, but encode uses the server's canonical byte. (ChType::Nothing, Column::Nothing(c)) => { + reserve_output(buf, c.len)?; buf.resize(buf.len() + c.len, b'0'); } - (ChType::Bool, Column::Bool(c)) => encode_bool_data(buf, c), + (ChType::Bool, Column::Bool(c)) => encode_bool_data(buf, c)?, (ChType::Int8, Column::Int8(c)) => encode_primitive!(buf, &c.values, i8), (ChType::Int16, Column::Int16(c)) => encode_primitive!(buf, &c.values, i16), (ChType::Int32, Column::Int32(c)) => encode_primitive!(buf, &c.values, i32), @@ -1336,7 +1359,7 @@ fn encode_column_body( // so write the contiguous array buffer without conversion. (ChType::BFloat16, Column::BFloat16(c)) => encode_bfloat16_data(buf, c), (ChType::QBit { element_type, .. }, Column::QBit(c)) => { - encode_qbit_data(buf, c, *element_type) + encode_qbit_data(buf, c, *element_type)? } // Temporal types are plain little-endian primitives at their native width; // timezone and precision live only in the type string (rendered by @@ -1427,8 +1450,8 @@ fn encode_column_body( /// the per-row `index / 8` and `index % 8` recompute is amortized to one shift per /// bit. [`validate_column`] checks `col.bitmap.len() >= col.len.div_ceil(8)` before /// any bytes are written, so every index read here is in range. -fn encode_bool_data(buf: &mut Vec, col: &BoolColumn) { - buf.reserve(col.len); +fn encode_bool_data(buf: &mut Vec, col: &BoolColumn) -> Result<(), EncodeError> { + reserve_output(buf, col.len)?; let full_bytes = col.len / 8; for &byte in &col.bitmap[..full_bytes] { for bit in 0..8 { @@ -1442,6 +1465,7 @@ fn encode_bool_data(buf: &mut Vec, col: &BoolColumn) { buf.push((byte >> bit) & 1); } } + Ok(()) } /// Encode a `String` column body: one varint length prefix then the raw value @@ -1503,15 +1527,29 @@ fn encode_qbit_words( num_rows: usize, dimension: usize, to_word: F, -) where +) -> Result<(), EncodeError> +where W: QBitWord, F: Fn(&T) -> W, { let bit_width = W::BYTES * 8; let bytes_per_plane_row = dimension / 8 + usize::from(dimension % 8 != 0); - let plane_stride = num_rows * bytes_per_plane_row; + // Planes round each row up to whole bytes, so the output can be up to + // eight times the input. Check the size instead of trusting it. + let plane_stride = + num_rows + .checked_mul(bytes_per_plane_row) + .ok_or(EncodeError::OutputTooLarge { + additional: usize::MAX, + })?; + let total = plane_stride + .checked_mul(bit_width) + .ok_or(EncodeError::OutputTooLarge { + additional: usize::MAX, + })?; + reserve_output(buf, total)?; let start = buf.len(); - buf.resize(start + plane_stride * bit_width, 0); + buf.resize(start + total, 0); let out = &mut buf[start..]; for row in 0..num_rows { @@ -1540,9 +1578,14 @@ fn encode_qbit_words( } } } + Ok(()) } -fn encode_qbit_data(buf: &mut Vec, col: &QBitColumn, element_type: QBitElementType) { +fn encode_qbit_data( + buf: &mut Vec, + col: &QBitColumn, + element_type: QBitElementType, +) -> Result<(), EncodeError> { let num_rows = col.len(); match (element_type, col.values.as_ref()) { (QBitElementType::BFloat16, Column::BFloat16(values)) => { diff --git a/src/native/encode/tests/nothing.rs b/src/native/encode/tests/nothing.rs index e607295..dc264c6 100644 --- a/src/native/encode/tests/nothing.rs +++ b/src/native/encode/tests/nothing.rs @@ -196,3 +196,29 @@ fn low_cardinality_nothing_is_not_encodable() { Err(EncodeError::UnsupportedType { .. }) )); } + +/// Zero-width rows cost no input memory, so the row count alone sizes the +/// output. An impossible size must be an error. Before the checked reserve, +/// `buf.len() + rows` wrapped on 32-bit targets and truncated the block. +#[test] +fn encode_zero_width_rows_past_the_address_space_is_an_error() { + let rows = usize::MAX; + for (ch_type, column) in [ + (ChType::Nothing, Column::Nothing(NothingColumn::new(rows))), + ( + ChType::Tuple(Vec::new()), + Column::Tuple(TupleColumn::new(Vec::new(), rows)), + ), + ] { + let batch = ColBatch { + schema: Schema::new(vec![Field { + name: "z".into(), + ch_type, + }]), + columns: vec![column], + num_rows: rows, + }; + let err = encode_block(&batch, &EncodeOptions::default()).unwrap_err(); + assert_eq!(err, EncodeError::OutputTooLarge { additional: rows }); + } +} diff --git a/tests/tcp_compression.rs b/tests/tcp_compression.rs index ed5244b..8d14bb1 100644 --- a/tests/tcp_compression.rs +++ b/tests/tcp_compression.rs @@ -17,7 +17,9 @@ const HTTP_LZ4: &[u8] = include_bytes!("fixtures/http_multi_rev54460_lz4.native" const TCP_PLAIN: &[u8] = include_bytes!("fixtures/tcp_multi_rev54460.packets"); const TCP_LZ4: &[u8] = include_bytes!("fixtures/tcp_multi_rev54460_lz4.packets"); const TCP_LARGE: &[u8] = include_bytes!("fixtures/tcp_large_rev54460_lz4.packets"); +#[cfg(feature = "zstd")] const TCP_ZSTD: &[u8] = include_bytes!("fixtures/tcp_multi_rev54460_zstd.packets"); +#[cfg(feature = "zstd")] const TCP_LARGE_ZSTD: &[u8] = include_bytes!("fixtures/tcp_large_rev54460_zstd.packets"); fn options() -> DecodeOptions { @@ -148,6 +150,7 @@ fn tcp_compressed_and_plain_packets_decode_identically() { assert_small_values(&plain); } +#[cfg(feature = "zstd")] #[test] fn tcp_zstd_and_plain_packets_decode_identically() { let (plain, _) = packets(TCP_PLAIN, false); @@ -157,6 +160,7 @@ fn tcp_zstd_and_plain_packets_decode_identically() { assert_small_values(&compressed); } +#[cfg(feature = "zstd")] #[test] fn tcp_large_zstd_block_matches_lz4_across_frames() { let (expected, expected_frames) = packets(TCP_LARGE, true); @@ -166,6 +170,7 @@ fn tcp_large_zstd_block_matches_lz4_across_frames() { assert_eq!(frames[1], [1_048_576, 51_465]); } +#[cfg(feature = "zstd")] #[test] fn real_zstd_frame_retries_truncation_and_preserves_packet_suffix() { // Each packet begins with the raw Data code and empty block name.