ruststream 0.7.0

[workspace]
members = ["crates/ruststream-macros"]
# `templates/` holds cargo-generate scaffolds (rendered by `cargo generate`, not built here): their
# sources carry `{{project-name}}` placeholders that are not valid Rust/TOML until rendered, so they
# must stay out of the workspace. `exclude` alone is not enough: cargo's git-source package
# discovery ignores it and parses every `Cargo.toml` in the repository, which is why the scaffold
# manifests are named `Cargo.toml.liquid` (cargo-generate drops the suffix when it renders them).
exclude = ["templates"]

[workspace.package]
version = "0.7.0"
edition = "2024"
rust-version = "1.95"
license = "Apache-2.0"
repository = "https://github.com/powersemmi/ruststream"
authors = ["RustStream contributors"]

[[bin]]
name = "ruststream"
path = "src/bin/ruststream/main.rs"
required-features = ["cli"]

[[example]]
name = "macro_app"
required-features = ["macros", "memory"]

[[example]]
name = "otel_export"
required-features = ["otel", "macros", "memory", "json"]

[[example]]
name = "routed_service"
path = "examples/routed_service/main.rs"
required-features = ["macros", "memory", "json", "metrics", "asyncapi", "logging"]

[[example]]
name = "quickstart"
required-features = ["macros", "memory", "json"]

[[example]]
name = "threads"
required-features = ["macros", "memory", "json", "logging"]

# No codec feature in the list, and none missing: the message serializes itself, so the whole
# service builds with the codec layer switched off.
[[example]]
name = "protobuf"
required-features = ["macros", "memory"]

# The `manual_*` examples are the macro-free counterparts the guides show side by side with the
# macro form. They deliberately do not require the `macros` feature: that is what proves the
# hand-written path stands on its own.
[[example]]
name = "manual_quickstart"
path = "examples/manual/quickstart.rs"
required-features = ["memory", "json"]

# The counterpart of `protobuf` with the derives written out: no codec feature, and no `macros`
# either, which is what shows the lanes are public traits rather than macro-only sugar.
[[example]]
name = "manual_protobuf"
path = "examples/manual/protobuf.rs"
required-features = ["memory"]

[[example]]
name = "manual_tutorial"
path = "examples/manual/tutorial/main.rs"
required-features = ["memory", "json", "asyncapi"]

[[example]]
name = "manual_tutorial_first_app"
path = "examples/manual/tutorial/first_app.rs"
required-features = ["memory", "json", "asyncapi"]

[[example]]
name = "manual_tutorial_reply_app"
path = "examples/manual/tutorial/reply_app.rs"
required-features = ["memory", "json", "asyncapi"]

[[example]]
name = "manual_subscribers"
path = "examples/manual/subscribers.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_seek"
path = "examples/manual/seek.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_publishing"
path = "examples/manual/publishing.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_retry"
path = "examples/manual/retry.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_failure_policy"
path = "examples/manual/failure_policy.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_post_settle"
path = "examples/manual/post_settle.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_routing"
path = "examples/manual/routing.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_codecs"
path = "examples/manual/codecs.rs"
required-features = ["memory", "json", "cbor"]

[[example]]
name = "manual_custom_codec"
path = "examples/manual/custom_codec.rs"
required-features = ["memory", "json", "cbor"]

[[example]]
name = "manual_middleware"
path = "examples/manual/middleware.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_middleware_app_scope"
path = "examples/manual/middleware_app_scope.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_middleware_router_scope"
path = "examples/manual/middleware_router_scope.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_context"
path = "examples/manual/context.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_context_field"
path = "examples/manual/context_field.rs"

[[example]]
name = "manual_from_context"
path = "examples/manual/from_context.rs"
required-features = ["testing", "memory", "json"]

[[example]]
name = "manual_typed_headers"
path = "examples/manual/typed_headers.rs"
required-features = ["testing", "memory", "json", "asyncapi"]

[[example]]
name = "manual_ctx_extractor"
path = "examples/manual/ctx_extractor.rs"
required-features = ["testing", "memory", "json"]

