mq-bridge-py-basic 0.3.0__tar.gz → 0.3.1__tar.gz

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/.github/workflows/publish-node.yml

@@ -10,11 +10,12 @@ name: Publish Node Package
 # RHEL 9 (glibc 2.34), Debian 11/12 and Ubuntu 20.04+ — covering the priority
 # server targets. macOS/Windows build natively.
 #
-# Auth: token-or-OIDC. If the `NPM_TOKEN` secret is set it is used (needed for the
-# one-time bootstrap that creates the 5 platform packages, since npm has no
-# pending-publisher concept). Once all six packages exist and trusted publishing
-# is configured for them, remove the secret and publishing continues via OIDC
-# (id-token) with provenance — no token.
+# Auth: OIDC trusted publishing. The one-time bootstrap (which used an NPM_TOKEN
+# secret to create the 5 platform packages, since npm has no pending-publisher
+# concept) is done; all six packages exist with trusted publishing configured, so
+# publishing runs via OIDC (id-token) with provenance — no token. We deliberately
+# do NOT read NPM_TOKEN: a present-but-expired secret would be sent to the registry
+# and 401 instead of falling back to OIDC, so the credential is left out entirely.
 
 on:
   release:
@@ -67,6 +68,9 @@ jobs:
         env:
           CARGO_NET_RETRY: "5"
           CARGO_NET_GIT_FETCH_WITH_CLI: "true"
+          # curl's HTTP/2 multiplexing flakes on Windows runners ("[55] Failed
+          # sending data to the peer"); force HTTP/1.1 so fetches are reliable.
+          CARGO_HTTP_MULTIPLEXING: "false"
         run: >-
           npx napi build --platform --release --strip
           --target ${{ matrix.target }}
@@ -129,6 +133,9 @@ jobs:
         env:
           CARGO_NET_RETRY: "5"
           CARGO_NET_GIT_FETCH_WITH_CLI: "true"
+          # curl's HTTP/2 multiplexing flakes on Windows runners ("[55] Failed
+          # sending data to the peer"); force HTTP/1.1 so fetches are reliable.
+          CARGO_HTTP_MULTIPLEXING: "false"
         run: >-
           npx napi build --platform --release --strip
           --target ${{ matrix.target }}
@@ -220,8 +227,7 @@ jobs:
       - name: Publish platform packages and root
         working-directory: node/mq-bridge-node
         env:
-          # Empty when the secret is unset -> npm falls back to OIDC.
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # No NODE_AUTH_TOKEN: publishing is OIDC-only (trusted publishing).
           NPM_CONFIG_PROVENANCE: "true"
         run: |
           set -e

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/Cargo.lock

