serverish 2.2.0__tar.gz → 2.3.0__tar.gz

{serverish-2.2.0 → serverish-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serverish
-Version: 2.2.0
+Version: 2.3.0
 Summary: helpers for server alike projects
 License-File: LICENSE
 Author: Mikołaj Kałuszyński
@@ -50,6 +50,10 @@ this will install `nats-py` package.
 - Custom JetStream API replacing nats-py private internals access
 
 ## Changes
+* 2.3 **Breaking:** exceptions of the NATS client library (`nats.errors.*`) no longer leak from the
+  Messenger API - every error is a `ServerishError` (see [Error handling](doc/concepts.md#error-handling)).
+  Replace `except nats.errors...` handlers around serverish calls. `raise_on_publish_error=False`
+  covers a missing connection too.
 * 1.7 Subscription reliability: reader auto-recovers from NATS disconnects and consumer expiry,
   RPC responder auto-resubscribes, `health_status` property on all drivers (reader, publisher,
   RPC responder, connection) with reconnect counts, error tracking, slow consumer detection.

{serverish-2.2.0 → serverish-2.3.0}/README.md

@@ -28,6 +28,10 @@ this will install `nats-py` package.
 - Custom JetStream API replacing nats-py private internals access
 
 ## Changes
+* 2.3 **Breaking:** exceptions of the NATS client library (`nats.errors.*`) no longer leak from the
+  Messenger API - every error is a `ServerishError` (see [Error handling](doc/concepts.md#error-handling)).
+  Replace `except nats.errors...` handlers around serverish calls. `raise_on_publish_error=False`
+  covers a missing connection too.
 * 1.7 Subscription reliability: reader auto-recovers from NATS disconnects and consumer expiry,
   RPC responder auto-resubscribes, `health_status` property on all drivers (reader, publisher,
   RPC responder, connection) with reconnect counts, error tracking, slow consumer detection.

{serverish-2.2.0 → serverish-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "serverish"
-version = "2.2.0"
+version = "2.3.0"
 description = "helpers for server alike projects"
 authors = ["Mikołaj Kałuszyński", "MMME team"]
 readme = "README.md"
@@ -24,7 +24,7 @@ pytest = ">=9.1,<10"
 pytest-asyncio = "^1.4"
 nats-py = "^2.6.0"
 jupyter = "*"
-rich = "^13.5.2"
+rich = ">=13.5.2"
 aiodns = ">=3.1.1,<5"
 testcontainers = {extras = ["nats"], version = "^4.14.2"}
 pytest-timeout = "^2.4.0"

{serverish-2.2.0 → serverish-2.3.0}/serverish/base/exceptions.py

@@ -13,6 +13,57 @@ class MessengerCannotConnect(ServerishError):
     pass
 
 class MessengerNotConnected(ServerishError):
+    """Raised when an operation needs a NATS connection which is not there
+
+    Either the Messenger has not been opened, or the connection is gone
+    (see `MessengerConnectionClosed`).
+    """
+    pass
+
+
+class MessengerTransportError(ServerishError):
+    """Raised when the underlying NATS client fails to carry out an operation
+
+    Common base of all errors translated from the NATS client library. The
+    original exception is always available as ``__cause__``; serverish users
+    are not expected to inspect it, nor to know the client library at all.
+    """
+    pass
+
+
+class MessengerConnectionClosed(MessengerTransportError, MessengerNotConnected):
+    """Raised when the NATS connection is closed, draining, stale or has no server to talk to"""
+    pass
+
+
+class MessengerOutboundBufferFull(MessengerTransportError):
+    """Raised when the client's outbound buffer overflows
+
+    Typically the connection is down (reconnecting) and messages published
+    in the meantime no longer fit the pending buffer.
+    """
+    pass
+
+
+class MessengerJetStreamError(MessengerTransportError):
+    """Raised when the JetStream API refuses or fails a request
+
+    Attributes:
+        code (int | None): HTTP-like status of the response (e.g. 404, 503)
+        err_code (int | None): JetStream specific error code
+        description (str | None): server-side error description
+    """
+
+    def __init__(self, *args, code: int | None = None, err_code: int | None = None,
+                 description: str | None = None) -> None:
+        super().__init__(*args)
+        self.code = code
+        self.err_code = err_code
+        self.description = description
+
+
+class MessengerTransportTimeout(MessengerTransportError, TimeoutError):
+    """Raised when the NATS server did not answer in time"""
     pass
 
 class MessengerReaderStopped(ServerishError):
@@ -52,7 +103,7 @@ class MessengerRequestNoResultYet(MessengerRequestNoResponse):
     pass
 
 
-class MessengerPublishAckTimeout(ServerishError, TimeoutError):
+class MessengerPublishAckTimeout(MessengerTransportTimeout):
     """Raised when JetStream did not confirm a publish within the ack timeout.
 
     The message MAY have been delivered and stored — only the acknowledgement

serverish-2.3.0/serverish/connection/nats_errors.py

@@ -0,0 +1,97 @@
+"""Translation of NATS client library errors into serverish exceptions
+
+The single place where ``nats.errors`` / ``nats.js.errors`` exceptions are
+mapped onto the `ServerishError` hierarchy. The messenger API never lets a
+raw client-library exception out: whoever catches `ServerishError` handles
+every failure serverish can report, without knowing which client library
+(or which version of it) works underneath.
+
+Use `nats_errors_translated` around calls into the client library at the
+public boundary of a driver. Code which reacts to specific client errors
+internally keeps catching the raw exceptions inside that boundary.
+"""
+from __future__ import annotations
+
+import contextlib
+from typing import Iterator
+
+import nats.errors
+import nats.js.errors
+
+from serverish.base.exceptions import (ServerishError, MessengerTransportError, MessengerConnectionClosed,
+                                       MessengerOutboundBufferFull, MessengerJetStreamError,
+                                       MessengerTransportTimeout)
+
+_CONNECTION_GONE = (
+    nats.errors.ConnectionClosedError,
+    nats.errors.ConnectionDrainingError,
+    nats.errors.ConnectionReconnectingError,
+    nats.errors.StaleConnectionError,
+    nats.errors.UnexpectedEOF,  # a StaleConnectionError subclass today - listed so the mapping does not depend on it
+    nats.errors.NoServersError,
+)
+
+# Status implied by the class of a JetStream API error; the client library
+# does not always fill `code` in (e.g. errors it raises on its own)
+_API_ERROR_CODES = (
+    (nats.js.errors.NotFoundError, 404),
+    (nats.js.errors.BadRequestError, 400),
+    (nats.js.errors.ServiceUnavailableError, 503),
+    (nats.js.errors.ServerError, 500),
+)
+
+
+def translate_nats_error(error: Exception, context: str) -> Exception:
+    """Returns the serverish counterpart of a NATS client library exception
+
+    Args:
+        error: exception to translate
+        context: what serverish was doing, the lead of the resulting message
+
+    Returns:
+        A `MessengerTransportError` (subclass) for a client library error -
+        raise it ``from error`` to keep the original as ``__cause__``.
+        Any other exception (serverish ones included) is returned unchanged.
+    """
+    if isinstance(error, ServerishError) or not isinstance(error, nats.errors.Error):
+        return error
+    message = f"{context}: {error}"
+    if isinstance(error, _CONNECTION_GONE):
+        return MessengerConnectionClosed(message)
+    if isinstance(error, nats.errors.OutboundBufferLimitError):
+        return MessengerOutboundBufferFull(message)
+    if isinstance(error, nats.js.errors.APIError):
+        return MessengerJetStreamError(message, code=jetstream_error_code(error), err_code=error.err_code,
+                                       description=error.description)
+    if isinstance(error, nats.errors.TimeoutError):
+        return MessengerTransportTimeout(message)
+    return MessengerTransportError(message)
+
+
+@contextlib.contextmanager
+def nats_errors_translated(context: str) -> Iterator[None]:
+    """Context manager translating NATS client library errors raised in its body
+
+    Args:
+        context: what serverish is doing, the lead of the resulting message
+
+    Raises:
+        MessengerTransportError: (subclass) instead of any ``nats.errors.Error``
+    """
+    try:
+        yield
+    except nats.errors.Error as e:
+        raise translate_nats_error(e, context) from e
+
+
+def jetstream_error_code(error: Exception) -> int | None:
+    """Returns the HTTP-like status code of a JetStream API error, raw or translated"""
+    if isinstance(error, MessengerJetStreamError):
+        return error.code
+    if isinstance(error, nats.js.errors.APIError):
+        if error.code is not None:
+            return int(error.code)
+        for cls, code in _API_ERROR_CODES:
+            if isinstance(error, cls):
+                return code
+    return None

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/messenger.py

@@ -24,11 +24,12 @@ from nats.aio.msg import Msg
 from serverish.base import dt_utcnow_array, dt_from_array, Task, create_task, dt_ensure_array
 from serverish.base.collector import Collector
 from serverish.connection.connection_jets import ConnectionJetStream
-from serverish.base.idmanger import gen_id
+from serverish.base.idmanger import gen_id, gen_uid
 from serverish.base.manageable import Manageable
 from serverish.messenger.msgvalidator import MsgValidator
 from serverish.base.singleton import Singleton
-from serverish.base import MessengerCannotConnect
+from serverish.base import MessengerCannotConnect, MessengerNotConnected
+from serverish.connection.nats_errors import nats_errors_translated
 
 if TYPE_CHECKING:
     from serverish.messenger.msg_publisher import MsgPublisher
@@ -51,12 +52,20 @@ class Messenger(Singleton):
     def __init__(self, name: str = None, parent: Collector = None, **kwargs) -> None:
         self.validator = MsgValidator()
         self.opener_task: Task | None = None
+        # Random per-process token, part of the Nats-Msg-Id dedup header.
+        # meta.id (gen_id) is only process-locally unique - two processes (or one
+        # process restarted within the stream's duplicate window) both emit
+        # 'msg-1', 'msg-2', ..., and JetStream would silently drop the later
+        # publishes as duplicates. The instance prefix makes the dedup identity
+        # global while retries still reuse the exact same header.
+        self.instance_id: str = gen_uid('mi', 12)
         super().__init__(name, parent, **kwargs)
 
     @property
     def connection(self) -> ConnectionJetStream:
         if self.conn is None:
-            raise ValueError("Messenger connection have not been opened, use configure(host, port) first")
+            raise MessengerNotConnected("Messenger connection has not been opened, "
+                                        "use Messenger().open(host, port) or Messenger().context(host, port) first")
         return self.conn
 
     async def open(self, host: str | None = None, port: int | None = None,
@@ -312,8 +321,11 @@ class Messenger(Singleton):
 
     async def purge(self, subject: str) -> None:
         js = self.connection.js
-        stream = await js.find_stream_name_by_subject(subject)
-        await js.purge_stream(stream, subject=subject)
+        if js is None:
+            raise MessengerNotConnected(f"Cannot purge subject '{subject}', JetStream not connected")
+        with nats_errors_translated(f"Purging subject '{subject}' failed"):
+            stream = await js.find_stream_name_by_subject(subject)
+            await js.purge_stream(stream, subject=subject)
 
     @staticmethod
     def get_publisher(subject: str) -> "MsgPublisher":

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_callback_sub.py

@@ -21,7 +21,12 @@ class MsgCallbackSubscriber(MsgReader):
     """
     callback = param.Callable(default=None, doc="Callback function to call on each message")
     task = param.ClassSelector(default=None, class_=Task, doc="Task for reading messages")
-    _stop_event = param.ClassSelector(default=Event(), class_=Event, doc="Event to stop reading messages")
+
+    def __init__(self, *args, **kwargs) -> None:
+        # per instance: a class-level default would be one Event shared by all subscribers,
+        # stopping one would stop them all
+        self._stop_event: Event = Event()
+        super().__init__(*args, **kwargs)
 
     async def open(self) -> None:
         return await super().open()

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_core_pub.py

@@ -5,6 +5,7 @@ import jsonschema
 import param
 
 from serverish.base import MessengerNotConnected
+from serverish.connection.nats_errors import translate_nats_error
 from serverish.messenger.messenger import MsgDriver, log
 
 
@@ -15,7 +16,8 @@ class MsgCorePub(MsgDriver):
     on subjects that are not backed by a JetStream stream.
 
     Parameters:
-        raise_on_publish_error (bool): Raise on publish error, default ``True`` re-raises underlying exceptions
+        raise_on_publish_error (bool): Raise on publish error (default ``True``). When ``False``, errors
+            (a missing connection included) are logged and reported in the returned message instead
     """
 
     raise_on_publish_error = param.Boolean(default=True, doc="Raise on publish error")
@@ -32,7 +34,11 @@ class MsgCorePub(MsgDriver):
 
         Raises:
             MessengerNotConnected: if the NATS connection is not available
-            jsonschema.ValidationError: if the message fails schema validation
+            MessengerTransportError: any other failure of the underlying NATS client
+            jsonschema.ValidationError: if the message fails schema validation (always raised)
+
+            With ``raise_on_publish_error`` set to False the serverish errors above are not raised:
+            the error is logged and the message is returned with the ``error`` tag.
         """
         from serverish.messenger import Messenger
         messenger: Messenger = self.messenger
@@ -51,22 +57,19 @@ class MsgCorePub(MsgDriver):
                     f"Trying to publish to subject '{self.subject}' failed. NATS not connected"
                 )
             await nc.publish(self.subject, bdata)
-        except MessengerNotConnected:
-            raise
-        except AttributeError:
-            raise MessengerNotConnected(
-                f"Trying to publish to subject '{self.subject}' failed. NATS not connected"
-            )
         except Exception as e:
+            error = translate_nats_error(e, f"Publishing message {msg['meta']['id']} to '{self.subject}' failed")
             log.error(
                 f"Trying to publish to subject '{self.subject}' failed. "
-                f"Message {msg['meta']['id']} publish error: {e}"
+                f"Message {msg['meta']['id']} publish error: {error}"
             )
             if self.raise_on_publish_error:
-                raise e
+                if error is e:
+                    raise e
+                raise error from e
             else:
                 msg['meta']['tags'].append('error')
-                msg['meta']['status'] = str(e)
+                msg['meta']['status'] = str(error)
         return msg
 
 

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_core_read.py

@@ -6,7 +6,8 @@ import logging
 from nats.aio.msg import Msg
 from nats.aio.subscription import Subscription
 
-from serverish.base.exceptions import MessengerReaderStopped
+from serverish.base.exceptions import MessengerReaderStopped, MessengerNotConnected
+from serverish.connection.nats_errors import nats_errors_translated
 from serverish.messenger.messenger import MsgDriver
 
 log = logging.getLogger(__name__.rsplit('.')[-1])
@@ -79,7 +80,8 @@ class MsgCoreReader(MsgDriver):
             self.connection.remove_reconnect_cb(self._reconnect_cb)
             self._reconnect_cb = None
         if self.subscription is not None:
-            await self.subscription.unsubscribe()
+            with nats_errors_translated(f"Unsubscribing from '{self.subject}' failed"):
+                await self.subscription.unsubscribe()
             self.subscription = None
         return await super().close()
 
@@ -90,6 +92,8 @@ class MsgCoreReader(MsgDriver):
     async def _do_subscribe(self) -> None:
         """(Re-)create the raw NATS subscription, routing messages into the queue."""
         nc = self.connection.nc
+        if nc is None:
+            raise MessengerNotConnected(f"Cannot subscribe to '{self.subject}', NATS not connected")
 
         async def _cb(nats_msg: Msg) -> None:
             if self._queue is None:
@@ -101,7 +105,8 @@ class MsgCoreReader(MsgDriver):
                 return
             await self._queue.put((data, meta))
 
-        self.subscription = await nc.subscribe(self.subject, cb=_cb)
+        with nats_errors_translated(f"Subscribing to '{self.subject}' failed"):
+            self.subscription = await nc.subscribe(self.subject, cb=_cb)
 
     # ------------------------------------------------------------------
     # Reading

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_kv.py

@@ -19,6 +19,7 @@ import param
 from nats.js.kv import KeyValue
 
 from serverish.base import MessengerKvBucketNotFound, MessengerKvMalformed, dt_ensure_array
+from serverish.connection.nats_errors import nats_errors_translated
 from serverish.messenger.messenger import MsgDriver
 
 log = logging.getLogger(__name__.rsplit('.')[-1])
@@ -48,14 +49,15 @@ class MsgKvDriver(MsgDriver):
             self.subject = f'$KV.{self.bucket}'  # diagnostic only, KV entries are addressed by bucket/key
 
     async def open(self) -> None:
-        try:
-            self.kv = await self.connection.ensure_kv_bucket(self.bucket,
-                                                             create_if_needed=self.create_bucket,
-                                                             **self.bucket_config)
-        except nats.js.errors.BucketNotFoundError as e:
-            raise MessengerKvBucketNotFound(
-                f"KV bucket '{self.bucket}' does not exist, "
-                f"create it externally or open the driver with create_bucket=True") from e
+        with nats_errors_translated(f"Opening KV bucket '{self.bucket}' failed"):
+            try:
+                self.kv = await self.connection.ensure_kv_bucket(self.bucket,
+                                                                 create_if_needed=self.create_bucket,
+                                                                 **self.bucket_config)
+            except nats.js.errors.BucketNotFoundError as e:
+                raise MessengerKvBucketNotFound(
+                    f"KV bucket '{self.bucket}' does not exist, "
+                    f"create it externally or open the driver with create_bucket=True") from e
         await super().open()
 
     async def close(self) -> None:

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_kv_read.py

@@ -4,6 +4,7 @@ import param
 from nats.js.kv import KeyValue
 
 from serverish.base import MessengerReaderStopped
+from serverish.connection.nats_errors import nats_errors_translated
 from serverish.messenger.messenger import Messenger
 from serverish.messenger.msg_kv import MsgKvDriver, log
 
@@ -34,9 +35,10 @@ class MsgKvReader(MsgKvDriver):
 
     async def open(self) -> None:
         await super().open()
-        self._watcher = await self.kv.watch(self.key,
-                                            include_history=self.include_history,
-                                            ignore_deletes=self.ignore_deletes)
+        with nats_errors_translated(f"Watching KV {self.bucket}/{self.key} failed"):
+            self._watcher = await self.kv.watch(self.key,
+                                                include_history=self.include_history,
+                                                ignore_deletes=self.ignore_deletes)
 
     async def close(self) -> None:
         if self._watcher is not None:
@@ -54,7 +56,8 @@ class MsgKvReader(MsgKvDriver):
         if self._watcher is None:
             raise MessengerReaderStopped(f"KV reader {self} is not open")
         while True:
-            entry = await self._watcher.__anext__()  # raises StopAsyncIteration when watcher is stopped
+            with nats_errors_translated(f"Watching KV {self.bucket}/{self.key} failed"):
+                entry = await self._watcher.__anext__()  # raises StopAsyncIteration when watcher is stopped
             if entry is None:
                 # nats-py sends a None marker once the initial replay is done, it is not a value
                 continue

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_kv_store.py

@@ -4,6 +4,7 @@ import nats.js.errors
 from nats.js.kv import KeyValue
 
 from serverish.base import MessengerKvKeyNotFound
+from serverish.connection.nats_errors import nats_errors_translated
 from serverish.messenger.messenger import Messenger, MsgDriver
 from serverish.messenger.msg_kv import MsgKvDriver, log
 
@@ -31,7 +32,8 @@ class MsgKvStore(MsgKvDriver):
             dict: published message, with meta['kv'] carrying bucket/key/revision
         """
         msg, bdata = self.encode_envelope(data, meta)
-        revision = await self.kv.put(key, bdata)
+        with nats_errors_translated(f"KV PUT {self.bucket}/{key} failed"):
+            revision = await self.kv.put(key, bdata)
         msg['meta']['kv'] = {'bucket': self.bucket, 'key': key, 'revision': revision, 'operation': 'PUT'}
         self.messenger.log_msg_trace(msg.get('data', {}), msg['meta'], f"KV PUT {self.bucket}/{key}")
         return msg
@@ -48,10 +50,11 @@ class MsgKvStore(MsgKvDriver):
             MessengerKvKeyNotFound: key does not exist (or is deleted)
             MessengerKvMalformed: entry is not a serverish envelope
         """
-        try:
-            entry = await self.kv.get(key, revision=revision)
-        except nats.js.errors.KeyNotFoundError as e:
-            raise MessengerKvKeyNotFound(f"Key '{key}' not found in KV bucket '{self.bucket}'") from e
+        with nats_errors_translated(f"KV GET {self.bucket}/{key} failed"):
+            try:
+                entry = await self.kv.get(key, revision=revision)
+            except nats.js.errors.KeyNotFoundError as e:
+                raise MessengerKvKeyNotFound(f"Key '{key}' not found in KV bucket '{self.bucket}'") from e
         data, meta = self.decode_entry(entry)
         self.messenger.log_msg_trace(data, meta, f"KV GET {self.bucket}/{key}")
         return data, meta
@@ -59,22 +62,25 @@ class MsgKvStore(MsgKvDriver):
     @MsgDriver.ensure_open
     async def delete(self, key: str) -> None:
         """Places a delete marker for the key and removes previous revisions"""
-        await self.kv.delete(key)
+        with nats_errors_translated(f"KV DEL {self.bucket}/{key} failed"):
+            await self.kv.delete(key)
         log.debug(f"KV DEL {self.bucket}/{key}")
 
     @MsgDriver.ensure_open
     async def purge(self, key: str) -> None:
         """Removes the key including all its revisions"""
-        await self.kv.purge(key)
+        with nats_errors_translated(f"KV PURGE {self.bucket}/{key} failed"):
+            await self.kv.purge(key)
         log.debug(f"KV PURGE {self.bucket}/{key}")
 
     @MsgDriver.ensure_open
     async def keys(self) -> list[str]:
         """Returns list of keys in the bucket, empty list for an empty bucket"""
-        try:
-            return await self.kv.keys()
-        except nats.js.errors.NoKeysError:
-            return []
+        with nats_errors_translated(f"Listing keys of KV bucket '{self.bucket}' failed"):
+            try:
+                return await self.kv.keys()
+            except nats.js.errors.NoKeysError:
+                return []
 
     @MsgDriver.ensure_open
     async def history(self, key: str) -> list[tuple[dict | None, dict]]:
@@ -86,16 +92,18 @@ class MsgKvStore(MsgKvDriver):
         Raises:
             MessengerKvKeyNotFound: key has no history in the bucket
         """
-        try:
-            entries = await self.kv.history(key)
-        except nats.js.errors.NoKeysError as e:
-            raise MessengerKvKeyNotFound(f"Key '{key}' has no history in KV bucket '{self.bucket}'") from e
+        with nats_errors_translated(f"KV history of {self.bucket}/{key} failed"):
+            try:
+                entries = await self.kv.history(key)
+            except nats.js.errors.NoKeysError as e:
+                raise MessengerKvKeyNotFound(f"Key '{key}' has no history in KV bucket '{self.bucket}'") from e
         return [self.decode_entry(entry) for entry in entries]
 
     @MsgDriver.ensure_open
     async def status(self) -> KeyValue.BucketStatus:
         """Returns the status of the underlying KV bucket"""
-        return await self.kv.status()
+        with nats_errors_translated(f"Status of KV bucket '{self.bucket}' failed"):
+            return await self.kv.status()
 
 
 def get_kvstore(bucket: str, **kwargs) -> MsgKvStore:

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_publisher.py

@@ -8,6 +8,7 @@ import nats.js
 import param
 
 from serverish.base import MessengerNotConnected, MessengerPublishAckTimeout
+from serverish.connection.nats_errors import translate_nats_error
 from serverish.messenger import Messenger
 from serverish.messenger.messenger import MsgDriver, log
 
@@ -26,7 +27,8 @@ class MsgPublisher(MsgDriver):
     processed too late), the retry is discarded by the server.
 
     Parameters:
-        raise_on_publish_error (bool): Raise on publish error, default `True` re-raises underlying exceptions
+        raise_on_publish_error (bool): Raise on publish error (default `True`). When `False`, errors
+            (a missing connection included) are logged and reported in the returned message instead
         ack_timeout_retries (int): How many times to retry a publish for which no JetStream
             ack arrived in time (default 2). Retries are deduplicated server-side via
             ``Nats-Msg-Id``. When retries are exhausted, `MessengerPublishAckTimeout` is
@@ -63,8 +65,14 @@ class MsgPublisher(MsgDriver):
         Returns:
             dict: published message, or message to be published with the `error` tag in meta if failed
         Raises:
-            Raises nats errors if the message could not be published until `raise_on_publish_error` is set to True
-            otherwise logs the error, and returns the message with the `error` tag and `status` set to the error message.
+            MessengerNotConnected: no connection to publish through
+            MessengerPublishAckTimeout: JetStream did not confirm the publish (after retries)
+            MessengerTransportError: any other failure of the underlying NATS client
+            jsonschema.ValidationError: the message does not match its schema (always raised)
+
+            With `raise_on_publish_error` set to False the serverish errors above are not raised:
+            the error is logged and the message is returned with the `error` tag and `status`
+            set to the error message.
         """
         msg = self.messenger.create_msg(data, meta)
         bdata = self.messenger.encode(msg)
@@ -75,17 +83,16 @@ class MsgPublisher(MsgDriver):
             raise e
         self.messenger.log_msg_trace(msg['data'], msg['meta'], f"PUB to {self.subject}")
         headers = dict(kwargs.pop('headers', None) or {})
-        headers.setdefault('Nats-Msg-Id', msg['meta']['id'])  # server-side dedup, makes ack-timeout retries safe
+        # Server-side dedup id: makes ack-timeout retries safe. Must be globally
+        # unique, hence the per-process instance prefix - meta.id alone is only
+        # process-locally unique and would collide across processes/restarts,
+        # silently dropping messages within the stream's duplicate window.
+        headers.setdefault('Nats-Msg-Id', f"{self.messenger.instance_id}:{msg['meta']['id']}")
         try:
             await self._publish_with_ack_retries(bdata, headers, msg['meta']['id'], **kwargs)
             # Track successful publish
             self._publish_count += 1
             self._last_publish_time = time.monotonic()
-        except AttributeError as e:  # no js - not connected
-            self._error_count += 1
-            self._last_error = e
-            log.error(f"Trying to publish to subject '{self.subject}' failed. JetStream not connected")
-            raise MessengerNotConnected(f"Trying to publish to subject '{self.subject}' failed. JetStream not connected")
         except (nats.errors.NoRespondersError, nats.js.errors.NoStreamResponseError):
             # it's OK for non-jetstream, we just don't have subscribers yet
             # Still count as successful publish (message was sent, just no stream to persist)
@@ -95,15 +102,18 @@ class MsgPublisher(MsgDriver):
                 f'No subscribers yet returned by NATS server for subject {self.subject}, '
                 f'if it was meant to be jetstream, the subject does not exist in any stream!')
         except Exception as e:
+            error = translate_nats_error(e, f"Publishing message {msg['meta']['id']} to '{self.subject}' failed")
             self._error_count += 1
-            self._last_error = e
+            self._last_error = error
             log.error(f"Trying to publish to subject '{self.subject}' failed. "
-                      f"Message {msg['meta']['id']} publish error: {e}")
+                      f"Message {msg['meta']['id']} publish error: {error}")
             if self.raise_on_publish_error:
-                raise e
+                if error is e:
+                    raise e
+                raise error from e
             else:
                 msg['meta']['tags'].append('error')
-                msg['meta']['status'] = str(e)
+                msg['meta']['status'] = str(error)
         return msg
 
     async def _publish_with_ack_retries(self, bdata: bytes, headers: dict, msg_id: str, **kwargs) -> None:
@@ -115,11 +125,16 @@ class MsgPublisher(MsgDriver):
         Nats-Msg-Id header, so this never produces duplicates.
 
         Raises:
+            MessengerNotConnected: JetStream is not connected
             MessengerPublishAckTimeout: no ack after all retries
         """
+        js = self.connection.js
+        if js is None:
+            raise MessengerNotConnected(f"Trying to publish to subject '{self.subject}' failed. "
+                                        f"JetStream not connected")
         for attempt in range(self.ack_timeout_retries + 1):
             try:
-                await self.connection.js.publish(self.subject, bdata, headers=headers, **kwargs)
+                await js.publish(self.subject, bdata, headers=headers, **kwargs)
                 return
             except nats.errors.TimeoutError as e:
                 if attempt < self.ack_timeout_retries:

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_reader.py

@@ -19,9 +19,10 @@ from nats.js.api import DeliverPolicy, ConsumerConfig
 
 from serverish.base import wait_for_psce
 from serverish.base.exceptions import (MessengerReaderStopped, MessengerReaderConfigError,
-                                       MessengerNotConnected,
+                                       MessengerNotConnected, MessengerJetStreamError,
                                        MessengerReaderAlreadyOpen, MessengerRequestTimeout)
 from serverish.base.fifoset import FifoSet
+from serverish.connection.nats_errors import nats_errors_translated, translate_nats_error
 from serverish.messenger import Messenger
 from serverish.messenger.messenger import MsgDriver
 
@@ -141,6 +142,11 @@ class MsgReader(MsgDriver):
         Only stop signal and Cancel exception finish the iteration.
         One may change this behavior by setting `on_connection_close` to 'RAISE' or 'FINISH'.
         This will cause raising exception or finishing iteration on seruios erros.
+
+        Raises:
+            MessengerReaderStopped: the reader has been stopped (or finished, see `nowait`)
+            MessengerReaderConfigError: the server rejected the reader configuration, retrying is pointless
+            MessengerTransportError: (`error_behavior='RAISE'` only) failure of the underlying NATS client
         """
 
         # The reader loop's state and methods
@@ -401,8 +407,10 @@ class MsgReader(MsgDriver):
                 # Fatal NATS API errors (4xx): the same request will never
                 # succeed — stop retrying immediately and surface a clear
                 # MessengerReaderConfigError to the caller.
-                if isinstance(e.error, (nats.js.errors.BadRequestError,
-                                        nats.js.errors.NotFoundError)):
+                # (open() reports client errors translated, the original is its cause)
+                cause = e.error.__cause__ if isinstance(e.error, MessengerJetStreamError) else e.error
+                if isinstance(cause, (nats.js.errors.BadRequestError,
+                                      nats.js.errors.NotFoundError)):
                     log.error(st.fmt(f"fatal NATS error (not retrying): {e.error}"))
                     self._stop.set()
                     raise MessengerReaderConfigError(
@@ -411,7 +419,10 @@ class MsgReader(MsgDriver):
                 match self.error_behavior:
                     case 'RAISE':
                         log.error(st.fmt(f"raising read_next error:  {e.error}"))
-                        raise e.error
+                        error = translate_nats_error(e.error, f"Reading from '{self.subject}' failed")
+                        if error is e.error:
+                            raise e.error
+                        raise error from e.error
                     case 'FINISH':
                         log.error(st.fmt(f"finishing iteration on error: {e.error}"))
                         raise MessengerReaderStopped
@@ -622,6 +633,14 @@ class MsgReader(MsgDriver):
             ps._pending_next_msgs_calls.pop(task_name, None)
 
     async def open(self) -> None:
+        """Opens the reader: creates the JetStream consumer and subscribes to it
+
+        Raises:
+            MessengerReaderAlreadyOpen: the reader is open already
+            MessengerNotConnected: no connection to subscribe through
+            MessengerRequestTimeout: the server did not create the consumer in time
+            MessengerTransportError: any other failure of the underlying NATS client
+        """
         if self.pull_subscription is not None:
             raise MessengerReaderAlreadyOpen("Reader already open, do not reuse MsgReader instances")
 
@@ -652,13 +671,15 @@ class MsgReader(MsgDriver):
         # consumer_conf.durable_name = self.name if consumer_conf.durable_name is None else consumer_conf.durable_name
         if self.connection is None or self.connection.js is None:
             raise MessengerNotConnected('Cannot create pull subscription, not connected to NATS')
-        try:
-            ret = await self.connection.js.pull_subscribe(self.subject,
-                                                           durable=consumer_conf.durable_name,
-                                                           config=consumer_conf)
-        except TimeoutError as e:
-            raise MessengerRequestTimeout(e)
-        ci = await ret.consumer_info()
+        with nats_errors_translated(f"Creating consumer for '{self.subject}' failed"):
+            try:
+                ret = await self.connection.js.pull_subscribe(self.subject,
+                                                               durable=consumer_conf.durable_name,
+                                                               config=consumer_conf)
+            except nats.errors.TimeoutError as e:
+                raise MessengerRequestTimeout(
+                    f"Creating consumer for '{self.subject}' timed out: {e}") from e
+            ci = await ret.consumer_info()
         return ret
 
     async def _reopen(self) -> None:

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_rpc_req.py

@@ -3,10 +3,11 @@ from __future__ import annotations
 import asyncio
 from asyncio import CancelledError
 
-from nats.errors import NoRespondersError, TimeoutError
+import nats.errors
 
 from serverish.base import MessengerRequestNoResponders, MessengerRequestCanceled, MessengerRequestNoResultYet, \
-    MessengerRequestTimeout, MessengerRequestJetStreamSubject
+    MessengerRequestTimeout, MessengerRequestJetStreamSubject, MessengerNotConnected
+from serverish.connection.nats_errors import nats_errors_translated
 from serverish.base import Task, create_task
 from serverish.messenger import Messenger
 from serverish.messenger.messenger import MsgDriver
@@ -44,18 +45,21 @@ class MsgRpcRequester(MsgDriver):
         Raises:
             MessengerRequestNoResponders: if no responders were found for the request
             MessengerRequestTimeout: if no response was received in time
+            MessengerNotConnected: no connection to send the request through
+            MessengerTransportError: any other failure of the underlying NATS client
         """
-        from nats.aio.client import Client as NATS
-
-        nats: NATS = self.connection.nc
+        nc = self.connection.nc
+        if nc is None:
+            raise MessengerNotConnected(f"Request to '{self.subject}' failed. NATS not connected")
         msg = self.messenger.create_msg(data, meta=meta)
         bmsg = self.messenger.encode(msg)
-        try:
-            resp = await nats.request(self.subject, payload=bmsg, timeout=timeout)
-        except NoRespondersError as e:
-            raise MessengerRequestNoResponders(e)
-        except TimeoutError as e:
-            raise MessengerRequestTimeout(e)
+        with nats_errors_translated(f"Request to '{self.subject}' failed"):
+            try:
+                resp = await nc.request(self.subject, payload=bmsg, timeout=timeout)
+            except nats.errors.NoRespondersError as e:
+                raise MessengerRequestNoResponders(f"No responders for request to '{self.subject}'") from e
+            except nats.errors.TimeoutError as e:
+                raise MessengerRequestTimeout(f"No response to request to '{self.subject}' in time") from e
         rdata, rmeta = self.messenger.unpack_nats_msg(resp)
         if rmeta is None:
             raise MessengerRequestJetStreamSubject(self.subject)

{serverish-2.2.0 → serverish-2.3.0}/serverish/messenger/msg_rpc_resp.py

@@ -8,6 +8,8 @@ from typing import Callable
 from nats.aio.msg import Msg
 from nats.aio.subscription import Subscription
 
+from serverish.base import MessengerNotConnected
+from serverish.connection.nats_errors import nats_errors_translated
 from serverish.messenger import Messenger
 from serverish.messenger.messenger import MsgDriver
 
@@ -44,7 +46,8 @@ class Rpc:
         messenger = Messenger() # this is singleton anyway
         msg = messenger.create_msg(data=self.resp_data, meta=self.resp_meta)
         bmsg = messenger.encode(msg)
-        await self.nats_msg.respond(bmsg)
+        with nats_errors_translated(f"Responding to request on '{self.nats_msg.subject}' failed"):
+            await self.nats_msg.respond(bmsg)
 
 
 class MsgRpcResponder(MsgDriver):
@@ -120,9 +123,9 @@ class MsgRpcResponder(MsgDriver):
 
     async def _register_function_internal(self, callback: Callable[[Rpc], None] | Callable[[Rpc], asyncio.Future]):
         """Internal method to register the callback with NATS subscription"""
-        from nats.aio.client import Client as NATS
-
-        nats: NATS = self.connection.nc
+        nc = self.connection.nc
+        if nc is None:
+            raise MessengerNotConnected(f"Cannot subscribe RPC responder for '{self.subject}', NATS not connected")
         if asyncio.iscoroutinefunction(callback):
             acb = callback
             scb = None
@@ -152,13 +155,15 @@ class MsgRpcResponder(MsgDriver):
                 await rpc.send_response()
 
 
-        self.subscription = await nats.subscribe(self.subject, queue=self.subject, cb=_cb)
+        with nats_errors_translated(f"Subscribing RPC responder for '{self.subject}' failed"):
+            self.subscription = await nc.subscribe(self.subject, queue=self.subject, cb=_cb)
 
     async def close(self) -> None:
         """Close the responder and unregister from reconnection callbacks"""
         self.connection.remove_reconnect_cb(self.on_nats_reconnect)
         if self.subscription is not None:
-            await self.subscription.unsubscribe()
+            with nats_errors_translated(f"Unsubscribing RPC responder for '{self.subject}' failed"):
+                await self.subscription.unsubscribe()
         self._callback = None  # Clear callback reference
         return await super().close()