natsio-kvcodec 0.1.0__tar.gz

natsio_kvcodec-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: natsio-kvcodec
+Version: 0.1.0
+Summary: natsio extension: transparent KV key/value codecs (base64, path, zlib, chaining) over the core codec seam
+Keywords: nats,nats.io,jetstream,key-value,kv,codec
+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
+Description-Content-Type: text/markdown
+
+# natsio-kvcodec
+
+Transparent **key/value codecs** for natsio's KV store, over the core's
+`KeyCodec` / `ValueCodec` seam. Encode keys and values on the way in, decode
+them on the way out — `get()`, `keys()`, `watch()`, and `history()` all speak the
+*decoded* form while the bucket stores the *encoded* form.
+
+Mirrors [`orbit.go/kvcodec`](https://github.com/synadia-io/orbit.go/tree/main/kvcodec),
+pythonized. Stdlib only; no runtime dependencies beyond `natsio`.
+
+```bash
+pip install natsio-kvcodec
+```
+
+## Usage
+
+Pass codecs to any `create_key_value` / `key_value` variant — the natsio core
+already accepts `key_codec=` and `value_codec=`:
+
+```python
+from natsio.kv import KeyValueConfig
+from natsio.kvcodec import PathKeyCodec, ZlibValueCodec
+
+kv = await js.create_key_value(
+    KeyValueConfig(bucket="cfg"),
+    key_codec=PathKeyCodec(),      # "/app/db/url" stored as "app.db.url"
+    value_codec=ZlibValueCodec(),  # values compressed at rest & over the wire
+)
+
+await kv.put("/app/db/url", b"postgres://localhost")
+entry = await kv.get("/app/db/url")   # entry.key == "/app/db/url"
+await kv.keys()                        # ["/app/db/url"] — DECODED keys
+```
+
+Key and value codecs are independent; use either, both, or neither.
+
+## Codecs
+
+### Key codecs (`str -> str`)
+
+| Codec | What it does | orbit.go parity |
+|---|---|---|
+| `Base64KeyCodec` | Per-token raw URL-safe base64 (dots kept as separators). Lets a key carry characters illegal in NATS subjects — modulo the core-friction caveat below. | `Base64Codec` (key side) |
+| `PathKeyCodec` | Filesystem keys `/a/b/c` <-> NATS `a.b.c`. Leading `/` becomes the `_root_` sentinel, trailing `/` trimmed. | `PathCodec` |
+| `NoOpKeyCodec` | Identity (the core's `key_codec=None` already means identity; useful as a chain filler). | `NoOpCodec` |
+| `ChainKeyCodec(*codecs)` | Apply key codecs in sequence (encode first->last, decode last->first). | `KeyChainCodec` |
+
+Every key codec guarantees its **encoded output satisfies
+`natsio.kv.validate_key`** (the raw URL-safe base64 alphabet and `_root_`
+sentinel are all NATS-legal), so the core accepts the encoded key as a subject.
+
+`Base64KeyCodec`, `PathKeyCodec`, `NoOpKeyCodec`, and an all-filterable
+`ChainKeyCodec` also implement `encode_filter(pattern)` (the core's
+runtime-checkable `natsio.kv.FilterableKeyCodec` protocol), which encodes a
+wildcard pattern while preserving `*`/`>`. **The natsio core calls this** from
+`watch()`, so a wildcard watch under one of these codecs is encoded per token
+(`orders.>` -> `b3JkZXJz.>`) and works end-to-end — see Core Friction.
+
+### Value codecs (`bytes -> bytes`)
+
+| Codec | What it does | orbit.go parity |
+|---|---|---|
+| `ZlibValueCodec(level=-1)` | Transparent DEFLATE via stdlib `zlib`. | *natsio addition* |
+| `Base64ValueCodec` | Whole-value raw URL-safe base64. | `Base64Codec` (value side) |
+| `NoOpValueCodec` | Identity. | `NoOpCodec` |
+| `ChainValueCodec(*codecs)` | Apply value codecs in sequence. | `ValueChainCodec` |
+
+**`ZlibValueCodec` tradeoffs.** It trades CPU for bytes, and *small or
+incompressible values come out larger* (a ~6-byte zlib envelope). It is not
+encryption. If you only want at-rest compression, prefer
+`KeyValueConfig(compression=True)` (server-side S2, zero client CPU); reach for
+this codec when you want the bytes compressed **over the wire** and counted in
+`max_bytes`.
+
+## Errors
+
+Codecs fail loud (like orbit.go's `error` returns), never silently pass corrupt
+data through:
+
+- `NoCodecsError` — empty `ChainKeyCodec()` / `ChainValueCodec()`.
+- `KeyDecodeError` / `ValueDecodeError` — corrupt/non-encoded input (a non-base64
+  token, a bad zlib stream).
+- `WildcardNotSupportedError` — `encode_filter` on a chain with a non-filterable
+  member.
+
+All derive from `KvCodecError`.
+
+## orbit.go parity notes
+
+- **Two classes per base64, not one.** Go's structural typing lets a single
+  `Base64Codec` satisfy both `KeyCodec` and `ValueCodec`. natsio's protocols
+  have different `encode` signatures (`str->str` vs `bytes->bytes`), so this
+  ships `Base64KeyCodec` and `Base64ValueCodec`.
+- **Naming.** orbit uses `EncodeKey`/`DecodeKey`; the natsio seam uses
+  `encode`/`decode`, so codecs follow the natsio spelling.
+- **`ZlibValueCodec` is new.** orbit ships only base64 for values; a value codec
+  is the natural home for compression, so natsio adds one.
+- Exact base64/path/filter **test vectors are ported** from orbit's
+  `codec_test.go` / `chain_codec_test.go`, so behavior matches byte-for-byte
+  (`Base64KeyCodec().encode("test.key...") == "dGVzdA.a2V5..."`, etc.).
+- **`PathKeyCodec` dot caveat (shared with orbit).** It maps `/`<->`.` and cannot
+  distinguish a literal `.` in the input from a separator, so feed it
+  path-style keys; `a.b` decodes back as `a/b`.
+
+## Core friction
+
+Building this extension stress-tested the codec seam. Two real gaps surfaced
+(neither is a codec bug — both are in the core, documented here so the behavior
+isn't surprising):
+
+1. **The raw key is validated *before* the codec runs, defeating Base64's main
+   use case.** `KeyValue._encode_key` calls `validate_key(raw_key)` and *then*
+   `validate_key(codec.encode(raw_key))`. So `put("Acme Inc.contact", ...)` with
+   `Base64KeyCodec` raises `InvalidKeyError` on the space — even though the codec
+   would turn it into the perfectly valid `QWNtZSBJbmM.Y29udGFjdA`. The escape-
+   exotic-characters scenario from orbit's own README cannot work end-to-end.
+   *Proposal:* when a `key_codec` is set, validate only the **encoded** key; the
+   raw key is the user's domain and only the stored subject must be NATS-legal.
+
+2. **`keys()` / `iter_keys()` (and `purge_deletes()`) still run the value codec
+   on a payload the server deliberately stripped.** Those paths use a
+   headers-only (`meta_only`) watch, so every delivery has an empty payload —
+   but `_entry_from_msg` unconditionally calls `value_codec.decode(payload)` for
+   `PUT` entries. Any value codec that can't decode `b""` (`ZlibValueCodec`,
+   encryption, length-prefixed framing) makes `keys()` raise `ValueDecodeError`.
+   *Proposal:* skip value decoding for headers-only deliveries (or when the
+   payload is empty under `meta_only`). Pinned by a strict `xfail` in
+   `test_kvcodec_live.py::test_keys_under_framing_value_codec_is_broken`.
+
+A third one — **the filter hook — is now closed.** orbit's `FilterableKeyCodec`
+lets a wildcard watch encode tokens individually (`orders.>` -> `b3JkZXJz.>`).
+The natsio core mirrors this: `watch()` recognises the runtime-checkable
+`natsio.kv.FilterableKeyCodec` protocol (which the codecs here implement) and
+calls `encode_filter()`, so per-token wildcard watches work end-to-end. Under a
+codec the *raw* filter is the caller's domain (it may be in the codec's own
+notation, e.g. `PathKeyCodec`'s `/a/*`) — only the encoded filter must be a
+legal subject filter. A wildcard watch under a *non*-filterable codec is still
+refused (`ConfigError`): encoding the whole key would mangle the `*`/`>`.

natsio_kvcodec-0.1.0/README.md

@@ -0,0 +1,138 @@
+# natsio-kvcodec
+
+Transparent **key/value codecs** for natsio's KV store, over the core's
+`KeyCodec` / `ValueCodec` seam. Encode keys and values on the way in, decode
+them on the way out — `get()`, `keys()`, `watch()`, and `history()` all speak the
+*decoded* form while the bucket stores the *encoded* form.
+
+Mirrors [`orbit.go/kvcodec`](https://github.com/synadia-io/orbit.go/tree/main/kvcodec),
+pythonized. Stdlib only; no runtime dependencies beyond `natsio`.
+
+```bash
+pip install natsio-kvcodec
+```
+
+## Usage
+
+Pass codecs to any `create_key_value` / `key_value` variant — the natsio core
+already accepts `key_codec=` and `value_codec=`:
+
+```python
+from natsio.kv import KeyValueConfig
+from natsio.kvcodec import PathKeyCodec, ZlibValueCodec
+
+kv = await js.create_key_value(
+    KeyValueConfig(bucket="cfg"),
+    key_codec=PathKeyCodec(),      # "/app/db/url" stored as "app.db.url"
+    value_codec=ZlibValueCodec(),  # values compressed at rest & over the wire
+)
+
+await kv.put("/app/db/url", b"postgres://localhost")
+entry = await kv.get("/app/db/url")   # entry.key == "/app/db/url"
+await kv.keys()                        # ["/app/db/url"] — DECODED keys
+```
+
+Key and value codecs are independent; use either, both, or neither.
+
+## Codecs
+
+### Key codecs (`str -> str`)
+
+| Codec | What it does | orbit.go parity |
+|---|---|---|
+| `Base64KeyCodec` | Per-token raw URL-safe base64 (dots kept as separators). Lets a key carry characters illegal in NATS subjects — modulo the core-friction caveat below. | `Base64Codec` (key side) |
+| `PathKeyCodec` | Filesystem keys `/a/b/c` <-> NATS `a.b.c`. Leading `/` becomes the `_root_` sentinel, trailing `/` trimmed. | `PathCodec` |
+| `NoOpKeyCodec` | Identity (the core's `key_codec=None` already means identity; useful as a chain filler). | `NoOpCodec` |
+| `ChainKeyCodec(*codecs)` | Apply key codecs in sequence (encode first->last, decode last->first). | `KeyChainCodec` |
+
+Every key codec guarantees its **encoded output satisfies
+`natsio.kv.validate_key`** (the raw URL-safe base64 alphabet and `_root_`
+sentinel are all NATS-legal), so the core accepts the encoded key as a subject.
+
+`Base64KeyCodec`, `PathKeyCodec`, `NoOpKeyCodec`, and an all-filterable
+`ChainKeyCodec` also implement `encode_filter(pattern)` (the core's
+runtime-checkable `natsio.kv.FilterableKeyCodec` protocol), which encodes a
+wildcard pattern while preserving `*`/`>`. **The natsio core calls this** from
+`watch()`, so a wildcard watch under one of these codecs is encoded per token
+(`orders.>` -> `b3JkZXJz.>`) and works end-to-end — see Core Friction.
+
+### Value codecs (`bytes -> bytes`)
+
+| Codec | What it does | orbit.go parity |
+|---|---|---|
+| `ZlibValueCodec(level=-1)` | Transparent DEFLATE via stdlib `zlib`. | *natsio addition* |
+| `Base64ValueCodec` | Whole-value raw URL-safe base64. | `Base64Codec` (value side) |
+| `NoOpValueCodec` | Identity. | `NoOpCodec` |
+| `ChainValueCodec(*codecs)` | Apply value codecs in sequence. | `ValueChainCodec` |
+
+**`ZlibValueCodec` tradeoffs.** It trades CPU for bytes, and *small or
+incompressible values come out larger* (a ~6-byte zlib envelope). It is not
+encryption. If you only want at-rest compression, prefer
+`KeyValueConfig(compression=True)` (server-side S2, zero client CPU); reach for
+this codec when you want the bytes compressed **over the wire** and counted in
+`max_bytes`.
+
+## Errors
+
+Codecs fail loud (like orbit.go's `error` returns), never silently pass corrupt
+data through:
+
+- `NoCodecsError` — empty `ChainKeyCodec()` / `ChainValueCodec()`.
+- `KeyDecodeError` / `ValueDecodeError` — corrupt/non-encoded input (a non-base64
+  token, a bad zlib stream).
+- `WildcardNotSupportedError` — `encode_filter` on a chain with a non-filterable
+  member.
+
+All derive from `KvCodecError`.
+
+## orbit.go parity notes
+
+- **Two classes per base64, not one.** Go's structural typing lets a single
+  `Base64Codec` satisfy both `KeyCodec` and `ValueCodec`. natsio's protocols
+  have different `encode` signatures (`str->str` vs `bytes->bytes`), so this
+  ships `Base64KeyCodec` and `Base64ValueCodec`.
+- **Naming.** orbit uses `EncodeKey`/`DecodeKey`; the natsio seam uses
+  `encode`/`decode`, so codecs follow the natsio spelling.
+- **`ZlibValueCodec` is new.** orbit ships only base64 for values; a value codec
+  is the natural home for compression, so natsio adds one.
+- Exact base64/path/filter **test vectors are ported** from orbit's
+  `codec_test.go` / `chain_codec_test.go`, so behavior matches byte-for-byte
+  (`Base64KeyCodec().encode("test.key...") == "dGVzdA.a2V5..."`, etc.).
+- **`PathKeyCodec` dot caveat (shared with orbit).** It maps `/`<->`.` and cannot
+  distinguish a literal `.` in the input from a separator, so feed it
+  path-style keys; `a.b` decodes back as `a/b`.
+
+## Core friction
+
+Building this extension stress-tested the codec seam. Two real gaps surfaced
+(neither is a codec bug — both are in the core, documented here so the behavior
+isn't surprising):
+
+1. **The raw key is validated *before* the codec runs, defeating Base64's main
+   use case.** `KeyValue._encode_key` calls `validate_key(raw_key)` and *then*
+   `validate_key(codec.encode(raw_key))`. So `put("Acme Inc.contact", ...)` with
+   `Base64KeyCodec` raises `InvalidKeyError` on the space — even though the codec
+   would turn it into the perfectly valid `QWNtZSBJbmM.Y29udGFjdA`. The escape-
+   exotic-characters scenario from orbit's own README cannot work end-to-end.
+   *Proposal:* when a `key_codec` is set, validate only the **encoded** key; the
+   raw key is the user's domain and only the stored subject must be NATS-legal.
+
+2. **`keys()` / `iter_keys()` (and `purge_deletes()`) still run the value codec
+   on a payload the server deliberately stripped.** Those paths use a
+   headers-only (`meta_only`) watch, so every delivery has an empty payload —
+   but `_entry_from_msg` unconditionally calls `value_codec.decode(payload)` for
+   `PUT` entries. Any value codec that can't decode `b""` (`ZlibValueCodec`,
+   encryption, length-prefixed framing) makes `keys()` raise `ValueDecodeError`.
+   *Proposal:* skip value decoding for headers-only deliveries (or when the
+   payload is empty under `meta_only`). Pinned by a strict `xfail` in
+   `test_kvcodec_live.py::test_keys_under_framing_value_codec_is_broken`.
+
+A third one — **the filter hook — is now closed.** orbit's `FilterableKeyCodec`
+lets a wildcard watch encode tokens individually (`orders.>` -> `b3JkZXJz.>`).
+The natsio core mirrors this: `watch()` recognises the runtime-checkable
+`natsio.kv.FilterableKeyCodec` protocol (which the codecs here implement) and
+calls `encode_filter()`, so per-token wildcard watches work end-to-end. Under a
+codec the *raw* filter is the caller's domain (it may be in the codec's own
+notation, e.g. `PathKeyCodec`'s `/a/*`) — only the encoded filter must be a
+legal subject filter. A wildcard watch under a *non*-filterable codec is still
+refused (`ConfigError`): encoding the whole key would mangle the `*`/`>`.

natsio_kvcodec-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["uv_build>=0.10,<0.11"]
+build-backend = "uv_build"
+
+[project]
+name = "natsio-kvcodec"
+version = "0.1.0"
+description = "natsio extension: transparent KV key/value codecs (base64, path, zlib, chaining) over the core codec seam"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Corrupt Mane", email = "corruptmane@gmail.com" }]
+keywords = ["nats", "nats.io", "jetstream", "key-value", "kv", "codec"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["natsio"]
+
+[tool.uv.sources]
+natsio = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "natsio.kvcodec"
+namespace = true

natsio_kvcodec-0.1.0/src/natsio/kvcodec/__init__.py

@@ -0,0 +1,69 @@
+"""natsio.kvcodec — KV key/value codecs over the core's codec seam.
+
+Ready-made :class:`natsio.kv.KeyCodec` / :class:`natsio.kv.ValueCodec`
+implementations, mirroring `orbit.go/kvcodec
+<https://github.com/synadia-io/orbit.go/tree/main/kvcodec>`_, for
+:func:`natsio.jetstream.JetStreamContext.create_key_value`'s ``key_codec=`` /
+``value_codec=`` arguments::
+
+    from natsio.kv import KeyValueConfig
+    from natsio.kvcodec import PathKeyCodec, ZlibValueCodec
+
+    kv = await js.create_key_value(
+        KeyValueConfig(bucket="cfg"),
+        key_codec=PathKeyCodec(),        # "/app/db" stored as "app.db"
+        value_codec=ZlibValueCodec(),    # values compressed at rest
+    )
+    await kv.put("/app/db/url", b"postgres://...")
+    (await kv.get("/app/db/url")).value  # transparently decoded
+
+Codecs are transparent: keys/values are encoded on write and decoded on read,
+including the keys returned by ``keys()``/``iter_keys()`` and the entries from
+``watch()``/``history()``.
+
+See the package README for the mapping to orbit.go codecs and the "Core
+friction" notes (raw-key pre-validation, and wildcard watches under a key
+codec).
+"""
+
+from .errors import (
+    KeyDecodeError,
+    KeyEncodeError,
+    KvCodecError,
+    NoCodecsError,
+    ValueDecodeError,
+    ValueEncodeError,
+    WildcardNotSupportedError,
+)
+from .key_codecs import (
+    Base64KeyCodec,
+    ChainKeyCodec,
+    FilterableKeyCodec,
+    NoOpKeyCodec,
+    PathKeyCodec,
+)
+from .value_codecs import (
+    Base64ValueCodec,
+    ChainValueCodec,
+    NoOpValueCodec,
+    ZlibValueCodec,
+)
+
+__all__ = [
+    "Base64KeyCodec",
+    "Base64ValueCodec",
+    "ChainKeyCodec",
+    "ChainValueCodec",
+    "FilterableKeyCodec",
+    "KeyDecodeError",
+    "KeyEncodeError",
+    "KvCodecError",
+    "NoCodecsError",
+    "NoOpKeyCodec",
+    "NoOpValueCodec",
+    "PathKeyCodec",
+    "ValueDecodeError",
+    "ValueEncodeError",
+    "WildcardNotSupportedError",
+    "ZlibValueCodec",
+]

natsio_kvcodec-0.1.0/src/natsio/kvcodec/errors.py

@@ -0,0 +1,61 @@
+"""Typed errors for kvcodec.
+
+Codecs fail *loud*: a corrupt or non-encoded input raises rather than silently
+passing through. This mirrors orbit.go/kvcodec (which returns an ``error`` from
+every ``Decode*``) and keeps a bucket that somehow accumulated foreign/garbage
+data from being misread as if it round-tripped cleanly.
+"""
+
+__all__ = [
+    "KeyDecodeError",
+    "KeyEncodeError",
+    "KvCodecError",
+    "NoCodecsError",
+    "ValueDecodeError",
+    "ValueEncodeError",
+    "WildcardNotSupportedError",
+]
+
+
+class KvCodecError(Exception):
+    """Base class for every kvcodec failure."""
+
+
+class NoCodecsError(KvCodecError, ValueError):
+    """A chain codec was constructed with zero codecs (orbit ``ErrNoCodecs``)."""
+
+
+class KeyEncodeError(KvCodecError):
+    """A key codec could not encode a key (orbit ``ErrKeyEncodeFailed``)."""
+
+
+class KeyDecodeError(KvCodecError):
+    """A key codec could not decode a stored key (orbit ``ErrKeyDecodeFailed``).
+
+    Raised on corrupt/non-encoded key tokens — e.g. a base64 token that is not
+    valid base64.
+    """
+
+
+class ValueEncodeError(KvCodecError):
+    """A value codec could not encode a value (orbit ``ErrValueEncodeFailed``)."""
+
+
+class ValueDecodeError(KvCodecError):
+    """A value codec could not decode a stored value (orbit ``ErrValueDecodeFailed``).
+
+    Raised on corrupt/non-encoded payloads — e.g. a zlib stream with a bad
+    checksum, or non-base64 bytes.
+    """
+
+
+class WildcardNotSupportedError(KvCodecError):
+    """A filter with ``*``/``>`` was handed to a codec that cannot preserve them
+    (orbit ``ErrWildcardNotSupported``).
+
+    NOTE: the natsio core does not yet call ``encode_filter`` — it refuses
+    wildcard watches under any key codec outright (see the extension README's
+    "Core friction" section). This error exists for codecs that *do* implement
+    :class:`~natsio.kvcodec.FilterableKeyCodec`, and for the day the seam grows
+    a filter hook.
+    """

natsio_kvcodec-0.1.0/src/natsio/kvcodec/key_codecs.py

@@ -0,0 +1,220 @@
+"""Key codecs — bidirectional ``str -> str`` transforms over the core's
+:class:`natsio.kv.KeyCodec` seam.
+
+Every codec here guarantees that the *encoded* form of any NATS-valid key is
+itself a NATS-valid key (it satisfies :func:`natsio.kv.validate_key`), so the
+core accepts it as a subject token. See the extension README for the one place
+this is not enough — the core validates the *raw* key too, which blocks
+Base64's escape-exotic-characters use case.
+"""
+
+import base64
+import binascii
+from typing import cast
+
+from natsio.kv import FilterableKeyCodec as CoreFilterableKeyCodec
+from natsio.kv import KeyCodec
+
+from .errors import (
+    KeyDecodeError,
+    NoCodecsError,
+    WildcardNotSupportedError,
+)
+
+__all__ = [
+    "Base64KeyCodec",
+    "ChainKeyCodec",
+    "FilterableKeyCodec",
+    "NoOpKeyCodec",
+    "PathKeyCodec",
+]
+
+# Subject wildcards. A whole-token ``*`` matches one token; a final ``>``
+# matches the rest. A filter is a key that may contain these; encode_filter
+# must pass them through untouched.
+_WILDCARDS = frozenset({"*", ">"})
+
+
+class FilterableKeyCodec(CoreFilterableKeyCodec):
+    """Marker/base for key codecs that can encode a *filter* (a key that may
+    contain ``*``/``>`` wildcards) while preserving the wildcards.
+
+    Explicitly implements the core's runtime-checkable
+    :class:`natsio.kv.FilterableKeyCodec` protocol, so the core's ``watch()``
+    recognises these codecs (via ``isinstance``) and encodes wildcard filters
+    per token instead of refusing them. Mirrors orbit.go's optional
+    ``FilterableKeyCodec`` interface. A codec is "filterable" iff it provides
+    ``encode_filter``; :class:`ChainKeyCodec` is filterable only when *every*
+    member is.
+
+    Subclassing is not required — the core protocol is structural — but
+    subclassing documents intent and gives you the :meth:`is_filterable`
+    helper.
+    """
+
+    @staticmethod
+    def is_filterable(codec: object) -> bool:
+        return isinstance(codec, CoreFilterableKeyCodec)
+
+    def encode_filter(self, key_filter: str) -> str:
+        # Overridden by every concrete filterable codec here; the default keeps
+        # the type visible to callers that ``cast`` a checked member.
+        raise NotImplementedError
+
+
+class NoOpKeyCodec(FilterableKeyCodec):
+    """Identity key codec (orbit ``NoOpCodec``).
+
+    The core already treats ``key_codec=None`` as identity, so this is only
+    useful as an explicit filler inside a :class:`ChainKeyCodec` or when a
+    non-optional codec argument is wanted.
+    """
+
+    def encode(self, key: str) -> str:
+        return key
+
+    def decode(self, key: str) -> str:
+        return key
+
+    def encode_filter(self, key_filter: str) -> str:
+        return key_filter
+
+
+def _b64_encode_token(token: str) -> str:
+    # Raw URL-safe base64 (no ``=`` padding), matching orbit.go's
+    # base64.RawURLEncoding. The alphabet ``A-Za-z0-9-_`` is a subset of what a
+    # NATS key token allows, so the result is always a valid token.
+    return base64.urlsafe_b64encode(token.encode()).rstrip(b"=").decode("ascii")
+
+
+def _b64_decode_token(token: str) -> str:
+    padded = token + "=" * (-len(token) % 4)
+    try:
+        return base64.urlsafe_b64decode(padded).decode("utf-8")
+    except (binascii.Error, ValueError) as exc:
+        raise KeyDecodeError(f"invalid base64 key token {token!r}: {exc}") from exc
+
+
+class Base64KeyCodec(FilterableKeyCodec):
+    """Per-token URL-safe base64 (orbit ``Base64Codec`` key side).
+
+    The key is split on ``.`` and each token is base64-encoded independently, so
+    dots keep their meaning as subject-token separators and wildcard filters
+    stay per-token (:meth:`encode_filter`). Because the raw URL-safe alphabet is
+    a subset of the NATS key alphabet, encoding a NATS-valid key yields a
+    NATS-valid key.
+
+    Its *purpose* — per orbit — is to let keys carry characters that are not
+    valid in NATS subjects (spaces, ``@``, ``:`` ...). The codec does that
+    correctly, BUT the natsio core validates the *raw* key before any codec
+    runs, so such keys are rejected before this codec sees them. See the
+    README's "Core friction" section.
+    """
+
+    def encode(self, key: str) -> str:
+        return ".".join(_b64_encode_token(t) for t in key.split("."))
+
+    def decode(self, key: str) -> str:
+        return ".".join(_b64_decode_token(t) for t in key.split("."))
+
+    def encode_filter(self, key_filter: str) -> str:
+        return ".".join(t if t in _WILDCARDS else _b64_encode_token(t) for t in key_filter.split("."))
+
+
+# Path keys that start with ``/`` are stored with this sentinel first token,
+# because a NATS subject cannot start with ``.`` (which is what a bare leading
+# ``/`` would otherwise become). Matches orbit.go's ``_root_``.
+_ROOT_PREFIX = "_root_"
+
+
+class PathKeyCodec(FilterableKeyCodec):
+    """Filesystem-style keys ``/a/b/c`` <-> NATS ``a.b.c`` (orbit ``PathCodec``).
+
+    Rules (mirrored from orbit.go, verified against its test vectors):
+
+    * a leading ``/`` becomes the ``_root_`` sentinel token (``/`` alone ->
+      ``_root_``); this keeps the leading-slash distinction round-trippable
+      without producing a subject that starts with ``.``;
+    * a trailing ``/`` is trimmed (subjects cannot end with ``.``);
+    * remaining ``/`` become ``.``.
+
+    Key-only: values pass through untouched, so pair it with a value codec (or
+    none) via :func:`natsio.jetstream.JetStreamContext.create_key_value`'s
+    separate ``value_codec=``.
+
+    Caveat (shared with orbit.go): the codec maps ``/`` <-> ``.`` and cannot
+    tell a *literal* ``.`` in the input from a separator, so feed it path-style
+    keys (separators are ``/``). A dotted input like ``a.b`` decodes back as
+    ``a/b`` — it does not round-trip.
+
+    Edge case worth knowing: an *empty* path segment (``/a//b``) encodes to a
+    key with an empty token (``_root_.a..b``), which is NOT a valid NATS key —
+    the core's post-encode ``validate_key`` rejects it with ``InvalidKeyError``.
+    orbit.go has the same latent output; natsio just catches it at the seam.
+    """
+
+    def encode(self, key: str) -> str:
+        if key.startswith("/"):
+            if key == "/":
+                return _ROOT_PREFIX
+            key = _ROOT_PREFIX + "." + key[1:]
+        key = key.removesuffix("/")
+        return key.replace("/", ".")
+
+    def decode(self, key: str) -> str:
+        if key == _ROOT_PREFIX:
+            return "/"
+        prefix = _ROOT_PREFIX + "."
+        if key.startswith(prefix):
+            return "/" + key[len(prefix) :].replace(".", "/")
+        return key.replace(".", "/")
+
+    def encode_filter(self, key_filter: str) -> str:
+        # PathCodec's encode already leaves ``*``/``>`` alone (they contain no
+        # ``/``), so filter-encoding is just encode. Matches orbit.go.
+        return self.encode(key_filter)
+
+
+class ChainKeyCodec(FilterableKeyCodec):
+    """Apply several key codecs in sequence (orbit ``KeyChainCodec``).
+
+    Encoding runs the codecs first-to-last; decoding runs them last-to-first, so
+    ``decode(encode(k)) == k``. Construct with at least one codec, else
+    :class:`~natsio.kvcodec.NoCodecsError`.
+
+    Example — path notation *then* base64-escape the segments::
+
+        ChainKeyCodec(PathKeyCodec(), Base64KeyCodec())
+
+    :meth:`encode_filter` is available only when *every* member is filterable;
+    otherwise it raises :class:`~natsio.kvcodec.WildcardNotSupportedError`
+    naming the offending position (a chain cannot promise wildcard preservation
+    if any link would mangle a ``*``/``>``).
+    """
+
+    __slots__ = ("_codecs",)
+
+    def __init__(self, *codecs: KeyCodec) -> None:
+        if not codecs:
+            raise NoCodecsError("at least one codec must be provided")
+        self._codecs: tuple[KeyCodec, ...] = codecs
+
+    def encode(self, key: str) -> str:
+        for codec in self._codecs:
+            key = codec.encode(key)
+        return key
+
+    def decode(self, key: str) -> str:
+        for codec in reversed(self._codecs):
+            key = codec.decode(key)
+        return key
+
+    def encode_filter(self, key_filter: str) -> str:
+        for index, codec in enumerate(self._codecs):
+            if not FilterableKeyCodec.is_filterable(codec):
+                raise WildcardNotSupportedError(
+                    f"codec {index} ({type(codec).__name__}) does not support wildcard filtering"
+                )
+        for codec in self._codecs:
+            key_filter = cast("FilterableKeyCodec", codec).encode_filter(key_filter)
+        return key_filter

natsio_kvcodec-0.1.0/src/natsio/kvcodec/value_codecs.py

@@ -0,0 +1,124 @@
+"""Value codecs — bidirectional ``bytes -> bytes`` transforms over the core's
+:class:`natsio.kv.ValueCodec` seam.
+
+Values are never validated by the core (only keys are), so a value codec may
+produce arbitrary bytes.
+"""
+
+import base64
+import binascii
+import zlib
+
+from natsio.kv import ValueCodec
+
+from .errors import NoCodecsError, ValueDecodeError
+
+__all__ = [
+    "Base64ValueCodec",
+    "ChainValueCodec",
+    "NoOpValueCodec",
+    "ZlibValueCodec",
+]
+
+
+class NoOpValueCodec:
+    """Identity value codec (orbit ``NoOpCodec``, value side).
+
+    ``value_codec=None`` already means identity in the core; use this only as an
+    explicit filler in a :class:`ChainValueCodec`.
+    """
+
+    def encode(self, value: bytes) -> bytes:
+        return value
+
+    def decode(self, value: bytes) -> bytes:
+        return value
+
+
+class Base64ValueCodec:
+    """Whole-value raw URL-safe base64 (orbit ``Base64Codec`` value side).
+
+    Rarely useful on its own for a KV value (it only inflates size by ~33% and
+    adds no safety, since values are opaque bytes to NATS), but it mirrors
+    orbit.go and is handy as a chain link or for producing ASCII-safe payloads.
+    """
+
+    def encode(self, value: bytes) -> bytes:
+        return base64.urlsafe_b64encode(value).rstrip(b"=")
+
+    def decode(self, value: bytes) -> bytes:
+        padded = value + b"=" * (-len(value) % 4)
+        try:
+            return base64.urlsafe_b64decode(padded)
+        except (binascii.Error, ValueError) as exc:
+            raise ValueDecodeError(f"invalid base64 value: {exc}") from exc
+
+
+class ZlibValueCodec:
+    """Transparent DEFLATE compression via stdlib :mod:`zlib`.
+
+    Not in orbit.go (which ships only base64 for values) — a natsio judgment
+    call, since a value codec is the natural home for compression.
+
+    Tradeoffs, so you use it deliberately:
+
+    * **CPU for bytes.** Every put compresses and every get decompresses. For
+      hot, tiny values that overhead can dwarf the savings.
+    * **Small values grow.** zlib adds a ~2-byte header + 4-byte checksum, so
+      short/incompressible payloads come out *larger*. Compression is a win for
+      larger, repetitive values (JSON, text, logs).
+    * **Not encryption.** It hides nothing; it only shrinks.
+    * **Server-side compression exists.** ``KeyValueConfig(compression=True)``
+      compresses the whole stream at rest (S2), transparently and without client
+      CPU. Prefer that unless you specifically want the bytes compressed *over
+      the wire* and in ``max_bytes`` accounting — which is what this codec buys
+      you.
+
+    ``level`` is the standard zlib 0-9 (default ``-1`` = library default ~6).
+    A corrupt/non-zlib payload raises :class:`~natsio.kvcodec.ValueDecodeError`.
+    """
+
+    __slots__ = ("_level",)
+
+    def __init__(self, level: int = -1) -> None:
+        if not (-1 <= level <= 9):
+            raise ValueError(f"zlib level must be between -1 and 9, got {level}")
+        self._level = level
+
+    def encode(self, value: bytes) -> bytes:
+        return zlib.compress(value, self._level)
+
+    def decode(self, value: bytes) -> bytes:
+        try:
+            return zlib.decompress(value)
+        except zlib.error as exc:
+            raise ValueDecodeError(f"invalid zlib value: {exc}") from exc
+
+
+class ChainValueCodec:
+    """Apply several value codecs in sequence (orbit ``ValueChainCodec``).
+
+    Encoding runs first-to-last, decoding last-to-first. Construct with at least
+    one codec, else :class:`~natsio.kvcodec.NoCodecsError`.
+
+    Order matters: ``ChainValueCodec(ZlibValueCodec(), Base64ValueCodec())``
+    compresses *then* base64s (ASCII-safe compressed payload); the reverse would
+    base64 first and compress incompressible base64 output — usually pointless.
+    """
+
+    __slots__ = ("_codecs",)
+
+    def __init__(self, *codecs: ValueCodec) -> None:
+        if not codecs:
+            raise NoCodecsError("at least one codec must be provided")
+        self._codecs: tuple[ValueCodec, ...] = codecs
+
+    def encode(self, value: bytes) -> bytes:
+        for codec in self._codecs:
+            value = codec.encode(value)
+        return value
+
+    def decode(self, value: bytes) -> bytes:
+        for codec in reversed(self._codecs):
+            value = codec.decode(value)
+        return value