serverish - helpers for server alike projects

Features

• Component management
• Singletons
• Connections management and diagnostics
• NATS based Messenger — publishers, readers, KV buckets, RPC (user guide with examples)
• Live documents - auto-updating configuration from NATS

See the Messenger user guide and the doc directory for more documentation.

Optional (extras) dependencies

The following extras are available:

• messenger - for using NATS based Messenger. Will install nats-py package.
• dns - for using aiodns DNS resolver for connection status diagnostics, it's extracted as an extra dependency because it's not available on all platforms.

In order to use Messenger, you have to add extra 'messenger' to your project.toml serveris dependency, e.g.:

serverish = {git="https://github.com/AkondLab/serverish.git", extras=["messenger"], branch="master"}

or specify dpendency with extras in the pip convention: serverish[messenger]. this will install nats-py package.

Plans

• Decorators @messenger.sub(subject) (Web framework style)
• Progress with automatic increment for known durations e.g. pro_pub.update(completed=1, when=+20)
• Custom JetStream API replacing nats-py private internals access

Changes

• 2.5.1 A reader which is open reads. A recovery cut short by the network could leave a reader open and deaf for good: its consumer alive on the server, the answers reaching nobody (seen in a long-running service after a power outage). The reader now replaces its consumer and subscription as one, the new pair first, and judges them by the server's answers to its own pull requests instead of asking whether the consumer exists - one JetStream API request per reader every 10 s less. A missing consumer is never a fatal error, a missing stream still is. RetryPolicy.total_timeout of a reader limits an attempt to recover as well, not only the pauses between attempts.
• 2.5 Deadlines and cancellation. Python 3.11+. publish(timeout=X) is now the deadline of the whole call, retries included (it used to apply to each of up to 3 attempts); without it a publish gives up after RetryPolicy.total_timeout (15 s; a journal entry after 5 s). New RetryPolicy.attempt_timeout. Every timeout is a MessengerTimeout. A reader's total_timeout is a real deadline and its clock stops when the server answers again. A cancelled read_next() always ends (a cancellation lost in the client library kept it polling for ever). wait_for_psce() is deprecated: use asyncio.timeout().
• 2.4 Policy objects (DeliveryPolicy, ErrorPolicy/RetryPolicy, BatchPolicy) for typed driver configuration with backward-compatible string/kwarg forms; dynamic pull batching by default; driver lifecycle fixes (closed drivers leave the Messenger tree); deprecates get_singlepublisher/get_singlereader and publishing on never-opened publishers. See the Messenger user guide.
• 2.3.2 Quieter and more honest logs when the connection is in trouble: an idle reader no longer asks the server about its consumer every 2 s (only the periodic health check does), a warning raised by many readers at once is logged once with a summary of the rest, Messenger.open() giving up logs one warning (no traceback, no false "backgrounding"). Messenger.is_open is true on a server which stores nothing yet. After a failed open() the Messenger is closed, so open() can be called again.
• 2.3.1 Subjects, not streams: get_publisher(subject, persistent=True) guarantees that published means stored (MessengerNotPersisted, checked on open()); publishing to a subject nobody stores now warns instead of passing silently. Subject families (family=True on readers: a subject and everything below it) and get_kvreader(..., nowait=True). See Subjects. Removed the unused MsgReader.next_msg() (an orphaned internal helper returning raw client-library messages; use read_next()).
• 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). Replace except nats.errors... handlers around serverish calls. raise_on_publish_error=False covers a missing connection too.
• 2.2 Deterministic end-of-data for nowait readers (server-stamped num_pending, no fixed waits); publish ack-timeout handling with Nats-Msg-Id dedup and transparent retries; common ServerishError exception base. Use 2.2.1+ — 2.2.0 is yanked (silent message loss, #38).
• 2.1 JetStream KV bucket support: MsgKvStore/MsgKvReader/MsgKvSubscriber with full envelope semantics and one-shot kv_get/kv_put.
• 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. Comprehensive test suite (194 tests) with testcontainers-based NATS fixtures.
• 1.5 Introduces live documents (LiveDocument, get_documentreader(), get_live_document()) for auto-updating configuration from NATS.
• 1.4 Contains improvements to the network problems recovery and connection tracking.
• 1.1 Switches to param 2.* nad py-nats 1.7.*. Also, publisher may reraise exceptions or ignore them.
• 1.0 Changes NATS subscriptions to pull only
• 0.12 Extends messges metdata of nats section, Handles reconnection of subscriptions,
• 0.11 Extends, tasks, NATS connection tracking and messenger opening options (Messenger.open)
• 0.10 Adds timestamp to journal messages and extablishes schema for journal messages.
• 0.9.1 Makes dependency to aiodns optional.
• 0.9.0 Introduces Logging handler for passing standard logging messages to the Messenger.
• 0.8 Introduces journal publishing/reading API.
• 0.7 Includes progress tracking messages in the Messenger API.
• 0.6 introduces breaking changes in the Messenger API:
  • Convenience functions get_xxxxx() returning publishers/readers are synchronous now. Remove await-ing for their results.
  • Change of signature of the callback for MsgRpcResponder.register_function for Rpc->None.

Credits

This package uses some code and ideas from the rich package (Copyright (c) 2020 Will McGugan).