natsio-counters 0.1.0__tar.gz

natsio_counters-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: natsio-counters
+Version: 0.1.0
+Summary: natsio extension: distributed counters (ADR-49) over JetStream counter streams
+Keywords: nats,nats.io,jetstream,counters,distributed-counter,adr-49
+Author: Corrupt Mane
+Author-email: Corrupt Mane <corruptmane@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: natsio
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/corruptmane/natsio
+Project-URL: Repository, https://github.com/corruptmane/natsio
+Project-URL: Changelog, https://github.com/corruptmane/natsio/blob/main/extensions/natsio-counters/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# natsio-counters
+
+Distributed counters over JetStream counter streams
+([ADR-49](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-49.md)),
+mirroring [`orbit.go/counters`](https://github.com/synadia-io/orbit.go/tree/main/counters).
+Distribution `natsio-counters`, imported as `natsio.counters`. Zero runtime
+dependencies beyond `natsio`. Pre-1.0, no API-stability promises.
+
+Requires **nats-server 2.12+** (the `allow_msg_counter` stream feature).
+
+## What it is
+
+A *counter stream* is a normal JetStream stream created with
+`allow_msg_counter`. Every subject the stream captures becomes an independent,
+**arbitrary-precision** counter. Incrementing is an ordinary publish carrying a
+`Nats-Incr` header; the server folds the delta into a running total, stores it
+as the subject's latest message, and returns the new value in the PubAck — so a
+bare `add` needs no follow-up read.
+
+Python `int` is itself unbounded, so it is used directly for both deltas and
+values — no big-integer wrapper.
+
+## Usage
+
+```python
+import natsio
+from natsio.counters import CounterConfig, create_counter, get_counter
+
+nc = await natsio.connect("nats://localhost")
+js = nc.jetstream()
+
+# Create a counter stream (allow_msg_counter + allow_direct are forced on).
+counter = await create_counter(js, CounterConfig(name="COUNTS", subjects=["events.>"]))
+# ...or bind an existing one:  counter = await get_counter(js, "COUNTS")
+
+# Increment / decrement — returns the new running total, straight from the PubAck.
+await counter.add("events.orders", 1)      # -> 1
+await counter.add("events.orders", 10)     # -> 11
+await counter.add("events.orders", -4)     # negative deltas are fine  -> 7
+await counter.add("events.orders", 0)      # zero is a valid no-op increment
+
+# Read a single counter's current value.
+value = await counter.load("events.orders")          # -> 7
+
+# Full entry: value + most-recent increment + source history (aggregation only).
+entry = await counter.get("events.orders")
+print(entry.value, entry.incr, entry.sources)
+
+# Enumerate many counters in one batch Direct Get (wildcards allowed).
+async for entry in counter.get_multiple(["events.>"]):
+    print(entry.subject, entry.value)
+```
+
+## API
+
+| Symbol | Purpose |
+|---|---|
+| `create_counter(js, config)` | Create a counter stream and return its `Counter`. |
+| `get_counter(js, name)` | Bind an existing counter stream by name. |
+| `counter_from_stream(js, stream)` | Wrap an already-fetched counter `Stream` (no round-trip). |
+| `Counter.add(subject, delta) -> int` | Increment/decrement; returns the new total. |
+| `Counter.load(subject) -> int` | Current value of one subject's counter. |
+| `Counter.get(subject) -> CounterEntry` | Value + last increment + sources. |
+| `Counter.get_multiple(subjects) -> AsyncIterator[CounterEntry]` | Batch/wildcard enumeration. |
+| `CounterConfig` | Counter-stream configuration. |
+| `CounterEntry` | `subject`, `value`, `sources`, `incr`. |
+
+Errors (all subclass `natsio.jetstream.JetStreamError`): `CounterNotEnabledError`,
+`DirectAccessRequiredError`, `CounterNotFoundError`,
+`CounterSubjectNotInitializedError`, `InvalidCounterValueError`.
+
+## ADR-49 wire contract
+
+Pinned by the wire-contract tests and exported as constants:
+
+- **Increment header** `Nats-Incr` (`COUNTER_INCREMENT_HEADER`) — a base-10
+  integer of any size, optional leading sign. A counter stream **rejects any
+  publish without it** (`message counter increment is missing`).
+- **Sources header** `Nats-Counter-Sources` (`COUNTER_SOURCES_HEADER`) —
+  server-set JSON `{source_stream: {subject: contribution}}`; present only on
+  aggregating counters.
+- **Stored payload** `{"val": "<int-as-string>"}` — the value is a *string* so
+  it survives languages whose JSON numbers cap at 2^53.
+- **PubAck** carries the new total in its `val` field (fast feedback, no Get).
+
+Notes: `allow_msg_counter` can be set **only at stream creation** (it is read-only
+afterwards) and is **incompatible with per-message TTLs and message schedules**,
+so `CounterConfig` intentionally does not expose those knobs. Reads use Direct
+Get, so `allow_direct` is required (and forced on by `create_counter`).

natsio_counters-0.1.0/README.md

@@ -0,0 +1,89 @@
+# natsio-counters
+
+Distributed counters over JetStream counter streams
+([ADR-49](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-49.md)),
+mirroring [`orbit.go/counters`](https://github.com/synadia-io/orbit.go/tree/main/counters).
+Distribution `natsio-counters`, imported as `natsio.counters`. Zero runtime
+dependencies beyond `natsio`. Pre-1.0, no API-stability promises.
+
+Requires **nats-server 2.12+** (the `allow_msg_counter` stream feature).
+
+## What it is
+
+A *counter stream* is a normal JetStream stream created with
+`allow_msg_counter`. Every subject the stream captures becomes an independent,
+**arbitrary-precision** counter. Incrementing is an ordinary publish carrying a
+`Nats-Incr` header; the server folds the delta into a running total, stores it
+as the subject's latest message, and returns the new value in the PubAck — so a
+bare `add` needs no follow-up read.
+
+Python `int` is itself unbounded, so it is used directly for both deltas and
+values — no big-integer wrapper.
+
+## Usage
+
+```python
+import natsio
+from natsio.counters import CounterConfig, create_counter, get_counter
+
+nc = await natsio.connect("nats://localhost")
+js = nc.jetstream()
+
+# Create a counter stream (allow_msg_counter + allow_direct are forced on).
+counter = await create_counter(js, CounterConfig(name="COUNTS", subjects=["events.>"]))
+# ...or bind an existing one:  counter = await get_counter(js, "COUNTS")
+
+# Increment / decrement — returns the new running total, straight from the PubAck.
+await counter.add("events.orders", 1)      # -> 1
+await counter.add("events.orders", 10)     # -> 11
+await counter.add("events.orders", -4)     # negative deltas are fine  -> 7
+await counter.add("events.orders", 0)      # zero is a valid no-op increment
+
+# Read a single counter's current value.
+value = await counter.load("events.orders")          # -> 7
+
+# Full entry: value + most-recent increment + source history (aggregation only).
+entry = await counter.get("events.orders")
+print(entry.value, entry.incr, entry.sources)
+
+# Enumerate many counters in one batch Direct Get (wildcards allowed).
+async for entry in counter.get_multiple(["events.>"]):
+    print(entry.subject, entry.value)
+```
+
+## API
+
+| Symbol | Purpose |
+|---|---|
+| `create_counter(js, config)` | Create a counter stream and return its `Counter`. |
+| `get_counter(js, name)` | Bind an existing counter stream by name. |
+| `counter_from_stream(js, stream)` | Wrap an already-fetched counter `Stream` (no round-trip). |
+| `Counter.add(subject, delta) -> int` | Increment/decrement; returns the new total. |
+| `Counter.load(subject) -> int` | Current value of one subject's counter. |
+| `Counter.get(subject) -> CounterEntry` | Value + last increment + sources. |
+| `Counter.get_multiple(subjects) -> AsyncIterator[CounterEntry]` | Batch/wildcard enumeration. |
+| `CounterConfig` | Counter-stream configuration. |
+| `CounterEntry` | `subject`, `value`, `sources`, `incr`. |
+
+Errors (all subclass `natsio.jetstream.JetStreamError`): `CounterNotEnabledError`,
+`DirectAccessRequiredError`, `CounterNotFoundError`,
+`CounterSubjectNotInitializedError`, `InvalidCounterValueError`.
+
+## ADR-49 wire contract
+
+Pinned by the wire-contract tests and exported as constants:
+
+- **Increment header** `Nats-Incr` (`COUNTER_INCREMENT_HEADER`) — a base-10
+  integer of any size, optional leading sign. A counter stream **rejects any
+  publish without it** (`message counter increment is missing`).
+- **Sources header** `Nats-Counter-Sources` (`COUNTER_SOURCES_HEADER`) —
+  server-set JSON `{source_stream: {subject: contribution}}`; present only on
+  aggregating counters.
+- **Stored payload** `{"val": "<int-as-string>"}` — the value is a *string* so
+  it survives languages whose JSON numbers cap at 2^53.
+- **PubAck** carries the new total in its `val` field (fast feedback, no Get).
+
+Notes: `allow_msg_counter` can be set **only at stream creation** (it is read-only
+afterwards) and is **incompatible with per-message TTLs and message schedules**,
+so `CounterConfig` intentionally does not expose those knobs. Reads use Direct
+Get, so `allow_direct` is required (and forced on by `create_counter`).

natsio_counters-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["uv_build>=0.10,<0.11"]
+build-backend = "uv_build"
+
+[project]
+name = "natsio-counters"
+version = "0.1.0"
+description = "natsio extension: distributed counters (ADR-49) over JetStream counter streams"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Corrupt Mane", email = "corruptmane@gmail.com" }]
+keywords = ["nats", "nats.io", "jetstream", "counters", "distributed-counter", "adr-49"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["natsio"]
+
+[project.urls]
+Homepage = "https://github.com/corruptmane/natsio"
+Repository = "https://github.com/corruptmane/natsio"
+Changelog = "https://github.com/corruptmane/natsio/blob/main/extensions/natsio-counters/CHANGELOG.md"
+
+[tool.uv.sources]
+natsio = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "natsio.counters"
+namespace = true

natsio_counters-0.1.0/src/natsio/counters/__init__.py

@@ -0,0 +1,61 @@
+"""Distributed counters over JetStream counter streams (ADR-49).
+
+A counter stream (``allow_msg_counter``) turns every subject it captures into
+an independent, arbitrary-precision counter. Increments are ordinary publishes
+carrying a ``Nats-Incr`` header; the server folds them into a running total and
+returns the new value in the PubAck, so a bare ``add`` needs no follow-up read.
+
+    js = nc.jetstream()
+    counter = await create_counter(js, CounterConfig(name="COUNTS", subjects=["events.>"]))
+
+    total = await counter.add("events.orders", 1)      # -> 1
+    total = await counter.add("events.orders", 10)     # -> 11
+    total = await counter.add("inventory.widgets", -3) # negative deltas are fine
+
+    value = await counter.load("events.orders")        # -> 11
+    entry = await counter.get("events.orders")          # value + last increment + sources
+
+    async for entry in counter.get_multiple(["events.>"]):
+        print(entry.subject, entry.value)
+
+Requires server 2.12+ (``allow_msg_counter``). ``allow_msg_counter`` can only
+be set when the stream is created and is incompatible with per-message TTLs and
+message schedules.
+"""
+
+from natsio.counters.counter import Counter, counter_from_stream, create_counter, get_counter
+from natsio.counters.entities import (
+    COUNTER_INCREMENT_HEADER,
+    COUNTER_SOURCES_HEADER,
+    CounterConfig,
+    CounterEntry,
+    CounterSources,
+    parse_counter_value,
+    parse_sources,
+)
+from natsio.counters.errors import (
+    CounterNotEnabledError,
+    CounterNotFoundError,
+    CounterSubjectNotInitializedError,
+    DirectAccessRequiredError,
+    InvalidCounterValueError,
+)
+
+__all__ = [
+    "COUNTER_INCREMENT_HEADER",
+    "COUNTER_SOURCES_HEADER",
+    "Counter",
+    "CounterConfig",
+    "CounterEntry",
+    "CounterNotEnabledError",
+    "CounterNotFoundError",
+    "CounterSources",
+    "CounterSubjectNotInitializedError",
+    "DirectAccessRequiredError",
+    "InvalidCounterValueError",
+    "counter_from_stream",
+    "create_counter",
+    "get_counter",
+    "parse_counter_value",
+    "parse_sources",
+]

natsio_counters-0.1.0/src/natsio/counters/counter.py

@@ -0,0 +1,183 @@
+"""The Counter handle: increment, load, and enumerate ADR-49 counters."""
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from natsio.jetstream.entities import DiscardPolicy, StorageCompression, StreamConfig
+from natsio.jetstream.errors import MessageNotFoundError, StreamNotFoundError
+from natsio.jetstream.stream import Stream
+
+from .entities import (
+    COUNTER_INCREMENT_HEADER,
+    CounterConfig,
+    CounterEntry,
+    parse_counter_value,
+    parse_sources,
+)
+from .errors import (
+    CounterNotEnabledError,
+    CounterNotFoundError,
+    CounterSubjectNotInitializedError,
+    DirectAccessRequiredError,
+    InvalidCounterValueError,
+)
+
+if TYPE_CHECKING:
+    from natsio.jetstream.context import JetStreamContext
+
+__all__ = ["Counter", "counter_from_stream", "create_counter", "get_counter"]
+
+
+class Counter:
+    """A handle to a JetStream stream configured for distributed counters.
+
+    Every subject the stream captures is an independent counter. Obtain via
+    `create_counter`, `get_counter`, or `counter_from_stream`.
+
+    Python ``int`` is arbitrary-precision, so it is used directly for both
+    deltas and values — no big-integer wrapper is needed to match the ADR-49
+    unbounded-integer semantics.
+    """
+
+    __slots__ = ("_ctx", "_stream", "name")
+
+    def __init__(self, ctx: "JetStreamContext", stream: Stream) -> None:
+        config = stream.cached_info.config
+        if not config.allow_msg_counter:
+            raise CounterNotEnabledError(
+                f"stream {config.name!r} is not a counter stream (needs allow_msg_counter=True)"
+            )
+        if not config.allow_direct:
+            raise DirectAccessRequiredError(f"stream {config.name!r} needs allow_direct=True for counter reads")
+        self._ctx = ctx
+        self._stream = stream
+        self.name = config.name
+
+    def __repr__(self) -> str:
+        return f"Counter(name={self.name!r})"
+
+    # -- writes --------------------------------------------------------------
+
+    async def add(self, subject: str, delta: int) -> int:
+        """Increment (or, with a negative ``delta``, decrement) ``subject``.
+
+        Returns the new running total, taken from the PubAck's ``val`` field —
+        no follow-up read. ``delta`` of ``0`` is a valid no-op increment that
+        still initializes the subject. The ``subject`` must be covered by the
+        stream's subjects, else `NoStreamResponseError`.
+        """
+        if isinstance(delta, bool) or not isinstance(delta, int):
+            raise InvalidCounterValueError(f"counter delta must be an int, got {type(delta).__name__}")
+        ack = await self._ctx.publish(subject, b"", headers={COUNTER_INCREMENT_HEADER: str(delta)})
+        if not ack.val:
+            raise InvalidCounterValueError(f"counter increment for {subject!r} returned no value")
+        return int(ack.val, 10)
+
+    # -- reads ---------------------------------------------------------------
+
+    async def load(self, subject: str) -> int:
+        """The current value of ``subject``'s counter.
+
+        Raises `CounterSubjectNotInitializedError` if nothing has been
+        added to ``subject`` yet.
+        """
+        stored = await self._get_last(subject)
+        return parse_counter_value(stored.payload)
+
+    async def get(self, subject: str) -> CounterEntry:
+        """The full `CounterEntry` for ``subject`` (value, sources, last increment).
+
+        Raises `CounterSubjectNotInitializedError` if nothing has been
+        added to ``subject`` yet.
+        """
+        stored = await self._get_last(subject)
+        return _entry_from_parts(subject, stored.payload, stored.headers)
+
+    async def _get_last(self, subject: str) -> Any:
+        try:
+            return await self._stream.get_msg(subject=subject)
+        except MessageNotFoundError:
+            raise CounterSubjectNotInitializedError(f"counter not initialized for subject {subject!r}") from None
+
+    async def get_multiple(self, subjects: list[str]) -> AsyncIterator[CounterEntry]:
+        """Yield a `CounterEntry` for each subject matching ``subjects``.
+
+        ``subjects`` may contain wildcards (``*`` / ``>``); each matched subject
+        yields its current entry. Backed by a single batch Direct Get
+        (``Stream.get_last_msgs_for``, ``multi_last`` per ADR-31) rather than one
+        round-trip per subject.
+        """
+        if not subjects:
+            return
+        async for stored in self._stream.get_last_msgs_for(subjects):
+            if not stored.subject:
+                continue
+            yield _entry_from_parts(stored.subject, stored.payload, stored.headers)
+
+
+def _entry_from_parts(subject: str, payload: bytes, headers: Any) -> CounterEntry:
+    value = parse_counter_value(payload)
+    sources = parse_sources(headers)
+    incr: int | None = None
+    if headers is not None:
+        raw_incr = headers.get(COUNTER_INCREMENT_HEADER)
+        if raw_incr:
+            try:
+                incr = int(raw_incr, 10)
+            except ValueError as exc:
+                raise InvalidCounterValueError(f"invalid {COUNTER_INCREMENT_HEADER} header: {raw_incr!r}") from exc
+    return CounterEntry(subject=subject, value=value, sources=sources, incr=incr)
+
+
+def _counter_stream_config(config: CounterConfig) -> StreamConfig:
+    """Map a `CounterConfig` onto its ADR-49 backing stream."""
+    return StreamConfig(
+        name=config.name,
+        description=config.description,
+        subjects=list(config.subjects),
+        storage=config.storage,
+        num_replicas=config.replicas,
+        max_bytes=config.max_bytes,
+        max_msgs_per_subject=config.max_msgs_per_subject,
+        max_age=config.max_age,
+        placement=config.placement,
+        compression=StorageCompression.S2 if config.compression else None,
+        metadata=config.metadata,
+        discard=DiscardPolicy.OLD,
+        allow_msg_counter=True,
+        allow_direct=True,
+    )
+
+
+def counter_from_stream(js: "JetStreamContext", stream: Stream) -> Counter:
+    """Wrap an existing counter `Stream` as a `Counter` (no round-trip).
+
+    Raises `CounterNotEnabledError` /
+    `DirectAccessRequiredError` if the stream is not counter-capable.
+    """
+    return Counter(js, stream)
+
+
+async def create_counter(js: "JetStreamContext", config: CounterConfig) -> Counter:
+    """Create a counter stream from ``config`` and return its `Counter`.
+
+    Re-creating with an identical configuration is idempotent; an existing
+    stream with a different configuration surfaces as the mapped
+    `APIError` (``StreamNameInUseError``).
+    """
+    stream = await js.create_stream(_counter_stream_config(config))
+    return Counter(js, stream)
+
+
+async def get_counter(js: "JetStreamContext", name: str) -> Counter:
+    """Bind an existing counter stream by ``name``.
+
+    Raises `CounterNotFoundError` if no such stream exists, or
+    `CounterNotEnabledError` /
+    `DirectAccessRequiredError` if it exists but is not a counter.
+    """
+    try:
+        stream = await js.stream(name)
+    except StreamNotFoundError:
+        raise CounterNotFoundError(f"no counter stream named {name!r}") from None
+    return Counter(js, stream)

natsio_counters-0.1.0/src/natsio/counters/entities.py

@@ -0,0 +1,143 @@
+"""Counter data types and the ADR-49 wire contract (headers, payload).
+
+The constants here are the pinned wire contract — kept as plain ``str`` (like
+``natsio.jetstream.headers``) because they go straight onto the wire, and
+asserted byte-for-byte against the oracle in the wire-contract tests.
+"""
+
+import json
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any, Final
+
+from natsio._internal.protocol import Headers
+from natsio.errors import ConfigError
+from natsio.jetstream.entities import Placement, StorageType
+
+from .errors import InvalidCounterValueError
+
+__all__ = [
+    "COUNTER_INCREMENT_HEADER",
+    "COUNTER_SOURCES_HEADER",
+    "CounterConfig",
+    "CounterEntry",
+    "CounterSources",
+    "parse_counter_value",
+    "parse_sources",
+]
+
+# -- ADR-49 wire contract ----------------------------------------------------
+# Client-set on a publish to increment (or, with a leading '-', decrement) the
+# per-subject counter. The value is a base-10 integer of arbitrary size.
+COUNTER_INCREMENT_HEADER: Final = "Nats-Incr"
+# Server-set on stored counter messages: a JSON object mapping each contributing
+# source stream to its per-subject contributions (populated on aggregating
+# streams that source from other counters). Absent on plain single-stream
+# counters.
+COUNTER_SOURCES_HEADER: Final = "Nats-Counter-Sources"
+
+# The stored counter payload is ``{"val": "<base-10 integer as a string>"}``.
+# The value is a *string* on the wire so it survives languages whose JSON
+# numbers top out at 2**53; Python ``int`` is itself arbitrary-precision, so it
+# is the natural in-memory type on both the read and the write side.
+_PAYLOAD_VALUE_KEY: Final = "val"
+
+type CounterSources = dict[str, dict[str, int]]
+"""``{source_stream: {subject: contribution}}`` — see ``COUNTER_SOURCES_HEADER``."""
+
+
+@dataclass(frozen=True, slots=True)
+class CounterEntry:
+    """A counter's current state for one subject.
+
+    ``value`` is the running total; ``incr`` is the most recent increment
+    (useful for auditing/recounting); ``sources`` is present only when the
+    counter aggregates other streams.
+    """
+
+    subject: str
+    value: int
+    sources: CounterSources | None = None
+    incr: int | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CounterConfig:
+    """Configuration for a counter stream (ADR-49).
+
+    Maps onto a JetStream stream with ``allow_msg_counter`` (the counter
+    behaviour) and ``allow_direct`` (the read path) forced on. Every subject the
+    stream captures is an independent counter. ``allow_msg_counter`` is settable
+    only at creation and is incompatible with per-message TTLs and message
+    schedules, so those knobs are intentionally not exposed here.
+    """
+
+    name: str
+    subjects: list[str]
+    description: str | None = None
+    storage: StorageType = StorageType.FILE
+    replicas: int = 1
+    max_bytes: int = -1
+    # Cap the retained increment history per subject (-1 = unlimited). The
+    # current value is always the last message per subject regardless.
+    max_msgs_per_subject: int = -1
+    # Age off old increments (None = never). Does not affect the current value
+    # unless a subject goes fully idle past this age.
+    max_age: timedelta | None = None
+    placement: Placement | None = None
+    compression: bool = False
+    metadata: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.subjects:
+            raise ConfigError("a counter stream needs at least one subject")
+
+
+def parse_counter_value(data: bytes) -> int:
+    """Parse a stored counter payload ``{"val": "<int>"}`` into an ``int``.
+
+    Raises `InvalidCounterValueError` on empty data, malformed JSON,
+    a missing ``val`` key, or a non-integer value.
+    """
+    if not data:
+        raise InvalidCounterValueError("empty counter value")
+    try:
+        payload: dict[str, Any] = json.loads(data)
+    except (ValueError, TypeError) as exc:
+        raise InvalidCounterValueError(f"malformed counter payload: {exc}") from exc
+    if not isinstance(payload, dict) or _PAYLOAD_VALUE_KEY not in payload:
+        raise InvalidCounterValueError(f"counter payload missing {_PAYLOAD_VALUE_KEY!r} field")
+    raw = payload[_PAYLOAD_VALUE_KEY]
+    try:
+        # ``int(str, 10)`` semantics: accept the string form the server writes,
+        # reject floats/booleans/None that would slip past a bare ``int()``.
+        return int(str(raw), 10)
+    except (ValueError, TypeError) as exc:
+        raise InvalidCounterValueError(f"invalid counter value: {raw!r}") from exc
+
+
+def parse_sources(headers: Headers | None) -> CounterSources | None:
+    """Parse the ``Nats-Counter-Sources`` header, or ``None`` when absent.
+
+    Raises `InvalidCounterValueError` on malformed JSON or a
+    non-integer contribution.
+    """
+    if headers is None:
+        return None
+    raw = headers.get(COUNTER_SOURCES_HEADER)
+    if not raw:
+        return None
+    try:
+        decoded: dict[str, dict[str, str]] = json.loads(raw)
+    except (ValueError, TypeError) as exc:
+        raise InvalidCounterValueError(f"malformed {COUNTER_SOURCES_HEADER} header: {exc}") from exc
+    result: CounterSources = {}
+    for source_id, contributions in decoded.items():
+        parsed: dict[str, int] = {}
+        for subject, value in contributions.items():
+            try:
+                parsed[subject] = int(str(value), 10)
+            except (ValueError, TypeError) as exc:
+                raise InvalidCounterValueError(f"invalid source contribution for {subject!r}: {value!r}") from exc
+        result[source_id] = parsed
+    return result

natsio_counters-0.1.0/src/natsio/counters/errors.py

@@ -0,0 +1,39 @@
+"""Counter error types (mirrors orbit.go ``counters/errors.go``)."""
+
+from natsio.jetstream.errors import JetStreamError
+
+__all__ = [
+    "CounterNotEnabledError",
+    "CounterNotFoundError",
+    "CounterSubjectNotInitializedError",
+    "DirectAccessRequiredError",
+    "InvalidCounterValueError",
+]
+
+
+class CounterNotEnabledError(JetStreamError):
+    """Wrapped a stream that lacks ``allow_msg_counter``.
+
+    ``allow_msg_counter`` can only be set at stream creation (ADR-49); an
+    existing plain stream cannot be turned into a counter after the fact.
+    """
+
+
+class DirectAccessRequiredError(JetStreamError):
+    """Wrapped a stream that lacks ``allow_direct``.
+
+    Reads (``load``/``get``/``get_multiple``) go through Direct Get, so the
+    backing stream must have ``allow_direct=True``.
+    """
+
+
+class InvalidCounterValueError(JetStreamError):
+    """A counter delta or a stored counter payload was not a valid integer."""
+
+
+class CounterNotFoundError(JetStreamError):
+    """No counter stream with that name exists."""
+
+
+class CounterSubjectNotInitializedError(JetStreamError):
+    """The subject has no stored increment yet — its counter is uninitialized."""