// STRYKE-ZMQ — ZEROMQ CLIENT FOR STRYKE // REQ/REP + PUB/SUB + PUSH/PULL + DEALER/ROUTER

Install

# from a release tarball (no rustc/cmake on the consumer machine)
s pkg install -g github.com/MenkeTechnologies/stryke-zmq

# from a local checkout
cd ~/projects/stryke-zmq
cargo build --release        # first build vendors libzmq via cmake (~1-2 min)
s pkg install -g .           # cdylib lands in ~/.stryke/store/zmq@<version>/

# one-liner
make install

There is no CLI launcher — this is a library. The cdylib is dlopened in-process on the first use Zmq; a shared zmq::Context plus a socket-handle registry are held in OnceCell, so sockets persist across calls.

Quick start

use Zmq

# REQ/REP over TCP
val $server = Zmq::socket("rep", bind => "tcp://*:5555")
val $client = Zmq::socket("req", connect => "tcp://localhost:5555")

Zmq::send($client, "ping")
val $request = Zmq::recv($server, timeout_ms => 1000)   # "ping"
Zmq::send($server, "pong")
val $reply = Zmq::recv($client, timeout_ms => 1000)     # "pong"

Zmq::close($client)
Zmq::close($server)

PUB/SUB with a topic filter and a one-shot request:

val $sub = Zmq::socket("sub", connect => "tcp://localhost:5556", subscribe => "weather")
val $msg = Zmq::recv($sub, timeout_ms => 500)

val $reply = Zmq::request("tcp://localhost:5555", "hello", timeout_ms => 2000)

PUSH/PULL pipeline and multipart frames over inproc (from examples/):

# PUSH/PULL — fan-out work distribution
val $puller = Zmq::socket("pull", bind => "inproc://work")
val $pusher = Zmq::socket("push", connect => "inproc://work")
Zmq::send($pusher, $_) for ("task-a", "task-b", "task-c")
val $task = Zmq::recv($puller, timeout_ms => 1000)

# multipart — atomic frame group
Zmq::send_multipart($dealer, ["header", "body", "trailer"])
val @frames = Zmq::recv_multipart($router, timeout_ms => 1000)

API — complete reference

The whole Zmq namespace, grouped by purpose. Every function below exists in lib/Zmq.stk. Functions split into two classes: socket ops (take a handle, touch a live libzmq socket) and pure helpers (validation, endpoint, topic, and table utilities — no socket created, no FFI socket call).

Introspection

Socket lifecycle

Send / receive

Pub/sub topic filters

Socket options + readiness

Monitor + proxy device

CURVE + Z85 codec

Endpoint helpers (pure)

Topic + subscription helpers (pure)

Socket-type + table helpers (pure)

Endpoints follow ZeroMQ transport syntax: tcp://host:port, ipc:///path, inproc://name, pgm://, epgm://. The pure helpers create no socket. Full prose reference in the README API section.

Socket types

Twelve types are accepted by Zmq::socket, one per ZeroMQ messaging pattern. Aliases (e.g. publish) collapse to the canonical name via Zmq::valid_socket_type.

Encodings & binary-safe payloads

Payloads default to UTF-8 framing. For arbitrary bytes (NULs, high bytes), pass encoding => "hex" or encoding => "base64" on both the send and the matching recv so the message round-trips intact. Zmq::encoding_names() lists every accepted encoding with its aliases and a binary_safe flag.

# round-trip a NUL-containing byte string as hex
Zmq::send($a, "\x00\xff\x01", encoding => "hex")
val $bytes = Zmq::recv($b, timeout_ms => 1000, encoding => "hex")

Socket options

Zmq::set/Zmq::get cover the full libzmq option surface, grouped by value kind. Zmq::socket_option_names() returns the live table ({ name, settable, gettable, kind }); guard one lookup with Zmq::valid_socket_option($opt).

val $s = Zmq::socket("dealer")
Zmq::set($s, "rcvtimeo", 500)
Zmq::set($s, "identity", "worker-1")
val $id = Zmq::get($s, "identity")

Monitoring socket lifecycle

Zmq::monitor wires a socket's connect/disconnect/handshake events to an inproc PAIR; Zmq::monitor_recv decodes one event at a time. Zmq::socket_event_names() lists every event with its flag and is_error bit, and Zmq::parse_monitor_event maps a raw 16-bit event id to its symbolic name plus what the 32-bit value carries (fd, errno, reconnect interval, protocol error code, ZAP status).