[[example]]
name = "manual_lifespan"
path = "examples/manual/lifespan.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_asyncapi_http"
path = "examples/manual/asyncapi_http.rs"
required-features = ["memory", "asyncapi"]

[[example]]
name = "manual_metrics_http"
path = "examples/manual/metrics_http.rs"
required-features = ["memory", "metrics", "json"]

[[example]]
name = "manual_http_outbox"
path = "examples/manual/http_outbox.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_logging_middleware"
path = "examples/manual/logging_middleware.rs"
required-features = ["memory", "json", "logging"]

[[example]]
name = "manual_routed_service_orders"
path = "examples/manual/routed_service_orders.rs"
required-features = ["memory", "json"]

[[example]]
name = "manual_otel_export"
path = "examples/manual/otel_export.rs"
required-features = ["otel", "memory", "json"]

[[example]]
name = "tutorial"
path = "examples/tutorial/main.rs"
required-features = ["macros", "memory", "json", "asyncapi"]

[[example]]
name = "tutorial_first_app"
path = "examples/tutorial/first_app.rs"
required-features = ["macros", "memory", "json", "asyncapi"]

[[example]]
name = "tutorial_reply_app"
path = "examples/tutorial/reply_app.rs"
required-features = ["macros", "memory", "json", "asyncapi"]

[[example]]
name = "subscribers"
required-features = ["macros", "memory", "json"]

[[example]]
name = "seek"
required-features = ["macros", "memory", "json"]

[[example]]
name = "publishing"
required-features = ["macros", "memory", "json"]

[[example]]
name = "retry"
required-features = ["macros", "memory", "json"]

[[example]]
name = "failure_policy"
required-features = ["macros", "memory", "json"]

[[example]]
name = "post_settle"
required-features = ["macros", "memory", "json"]

[[example]]
name = "routing"
required-features = ["macros", "memory", "json"]

[[example]]
name = "codecs"
required-features = ["macros", "memory", "json", "cbor"]

[[example]]
name = "custom_codec"
required-features = ["macros", "memory", "json", "cbor"]

[[example]]
name = "middleware"
required-features = ["macros", "memory", "json"]

[[example]]
name = "middleware_app_scope"
required-features = ["macros", "memory", "json"]

[[example]]
name = "middleware_router_scope"
required-features = ["macros", "memory", "json"]

[[example]]
name = "context"
required-features = ["macros", "memory", "json"]

[[example]]
name = "context_field"

[[example]]
name = "from_context"
required-features = ["testing", "macros", "memory", "json"]

[[example]]
name = "typed_headers"
required-features = ["testing", "macros", "memory", "json", "asyncapi"]

[[example]]
name = "ctx_extractor"
required-features = ["testing", "macros", "memory", "json"]

[[example]]
name = "lifespan"
required-features = ["macros", "memory", "json"]

[[example]]
name = "asyncapi_http"
required-features = ["macros", "memory", "asyncapi"]

[[example]]
name = "metrics_http"
# `json` is load-bearing: the reply publisher needs a codec, so the example does not build
# without one. It compiled only because `json` is a default feature.
required-features = ["macros", "memory", "metrics", "json"]

[[example]]
name = "http_outbox"
required-features = ["macros", "memory", "json"]

[[example]]
name = "logging"
required-features = ["macros", "memory", "json", "logging"]

[[example]]
name = "logging_middleware"
required-features = ["macros", "memory", "json", "logging"]

[[example]]
name = "testing"
required-features = ["testing", "macros", "memory", "json"]

[[test]]
name = "app_dispatch"
required-features = ["memory", "json"]

[[test]]
name = "seek_api"
required-features = ["testing", "macros", "memory", "json"]

[[test]]
name = "asyncapi"
required-features = ["asyncapi", "memory", "macros"]

[[test]]
name = "batch_subscriber"
required-features = ["macros", "memory", "json", "testing"]

[[test]]
name = "codecs"
required-features = ["macros", "memory", "cbor", "msgpack"]

[[test]]
name = "composition_rules"
required-features = ["macros", "memory", "json", "testing"]

