Skip to content

Add JetStream KV bucket support (v2.1.0) - #35

Merged
majkelx merged 2 commits into
masterfrom
feature/kv-buckets
Aug 5, 2026
Merged

majkelx merged 2 commits into
masterfrom
feature/kv-buckets

Conversation

@majkelx

@majkelx majkelx commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds first-class support for NATS JetStream KV buckets to the Messenger, following the existing driver architecture.

New driver hierarchy (all under MsgDriver):

MsgKvDriver                # common base: bucket bind/create, envelope encode/decode
├── MsgKvStore             # put / get / delete / purge / keys / history / status
└── MsgKvReader            # async iterator over kv.watch(), yields (data, meta)
    └── MsgKvSubscriber    # callback on each change, stop-on-False semantics
  • Full envelope semantics: values are always serverish {"data", "meta"} envelopes — put validates against schemas, reading a foreign (non-serverish) entry raises MessengerKvMalformed instead of returning garbage. The only protocol-forced exception: KV delete/purge tombstones carry no payload and surface as (None, meta) with meta['kv']['operation'] set to 'DEL'/'PURGE'.
  • Key/revision metadata in meta['kv']: bucket, key, revision, operation, created.
  • ConnectionJetStream.ensure_kv_bucket() — buckets are not created on the fly by default (consistent with stream philosophy); drivers opt in via create_bucket=True + bucket_config.
  • Factories: Messenger.get_kvstore / get_kvreader / get_kvsubscriber, module-level get_kvstore/get_kvreader/get_kvsubscriber and one-shot kv_put / kv_get.
  • New exceptions: MessengerKvBucketNotFound, MessengerKvKeyNotFound, MessengerKvMalformed.
  • The watch loop lives only in MsgKvReader, the background-task machinery only in MsgKvSubscriber — linear hierarchy prepared for a future MsgKvDocumentReader (LiveDocument over a bucket).

Version bumped to 2.1.0 (new feature, backward compatible).

Testing

  • 9 new tests in tests/test_messenger_kv.py (put/get round-trip, delete, keys/history, malformed entry, missing bucket, one-shot helpers, watch iteration incl. delete markers, callback subscriber).
  • Full suite: 300 passed, 8 skipped, 1 xfailed — no regressions.

Related: #34 (shared Event() default in MsgCallbackSubscriber, noticed while implementing MsgKvSubscriber).

🤖 Generated with Claude Code

https://claude.ai/code/session_01HfMGwatJe81U9aekr51R7f

@majkelx
majkelx merged commit fedfa90 into master Aug 5, 2026
2 checks passed
@majkelx
majkelx deleted the feature/kv-buckets branch August 5, 2026 12:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant