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 judges without appending and transports lists the kinds this build can open. docs/queues.md, docs/validators.md 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 — 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.9.5

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.9.5
File Actions
onemessagebus_cli-0.9.5-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for onemessagebus_cli-0.9.5-py3-none-win_amd64.whl
onemessagebus_cli-0.9.5-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.9.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
onemessagebus_cli-0.9.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for onemessagebus_cli-0.9.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
onemessagebus_cli-0.9.5-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for onemessagebus_cli-0.9.5-py3-none-macosx_11_0_arm64.whl

Total release size: 18.7 MB

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

Download URL onemessagebus_cli-0.9.5-py3-none-win_amd64.whl
Size 4.8 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
69020946c76cada9276f8745bffc8cfe00a53b025f85752b1c14b6e9c1e97b34
BLAKE2b-256 checksum
How to use checksums
11e075f33f0e9f8f9d1b14719d0504fa75550a9a424ea2d801448c0e691175d0
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.9.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL onemessagebus_cli-0.9.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 4.9 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
56f01a8da9da90f23cc385904a0468ea845811df1375bf075324772bc46f6341
BLAKE2b-256 checksum
How to use checksums
cb62fc4a6ad5be3421c0e2ecd04b787d8b65ea73521269357cc3140df1d846fe
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.9.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL onemessagebus_cli-0.9.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 4.5 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
83eb9f2ad31ed2d34d92195ee5a3d5eedfb03d5156906f5d2ba7659add85bf1a
BLAKE2b-256 checksum
How to use checksums
801bd73e62cacad33e04c3b35565dcde0b1ba1b38058083ae74b96afa84a79ea
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.9.5-py3-none-macosx_11_0_arm64.whl

Download URL onemessagebus_cli-0.9.5-py3-none-macosx_11_0_arm64.whl
Size 4.4 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
21ad5b87b6261b737e64257e75c589eb26d8c73e185dc53c4bd0134a47ef0d3e
BLAKE2b-256 checksum
How to use checksums
dc0ba74be6d54497ca2fee242f91581b9e61a9eb915037ea925a3fee7ce6135e
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.9.5

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