Zmq::monitor($sock, "inproc://mon", events => "all")
val $ev = Zmq::monitor_recv($mon, timeout_ms => 1000)   # { event, value, endpoint }

A backgrounded Zmq::proxy($frontend, $backend, %opts) runs a zmq_proxy device with optional capture and steerable control sockets.

Socket handles

ZeroMQ sockets are stateful and long-lived, so the API is handle-based: Zmq::socket returns an integer handle the caller keeps; every later op takes that handle. This is deliberate — a SUB socket must stay open to keep receiving and a REQ/REP exchange is a send→recv state machine. A fork-per-call model would drop messages between calls and re-pay connection setup each time.

The cdylib holds the sockets in a registry behind a mutex. ZeroMQ requires one-thread-at-a-time access per socket; the mutex provides exactly that, plus the cross-thread memory fence libzmq mandates when a socket migrates between threads (zmq::Socket is Send, not Sync).

Why a package, not a builtin

ZeroMQ integration requires libzmq, the C library every ZMQ binding wraps. The Rust binding (zmq → zmq-sys → zeromq-src) compiles libzmq and libsodium from source and links them statically. The artifact is big enough that it doesn't belong in stryke core — opt in once, get all four messaging patterns.

Because libzmq is vendored into the cdylib, there is no system libzmq.so/.dylib requirement on the consumer machine. A from-source build needs cmake plus a C/C++ compiler; the published release tarball is prebuilt per host triple.

FFI layer

Each zmq__* export in the cdylib is a JSON-string-in / JSON-string-out function. stryke's FFI bridge resolves the symbols listed in stryke.toml's [ffi] table on first use Zmq, passes a JSON-encoded args dict per call, and copies the returned JSON into a stryke string. Allocations are freed via stryke_free_cstring.

# a handler error becomes a stryke die
{"error": "Zmq::recv: ..."}

# a receive timeout becomes undef / empty-list in the wrapper
{"timeout": true}

A handler that panics is caught at the boundary and returned as an error rather than crossing the FFI boundary and aborting the host shell.

Troubleshooting

Layout

stryke-zmq/
├── Cargo.toml             # cdylib crate (zmq -> vendored libzmq)
├── src/lib.rs             # zmq__* exports + socket registry + tests
├── stryke.toml            # package manifest + [ffi] table
├── lib/Zmq.stk            # stryke wrapper (use Zmq)
├── examples/              # req_rep, pub_sub, push_pull, multipart
├── t/                     # stryke assertion suites
├── tests/                 # docs/readme/polish lint gates
├── Makefile               # `make install` builds + installs
└── docs/                  # this site (GitHub Pages)

Sibling packages

Part of the stryke package family. Browse the others via the MenkeTechnologiesMeta umbrella repo:

• stryke-arrow — Apache Arrow / Parquet / Feather
• stryke-aws — S3, DynamoDB, SQS, Lambda, STS
• stryke-azure — Blob, Queues, Cosmos DB, Key Vault, Entra
• stryke-clickhouse — ClickHouse
• stryke-demo — live demos for every connector
• stryke-docker — Docker daemon API
• stryke-duckdb — embedded DuckDB SQL engine
• stryke-email — email + campaign client
• stryke-fleet — parallel expect/PTY automation
• stryke-gcp — Cloud Storage, Pub/Sub, Secret Manager, BigQuery, Firestore
• stryke-grpc — reflection-based gRPC client
• stryke-gui — mouse / keyboard / screen / clipboard automation
• stryke-k8s — Kubernetes
• stryke-kafka — Apache Kafka
• stryke-mcpd — MCP servers without a runtime
• stryke-mongo — MongoDB
• stryke-mssql — Microsoft SQL Server
• stryke-mysql — MySQL / MariaDB
• stryke-neo4j — Neo4j graph (Bolt)
• stryke-office — Office docs / PDF / images
• stryke-parquet — Parquet file inspector
• stryke-polars — Polars + ndarray + linalg + FFT
• stryke-postgres — PostgreSQL
• stryke-redis — Redis / Valkey
• stryke-scrape — web scraping / crawling
• stryke-scylla — ScyllaDB / Cassandra
• stryke-search — Elasticsearch / OpenSearch
• stryke-selenium — browser automation (WebDriver)
• stryke-spark — Spark Connect (no JVM)
• stryke-utils — pure-stryke utility belt