@@ -3082,7 +3082,7 @@ dependencies = [
 
 [[package]]
 name = "mq-bridge"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "anyhow",
  "arc-swap",
@@ -3147,20 +3147,32 @@ dependencies = [
  "zeromq",
 ]
 
+[[package]]
+name = "mq-bridge-bindings-common"
+version = "0.3.1"
+dependencies = [
+ "anyhow",
+ "fast-uuid-v7",
+ "mq-bridge",
+ "serde",
+ "serde_yaml_ng",
+ "tokio",
+]
+
 [[package]]
 name = "mq-bridge-node"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "anyhow",
  "async-trait",
  "bytes",
  "fast-uuid-v7",
  "mq-bridge",
+ "mq-bridge-bindings-common",
  "napi",
  "napi-build",
  "napi-derive",
  "schemars",
- "serde",
  "serde_json",
  "serde_yaml_ng",
  "tokio",
@@ -3169,13 +3181,14 @@ dependencies = [
 
 [[package]]
 name = "mq-bridge-py"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "anyhow",
  "async-trait",
  "bytes",
  "fast-uuid-v7",
  "mq-bridge",
+ "mq-bridge-bindings-common",
  "pyo3",
  "rustls 0.23.40",
  "schemars",

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/Cargo.toml

@@ -12,11 +12,11 @@ keywords = ["messaging", "kafka", "nats", "amqp", "cqrs"]
 categories = ["asynchronous", "network-programming"]
 
 [workspace]
-members = ["python/mq-bridge-py"]
+members = ["bindings-common", "python/mq-bridge-py"]
 resolver = "2"
 
 [workspace.package]
-version = "0.3.0"
+version = "0.3.1"
 
 [workspace.dependencies]
 anyhow = "1.0"

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mq-bridge-py-basic
-Version: 0.3.0
+Version: 0.3.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -38,12 +38,14 @@ Memory and file endpoints are always present in both packages. Use `mq-bridge-py
 
 The public API stays close to mq-bridge itself:
 
-- `Route.from_yaml(path, name)` loads one named route from a YAML file
-- `Route.from_yaml_str(text, name)` / `Route.from_config(mapping, name)` build a route from an in-memory YAML string or a Python `dict`, no file required
+- `Route.from_file(path, name=None)` loads a route from a YAML/JSON file. The three constructors differ only by source: `from_file` (path), `from_str` (in-memory YAML/JSON string), `from_config` (Python `dict`)
+- The `name` is optional: pass it to pick one entry out of a `routes:`/`publishers:` document, or omit it to treat the whole config as a single bare route/endpoint body
 - `Route.with_handler(...)` attaches a raw `Message` handler, with lazy `json()`/`text()` readers and `with_json()`/`with_payload()` response helpers
 - `Route.add_handler(kind, ...)` uses mq-bridge's `kind` dispatch and delivers decoded JSON
 - `RetryableError` and `NonRetryableError` let Python handlers signal retry intent
-- `Publisher.from_yaml(path, name)` (plus `from_yaml_str` / `from_config`) loads one named publisher
+- `Publisher.from_file(path, name=None)` (plus `from_str` / `from_config`) builds a publisher endpoint
+
+`from_yaml` / `from_yaml_str` remain as deprecated aliases for `from_file` / `from_str`.
 - `Publisher.send_json(...)` and `Publisher.request_json(...)` serialize Python JSON values in Rust
 
 The Python surface is synchronous and blocking. Tokio, broker I/O, routing, and batching all stay in Rust.
@@ -53,10 +55,10 @@ The Python surface is synchronous and blocking. Tokio, broker I/O, routing, and
 `mq-bridge-app` can create and test route and endpoint JSON/YAML through its UI.
 It does not replace your Python code or handlers, but it is useful when you want
 a known-good connection and route shape before pasting the configuration into
-Python. Load the generated config with `Route.from_config`, `Route.from_yaml`,
-`Publisher.from_config`, or `Publisher.from_yaml`.
+Python. Load the generated config with `Route.from_config`, `Route.from_file`,
+`Publisher.from_config`, or `Publisher.from_file`.
 
-For the `from_config` / `from_yaml_str` mappings, `mq_bridge.config` ships
+For the `from_config` / `from_str` mappings, `mq_bridge.config` ships
 `TypedDict` definitions so editors autocomplete the config keys (`input`,
 `output`, `batch_size`, every transport config, middleware, …):
 
@@ -117,6 +119,91 @@ with Route.from_config(config, "orders_route").with_handler(handle):
 Configuration/connection errors surface from `start()` itself, not from a
 background thread. `run()` remains available for the blocking single-route case.
 
+## Pull-based consumer
+
+`Route` is push-based: you attach a handler and the route drives it. When you
+instead want to **pull** messages on your own schedule — e.g. to feed a
+generator-style sink such as a [`dlt`](https://dlthub.com) resource — use
+`Consumer`. It wraps any input endpoint and hands batches back to Python:
+
+```python
+from mq_bridge import Consumer
+
+consumer = Consumer.from_config({"nats": {"subject": "orders", "url": "nats://localhost:4222"}})
+
+while not consumer.exhausted:
+    batch = consumer.poll(max=500, timeout_ms=1000)   # [] on timeout
+    if not batch:
+        continue
+    for message in batch:
+        handle(message.json())
+    consumer.commit()                                 # ack only after handling
+```
+
+`poll()` receives up to `max` messages **without** acknowledging them;
+`commit()` acks every batch returned since the last commit, advancing the
+consumer offset (or removing them from the queue). Committing only after the
+downstream write succeeds gives at-least-once delivery: a crash before `commit()`
+re-delivers the batch. `poll()` returns `[]` once `timeout_ms` elapses with
+nothing received (omit it to block until a message arrives), and sets
+`exhausted` once a bounded source (e.g. a file) is fully drained — streaming
+brokers never set it.
+
+> **You must call `commit()` — it is not optional.** It is the only thing that
+> tells the broker a batch is done. If you keep polling without committing:
+> - the consumer offset never advances, so every message is **re-delivered** on
+>   the next run (and you reprocess from the start);
+> - most brokers stop sending once their unacknowledged/prefetch window fills, so
+>   `poll()` eventually **stalls** and returns nothing;
+> - the uncommitted batches are held in memory pending their ack, so the process
+>   **grows unbounded**.
+>
+> Commit after each batch you have durably handled (as in the loops above). If a
+> batch fails downstream, simply *don't* commit it — it will be redelivered.
+
+`consumer.status()` returns a snapshot dict (`healthy`, `target`, `pending`,
+`capacity`, `error`, `details`). `pending` is the broker backlog/lag where the
+transport reports it — Kafka offset lag, AMQP queue depth, NATS JetStream
+`num_pending` — so `pending == 0` is a precise "caught up" check for a bounded
+drain; it is `None` where the broker exposes no backlog (core NATS, MQTT), where
+you fall back to a `timeout_ms` that returns `[]`. It's a point-in-time snapshot,
+not a guarantee.
+
+`consumer.close()` releases the broker connection; it's idempotent, and `poll()`
+/`status()` raise afterwards. Python is garbage-collected, so close explicitly
+(or use the context-manager form, which closes on exit) rather than relying on
+the object being collected:
+
+```python
+with Consumer.from_config(cfg) as consumer:
+    batch = consumer.poll(max=500, timeout_ms=1000)
+    ...
+    consumer.commit()
+# connection released here
+```
+
+The endpoint config decides durability exactly as a route input does: a
+consumer-group config resumes from the last commit, a subscriber config receives
+only new messages. `Consumer.from_file` / `from_str` accept the same shapes,
+plus a named entry under a `consumers:` document section.
+
+As a `dlt` resource this is a few lines:
+
+```python
+import dlt
+from mq_bridge import Consumer
+
+@dlt.resource(name="orders")
+def orders():
+    consumer = Consumer.from_config({"nats": {"subject": "orders", "url": "nats://localhost:4222"}})
+    while not consumer.exhausted:
+        batch = consumer.poll(max=500, timeout_ms=1000)
+        if not batch:
+            break                 # nothing more pending this run
+        yield [m.json() for m in batch]
+        consumer.commit()
+```
+
 ## Tuning (environment variables)
 
 These knobs are read from the environment at startup:

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/README.md

@@ -20,6 +20,28 @@
 It is not only a forwarder. A route can transform, filter, fan out, retry, rate-limit, deduplicate, or turn a request into a response before the message reaches the next system. The core is built on Tokio and keeps the transport details at the edge, so application code can mostly work with `CanonicalMessage`s and handlers.
 
 
+## Language Bindings
+
+`mq-bridge` is a Rust library, but the same engine ships as native bindings for **Python** and **Node.js**. The Tokio runtime, broker I/O, routing, and batching all stay in Rust; the binding is a thin layer for handlers and configuration.
+
+| Language | Package | Install |
+| :--- | :--- | :--- |
+| Rust | [`mq-bridge`](https://crates.io/crates/mq-bridge) | `cargo add mq-bridge` |
+| Python | [`mq-bridge-py`](python/mq-bridge-py/README.md) ([PyPI](https://pypi.org/project/mq-bridge-py/)) | `pip install mq-bridge-py` |
+| Node.js | [`mq-bridge`](node/mq-bridge-node/README.md) ([npm](https://www.npmjs.com/package/mq-bridge)) | `npm install mq-bridge` |
+
+The constructor names are kept aligned across languages, so a config loader reads the same in either binding (Python uses `snake_case`, Node uses `camelCase`):
+
+- `Route.from_file` / `Route.fromFile` — load a route from a YAML/JSON file
+- `Route.from_str` / `Route.fromStr` — load from an in-memory YAML/JSON string
+- `Route.from_config` / `Route.fromConfig` — load from a dict / JS object
+- the matching `Publisher.*` constructors build a publisher endpoint
+
+The `name` argument is optional in both: pass it to select one entry from a `routes:`/`publishers:` document, or omit it to treat the config as a single bare route/endpoint body.
+
+The Python binding also holds up well under load on the third-party [http-arena.com](https://www.http-arena.com/#sort=rps:-1&q=python) requests-per-second HTTP benchmark (live leaderboard — rankings shift over time). See [the Python analysis notes](python/mq-bridge-py/README.md#analysis) for the local HTTP comparison harness.
+
+
 ## Architecture
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for a detailed overview of the internal design, extensibility, and usage patterns.
@@ -161,7 +183,7 @@ https://github.com/marcomq/mq-bridge-app
 
 `mq-bridge-app` can be used to create and test route and endpoint configurations through a UI. The generated JSON/YAML can then be copied into an application and loaded by the Rust library or the Python bindings.
 
-This does not replace application code or handlers, but it is useful when you want a known-good connection and route shape before pasting the configuration into code. For Python projects, routes and publishers are commonly loaded from JSON/YAML with `Route.from_config`, `Route.from_yaml`, `Publisher.from_config`, or `Publisher.from_yaml`.
+This does not replace application code or handlers, but it is useful when you want a known-good connection and route shape before pasting the configuration into code. For Python and Node projects, routes and publishers are commonly loaded from JSON/YAML with `Route.from_file`/`fromFile` (a file path) and `Route.from_str`/`fromStr` (a JSON/YAML string), while `Route.from_config`/`fromConfig` takes an already-parsed dict/JS object. The matching `Publisher.*` constructors work the same way.
 
 ### Programmatic Handlers
 

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/benches/performance_bench.rs

@@ -190,7 +190,7 @@ pub mod kafka_helper {
             group_id: Some("perf_test_group_kafka".to_string()),
             topic: Some(topic.to_string()),
             producer_options: Some(vec![
-                ("queue.buffering.max.ms".to_string(), "50".to_string()), // Linger for 50ms to batch messages
+                ("queue.buffering.max.ms".to_string(), "1".to_string()), // Small linger; send_batch already enqueues a burst
                 ("acks".to_string(), "1".to_string()), // Wait for leader ack, a good balance
                 ("compression.type".to_string(), "snappy".to_string()), // Use snappy compression
             ]),

mq_bridge_py_basic-0.3.1/bindings-common/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "mq-bridge-bindings-common"
+version.workspace = true
+edition = "2021"
+publish = false
+description = "Shared config-loading and message helpers for the mq-bridge Python and Node bindings"
+license = "MIT"
+repository = "https://github.com/marcomq/mq-bridge"
+
+[lib]
+doctest = false
+
+[dependencies]
+anyhow.workspace = true
+fast-uuid-v7.workspace = true
+mq-bridge = { path = "..", default-features = false }
+serde = { workspace = true, features = ["derive"] }
+serde_yaml_ng.workspace = true
+tokio = { workspace = true, features = ["rt-multi-thread"] }

mq_bridge_py_basic-0.3.1/bindings-common/src/lib.rs

@@ -0,0 +1,308 @@
+//! Shared helpers for the mq-bridge language bindings (Python and Node).
+//!
+//! Both bindings used to carry their own copies of the config-document loading
+//! and route/publisher resolution logic. Those copies drifted (array-publisher
+//! support, default-name format, and where the `config:` root gets unwrapped all
+//! diverged), so the logic lives here once. Each binding keeps only its
+//! `#[pyo3]` / `#[napi]` wrappers and maps these `anyhow::Result`s to its native
+//! error type at the boundary.
+
+use std::collections::HashMap;
+use std::fs;
+use std::path::Path;
+
+use anyhow::Context;
+use mq_bridge::models::{Endpoint, PublisherConfig};
+use mq_bridge::Route;
+use serde::Deserialize;
+use tokio::runtime::{Builder, Runtime};
+
+/// A parsed `routes:` + `publishers:` configuration document.
+pub struct ConfigDocument {
+    pub routes: HashMap<String, Route>,
+    pub publishers: PublisherConfig,
+}
+
+/// One entry of a `publishers:` array (`- name: ... endpoint: ...`).
+#[derive(Debug, Deserialize)]
+struct NamedPublisher {
+    name: String,
+    endpoint: Endpoint,
+}
+
+/// Build the multi-threaded Tokio runtime the bindings drive their transports
+/// on.
+pub fn build_runtime() -> anyhow::Result<Runtime> {
+    Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .context("failed to build Tokio runtime")
+}
+
+/// Read and parse a YAML/JSON config file, unwrapping a `config:` export root
+/// if present.
+pub fn load_config_value(path: &Path) -> anyhow::Result<serde_yaml_ng::Value> {
+    let raw = fs::read_to_string(path)
+        .with_context(|| format!("failed to read config from {}", path.display()))?;
+    let value = serde_yaml_ng::from_str(&raw).context("failed to parse YAML config")?;
+    Ok(unwrap_config_root(value))
+}
+
+/// Load a named route from a config file.
+pub fn load_named_route(path: &Path, name: Option<&str>) -> anyhow::Result<Route> {
+    named_route_from_value(load_config_value(path)?, name)
+}
+
+/// Resolve a route from a config value. When `name` is `Some`, look it up in a
+/// `routes:` document (falling back to a single-route body). When `name` is
+/// `None`, the value must be a single bare route body. A `config:` export root
+/// is unwrapped first, so file, string, and mapping inputs behave identically.
+pub fn named_route_from_value(
+    value: serde_yaml_ng::Value,
+    name: Option<&str>,
+) -> anyhow::Result<Route> {
+    let value = unwrap_config_root(value);
+    if let Some(name) = name {
+        if let Ok(document) = load_document_from_value(value.clone()) {
+            if let Some(route) = document.routes.get(name).cloned() {
+                return Ok(route);
+            }
+        }
+    }
+
+    serde_yaml_ng::from_value(value).with_context(|| match name {
+        Some(name) => format!(
+            "No route named '{name}' found, and the config could not be parsed as a single route"
+        ),
+        None => "config could not be parsed as a single route body".to_string(),
+    })
+}
+
+/// Load a named publisher endpoint from a config file.
+pub fn load_named_publisher(path: &Path, name: Option<&str>) -> anyhow::Result<Endpoint> {
+    named_publisher_from_value(load_config_value(path)?, name)
+}
+
+/// Resolve a publisher endpoint from a config value. Mirrors
+/// [`named_route_from_value`]: name lookup in a `publishers:` document with a
+/// single-endpoint-body fallback, and a `config:` root unwrapped first.
+pub fn named_publisher_from_value(
+    value: serde_yaml_ng::Value,
+    name: Option<&str>,
+) -> anyhow::Result<Endpoint> {
+    let value = unwrap_config_root(value);
+    if let Some(name) = name {
+        if let Ok(document) = load_document_from_value(value.clone()) {
+            if let Some(endpoint) = document.publishers.get(name).cloned() {
+                return Ok(endpoint);
+            }
+        }
+    }
+
+    serde_yaml_ng::from_value(value).with_context(|| match name {
+        Some(name) => format!(
+            "No publisher named '{name}' found, and the config could not be parsed as a single publisher endpoint"
+        ),
+        None => "config could not be parsed as a single endpoint body".to_string(),
+    })
+}
+
+/// Load a named consumer endpoint from a config file.
+pub fn load_named_consumer(path: &Path, name: Option<&str>) -> anyhow::Result<Endpoint> {
+    named_consumer_from_value(load_config_value(path)?, name)
+}
+
+/// Resolve a consumer (input) endpoint from a config value. Mirrors
+/// [`named_publisher_from_value`]: when `name` is `Some`, look it up in a
+/// `consumers:` section; otherwise (or on a miss) parse the value as a single
+/// bare endpoint body. A `config:` export root is unwrapped first.
+pub fn named_consumer_from_value(
+    value: serde_yaml_ng::Value,
+    name: Option<&str>,
+) -> anyhow::Result<Endpoint> {
+    let value = unwrap_config_root(value);
+    if let Some(name) = name {
+        if let Some(map) = value.as_mapping() {
+            if let Some(section) = map.get(serde_yaml_ng::Value::String("consumers".to_string())) {
+                if let Ok(consumers) =
+                    serde_yaml_ng::from_value::<HashMap<String, Endpoint>>(section.clone())
+                {
+                    if let Some(endpoint) = consumers.get(name) {
+                        return Ok(endpoint.clone());
+                    }
+                }
+            }
+        }
+    }
+
+    serde_yaml_ng::from_value(value).with_context(|| match name {
+        Some(name) => format!(
+            "No consumer named '{name}' found, and the config could not be parsed as a single consumer endpoint"
+        ),
+        None => "config could not be parsed as a single endpoint body".to_string(),
+    })
+}
+
+/// Parse a value that may be a `{routes, publishers}` document, a bare
+/// `{name: route}` map, or (without those sections) a plain route map.
+pub fn load_document_from_value(value: serde_yaml_ng::Value) -> anyhow::Result<ConfigDocument> {
+    let value = unwrap_config_root(value);
+    let section_key = |name: &str| serde_yaml_ng::Value::String(name.to_string());
+    let routes_key = section_key("routes");
+    let publishers_key = section_key("publishers");
+
+    if let Some(map) = value.as_mapping() {
+        if map.contains_key(&routes_key) || map.contains_key(&publishers_key) {
+            let routes = map
+                .get(&routes_key)
+                .map_or_else(
+                    || Ok(HashMap::new()),
+                    |section| serde_yaml_ng::from_value(section.clone()),
+                )
+                .context("failed to parse 'routes' section")?;
+            let publishers = map.get(&publishers_key).map_or_else(
+                || Ok(PublisherConfig::new()),
+                |section| parse_publishers_section(section.clone()),
+            )?;
+            return Ok(ConfigDocument { routes, publishers });
+        }
+    }
+
+    let routes = serde_yaml_ng::from_value(value).context("failed to parse YAML as a route map")?;
+    Ok(ConfigDocument {
+        routes,
+        publishers: PublisherConfig::new(),
+    })
+}
+
+/// Parse a `publishers:` section, accepting either a `{name: endpoint}` map or a
+/// `[{name, endpoint}]` array.
+pub fn parse_publishers_section(value: serde_yaml_ng::Value) -> anyhow::Result<PublisherConfig> {
+    match value {
+        serde_yaml_ng::Value::Mapping(_) => {
+            serde_yaml_ng::from_value(value).context("failed to parse 'publishers' section")
+        }
+        serde_yaml_ng::Value::Sequence(_) => {
+            let entries: Vec<NamedPublisher> = serde_yaml_ng::from_value(value)
+                .context("failed to parse 'publishers' array section")?;
+            let mut publishers = PublisherConfig::new();
+            for entry in entries {
+                if publishers.contains_key(&entry.name) {
+                    return Err(anyhow::anyhow!(
+                        "duplicate publisher name '{}' in 'publishers' array section",
+                        entry.name
+                    ));
+                }
+                publishers.insert(entry.name, entry.endpoint);
+            }
+            Ok(publishers)
+        }
+        other => Err(anyhow::anyhow!(
+            "failed to parse 'publishers' section: expected a map or array, got {other:?}"
+        )),
+    }
+}
+
+/// Strip a `config:` export root if present (e.g. an `mq-bridge-app` export),
+/// returning the inner document. Idempotent.
+fn unwrap_config_root(value: serde_yaml_ng::Value) -> serde_yaml_ng::Value {
+    if let Some(map) = value.as_mapping() {
+        let config_key = serde_yaml_ng::Value::String("config".to_string());
+        if let Some(config) = map.get(&config_key) {
+            return config.clone();
+        }
+    }
+    value
+}
+
+/// Map an optional name from a binding boundary to `None` when missing or empty,
+/// so callers can omit it (or pass `""`) to mean "no name".
+pub fn normalize_name(name: Option<&str>) -> Option<&str> {
+    name.filter(|n| !n.is_empty())
+}
+
+/// Generated identity for a route built without an explicit name.
+pub fn default_route_name() -> String {
+    format!("route-{}", fast_uuid_v7::gen_id())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // An mq-bridge-app export: a `config:` root wrapping a document whose
+    // `publishers:` section is an array (the two shapes that had drifted
+    // between the bindings).
+    const EXPORT: &str = r#"
+config:
+  publishers:
+    - name: incoming
+      endpoint:
+        memory:
+          topic: orders
+          capacity: 16
+  routes:
+    orders_route:
+      input:
+        memory:
+          topic: orders
+          capacity: 16
+      output:
+        response: {}
+"#;
+
+    fn yaml(s: &str) -> serde_yaml_ng::Value {
+        serde_yaml_ng::from_str(s).unwrap()
+    }
+
+    #[test]
+    fn publishers_section_accepts_array_and_map() {
+        let array = yaml("- name: out\n  endpoint:\n    memory:\n      topic: t\n");
+        assert!(parse_publishers_section(array).unwrap().contains_key("out"));
+
+        let map = yaml("out:\n  memory:\n    topic: t\n");
+        assert!(parse_publishers_section(map).unwrap().contains_key("out"));
+    }
+
+    #[test]
+    fn named_lookups_unwrap_config_export_root() {
+        // The `config:` root is unwrapped, the array publishers parsed, and the
+        // named entries resolved.
+        let route = named_route_from_value(yaml(EXPORT), Some("orders_route"));
+        assert!(route.is_ok(), "route: {:?}", route.err());
+
+        let publisher = named_publisher_from_value(yaml(EXPORT), Some("incoming"));
+        assert!(publisher.is_ok(), "publisher: {:?}", publisher.err());
+    }
+
+    #[test]
+    fn document_exposes_routes_and_publishers() {
+        let doc = load_document_from_value(unwrap_config_root(yaml(EXPORT))).unwrap();
+        assert!(doc.routes.contains_key("orders_route"));
+        assert!(doc.publishers.contains_key("incoming"));
+    }
+
+    #[test]
+    fn named_consumer_resolves_section_and_bare_body() {
+        // Named lookup in a `consumers:` section.
+        let doc = yaml("consumers:\n  orders:\n    memory:\n      topic: t\n      capacity: 16\n");
+        assert!(named_consumer_from_value(doc, Some("orders")).is_ok());
+
+        // Bare single-endpoint body (no name).
+        let bare = yaml("memory:\n  topic: t\n  capacity: 16\n");
+        assert!(named_consumer_from_value(bare, None).is_ok());
+
+        // A `config:` export root is unwrapped before the `consumers:` lookup.
+        let export = yaml(
+            "config:\n  consumers:\n    orders:\n      memory:\n        topic: t\n        capacity: 16\n",
+        );
+        assert!(named_consumer_from_value(export, Some("orders")).is_ok());
+    }
+
+    #[test]
+    fn normalize_name_treats_empty_as_none() {
+        assert_eq!(normalize_name(Some("x")), Some("x"));
+        assert_eq!(normalize_name(Some("")), None);
+        assert_eq!(normalize_name(None), None);
+    }
+}

{mq_bridge_py_basic-0.3.0 → mq_bridge_py_basic-0.3.1}/mq_bridge/__init__.py

@@ -1,4 +1,5 @@
 from ._mq_bridge import (
+    Consumer,
     MemoryDrainer,
     Message,
     NonRetryableError,
@@ -10,6 +11,7 @@ from ._mq_bridge import (
 )
 
 __all__ = [
+    "Consumer",
     "MemoryDrainer",
     "Message",
     "NonRetryableError",