mq-bridge-py-basic 0.4.6__tar.gz → 0.4.7__tar.gz

{mq_bridge_py_basic-0.4.6 → mq_bridge_py_basic-0.4.7}/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 All notable changes to `mq-bridge`. Newest first.
 
+## 0.4.7
+
+### Changed
+
+- **The startup failure message distinguishes its two causes.** A route that never became ready
+  reports `failed to start: did not become ready within {n}ms`; a route whose task ended before
+  signalling ready reports `failed to start: ended before it signalled ready (outcome: ...)`.
+  The second case returns immediately and never involved the timeout, so reporting it as one
+  sent the reader looking for a stall that never happened. Both now carry the cause the
+  reconnect loop recorded, which the old message dropped. Code matching on the old
+  `failed to start within {n}ms or encountered an error` text needs updating; the substring
+  `failed to start` is unchanged.
+
+### Fixed
+
+- **A route that ran to completion is no longer reported as one that failed to start.** The run
+  task signals ready before its consume loop, so a drain over a small source can reach its
+  terminal while that signal is still buffered — leaving the reconnect loop's `select!` with two
+  ready branches and free to take the terminal one, dropping the startup channel unread.
+  `Route::run()` then returned an error for a drain that had already written its output, and
+  `mqb copy --drain` exited non-zero on a successful copy. Both terminal arms now forward a
+  ready signal that was already emitted.
+
+- **A completed route reports the messages it dropped even after an earlier reconnect failure.**
+  The drop report was suppressed whenever `EndpointStatus::error` was already set, including by a
+  transient failure the route recovered from. Only a `Failed` route's cause now outranks it.
+
+- **A plugin endpoint that rejects its config no longer reconnects forever.** `create_consumer`
+  and `create_publisher` flattened the plugin's status into a bare message, and the reconnect
+  loop decides by downcasting to `ConsumerError`/`PublisherError` — so every failure to open
+  looked like a connection fault worth retrying. A plugin answering `MQB_ERR_INVALID_CONFIG`,
+  `MQB_ERR_UNSUPPORTED`, `MQB_ERR_PERMANENT` or `MQB_ERR_PANIC` now stops the route with that
+  cause; `MQB_ERR_CONNECTION` and `MQB_ERR_RETRYABLE` still get the reconnect loop.
+
+## 0.4.6
+
+### Added
+
+- **`filter` middleware.** Keeps only the messages matching an expression and drops the rest,
+  on the input or the output: `- filter: "amount > 100"`. Payload fields are read by bare name
+  (`amount`, `order.status`), metadata under `meta.` and always as text, so a numeric comparison
+  needs a cast (`number(meta.http_status_code) >= 400`); `&&`/`||` and `and`/`or` both work. A
+  metadata-only expression never parses the payload. **Prefer the input** — a filter there drops
+  the message before the rest of the route touches it and acks it at the source. Requires the
+  new `filter` feature (it pulls the `zen-expression` engine), which is part of `middleware` and
+  `full` but **not** of `portable`.
+
+- **Predicate mode for `switch`.** `when: [{ if, to }, ...]` routes on the same expression
+  language, first match wins, so overlapping thresholds are safe to write and a payload-derived
+  key no longer has to be promoted into metadata first. A `switch` uses exactly one of `when` or
+  `metadata_key`/`cases`; naming both or neither is a startup error, as is a `when` list in a
+  build without the `filter` feature. Value lookup stays the cheaper mode when the key is
+  already in metadata.
+
+- **`expression` on `transform`.** A Zen expression producing the output document, applied after
+  `mapping` and before `schema` — for values that have to be calculated rather than copied.
+  Needs the `zen` feature.
+
+- **A `fanout` can reply.** If one branch produces a response — a `response` or `static` leg, or
+  a `request` whose `forward_to` replies — that response goes back to the caller, so a
+  request/reply input can fan a message out and still answer. Only one branch may answer: if
+  several do, the first in list order wins, and the route warns once rather than on every
+  message. A branch that *fails* nacks the whole fan-out, so the caller gets a `500` rather than
+  an answer that hides a lost message; opt out per branch with a `request` whose `forward_to`
+  does not reply, or a `dlq` on a plain branch.
+
+- **`pass_through_status` on the `http` endpoint.** On a **publisher**, a non-2xx response
+  becomes response data instead of a publisher error, so a route can branch on
+  `http_status_code` with a `switch` rather than treating every 404 as a failed send. Transport
+  failures and unreadable responses are still errors. On a **consumer**, once every output sink
+  opts in, a transient sink failure answers the request with `502` instead of stopping and
+  reconnecting a non-streaming request/reply route. Composite outputs such as `fanout` need the
+  flag on every leaf sink — a mixed output keeps the normal stop-and-reconnect policy — and
+  streamable HTTP inputs keep their protocol-specific error frames.
+
+### Changed
+
+- **A middleware that empties a batch no longer acknowledges ahead of the route.** `filter` and
+  `deduplication` can filter a batch down to nothing, and acking that straight away jumps ahead
+  of batches the route is still writing on a source with cumulative acks — the ordered sequencer
+  only sees the commits `receive_batch` returns, so a crash in that window lost them. On those
+  sources the emptied batch's commit is now held and runs from inside the next retained batch's
+  commit, which the sequencer does order.
+
+- **An `object_store` sink on `name_by: auto` switches to `write_time` names when a row-dropping
+  middleware is on the route.** A source-range name covers one *contiguous* run of positions, so
+  a batch with holes punched in it would be written as one object per surviving run — a filter
+  keeping 80% of rows turns one upload into roughly a hundred. The route logs one line at
+  startup saying it made the switch. This covers `filter`, `deduplication`, `weak_join`,
+  `transform` with `on_error: reject`, and a `switch` in `when` mode with no `default`. Set
+  `name_by: source_position` explicitly to keep replay-safe names and accept the fragmentation.
+
+- **`filter` expressions and a `switch`'s `when` cases are compiled when the config is loaded.**
+  An invalid expression is now a startup error naming the expression, instead of a per-message
+  failure that only surfaces once traffic arrives.
+
+### Fixed
+
+- **`switch` forwards connect and disconnect hooks to its destinations**, `cases` and `default`
+  alike, and one failing teardown no longer skips the rest.
+
+- **A failed `request` whose `forward_to` answers the caller surfaces the error** instead of
+  echoing the original message back as a success. The route then nacks (HTTP `500`) and a
+  `retry` or `dlq` on the endpoint sees the failure as usual. Forwarding to a plain sink still
+  acks, so routing a status with a `switch` is unchanged.
+
+- **Concurrent MongoDB consumers no longer claim documents out from under each other.** Two
+  consumers polling within the same second write the same `locked_until`, which is all the claim
+  query had to work with, so one poll could read back documents another had just taken. Each
+  claim now carries a unique `claim_token`, and the read-back, unlock, ack and delete are all
+  scoped to it — an expired lease that was re-claimed elsewhere is no longer deleted from under
+  its new owner.
+
+## 0.4.5
+
+No library changes: CI workflow timeouts and a version bump.
+
 ## 0.4.4
 
 ### Breaking

