Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions .github/workflows/bindings-test.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Binding packages test

# bindings.yml on the api fixture, whose Python consumers must print native Rust's transcript
# byte for byte, and on moq's stand-in facade at the exporter's moq pin, its first consumer.
# bindings.yml on the api fixture, whose Python and web consumers must print native Rust's
# transcript byte for byte, and on moq's stand-in facade at the exporter's moq pin, its first consumer.
# Read-only: nothing here publishes.
on:
workflow_call:
Expand All @@ -18,6 +18,9 @@ jobs:
features: doubled
example: transcript
python-check: ffi/tests/api.py
web-manifest-path: ffi/fixtures/api/Cargo.toml
scope: kixel-ai
web-check: ffi/tests/api.ts
# A module path a proxy could serve. No go-check, as no swift-check: api.go needs the
# wasm32 items this export lacks, so the consumer only loads the runtime.
go-module: example.com/api
Expand All @@ -31,5 +34,8 @@ jobs:
manifest-path: ffi/target/moq-ffi/Cargo.toml
python-check: ffi/moq/moq.py
swift-check: ffi/moq/moq.swift
# moq's wasm32 stand-in, which leaves moq-tokio out, as no wasm32 target builds it.
web-manifest-path: ffi/target/moq-ffi-web/Cargo.toml
scope: kixel-ai
# Under the export's own module, `moq`, which moq.go imports.
go-check: ffi/moq/moq.go
130 changes: 127 additions & 3 deletions .github/workflows/bindings.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
name: Binding packages

# The shared, read-only builder of a crate's rust2-ffi Python wheels, Swift package, and Go
# module, which
# a release workflow ffi/release/package.py's `init` writes calls at a pinned rust2 commit.
# The shared, read-only builder of a crate's rust2-ffi Python wheels, Swift package, Go
# module, and web package, which a release workflow ffi/release/package.py's `init` writes
# calls at a pinned rust2 commit.
# It publishes nothing and holds no credentials: the caller's own jobs publish what it
# uploads, once its consumers pass. See ffi/release/README.md.
on:
Expand All @@ -28,6 +28,26 @@ on:
description: The main.swift of an executable run on the installed Swift package
default: ''
type: string
web-manifest-path:
description: The Cargo.toml of the package whose wasm32-wasip1 export the npm and JSR package holds, often manifest-path; without it, no web package
default: ''
type: string
scope:
description: The npm and JSR scope the web package is named under, @<scope>/<crate>, without its @
default: ''
type: string
web-check:
description: A TypeScript module run on the installed npm package, importing the binding as ./web/<module>.ts does beside the export
default: ''
type: string
web-features:
description: Cargo features of a web crate apart from manifest-path's, which takes features
default: ''
type: string
web-example:
description: The example of a web crate apart from manifest-path's whose stdout web-check must print, which takes example
default: ''
type: string
go-module:
description: The Go module's path; without it, the export's own, which no proxy serves
default: ''
Expand All @@ -46,6 +66,9 @@ on:
module:
description: The Swift module, whose XCFramework is <module>FFI.xcframework.zip
value: ${{ jobs.facts.outputs.module }}
web:
description: Whether the build made the web package, <name>-web
value: ${{ inputs.web-manifest-path != '' }}

permissions:
contents: read
Expand All @@ -65,6 +88,7 @@ jobs:
tag: ${{ steps.facts.outputs.tag }}
module: ${{ steps.facts.outputs.module }}
fixture: ${{ steps.mode.outputs.fixture }}
web-fixture: ${{ steps.mode.outputs.web-fixture }}
rust2: ${{ steps.identity.outputs.workflow_repository }}
rust2-sha: ${{ steps.identity.outputs.workflow_sha }}
steps:
Expand All @@ -82,12 +106,18 @@ jobs:
- id: mode
env:
RUST2: ${{ steps.identity.outputs.workflow_repository }}
WEB_MANIFEST: ${{ inputs.web-manifest-path }}
run: |
if [[ "$RUST2" == "$GITHUB_REPOSITORY" && "$MANIFEST" == ffi/target/moq-ffi/Cargo.toml ]]; then
echo fixture=true >> "$GITHUB_OUTPUT"
else
echo fixture=false >> "$GITHUB_OUTPUT"
fi
if [[ "$RUST2" == "$GITHUB_REPOSITORY" && "$WEB_MANIFEST" == ffi/target/moq-ffi-web/Cargo.toml ]]; then
echo web-fixture=true >> "$GITHUB_OUTPUT"
else
echo web-fixture=false >> "$GITHUB_OUTPUT"
fi
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
path: source
Expand Down Expand Up @@ -433,6 +463,100 @@ jobs:
MODULE: ${{ needs.facts.outputs.module }}
run: bash rust2/ffi/release/consume-swift.sh swift apple