[[test]]
name = "conformance_self"
required-features = ["conformance", "memory"]

[[test]]
name = "failure_policy"
required-features = ["macros", "memory", "json"]

[[test]]
name = "from_context"
required-features = ["macros", "memory", "json", "testing"]

[[test]]
name = "ctx_extractor"
required-features = ["macros", "memory", "json", "testing"]

[[test]]
name = "macro_subscriber"
required-features = ["macros", "memory", "json"]

[[test]]
name = "metrics"
required-features = ["metrics", "memory", "json"]

[[test]]
name = "retry_semantics"
required-features = ["macros", "memory", "json"]

[[test]]
name = "scope_codec"
required-features = ["macros", "memory", "json"]

[[test]]
name = "router_include"
required-features = ["macros", "memory", "json"]

[[test]]
name = "router_publishing"
required-features = ["macros", "memory", "json"]

[[test]]
name = "workers"
required-features = ["macros", "memory", "json"]

[[test]]
name = "testing_harness"
required-features = ["testing", "macros", "memory", "json"]

[[test]]
name = "memory_routing"
required-features = ["testing", "macros", "memory", "json"]

[[test]]
name = "ui"
required-features = ["macros", "memory", "json"]

[package]
name = "ruststream"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
repository.workspace = true
authors.workspace = true
description = "Async messaging framework for Rust: broker-agnostic traits, router, codecs, and a conformance harness for broker authors."
readme = "README.md"
keywords = ["messaging", "async", "broker", "pubsub", "event-driven"]
categories = ["asynchronous", "network-programming"]

# The whole surface is behind additive features, and `default` is `json` alone, so a default build
# on docs.rs publishes a reference with the runtime, codec, AsyncAPI, metrics, testing and
# conformance modules missing - the ones the guides send readers to.
[package.metadata.docs.rs]
all-features = true

# The types from dependencies that the public API is allowed to name, checked by
# `cargo check-external-types` in CI. Every entry here is a version bump of that dependency
# turned into a breaking change for every broker crate downstream, so the list is the record of
# which ones that trade was accepted for. Paths are the internal ones the tool reports (it reads
# rustdoc JSON, not the re-export path), and a new leak is a compile error until it is either
# removed from the surface or argued for and added here.
[package.metadata.cargo_check_external_types]
allowed_external_types = [
    # Re-exported from the crate root so `#[subscriber]` and friends resolve without a second
    # dependency; the macro crate ships in lockstep with an exact pin.
    "ruststream_macros::*",
    # The message contract itself: a payload is whatever serde can carry, and the codecs are
    # generic over it. `serde_core` is where serde 1.0.229 moved the traits.
    "serde::*",
    "serde_core::*",
    # The payload container and the buffer handlers write into.
    "bytes::bytes::Bytes",
    "bytes::bytes_mut::BytesMut",
    # The owned string beside them: a header key and a message name are shared buffers, and the
    # type is in the signature that accepts one. `Str` is an alias, and the tool names the alias
    # where a signature spells it and the underlying type where an impl does, so both paths are
    # the same entry twice.
    "bytes_utils::string::Str",
    "bytes_utils::string::StrInner",
    # A Subscriber is a Stream: that is the core design decision, not an accident.
    "futures_core::stream::Stream",
    # `tokio::spawn` handles surface their join failure through the app lifecycle.
    "tokio::runtime::task::error::JoinError",
    # `MainRuntime` is the app's runtime as a handler reaches it: its `spawn` hands back tokio's
    # join handle, and `as_handle` is the runtime handle itself, the escape hatch for whatever
    # the two methods do not cover.
    "tokio::runtime::task::join::JoinHandle",
    "tokio::runtime::handle::Handle",
    # Optional-feature surfaces: each is the integration point the feature exists for, so the
    # foreign type is the API rather than an implementation detail leaking through it.
    "inventory::Collect",
    "schemars",
    "serde_json::error::Error",
    "serde_json::value::Value",
    "serde_norway::error::Error",
    "prometheus::errors::Error",
    "prometheus::registry::Registry",
    "tracing_subscriber::filter::directive::ParseError",
    "opentelemetry_otlp::exporter::ExporterBuildError",
    "opentelemetry_sdk::error::OTelSdkError",
    "opentelemetry_sdk::metrics::instrument::Instrument",
    "opentelemetry_sdk::metrics::instrument::Stream",
    "opentelemetry_sdk::metrics::meter_provider::SdkMeterProvider",
    "opentelemetry_sdk::trace::provider::SdkTracerProvider",
]