{mq_bridge_py_basic-0.4.6 → mq_bridge_py_basic-0.4.7}/Cargo.lock

@@ -3439,7 +3439,7 @@ dependencies = [
 
 [[package]]
 name = "mq-bridge"
-version = "0.4.6"
+version = "0.4.7"
 dependencies = [
  "aes-gcm",
  "anyhow",
@@ -3524,7 +3524,7 @@ dependencies = [
 
 [[package]]
 name = "mq-bridge-bindings-common"
-version = "0.4.6"
+version = "0.4.7"
 dependencies = [
  "anyhow",
  "fast-uuid-v7",
@@ -3538,7 +3538,7 @@ dependencies = [
 
 [[package]]
 name = "mq-bridge-node"
-version = "0.4.6"
+version = "0.4.7"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -3580,7 +3580,7 @@ dependencies = [
 
 [[package]]
 name = "mq-bridge-py"
-version = "0.4.6"
+version = "0.4.7"
 dependencies = [
  "anyhow",
  "async-trait",

{mq_bridge_py_basic-0.4.6 → mq_bridge_py_basic-0.4.7}/Cargo.toml

@@ -16,7 +16,7 @@ members = ["bindings-common", "python/mq-bridge-py"]
 resolver = "2"
 
 [workspace.package]
-version = "0.4.6"
+version = "0.4.7"
 
 [workspace.dependencies]
 anyhow = "1.0"

{mq_bridge_py_basic-0.4.6 → mq_bridge_py_basic-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mq-bridge-py-basic
-Version: 0.4.6
+Version: 0.4.7
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3

{mq_bridge_py_basic-0.4.6 → mq_bridge_py_basic-0.4.7}/src/plugin/endpoint.rs

@@ -99,11 +99,16 @@ impl CustomEndpointFactory for PluginEndpointFactory {
             if status == MQB_OK {
                 Ok(AssertSend(out))
             } else {
-                Err(anyhow!(
+                // Classify rather than flattening to a string: a plugin that
+                // rejected its config reports MQB_ERR_INVALID_CONFIG, and the
+                // route only breaks out of its reconnect loop for the error
+                // classes it can downcast back out of this `anyhow`.
+                let cause = anyhow!(
                     "endpoint plugin `{}` could not open an input for route `{route}`: {}",
                     plugin.name(),
                     plugin.take_error(err)
-                ))
+                );
+                Err(anyhow::Error::new(consumer_error_from(status, cause)))
             }
         })
         .await
@@ -146,11 +151,13 @@ impl CustomEndpointFactory for PluginEndpointFactory {
             if status == MQB_OK {
                 Ok(AssertSend(out))
             } else {
-                Err(anyhow!(
+                // Classified for the same reason as the consumer side above.
+                let cause = anyhow!(
                     "endpoint plugin `{}` could not open an output for route `{route}`: {}",
                     plugin.name(),
                     plugin.take_error(err)
-                ))
+                );
+                Err(anyhow::Error::new(publisher_error_from(status, cause)))
             }
         })
         .await
@@ -513,7 +520,12 @@ fn publisher_error(
     err: MqbBuffer,
     action: &str,
 ) -> PublisherError {
-    let cause = plugin_cause(plugin, err, action);
+    publisher_error_from(status, plugin_cause(plugin, err, action))
+}
+
+/// The status-to-class half of [`publisher_error`], for callers that already
+/// turned the plugin's error buffer into a message.
+pub(super) fn publisher_error_from(status: MqbStatus, cause: anyhow::Error) -> PublisherError {
     match status {
         MQB_ERR_RETRYABLE => PublisherError::Retryable(cause),
         MQB_ERR_CONNECTION => PublisherError::Connection(cause),
@@ -545,4 +557,33 @@ mod tests {
             MQB_DISPOSITION_ACK
         );
     }
+
+    // A plugin that rejected its config must not look like a transient fault:
+    // `create_consumer`/`create_publisher` classify with these, and the route
+    // only stops reconnecting for the permanent classes.
+    #[test]
+    fn a_rejected_plugin_config_is_permanent_not_retryable() {
+        assert!(matches!(
+            consumer_error_from(MQB_ERR_INVALID_CONFIG, anyhow!("bad field")),
+            ConsumerError::Permanent(_)
+        ));
+        assert!(matches!(
+            publisher_error_from(MQB_ERR_INVALID_CONFIG, anyhow!("bad field")),
+            PublisherError::NonRetryable(_)
+        ));
+    }
+
+    // The other half of the contract: a connection failure stays retryable, so
+    // a broker that is merely down still gets the reconnect loop.
+    #[test]
+    fn a_plugin_connection_failure_stays_retryable() {
+        assert!(matches!(
+            consumer_error_from(MQB_ERR_CONNECTION, anyhow!("broker down")),
+            ConsumerError::Connection(_)
+        ));
+        assert!(matches!(
+            publisher_error_from(MQB_ERR_CONNECTION, anyhow!("broker down")),
+            PublisherError::Connection(_)
+        ));
+    }
 }

{mq_bridge_py_basic-0.4.6 → mq_bridge_py_basic-0.4.7}/src/route.rs

@@ -101,13 +101,14 @@ impl Drop for OutcomeGuard {
             RouteOutcome::Failed
         });
         // A route that discarded data did not run clean, whatever its outcome.
-        // Never overwrite a recorded failure cause: that one explains why the
-        // route stopped, which is the more urgent of the two.
+        // Only a `Failed` route's cause is kept over the drop report: it explains
+        // why the route stopped. On any other outcome a lingering `error` is a
+        // stale reconnect failure the route recovered from, so the drops win.
         {
             let drops = recover_read_lock(&self.drops, "route_drop_report");
             if drops.count > 0 {
                 let mut s = recover_write_lock(&self.status, "route_handle_status");
-                if s.error.is_none() {
+                if s.error.is_none() || !matches!(outcome, RouteOutcome::Failed) {
                     s.error = Some(format!(
                         "dropped {} message(s): sink rejected them permanently and no dlq middleware is configured: {}",
                         drops.count,
@@ -370,6 +371,25 @@ const DRAIN_MAX_RECONNECT_ATTEMPTS: usize = 10;
 /// never reported healthy on the strength of the connect alone.
 const STABLE_RUN: std::time::Duration = std::time::Duration::from_secs(30);
 
+/// Forward a ready signal the run task already emitted but the reconnect loop
+/// never observed.
+///
+/// The inner task signals ready onto a `bounded(1)` channel *before* its consume
+/// loop, so the signal sits buffered. A drain over a small source can then reach
+/// its terminal within the same scheduling window, leaving `select!` with two
+/// ready branches and free to pick the terminal one at random. Without this, a
+/// route that ran to completion is reported to `run()` as one that never started.
+async fn forward_buffered_ready(
+    startup_notified: &mut bool,
+    iter_ready_rx: &async_channel::Receiver<()>,
+    ready_tx: &Sender<()>,
+) {
+    if !*startup_notified && iter_ready_rx.try_recv().is_ok() {
+        let _ = ready_tx.send(()).await;
+        *startup_notified = true;
+    }
+}
+
 async fn pause_after_empty_batch(delay_ms: u64) {
     if delay_ms > 0 {
         tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
@@ -1094,6 +1114,7 @@ impl Route {
                             let _ = internal_shutdown_tx.send(()).await;
                             // Wait for the inner task to finish gracefully.
                             let _ = run_task.await;
+                            forward_buffered_ready(&mut startup_notified, &iter_ready_rx, &ready_tx).await;
                             outcome_guard.set(RouteOutcome::Stopped);
                             break 'reconnect;
                         }
@@ -1126,6 +1147,7 @@ impl Route {
                             // Keep waiting for the run result / shutdown.
                         }
                         res = &mut run_task => {
+                            forward_buffered_ready(&mut startup_notified, &iter_ready_rx, &ready_tx).await;
                             match res {
                                 Ok(Ok(should_continue)) if !should_continue => {
                                     info!("Route '{}' completed gracefully. Shutting down.", name);
@@ -1226,32 +1248,49 @@ impl Route {
             }
         });
 
-        match tokio::time::timeout(startup_timeout, ready_rx.recv()).await {
-            Ok(Ok(_)) => Ok(RouteHandle {
+        let started = tokio::time::timeout(startup_timeout, ready_rx.recv()).await;
+        if let Ok(Ok(_)) = started {
+            return Ok(RouteHandle {
                 handle,
                 shutdown_tx,
                 status,
                 outcome,
-            }),
-            _ => {
-                handle.abort();
-                // The startup failure itself stays inside the reconnect loop, so
-                // surface the cause it recorded rather than a bare timeout.
-                // "connecting" is the initial marker, not a recorded failure.
-                let cause = recover_read_lock(&status, "route_handle_status")
-                    .error
-                    .clone()
-                    .filter(|e| e != "connecting")
-                    .map(|e| format!(": {e}"))
-                    .unwrap_or_default();
-                Err(anyhow::anyhow!(
-                    "Route '{}' failed to start within {}ms or encountered an error{}",
+            });
+        }
+        handle.abort();
+        // The startup failure itself stays inside the reconnect loop, so
+        // surface the cause it recorded rather than a bare timeout.
+        // "connecting" is the initial marker, not a recorded failure.
+        let cause = recover_read_lock(&status, "route_handle_status")
+            .error
+            .clone()
+            .filter(|e| e != "connecting")
+            .map(|e| format!(": {e}"))
+            .unwrap_or_default();
+        Err(match started {
+            // Every `ready_tx` was dropped: the route task ended without ever
+            // signalling ready. That returns immediately, so calling it a timeout
+            // sends the reader after a stall that never happened.
+            Ok(Err(_)) => {
+                let terminal = *recover_read_lock(&outcome, "route_handle_outcome");
+                anyhow::anyhow!(
+                    "Route '{}' failed to start: ended before it signalled ready (outcome: {}){}",
                     name_str,
-                    startup_timeout.as_millis(),
+                    terminal.map_or("unknown", |o| match o {
+                        RouteOutcome::Completed => "completed",
+                        RouteOutcome::Stopped => "stopped",
+                        RouteOutcome::Failed => "failed",
+                    }),
                     cause
-                ))
+                )
             }
-        }
+            _ => anyhow::anyhow!(
+                "Route '{}' failed to start: did not become ready within {}ms{}",
+                name_str,
+                startup_timeout.as_millis(),
+                cause
+            ),
+        })
     }
 
     /// The core logic of running the route, designed to be called within a reconnect loop.
@@ -3556,6 +3595,44 @@ mod tests {
         assert_eq!(state.publisher_disconnects.load(Ordering::SeqCst), 1);
     }
 
+    #[tokio::test]
+    async fn test_forward_buffered_ready_delivers_a_signal_the_loop_never_observed() {
+        // The terminal arms of the reconnect loop can win the `select!` race against a
+        // ready signal the run task already buffered. Forwarding it from there is what
+        // keeps a route that ran to completion from being reported as one that never
+        // started.
+        let (iter_ready_tx, iter_ready_rx) = bounded::<()>(1);
+        let (ready_tx, ready_rx) = bounded::<()>(1);
+        iter_ready_tx.send(()).await.unwrap();
+
+        let mut startup_notified = false;
+        forward_buffered_ready(&mut startup_notified, &iter_ready_rx, &ready_tx).await;
+        assert!(startup_notified);
+        assert!(
+            ready_rx.try_recv().is_ok(),
+            "buffered ready must reach `run()`"
+        );
+
+        // `run()` consumes the startup channel once, so a second send would sit unread.
+        iter_ready_tx.send(()).await.unwrap();
+        forward_buffered_ready(&mut startup_notified, &iter_ready_rx, &ready_tx).await;
+        assert!(
+            ready_rx.try_recv().is_err(),
+            "startup must not be notified twice"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_forward_buffered_ready_keeps_a_never_ready_route_a_failure() {
+        let (_iter_ready_tx, iter_ready_rx) = bounded::<()>(1);
+        let (ready_tx, ready_rx) = bounded::<()>(1);
+
+        let mut startup_notified = false;
+        forward_buffered_ready(&mut startup_notified, &iter_ready_rx, &ready_tx).await;
+        assert!(!startup_notified);
+        assert!(ready_rx.try_recv().is_err());
+    }
+
     #[tokio::test]
     async fn test_start_fails_on_unavailable_endpoint() {
         // tokio::time::pause();
@@ -3582,8 +3659,54 @@ mod tests {
         // The route should fail to start because the input endpoint fails to create.
         // The run() method waits for a ready signal which never comes.
         let result = route.run("test_start_fail").await;
-        assert!(result.is_err());
-        assert!(result.unwrap_err().to_string().contains("failed to start"));
+        let err = result.expect_err("must fail").to_string();
+        // A stalled connect is a timeout, not a route that ended: the two now read
+        // differently, and the recorded cause rides along.
+        assert!(
+            err.contains("failed to start: did not become ready within 5000ms")
+                && err.contains("Endpoint unavailable"),
+            "got: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_start_failure_distinguishes_an_ended_route_from_a_timeout() {
+        // A drain gives up after DRAIN_MAX_RECONNECT_ATTEMPTS, so the route task ends
+        // long before the startup timeout. `ready_rx` then fails immediately, and
+        // calling that a 5000ms timeout sends the reader after a stall that never
+        // happened.
+        let factory_name = format!("ended_before_ready_{}", fast_uuid_v7::gen_id());
+        register_endpoint_factory(
+            &factory_name,
+            Arc::new(MockEndpointFactory {
+                create_consumer_fail: true,
+                ..MockEndpointFactory::new()
+            }),
+        )
+        .unwrap();
+
+        let input = Endpoint {
+            endpoint_type: EndpointType::Custom {
+                name: factory_name,
+                config: serde_json::Value::Null,
+            },
+            middlewares: vec![],
+            handler: None,
+        };
+        let route = Route::new(input, Endpoint::new_memory("out", 10))
+            .with_exit_on_empty(true)
+            .with_reconnect_interval_ms(1);
+
+        let err = route
+            .run("test_ended_before_ready")
+            .await
+            .expect_err("must fail")
+            .to_string();
+        assert!(
+            err.contains("failed to start: ended before it signalled ready")
+                && err.contains("outcome: failed"),
+            "got: {err}"
+        );
     }
 
     #[tokio::test]