# The web binding's npm and JSR packages: web-manifest-path exported for wasm32-wasip1
# alone, the binding's only target, and its module built beside it; with native Rust's
# output on that target, which the consumers compare with.
web:
needs: facts
if: inputs.web-manifest-path != ''
runs-on: ubuntu-24.04
timeout-minutes: 60
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
path: source
persist-credentials: false
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ needs.facts.outputs.rust2 }}
ref: ${{ needs.facts.outputs.rust2-sha }}
path: rust2
persist-credentials: false
- uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2.90.2
if: needs.facts.outputs.web-fixture == 'true'
with:
tool: just
- name: Stand-in
if: needs.facts.outputs.web-fixture == 'true'
working-directory: source
run: just ffi standin "" web && cp ffi/moq/web.toml ffi/target/moq-ffi-web/ffi.toml
# npm packs, and Node's WASI runs the native example.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24'
- name: Exporter
working-directory: rust2/ffi
run: cargo build --locked --release
# The crate's own features and example, or a web crate's apart from it.
- name: Package
env:
WEB_MANIFEST: ${{ inputs.web-manifest-path }}
SCOPE: ${{ inputs.scope }}
VERSION: ${{ needs.facts.outputs.version }}
EXAMPLE: ${{ inputs.example }}
WEB_FEATURES: ${{ inputs.web-features }}
WEB_EXAMPLE: ${{ inputs.web-example }}
WEB_CHECK: ${{ inputs.web-check }}
run: |
if [[ "$(realpath -m "source/$WEB_MANIFEST")" == "$(realpath -m "source/$MANIFEST")" ]]; then
if [[ -n "$WEB_FEATURES$WEB_EXAMPLE" ]]; then
echo "::error::web-features and web-example are for a web crate apart from manifest-path's: set features and example"
exit 1
fi
features=$FEATURES example=$EXAMPLE
else
features=$WEB_FEATURES example=$WEB_EXAMPLE
fi
python3 -I rust2/ffi/release/package.py web --manifest-path "source/$WEB_MANIFEST" --features "$features" --scope "$SCOPE" --version "$VERSION" --example "$example" --out web
if [[ -n "$WEB_CHECK" ]]; then cp "source/$WEB_CHECK" web/check.ts; fi
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: ${{ needs.facts.outputs.name }}-web
path: web
if-no-files-found: error

# A new npm project depending on only the packed tarball, as an app's would, run on
# Node, Deno, and Bun and bundled by Vite and webpack; and JSR's checks of its package.
web-consumer:
needs: [facts, web]
runs-on: ubuntu-24.04
timeout-minutes: 20
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ needs.facts.outputs.rust2 }}
ref: ${{ needs.facts.outputs.rust2-sha }}
path: rust2
sparse-checkout: ffi/release
persist-credentials: false
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.facts.outputs.name }}-web
path: web
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24'
- uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
with:
deno-version: v2.x
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
- name: Install and run
run: |
args=()
if [[ -f web/check.ts ]]; then args+=(--check web/check.ts); fi
if [[ -f web/native.txt ]]; then args+=(--native web/native.txt); fi
python3 -I rust2/ffi/release/package.py consume-web --dist web "${args[@]}"

