Skip to main content

onemessagebus

A terminal tailing a queue: three backlogged records land at once, then new ones append a line at a time as another process writes them — each an id, a kind, a message and the instant the bus stamped it

A typed NDJSON message bus for anything that speaks in events. One envelope, one filter grammar, payload bounds and redaction, a schema registry with version read-sets, and an emitter and reader over streams, generic over the vocabulary a consumer declares.

Two artifacts:

  • onemessagebus — the core library. It knows the shape of an envelope and none of the words: which sources exist, which label keys are reserved and which top-level dimensions an envelope carries are a Vocabulary's to declare. Open reserves nothing; a vocabulary of your own — declared in the program that owns it, never in the bus — is proven through the same conformance table.
  • onemessagebus, the binary — the command line the sections below show, over the registry, the schema cache, NDJSON streams, the inbox and durable queues kept on a transport a configuration names. The local transport keeps each queue as plain files in one directory, and a distributed one is a plugin rather than a consumer change.

Install the command line

pip install onemessagebus-cli          # PyPI wheel, no toolchain needed
npm install -g onemessagebus-cli       # npm launcher, no toolchain needed
cargo install --git https://github.com/nickderobertis/onemessagebus onemessagebus-cli --locked

docs/cli.md is the whole command line; docs/wire.md is the wire; docs/contract.md is the approved contract the consumers restate from.

Every picture below is a capture of that binary run against a fixture of the kind the end-to-end journeys stage, gated on its content hash so it cannot drift away from what the tool prints (screenshots/AGENTS.md). The prose around them is an introduction: docs/cli.md is the reference, and crates/onemessagebus-cli/tests/docs.rs holds this page's verbs, profiles, sample commands, and every flag it names beside a verb, to the binary itself.

Queues

A queue is a log a transport keeps, under a layout that says how its records are shaped, who may write them and what happens to one that is claimed. send appends, next claims, subscribe tails as it grows — the GIF above is subscribe on this queue — status reports, validate decides without appending and transports lists the kinds this build can open. A queue's hooks keep, change, reroute, drop or refuse each offered message before anything is appended. docs/queues.md, docs/hooks.md, docs/validators.md (deprecated in favour of hooks) and docs/transport.md are those stories.

A send printing the queue, byte position and id its record landed at; a claim printing that record back; then one counts line per queue — records, waiting, pending, abandoned, unread, dropped — each with its consumers' cursors indented beneath it

Ask, and the answer that echoes the correlation

ask raises a question and waits for the one reply that carries its correlation; reply is how another process gives it. What the picture shows is the shape of that wait: a correlation the moment the question is queued, then nothing at all, then the answer. docs/ask.md is the rest.

An ask printing correlation: c-… and then, after a lead answers from another shell, one JSON line whose answer is reply and whose reply record carries that same correlation

Streams

events emit appends one envelope to a stream file, events merge reads any number of them back as one ordered stream, and --filter narrows what comes out. Which source words an envelope may carry, and how its labels are typed, come from the vocabulary --profile names — --profile open (the default) is the one this binary links. docs/wire.md is the envelope.

Two NDJSON streams merged into one timestamp-ordered listing — a checkout's and a warehouse's envelopes interleaved, with labels, payload and an artifact reference — then the same merge narrowed by a filter to one source

$ echo '{"note":"hello"}' | onemessagebus events emit run.ndjson --kind note-left --stream s-1 --source billing --label tenant=acme
{"v":1,"ts":"2026-09-13T06:16:27.838Z","stream":"s-1","seq":1,"source":"billing","kind":"note-left","labels":{"tenant":"acme"},"payload":{"note":"hello"},"artifacts":[]}

Schemas

schema list is every id this build knows, schema check judges a payload against one, schema register records a document of your own and schema gen renders one back as JSON or as Rust. Under them, schemas and schemas clear|fetch are the cache a configuration's links resolve through. docs/schema-links.md is how a link and its pin work.

A listing of registered schema ids — the bus's own transport and resident protocols beside a linked bundle's desk and frame schemas — then a check refusing a record at /blocking and exiting 1

