apache-iggy 0.9.1.dev1__tar.gz → 0.9.1.dev3__tar.gz

{apache_iggy-0.9.1.dev1 → apache_iggy-0.9.1.dev3}/Cargo.toml

@@ -33,6 +33,7 @@ members = [
     "core/configs_derive",
     "core/connectors/runtime",
     "core/connectors/sdk",
+    "core/connectors/sinks/bigquery_sink",
     "core/connectors/sinks/clickhouse_sink",
     "core/connectors/sinks/delta_sink",
     "core/connectors/sinks/doris_sink",
@@ -52,6 +53,7 @@ members = [
     "core/connectors/sources/elasticsearch_source",
     "core/connectors/sources/http_source",
     "core/connectors/sources/influxdb_source",
+    "core/connectors/sources/mqtt_source",
     "core/connectors/sources/postgres_source",
     "core/connectors/sources/random_source",
     "core/consensus",
@@ -85,8 +87,9 @@ warnings = "deny"
 [workspace.dependencies]
 actix-cors = "0.7.2"
 actix-files = "0.7.0"
-actix-web = "4.15.0"
-aes-gcm = "0.11.1"
+actix-web = "4.16.0"
+aes-gcm = { version = "0.11.1", features = ["zeroize"] }
+aes-gcm-siv = { version = "0.12.1", features = ["zeroize"] }
 ahash = { version = "0.8.12", features = ["serde"] }
 aligned-vec = "0.6.4"
 anyhow = "1.0.104"
@@ -94,7 +97,7 @@ apache-avro = "0.22.0"
 apple-native-keyring-store = { version = "1.0.2", features = ["keychain"] }
 arc-swap = "1.9.2"
 argon2 = "0.6.0"
-# arrow 58: iceberg 0.10.1 and deltalake 0.32.4 still require it.
+# arrow 58: iceberg 0.10.1 still requires it.
 arrow = "58.4.0"
 arrow-array = "58.4.0"
 arrow-json = "58.4.0"
@@ -112,20 +115,21 @@ bench-dashboard-server = { path = "core/bench/dashboard/server" }
 bench-dashboard-shared = { path = "core/bench/dashboard/shared" }
 bench-report = { path = "core/bench/report" }
 bench-runner = { path = "core/bench/runner" }
+bigdecimal = "0.4.11"
 bit-set = "0.11.1"
 blake3 = "1.8.7"
-bon = "3.10.1"
+bon = "3.10.2"
 byte-unit = { version = "5.2.6", default-features = false, features = ["serde", "byte", "std"] }
 bytemuck = { version = "1.25", features = ["derive", "min_const_generics"] }
 bytes = "1.12.1"
 cfg_aliases = "0.2.2"
 charming = "0.6.0"
 chrono = { version = "0.4.45", features = ["serde"] }
-clap = { version = "4.6.6", features = ["derive", "wrap_help"] }
-clap_complete = "4.6.9"
+clap = { version = "4.6.7", features = ["derive", "wrap_help"] }
+clap_complete = "4.6.11"
 clock = { path = "core/clock" }
 colored = "3.1.1"
-comfy-table = { version = "8.0.0", default-features = false }
+comfy-table = { version = "8.0.1", default-features = false }
 compio = { version = "0.19.2", features = [
     "runtime",
     "macros",
@@ -160,11 +164,10 @@ cyper-axum = { version = "0.9.0" }
 cyper-core = { version = "0.9.0", default-features = false }
 darling = "0.24"
 dashmap = "6.2.1"
-deltalake = { version = "0.32.4", features = ["azure", "gcs", "s3"] }
-derive-new = "0.7.0"
+deltalake = { version = "1.1.1", features = ["azure", "gcs", "s3"] }
 derive_builder = "0.20.2"
 derive_more = { version = "2.1.1", features = ["full"] }
-dircpy = "0.3.20"
+dircpy = "0.3.21"
 dirs = "7.0.0"
 dlopen2 = "0.9.0"
 dotenvy = "0.15.7"
@@ -172,11 +175,11 @@ dtor = "1.0.6"
 elasticsearch = { version = "9.1.0-alpha.1", features = ["rustls-tls"], default-features = false }
 enumset = "1.1"
 env_logger = "0.11.11"
-err_trail = { version = "0.11.2", features = ["tracing"] }
+err_trail = { version = "0.11.3", features = ["tracing"] }
 error_set = "0.9.2"
 figlet-rs = "1.0.0"
 figment = { version = "0.10.19", features = ["toml", "env"] }
-file-operation = "0.8.32"
+file-operation = "10.2.4"
 flatbuffers = "25.12.19"
 flate2 = "1.1.10"
 flume = "0.12.0"
@@ -186,6 +189,13 @@ futures-core = { version = "0.3.34", default-features = false }
 # Keep on the minor compio-tls 0.10 uses; the message_bus tripwire test catches drift.
 futures-rustls = "0.26.0"
 futures-util = "0.3.34"
+gcloud-bigquery = { version = "1.7.0", default-features = false, features = [
+    "auth",
+    "jwt-rust-crypto",
+    "rustls-tls",
+] }
+gcloud-gax = "1.4.0"
+gcloud-googleapis = { version = "1.3.0", features = ["bigquery"] }
 getrandom = { version = "0.4", features = ["wasm_js"] }
 git2 = { version = "0.21.0", default-features = false, features = ["vendored-libgit2"] }
 gloo = "0.12"
@@ -197,35 +207,35 @@ hostname = "0.4.2"
 http = "1.5.0"
 human-repr = "1.1.0"
 humantime = "2.4.0"
-hwlocality = "1.0.0-alpha.12"
-hyper = "1.11.1"
-hyper-util = { version = "0.1.20", features = ["server-auto", "service"] }
+hwlocality = "1.0.0-alpha.13"
+hyper = "1.12.0"
+hyper-util = { version = "0.1.21", features = ["server-auto", "service"] }
 iceberg = "0.10.1"
 iceberg-catalog-rest = "0.10.1"
 iceberg-storage-opendal = "0.10.1"
-iggy = { path = "core/sdk", version = "0.11.1-edge.1" }
-iggy-cli = { path = "core/cli", version = "0.14.1-edge.1" }
+iggy = { path = "core/sdk", version = "0.11.1-edge.3" }
+iggy-cli = { path = "core/cli", version = "0.14.1-edge.3" }
 iggy-gateway-kafka = { path = "gateways/kafka" }
-iggy_binary_protocol = { path = "core/binary_protocol", version = "0.11.1-edge.1" }
-iggy_common = { path = "core/common", version = "0.11.1-edge.1" }
+iggy_binary_protocol = { path = "core/binary_protocol", version = "0.11.1-edge.3" }
+iggy_common = { path = "core/common", version = "0.11.1-edge.3" }
 iggy_connector_doris_sink = { path = "core/connectors/sinks/doris_sink" }
-iggy_connector_sdk = { path = "core/connectors/sdk", version = "0.5.1-edge.1" }
+iggy_connector_sdk = { path = "core/connectors/sdk", version = "0.5.1-edge.2" }
 indexmap = "2.14.2"
 integration = { path = "core/integration" }
 ipnet = "2.12.2"
 journal = { path = "core/journal" }
 js-sys = "0.3"
-jsonwebtoken = { version = "11.0.0", features = ["rust_crypto"] }
+jsonwebtoken = { version = "11.1.0", features = ["rust_crypto"] }
 kafka-protocol = { version = "0.18.0", default-features = false, features = ["broker"] }
-keyring-core = "1.0.0"
-lapin = "2.5.1"
-lazy_static = "1.5.0"
+keyring-core = "1.0.1"
+lapin = "4.12.2"
+lazy_static = "1.5.1"
 # Pinned exactly: `metadata::stm::stream`'s keyed stats evictions lean on
 # left-right draining the previous batch's `absorb_second` before the current
 # batch's `absorb_first`, which is an implementation detail of 0.11.8's
 # `write.rs`, not a documented contract.
 left-right = "=0.11.8"
-libc = "0.2.189"
+libc = "0.2.190"
 log = "0.4.34"
 lz4 = "1.28.1"
 lz4_flex = "0.14.0"
@@ -243,10 +253,10 @@ mongodb = { version = "3.9.1", features = ["rustls-tls"] }
 nix = { version = "0.31.3", features = ["feature", "fs", "resource", "sched"] }
 nonzero_lit = "0.1.2"
 notify = "8.2.0"
-octocrab = "0.54.2"
-opentelemetry = { version = "0.32.0", features = ["trace", "logs"] }
-opentelemetry-appender-tracing = { version = "0.32.0", features = ["log"] }
-opentelemetry-otlp = { version = "0.32.0", features = [
+octocrab = "0.54.4"
+opentelemetry = { version = "0.33.1", features = ["trace", "logs"] }
+opentelemetry-appender-tracing = { version = "0.33.1", features = ["log"] }
+opentelemetry-otlp = { version = "0.33.1", features = [
     "logs",
     "trace",
     "grpc-tonic",
@@ -254,8 +264,8 @@ opentelemetry-otlp = { version = "0.32.0", features = [
     "http-proto",
     "reqwest-client",
 ] }
-opentelemetry-semantic-conventions = "0.32.1"
-opentelemetry_sdk = { version = "0.32.1", features = [
+opentelemetry-semantic-conventions = "0.33.1"
+opentelemetry_sdk = { version = "0.33.1", features = [
     "logs",
     "trace",
     "experimental_async_runtime",
@@ -265,45 +275,50 @@ opentelemetry_sdk = { version = "0.32.1", features = [
 papaya = "0.2.5"
 parquet = "58.4.0"
 partitions = { path = "core/partitions" }
-passterm = "2.0.6"
+passterm = "2.1.0"
 paste = "1.0"
-pgwire = "0.40.7"
+percent-encoding = "2.3.2"
+pgwire = "0.41.1"
 postcard = { version = "1.1.3", features = ["alloc"] }
 predicates = "3.1.4"
 proc-macro2 = "1"
 prometheus-client = "0.25.1"
 prost = "0.14.4"
 prost-types = "0.14.4"
-protox = "0.9.1"
-protox-parse = "0.9.0"
-quinn = "0.11.11"
+protox = "0.10.0"
+protox-parse = "0.10.0"
+quinn = "0.11.12"
 quote = "1"
-rand = "0.10.2"
+rand = "0.10.3"
 rand_xoshiro = "0.8.1"
 rayon = "1.12.0"
 rcgen = "0.14.10"
 regex = "1.13.1"
+regex-syntax = "0.8.11"
 reqwest = { version = "0.13.5", default-features = false, features = ["json", "rustls"] }
 reqwest-middleware = { version = "0.5.2", features = ["json", "query"] }
 reqwest-retry = "0.9.1"
 reqwest-tracing = "0.7.1"
 ring = "0.17.14"
 ringbuffer = "0.16.0"
-rmcp = "3.3.0"
+rmcp = "3.5.1"
 rmp = "0.8.15"
 rmp-serde = "1.3.1"
 rolling-file = "0.2.0"
-rust-embed = "8.12.0"
-rust-s3 = { version = "0.37.2", default-features = false, features = ["tokio-rustls-tls", "tags"] }
-rustls = { version = "0.23.45", features = ["ring"] }
+rumqttc-v4 = { package = "rumqttc-v4-next", version = "0.34.0", features = ["url"] }
+rumqttc-v5 = { package = "rumqttc-v5-next", version = "0.34.0", features = ["url"] }
+rust-embed = "8.13.0"
+rust-s3 = { version = "0.38.0", default-features = false, features = ["tokio-rustls-tls", "tags"] }
+rustls = { version = "0.23.46", features = ["ring"] }
+rustls-native-certs = "0.8.4"
 rustls-pemfile = "2.2.0"
 scopeguard = "1.2.0"
 sd-notify = "0.5"
 secrecy = { version = "0.10", features = ["serde"] }
 send_wrapper = "0.6.0"
 serde = { version = "1.0.229", features = ["derive", "rc"] }
-serde_json = "1.0.151"
-serde_with = { version = "3.23.0", features = ["base64", "macros"] }
+serde_json = "1.0.154"
+serde_with = { version = "3.24.0", features = ["base64", "macros"] }
 serde_yaml_ng = "0.10.0"
 serial_test = "4.0.1"
 server = { path = "core/server", default-features = false }
@@ -336,21 +351,25 @@ sysinfo = "0.39.6"
 system_stats = { path = "core/system_stats" }
 tempfile = "3.27.0"
 terminal_size = { version = "0.4.4" }
-test-case = "3.3.1"
+test-case = "3.4.0"
 # Pinned to 0.27 because testcontainers-modules 0.15.0 still requires it.
 testcontainers = { version = "0.27.3", features = ["reusable-containers"] }
 testcontainers-modules = { version = "0.15.0", features = ["postgres", "http_wait"] }
-thiserror = "2.0.20"
-tokio = { version = "1.53.1", features = ["full"] }
+thiserror = "2.0.21"
+token-source = "1.0.0"
+tokio = { version = "1.53.3", features = ["full"] }
 tokio-postgres = "0.7.18"
-tokio-rustls = "0.26.5"
+tokio-rustls = "0.26.6"
+tokio-stream = { version = "0.1.19", features = ["net"] }
 tokio-tungstenite = { version = "0.30", features = ["rustls-tls-webpki-roots"] }
-tokio-util = { version = "0.7.19", features = ["compat"] }
-toml = "1.1.6"
+tokio-util = { version = "0.7.20", features = ["compat"] }
+toml = "1.1.8"
+tonic = { version = "0.14.6", default-features = false, features = ["codegen", "router", "server"] }
+tonic-prost = "0.14.6"
 tower-http = { version = "0.7.1", features = ["add-extension", "cors", "trace"] }
 tracing = "0.1.44"
 tracing-appender = "0.2.5"
-tracing-opentelemetry = "0.33.0"
+tracing-opentelemetry = "0.34.0"
 tracing-subscriber = { version = "0.3.23", default-features = false, features = [
     "fmt",
     "env-filter",
@@ -358,11 +377,11 @@ tracing-subscriber = { version = "0.3.23", default-features = false, features =
 ] }
 trait-variant = "0.1.3"
 tungstenite = "0.30.0"
-twox-hash = { version = "2.1.4", features = ["xxhash32"] }
+twox-hash = { version = "2.1.5", features = ["xxhash32"] }
 ulid = "3.0.0"
 ureq = "3.4"
 url = "2.5.8"
-uuid = { version = "1.26.1", features = ["v4", "v7", "fast-rng", "serde", "zerocopy"] }
+uuid = { version = "1.28.0", features = ["v4", "v7", "fast-rng", "serde", "zerocopy"] }
 vergen-git2 = { version = "10.0.1", features = ["build", "cargo", "rustc", "si"] }
 walkdir = "2.5.0"
 wasm-bindgen = "0.2"
@@ -378,12 +397,17 @@ web-sys = { version = "0.3", features = [
 webpki-roots = "1.0.9"
 windows-native-keyring-store = "1.1.0"
 wiremock = "0.6"
+x509-parser = "0.18.1"
+xaes-256-gcm = "0.1.0"
 yew = { version = "0.23", features = ["csr"] }
 yew-router = "0.20"
 zbus-secret-service-keyring-store = { version = "1.0.1", features = ["rt-async-io-crypto-rust"] }
-zeroize = "1.9.0"
-zip = { version = "8.6.0", default-features = false, features = ["deflate"] }
-zstd = "0.13.3"
+zeroize = "1.9.1"
+zip = { version = "9.0.3", default-features = false, features = ["deflate"] }
+zstd = "0.14.2"
+
+[workspace.metadata.cargo-machete]
+ignored = ["prost"]
 
 [profile.release]
 lto = true

{apache_iggy-0.9.1.dev1 → apache_iggy-0.9.1.dev3}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: apache-iggy
-Version: 0.9.1.dev1
+Version: 0.9.1.dev3
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -41,7 +40,7 @@ License-File: NOTICE
 Summary: Apache Iggy is the persistent message streaming platform written in Rust, supporting QUIC, TCP and HTTP transport protocols, capable of processing millions of messages per second.
 Keywords: streaming,messaging,pubsub,iggy,rust,performance
 Author-email: Iggy Committers <dev@iggy.apache.org>
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Bug Tracker, https://github.com/apache/iggy/issues
 Project-URL: Discord, https://discord.gg/C5Sux5NcRa
@@ -79,7 +78,7 @@ pip install apache-iggy
 
 ### Prerequisites
 
-- Python 3.10+
+- Python 3.11+
 
 Published wheels include the Rust extension; installing a wheel does not require
 Rust. Building from source and running the development checks below also requires:
@@ -230,6 +229,11 @@ asyncio.run(main())
 transport. `examples/python/getting-started/producer.py` shows each swap in
 context.
 
+Established binary sessions survive transport loss. Password/PAT changes and
+PAT expiry do not end these sessions; logout, session lease expiry and account
+deactivation do. Reconnection binds the retained session before attempting a
+fresh login.
+
 `HttpConfig` differs from TCP in two ways. There is no reconnection policy and no
 `AutoLogin`: `connect()` does not dial over HTTP, but it does start the
 heartbeat that `heartbeat_interval` configures, so call it and then
@@ -260,6 +264,135 @@ async def main():
 asyncio.run(main())
 ```
 
+## Stream, Topic and User Options
+
+`create_stream`, `create_topic` and `create_user` take typed options: `StreamOptions`, `TopicOptions` and `UserOptions`. Updates are patches: `update_stream`, `update_topic` and `update_user` change only the fields you pass, and `reset` returns keys to their server defaults.
+
+A topic's `message_expiry` and `max_topic_size` are the only resettable keys. Settings such as the compression algorithm are fixed at creation and have no update field. `describe_options("stream" | "topic" | "user")` reports which keys are updatable, resettable, secret or read-only.
+
+The update methods also take `options` and `raw_reset`, which send keys and reset names verbatim, so a key newer than this build can be set or reset. The server decides those. A refused option raises `OptionError`, a `RuntimeError` whose `code` and `kind` name the refusal, for example `4103` and `"option_not_updatable"`, the same on every transport.
+
+Root user rename and status refusals also raise `OptionError` with code `4108` and kind `"cannot_modify_root_user"`.
+
+```python
+import asyncio
+import secrets
+from datetime import timedelta
+
+from apache_iggy import (
+    IggyClient,
+    IggyExpiry,
+    OptionKey,
+    StreamOptions,
+    TopicOptions,
+    encryption_key_fingerprint,
+)
+
+
+async def main():
+    client = IggyClient.from_connection_string("iggy+tcp://iggy:iggy@127.0.0.1:8090")
+    await client.connect()
+
+    key = secrets.token_bytes(32)
+    stream = await client.create_stream("orders", StreamOptions(encryption_key=key))
+    assert stream.encryption_key_source == "stream"
+    assert stream.encryption_key_fingerprint == encryption_key_fingerprint(key)
+
+    await client.create_topic(
+        "orders",
+        "created",
+        TopicOptions(
+            partitions_count=3,
+            compression_algorithm="gzip",
+            message_expiry=IggyExpiry.ExpireDuration(timedelta(days=7)),
+        ),
+    )
+    await client.update_topic(
+        "orders",
+        "created",
+        message_expiry=IggyExpiry.ExpireDuration(timedelta(days=1)),
+        reset=[OptionKey.MaxTopicSize],
+    )
+    await client.update_stream("orders", name="orders-v2")
+
+
+asyncio.run(main())
+```
+
+A stream encryption key must be 32 random bytes, given as `bytes` or as their canonical base64 text. The key travels inside the create request over whatever transport the client uses, so protecting it in transit with TLS is your responsibility.
+
+The server never returns the key, only `encryption_key_source`, `encryption_key_fingerprint` and `encryption_kek_fingerprints`. Without a key, a server with encryption enabled generates one for the stream and reports the source `"server"`. An invalid key raises `ValueError` before anything is sent, and no repr or error message contains it.
+
+## Metadata Changes
+
+`get_metadata_changes` reads the node's change log: one record per public result of a committed metadata operation, such as a stream created, a topic renamed, a user's permissions changed or a session closed. A mirror keeps a cursor, asks for the records after it, and stores the returned `next` cursor. The call needs root or the global `manage_servers` permission. A query the server would refuse raises `IggyError` with the invalid command code before anything is sent.
+
+```python
+import asyncio
+
+from apache_iggy import (
+    IggyClient,
+    MetadataChangeGroup,
+    MetadataChangeStart,
+    MetadataChangeStatus,
+)
+
+
+async def follow(client, groups):
+    start = MetadataChangeStart.Earliest()
+    while True:
+        page = await client.get_metadata_changes(start, groups=groups)
+        if page.status == MetadataChangeStatus.Ok:
+            for record in page.records:
+                print(record.op, record.actor_user_id, record.kind, record.change)
+            if page.next is not None:
+                start = MetadataChangeStart.After(page.next)
+            if not page.has_more:
+                await asyncio.sleep(1)
+        elif page.status == MetadataChangeStatus.Behind:
+            await asyncio.sleep(0.1)
+        else:
+            start = await rebuild(client, groups)
+
+
+async def rebuild(client, groups):
+    """Pages the current state, then returns the position to follow from."""
+    start = MetadataChangeStart.Current()
+    while True:
+        page = await client.get_metadata_changes(start, groups=groups)
+        if page.status == MetadataChangeStatus.Behind:
+            await asyncio.sleep(0.1)
+            continue
+        if page.status != MetadataChangeStatus.Ok:
+            start = MetadataChangeStart.Current()
+            continue
+        for item in page.items:
+            print(item.group, item.body)
+        if page.current_page_token is not None:
+            start = MetadataChangeStart.Current(page.current_page_token)
+        elif page.next is not None:
+            return MetadataChangeStart.After(page.next)
+        else:
+            start = MetadataChangeStart.Current()
+
+
+async def main():
+    client = IggyClient.from_connection_string("iggy+tcp://iggy:iggy@127.0.0.1:8090")
+    await client.connect()
+    await follow(client, [MetadataChangeGroup.Streams, MetadataChangeGroup.Topics])
+
+
+asyncio.run(main())
+```
+
+`Expired` means the log no longer holds the history after the cursor, and `Reset` means the cursor belongs to another history, for example after the data directory was rebuilt. Either way the mirror rebuilds from current state pages and then follows the changes after the anchor they return.
+
+Current pages need the parent groups of every selected group, for example `Topics` with `Streams`. Keep a rebuilt state private until a change page answers `Ok` with `has_more` false and a `head_op` at or above the last current page's.
+
+`record.kind` names the body in `record.change`, for example a `MetadataStreamChange` for `StreamCreated` and `StreamUpdated`. A record or item this build does not know has `kind` or `group` set to `None` and a `MetadataUnknownChange` or `MetadataUnknownItem` body with its codes and raw body, so a mirror can stop there rather than skip a change. Stream, topic and user bodies expose `options` and `derived_options` as `StreamDetails` does: a stream's key source and fingerprints, never its key.
+
+`str()` of a cursor gives its `mc1_` text and of a page token its `cs1_` text, and `MetadataChangeCursor.parse` and `MetadataCurrentPageToken.parse` read them back, so a mirror can store its position as a string. Log ids, checksums and client ids are Python ints.
+
 ## High-Level Producer
 
 The Python high-level producer API is a port of the Rust high-level producer
@@ -269,8 +402,9 @@ API. For detailed producer semantics and configuration guidance, see the
 Use `IggyClient.producer()` when an application repeatedly publishes to one
 stream and topic. Producer creation is asynchronous because it initializes the
 destination before returning. By default, it creates a missing stream and topic,
-uses balanced partitioning, sends directly in batches of up to 1,000 messages,
-and retries failed sends up to three times with a one-second retry interval.
+uses balanced partitioning and sends directly in batches of up to 1,000 messages.
+The binary driver retries each chunk within one 30-second deadline, preserving
+its request identity. The producer adds no retry under a new identity.
 
 The default mode is direct. Pass `BackgroundProducerConfig` to queue sends on
 background workers instead.
@@ -299,8 +433,6 @@ async def main():
         topic_partitions_count=3,
         topic_message_expiry=None,
         topic_max_size=None,
-        send_retries=3,
-        send_retry_interval=timedelta(seconds=1),
     )
 
     async with producer:
@@ -318,22 +450,78 @@ strategy for one call, or `send_to(stream, topic, messages, partitioning)` to
 send to another existing destination. `send_to()` does not create or initialize
 that destination.
 
-Direct sends use at-least-once delivery. A request can commit even when its
-response is lost, so any retry can write the same batch again. `send_retries`
-counts retries after the initial attempt. The first retry runs immediately, and
-`send_retry_interval` delays only later retries. Set `send_retries` to `None` or
-`0` to disable producer retries. Set `send_retry_interval` to `None` to run all
-enabled retries without a delay. A zero interval raises `ValueError`.
-
-Transport retries are separate from producer retries. For example, the default
-`HttpConfig(retries=3)` gives each producer attempt up to four HTTP attempts.
-
-A failed direct send raises `ProducerSendError`, which is a `RuntimeError`
-subclass. Its `cause` property contains the underlying error text. Its
+Binary transports retain the original request identity after an uncertain
+exchange. Persisted sends also provide crash-safe retry receipts; weaker topic
+policies can lose data and receipts on a crash. HTTP NoAck confirms dispatch
+only. An application resend creates a new request and can duplicate messages.
+
+Mutation retries belong to the shared client driver. The producer no longer accepts
+`send_retries` or `send_retry_interval`; passing either raises `TypeError`. HTTP
+keeps its configured HTTP retry policy and does not support operation recovery.
+HTTP 503 `relay_refused` follows that policy; the Rust-backed HTTP retry schedule
+does not use the server's `Retry-After` header.
+
+On a multi-node cluster, an HTTP call often reaches a node that is not the
+partition primary. For message sends, polls and consumer offset calls, that
+node relays the call to the primary. The relay needs identical `http.jwt`
+secrets or `cluster.auth` on every node. Without that key material, these calls
+answer 503 with code 58. See
+[HTTP routing and backpressure](../../core/server/README.md#http-routing-and-backpressure).
+
+Receipt access follows the server's [session and revocation policy](../../core/server/README.md#sessions-and-retry-receipts).
+An unresolved operation cannot recover its receipt after its original session
+ends, even after a new login or account reactivation. A fresh send can duplicate
+that operation.
+
+Each node counts the messages in its stream, topic and system stats. After a
+successful send, a node that is not the partition primary shows the new count
+only after the next prepare or commit broadcast. When no other write follows,
+this delay is at most `cluster.commit_broadcast_interval` (500 ms by default).
+See [metadata freshness and counters](../../core/server/README.md#metadata-freshness-and-counters).
+
+Every error that the Rust SDK reports reaches Python as `IggyError`, a `RuntimeError` subclass. Its `code` is the numeric Iggy error code, the same code that the other SDKs report, and its message is the SDK's error text, so branch on `code` rather than on the message. Three codes tell what happened to a request that did not complete:
+
+- 58 (`TransientNotAccepted`): the server did not admit the request, so a retry is safe.
+- 57 (`TransientNotCommitted`): the outcome is unknown, and the server possibly applied the write. Read the state before you write it again.
+- 40 (`Unauthenticated`): the request needs a session. Sign in, then retry.
+
+`OptionError`, `PendingOperationError` and `ProducerSendError` are `IggyError` subclasses. An error that the binding raises itself, such as a `ValueError`, a `TypeError`, or a plain `RuntimeError` for an invalid argument or a shut-down producer, is not an `IggyError` and carries no code.
+
+`PendingOperationError` exposes the exact integer `operation_id`, the numeric
+`code`, and `kind` (`"uncertain"`, `"lane_blocked"`, or `"not_retained"`). On the
+same live client, `await client.resolve_operation(operation_id,
+timeout=timedelta(seconds=30))` replays the original operation. A committed
+business rejection raises its original error and releases the lane; uncertainty
+keeps the operation retained. The default timeout is 30 seconds; it must be a
+positive `timedelta`. `await client.abandon_operation(operation_id)` releases the
+lane without establishing whether the operation committed. A session reset
+forgets retained operations, so recovery must use the original session.
+The client keeps the proved outcomes of its last `max_operations` replays, also
+across a session reset. A later `resolve_operation` of a proved operation
+returns the same outcome without a request.
+
+`TcpConfig`, `QuicConfig`, and `WebSocketConfig` accept `pending_operations=
+PendingOperationsConfig(max_operations=256, max_bytes=64 * 1024 * 1024)`. These
+client-wide defaults bound active and retained mutations across every partition.
+Admission waits before allocating a request ID. Queued writer frames keep their
+bytes charged until their last reference is released, even after abandonment.
+TCP, QUIC and WebSocket connection strings accept `max_pending_operations` and
+`max_pending_operation_bytes` as positive integers, for example
+`iggy+tcp://iggy:iggy@localhost:8090?max_pending_operations=256&max_pending_operation_bytes=67108864`.
+
+A failed direct send raises `ProducerSendError`, an `IggyError` with code 4056 (`ProducerSendFailed`). Its `cause` property contains the underlying error text, and its `__cause__` is the `IggyError` that ended the send, a structured `PendingOperationError` when applicable.
+
+The optional `operation_id` of a `ProducerSendError` identifies the retained send to resolve or abandon. Its
 `committed` property contains confirmations from completed chunks, and `failed`
-contains the remaining unconfirmed messages. If encryption is enabled, the
-failed messages contain encrypted payloads. Restore the original payloads
-before submitting them to the same producer again.
+contains the remaining messages without usable confirmations. For an `uncertain`
+cause, the first `uncertain` messages of `failed` form one chunk that may already
+have committed. Resolve its `operation_id` without submitting that chunk as a new
+send. A cause with code 57 retains no operation, yet its first `uncertain` messages may also have committed. For any other cause, `uncertain` is zero. For `lane_blocked`,
+none of `failed` was sent: the ID names an earlier operation to resolve before
+retrying. Abandonment or a session reset discards retained results, and
+`not_retained` does not prove non-commit. Resubmitting an uncertain chunk can
+duplicate messages. Before any safe resubmission, restore payloads changed by
+encryption.
 
 ### Background Mode
 
@@ -391,10 +579,11 @@ batch larger than the whole budget always fails. A zero byte budget is
 unlimited. `max_in_flight` separately bounds concurrent write requests across
 all shards; zero uses the runtime maximum.
 
-Producer retries and transport reconnection happen inside background workers.
+Binary driver retries and transport reconnection happen inside background workers.
 The Python API does not currently expose a background error callback, so a write
-that still fails after its retries is logged by the Rust SDK and its unconfirmed
-messages are dropped.
+that fails at its operation deadline is logged by the Rust SDK and its messages
+are dropped from the worker queue. An uncertain chunk remains retained by the
+client for recovery; it may already have committed.
 
 See the complete runnable
 [`background_producer.py`](../../examples/python/high-level/background_producer.py)