# The module as a GOPROXY serves it: the export's packages, and each Go target's library
# beside the runtime that links it.
go:
Expand Down
20 changes: 20 additions & 0 deletions bench/ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -430,12 +430,21 @@ revision later, on the same host and load (1 and 3 rounds).
| Swift | 3 | 2,147 KiB | 302 KiB | none |
| Go | 23 | 3,554 KiB | 435 KiB | none |
| Dart | 1 | 4,034 KiB | 376 KiB | 1,643 KiB / 62 KiB |
| TypeScript | 684 | 4,498 KiB | 1,000 KiB | 4,535 KiB / 259 KiB |

| native library | as built | stripped |
|---|---|---|
| `libmoq.a`, the C ABI that C, C++, Swift, and Go link | 193,455 KiB | 104,224 KiB |
| `libmoq.so`, with the Kotlin and Dart glue | 61,361 KiB | 46,029 KiB |
| `python/libmoq.so`, the CPython extension | 56,145 KiB | 42,166 KiB |
| `moq.wasm`, the wasm32 stand-in's module, with the web glue | 19,596 KiB | 17,632 KiB |

| web binding | raw | gzip | brotli |
|---|---|---|---|
| `moq.wasm`, stripped | 17,632 KiB | 4,657 KiB | 2,893 KiB |
| the TypeScript, 684 modules | 4,498 KiB | 1,000 KiB | 855 KiB |
| the npm package's JavaScript and declarations | 5,670 KiB | 1,454 KiB | 1,226 KiB |
| `export.ts` bundled by esbuild, minified | 23 KiB | 7 KiB | 7 KiB |

The stand-in exports all of moq-net, kio, and moq-pattern, and hang, moq-mux, and
moq-tokio's session side, far more than moq-ffi's UniFFI interface, so its sizes do not
Expand All @@ -445,6 +454,17 @@ but Python's links, and `src/jni`, `src/python`, and `src/dart`. The native libr
the export's default `release` build, which links all of moq's crates; "stripped" is
`strip --strip-all` on a copy.

The web rows (measured 2026-11-19 on fedora at the same moq pin, with this table's other
rows from 2026-11-13) are the wasm32 stand-in's export, which leaves out moq-tokio, built
with moq's release profile: fat LTO at `opt-level = 3`. A module "stripped" has no custom
section, its names among them; each file is compressed alone, gzip at level 6 and brotli at
11, as a host serves it. The release builder makes the packaged module at `opt-level =
"s"` when the crate sets no level: 13,359 KiB as built, 10,981 KiB stripped, 3,250 KiB
gzipped, and 2,135 KiB brotli'd. A caller pays for what it imports: `export.ts`, the
TypeScript benchmark, names 13 of the 684 modules, and esbuild's bundle of it and the
binding is 23 KiB, against 4.5 MiB of TypeScript. JSR caps a version at 20 MiB, which the
TypeScript and the `opt-level = 3` module pass, and the `"s"` module fits.

### What a call spends

From the CPU tables of 2026-11-10, measured at rust2 `7383790d` at a load average of 22 to
Expand Down
68 changes: 61 additions & 7 deletions bench/ffi/report.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
in CPU and wall time, each beside the median 1-minute load average over its rounds, read
from `just ffi bench-run`'s raw.tsv; the median time and peak RSS of the export and its
crate's build, beside moq's own, from its build.tsv; and the sizes of the export's generated bindings and
native libraries, and of the wasm32 stand-in's TypeScript and module.
native libraries, and of the wasm32 stand-in's TypeScript, module, and npm package, and of
one caller's bundle.