Serve a member protocol

serve answers a configured member protocol — serve --codec, one frame in and one response out — and serve --resident --socket instead holds the transport open and answers every capability over a unix socket, which is how both SDKs subscribe without spawning a process per call. deliver and inbox carried are the other side of that, for a receiver that is running and one that is not. docs/codecs.md and docs/inbox.md are those two.

A quote frame piped into a codec session and the response document it answered with, built from the frame's own fields

Exit codes are a contract

Three of them, and the table that assigns them is docs/cli.md's. What the picture shows is the shape a refusal takes when you meet one: a single line naming the verb, what was wrong with it, and where to read more.

A one-line refusal from onemessagebus ask — the verb, the invalid --timeout value it was given and a pointer to that verb's help — and the exit code 2 the shell then reports

Use the library

use onemessagebus::{Emitter, Filter, Labels, Matcher, Open, Source};
use serde_json::Map;

let emitter = Emitter::<Open>::new("billing-1", Source::from("billing"), Box::new(std::io::stdout()))
    .with_labels(Labels::new().with("tenant", "acme"))
    .with_filter(Filter {
        include: Vec::new(),
        exclude: vec![Matcher::new().kind("heartbeat")],
    });
let envelope = emitter.emit("invoice-issued", Map::new());
assert_eq!(envelope.seq, 1);

Every wire value is a Rust type with serde and schemars derivations, and the public API is stated in docs/contract.md.

Use the SDKs

pip install onemessagebus              # Python: import onemessagebus
npm install @onemessagebus/sdk         # TypeScript

Both are typed clients over the binary — one method per verb, message types declared as a Pydantic model or with Zod's defineMessage, subscriptions over a resident core — so a message defined in Python is validated by the Rust core and read typed in TypeScript. docs/sdk.md is the whole story.

Develop

just bootstrap   # from a clean clone
just check       # the deterministic gate: format, lint, tests incl. the binary journeys, docs, coverage
just gate        # check plus the diff-scoped LLM-judge tier; the bar before a push

AGENTS.md is the instruction layer; just --list is the command surface.

Metadata

Release files for onemessagebus-cli 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for onemessagebus-cli 0.10.0
File Actions
onemessagebus_cli-0.10.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for onemessagebus_cli-0.10.0-py3-none-win_amd64.whl
onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
onemessagebus_cli-0.10.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for onemessagebus_cli-0.10.0-py3-none-macosx_11_0_arm64.whl

Total release size: 19.1 MB

Release files / onemessagebus_cli-0.10.0-py3-none-win_amd64.whl

Download URL onemessagebus_cli-0.10.0-py3-none-win_amd64.whl
Size 4.9 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
aca01a583b5735dd0b8f9030de3a43d59cda4e7e090fd4b716085b22eb688224
BLAKE2b-256 checksum
How to use checksums
7640c99ad35978e08d0dffc107c037cc486cd93e083c503bd171bdfc44571d3a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 5.0 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
ed4ae85b57773ea65b633e35e37a86928c3882478e3d76494f99545ce3b17a4d
BLAKE2b-256 checksum
How to use checksums
a125d52d154612e81962e2f20db90961c622dcb0a027835cbc8b61d27100357a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL onemessagebus_cli-0.10.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 4.7 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
ae7423de4252ca0a740878487cb6e12a96e33ad2e87fac26bb0f0682cdbab309
BLAKE2b-256 checksum
How to use checksums
f446e5799aaab34a2701bba82ce0e79a6885979acbcb8921f8a754987d737e24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / onemessagebus_cli-0.10.0-py3-none-macosx_11_0_arm64.whl

Download URL onemessagebus_cli-0.10.0-py3-none-macosx_11_0_arm64.whl
Size 4.5 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
f9a4fe62d1cf7f96f829f2a0432917cccfa035ecb073ff1a57bd0eca1e4d28b6
BLAKE2b-256 checksum
How to use checksums
2bb2d89e2b9d02c794105a9d5732f02e8a82dc064a9dfa9ee22acf0e03c7f6c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for onemessagebus-cli 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page