[features]
default = ["json"]
memory = []
conformance = ["testing"]
json = ["dep:serde_json"]
msgpack = ["dep:rmp-serde"]
cbor = ["dep:ciborium"]
macros = ["dep:ruststream-macros"]
asyncapi = ["json", "dep:schemars", "dep:serde_norway"]
metrics = ["dep:prometheus"]
logging = ["dep:tracing-subscriber"]
cli = ["dep:clap", "dep:anyhow"]
poll-diagnostics = ["dep:quanta", "dep:pin-project-lite"]
testing = ["dep:inventory", "tokio/test-util"]
otel = [
    "dep:opentelemetry",
    "dep:opentelemetry_sdk",
    "dep:opentelemetry-otlp",
    "dep:tracing-opentelemetry",
    "dep:tracing-subscriber",
]

[dependencies]
bytes = "1"
# The owned string of the message path: a `Bytes` with the UTF-8 invariant, so a name and a header
# key clone by reference count and can be sliced out of a buffer a broker already holds.
# 0.1.3 is the real floor: `Str::from_static`, which is how a constant key costs nothing, arrived
# there.
bytes-utils = "0.1.3"
futures = "0.3"
# The ring that feeds each dedicated thread of a `threads(n)` subscription: a preallocated SPSC
# ring whose push and pop are a store each. 0.3.5 is the release whose costs were read.
rtrb = "0.4.0"
# 1.0.69 is the real floor: the typed-headers deserializer names `BorrowedStrDeserializer` and
# forwards the 128-bit methods, both of which arrived there.
serde = { version = "1.0.69", features = ["derive"] }
thiserror = "2"

# 1.44 is the real floor: a `threads(n)` thread yields through `task::coop::consume_budget`, which
# landed there.
tokio = { version = "1.44", features = ["rt-multi-thread", "macros", "sync", "time", "signal"] }
# 0.7.10 is the real floor: `TaskTracker`, which the runtime uses to join spawned handlers,
# landed there, so nothing below it ever compiled here.
tokio-util = { version = "0.7.10", features = ["rt"] }
# 0.1.29 is the real floor: it is the first release whose own `tracing-core` bound reaches 0.1.21,
# where `Value` for `Option<T>` landed - the dispatch spans record optional fields.
tracing = "0.1.29"
# The cycle counter the poll-time diagnostics read: `rdtsc` on x86_64 with an invariant TSC, the
# system counter on aarch64, the monotonic clock elsewhere.
quanta = { version = "0.13.0", optional = true }
pin-project-lite = { version = "0.2", optional = true }

# Exact pin: the two crates release in lockstep and the proc-macro surface tracks the library
# release for release (a loose range let a partial `cargo update` pair a new core with an old
# macros crate and fail to compile). Bumped by the same edit as [workspace.package].version.
ruststream-macros = { version = "=0.7.0", path = "crates/ruststream-macros", optional = true }
# 0.3.22 is the real floor, not 0.3: `tracing-opentelemetry` 0.34 requires `^0.3.22`, so the
# `otel` feature never resolved anything lower, and the declared bound claimed years of releases
# that were never built against.
tracing-subscriber = { version = "0.3.22", features = ["env-filter"], optional = true }
serde_json = { version = "1", optional = true }
rmp-serde = { version = "1", optional = true }
# 0.2.1 is the real floor: the crate-root `into_writer`/`from_reader` re-exports the CBOR codec
# calls arrived in that release.
ciborium = { version = "0.2.1", optional = true }
prometheus = { version = "0.14", default-features = false, optional = true }
schemars = { version = "1", optional = true }
serde_norway = { version = "0.9", optional = true }
clap = { version = "4", features = ["derive"], optional = true }
# 1.0.1 is the real floor: `bail!` with a formatted message does not compile against 1.0.0.
anyhow = { version = "1.0.1", optional = true }
# 0.3.5 is the real floor: earlier 0.3 releases lose the broker registrations to a plain GNU ld,
# so the registry comes back empty and the harness reports no transport for a broker that did
# register. Development setups on mold or lld happen to hide it.
inventory = { version = "0.3.5", optional = true }
opentelemetry = { version = "0.33", default-features = false, features = ["trace", "metrics"], optional = true }
opentelemetry_sdk = { version = "0.33", default-features = false, features = ["trace", "metrics", "rt-tokio"], optional = true }
opentelemetry-otlp = { version = "0.33", default-features = false, features = ["grpc-tonic", "trace", "metrics"], optional = true }
tracing-opentelemetry = { version = "0.34", optional = true }