Usage: report.py <raw.tsv> <build.tsv> <export dir> <web export dir>
Usage: report.py <raw.tsv> <build.tsv> <export dir> <web export dir> <caller.ts>
"""

import collections
Expand Down Expand Up @@ -85,6 +86,14 @@

# The TypeScript, under the wasm32 stand-in's export, and the glue its module builds with.
WEB_BINDING = ("TypeScript", ["web"], ["src/lib.rs", "src/rt.rs", "src/web"])

# Brotli at its densest, as a host precompresses what it serves; Python's standard library
# lacks it, so Node's.
BROTLI = (
"const zlib = require('node:zlib');"
"const data = require('node:fs').readFileSync(0);"
"process.stdout.write(String(zlib.brotliCompressSync(data, {params: {[zlib.constants.BROTLI_PARAM_QUALITY]: 11}}).length));"
)
WASM = ("`moq.wasm`, the wasm32 stand-in's module, with the web glue", "target/wasm32-wasip1/release/moq.wasm")

# The shared library's suffix, as `just ffi moq-export` names it on each platform it builds on.
Expand Down Expand Up @@ -124,6 +133,38 @@ def size(paths):
return raw, zipped


def typescript(path):
"""A TypeScript module the web binding writes, not its JavaScript or declarations."""
return path.endswith(".ts") and not path.endswith(".d.ts")


def compressed(data):
"""The raw, gzipped, and brotli'd bytes of `data`."""
brotli = subprocess.run(["node", "-e", BROTLI], input=data, capture_output=True, check=True).stdout
return len(data), len(gzip.compress(data, compresslevel=6, mtime=0)), int(brotli)


def sizes(paths):
"""The raw, gzipped, and brotli'd bytes of `paths`, each compressed alone as a host serves it."""
total = [0, 0, 0]
for path in paths:
with open(path, "rb") as f:
for i, n in enumerate(compressed(f.read())):
total[i] += n
return total


def bundle(caller):
"""`caller` and what it imports of the binding, bundled for the browser, minified and
tree-shaken, as an app's build ships it."""
with tempfile.TemporaryDirectory() as tmp:
out = os.path.join(tmp, "bundle.js")
subprocess.run(["esbuild", caller, "--bundle", "--minify", "--format=esm", "--platform=browser",
"--target=es2024", "--log-level=warning", f"--outfile={out}"], check=True)
with open(out, "rb") as f:
return f.read()


def wasm_stripped(data):
"""A wasm module without its custom sections, its names and debug info among them."""
out = bytearray(data[:8])
Expand Down Expand Up @@ -175,7 +216,7 @@ def builds(path):
return table(["step", "wall s", "CPU s", "peak RSS", "load average"], rows)


def main(raw_path, build_path, export, web):
def main(raw_path, build_path, export, web, caller):
rounds = collections.defaultdict(list)
with open(raw_path) as f:
for line in f:
Expand Down Expand Up @@ -224,9 +265,10 @@ def cell(lang, case, i):
print("### Size\n")
rows = []
for root, (name, generated, glue) in [(export, b) for b in BINDINGS] + [(web, WEB_BINDING)]:
raw, zipped = size(files(root, generated))
ours = [p for p in files(root, generated) if root != web or typescript(p)]
raw, zipped = size(ours)
glue_raw, glue_zipped = size(files(root, glue))
count = len(files(root, generated))
count = len(ours)
glue_cell = f"{kib(glue_raw)} / {kib(glue_zipped)}" if glue else "none"
rows.append([name, str(count), kib(raw), kib(zipped), glue_cell])
print(table(["binding", "files", "raw", "gzip", "Rust glue, raw / gzip"], rows))
Expand All @@ -246,8 +288,20 @@ def cell(lang, case, i):
rows.append([label, kib(len(data)), kib(len(wasm_stripped(data)))])
print(table(["native library", "as built", "stripped"], rows))

print()
everything = files(web, ["web"])
modules = [p for p in everything if typescript(p)]
package = [p for p in everything if p.endswith(".js") or p.endswith(".d.ts")]
rows = [
["`moq.wasm`, stripped", *map(kib, compressed(wasm_stripped(data)))],
[f"the TypeScript, {len(modules)} modules", *map(kib, sizes(modules))],
["the npm package's JavaScript and declarations", *map(kib, sizes(package))],
[f"`{os.path.basename(caller)}` bundled by esbuild, minified", *map(kib, compressed(bundle(caller)))],
]
print(table(["web binding", "raw", "gzip", "brotli"], rows))


if __name__ == "__main__":
if len(sys.argv) != 5:
if len(sys.argv) != 6:
sys.exit(__doc__)
main(sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4])
main(*sys.argv[1:])
Loading
Loading