# One scenario per file; `benches/common` is the shared setup. `just bench` names them, so a new
# file is added in two places and `scripts/bench_results.py` fails loudly when one of them is
# missed.
[[bench]]
name = "consume_json"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "consume_json_kilobyte"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "consume_lane"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "consume_pool"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "consume_threads"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "middleware"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "batch"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "reply"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "reply_lending"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "out_slot"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "typed_headers_write"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "typed_headers_read"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "request_reply"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "retry_copy"
harness = false
required-features = ["memory", "json", "macros"]

[[bench]]
name = "wall_clock"
harness = false
required-features = ["memory", "json", "macros"]

[dev-dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
# Registrations on the manual path are documented by default, so an example's message types
# derive `JsonSchema` whether or not the example itself turns the `asyncapi` feature on (the
# crate re-exports `schemars` only under that feature).
schemars = "1"
# 1.49 for the tests alone: they tell the app's runtime from a dedicated thread's by
# `Handle::id`, which is stable from there on.
tokio = { version = "1.49", features = ["rt-multi-thread", "macros", "sync", "time", "net", "test-util"] }
axum = "0.8"
trybuild = "1"
# The one real generator behind `#[wire(prost)]`. It is a dev-dependency and nothing else: the
# shorthand expands to paths in this crate, so the only way to know the expansion type-checks
# against the real trait is to compile a message against it. No `prost-build` and no `protoc`:
# the test writes out what a generator's `message_attribute` config would have emitted.
prost = "0.14"
opentelemetry = { version = "0.33", default-features = false, features = ["trace", "metrics"] }
opentelemetry_sdk = { version = "0.33", default-features = false, features = ["trace", "metrics", "rt-tokio", "testing"] }
gungraun = "=0.20.0"
divan = "0.1.21"
# The poll-diagnostics suite reads the warning the way an operator does: as a formatted log line.
tracing-subscriber = { version = "0.3.22", default-features = false, features = ["fmt", "std"] }

# What ships is optimized across crate boundaries: the framework is generic to the point where a
# dispatch path is only as cheap as the inlining it gets, and a build that stops at each crate
# boundary is not the one to publish numbers from.
[profile.release]
lto = "fat"

# The benchmarks measure what ships, so they are built the way a release is: the profile inherits
# it whole, and the only addition is the line tables a profile needs to name functions. Debug
# information is metadata and changes no codegen decision.
[profile.bench]
inherits = "release"
debug = "line-tables-only"

[lints.rust]
unsafe_op_in_unsafe_fn = "deny"
unreachable_pub = "deny"
missing_docs = "deny"
missing_debug_implementations = "warn"
unused_qualifications = "warn"

[lints.clippy]
correctness = { level = "deny", priority = -1 }
suspicious = { level = "deny", priority = -1 }
perf = { level = "deny", priority = -1 }
pedantic = { level = "warn", priority = -1 }
nursery = { level = "warn", priority = -1 }
cargo = { level = "warn", priority = -1 }
module_name_repetitions = "allow"
missing_const_for_fn = "allow"
multiple_crate_versions = "allow"
redundant_pub_crate = "allow"