nanocached 0.1.0__tar.gz

nanocached-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takashi Yamashina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nanocached-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: nanocached
+Version: 0.1.0
+Summary: asyncio client SDK for nanocached, a tiny distributed cache with client-side replication
+Author: Takashi Yamashina
+License-Expression: MIT
+Project-URL: Homepage, https://nanocached.org
+Project-URL: Repository, https://github.com/nanocached/nanocached
+Project-URL: Issues, https://github.com/nanocached/nanocached/issues
+Keywords: nanocached,cache,distributed-cache,rendezvous-hashing,client,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nanocached (Python)
+
+asyncio client SDK for [nanocached](https://github.com/nanocached/nanocached),
+a tiny distributed cache. Talks to either a single `nanocached-node` or a
+`nanocached-discovery`-fronted cluster — the SDK figures out which from the
+server's own handshake, so the calling code is identical either way.
+
+Requires Python 3.11+. No runtime dependencies.
+
+## Install
+
+```sh
+pip install nanocached
+```
+
+## Quick start
+
+```python
+import asyncio
+from nanocached import NanocachedClient
+
+async def main():
+    # Point at a single node, or at a discovery server fronting a
+    # cluster — same call either way. `addresses` always takes a list;
+    # a one-element list is the single-target case.
+    client = await NanocachedClient.connect([("127.0.0.1", 8357)])
+
+    await client.set("greeting", "hello", ttl_seconds=60)
+    value = await client.get("greeting")   # str | None
+    print(value)                           # hello
+    existed = await client.delete("greeting")  # bool
+
+    client.close()
+
+asyncio.run(main())
+```
+
+Or use it as an async context manager, which closes the client for you:
+
+```python
+async with await NanocachedClient.connect([("127.0.0.1", 8357)]) as client:
+    await client.set("greeting", "hello")
+    print(await client.get("greeting"))
+```
+
+Keys may be `str` (encoded as UTF-8) or `bytes`; values may likewise be
+`str` or `bytes` on the way in. `get(key)` strictly decodes the stored
+value as UTF-8 and returns `str | None` — a value that isn't valid UTF-8
+raises `UnicodeDecodeError` rather than silently mangling it. Use
+`get_bytes(key) -> bytes | None` for the raw bytes.
+
+## Discovery replicas
+
+When the cluster runs more than one discovery server, pass them all in
+`addresses`; both the initial connect and every node-list refresh try them
+in order. An address that is warming up after a restart (answers `B`) is
+skipped like an unreachable one; if every address is warming up, `connect()`
+raises `DiscoveryBusyError` — retry shortly.
+
+```python
+client = await NanocachedClient.connect([("10.0.0.1", 8357), ("10.0.0.2", 8357)])
+```
+
+## Replication
+
+The cluster's replication factor R rides along with the node list, so the
+SDK needs no configuration: `set`/`delete` fan out to all R owners of a
+key (the primary's result decides; a dead replica never fails a write),
+and `get` asks the primary, falling over to the next owner only when the
+holder is unreachable. `client.replication` exposes the factor in use.
+
+## Fire-and-forget replica writes
+
+Off by default. `set`/`delete` normally wait for every replica leg to
+finish, same as the primary. Enabling `fire_and_forget_replicas` returns
+as soon as the primary acks, letting replica legs finish in the
+background (doc/adr/0014-*.md):
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    fire_and_forget_replicas=True,
+)
+```
+
+Unlike `compress`, this is a pure latency/durability trade for this
+client's own writes — it carries no wire format, and different clients
+may use different settings freely. At most 32 replica writes across the
+whole client run in the background at once; past that cap, further
+replica legs run synchronously exactly as with the option off (a
+graceful degrade, not a queue or a drop). `close()` gives any
+still-in-flight background replica writes a chance to finish before
+tearing down their connections.
+
+## Read repair
+
+Off by default. A clean miss (the key's first-reached owner reports it
+missing) is normally accepted as-is. Enabling `read_repair` probes the
+remaining owners before accepting that, and repairs the primary in the
+background if one still has the value (doc/adr/0015-*.md):
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    read_repair=True,
+)
+```
+
+Closes the narrow window after a primary restart where a replica still
+holds a key its (fresh) primary doesn't, at the cost of extra reads only
+on the misses that hit that window. The repair write carries no TTL —
+the wire protocol's `G` response never returns one to preserve — and,
+unlike fire-and-forget replica writes, is uncapped and not drained on
+`close()`: this only fires on an already-rare clean miss, and losing one
+costs nothing beyond staying in the window for one more read.
+
+## Reconnect and keep-alive
+
+`nanocached-node` closes connections idle for 60 seconds; the SDK keeps
+its connections warm automatically, pinging any connection that real
+traffic has left idle for 30 seconds — so an idle timeout never severs a
+healthy client, and a request that does find its connection dead (a node
+restart, a network blip) redials and retries once transparently (all
+operations are idempotent). There is nothing to configure.
+
+## Authentication and TLS
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    auth_secret="change-me",   # NANOCACHED_AUTH_SECRET on the server
+    tls=True,                  # verifies against the platform trust store
+)
+```
+
+For a self-signed or private-CA server, pass `ca` — a PEM file of trusted
+root certificate(s), which replaces the default trust store:
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    tls=True,
+    ca="cluster-ca.pem",
+)
+```
+
+`ca` is only meaningful when `tls=True`; if `tls=False` it is silently
+ignored. An unreadable or unparseable CA file is a connect-time error.
+
+## Value compression
+
+Off by default. When enabled, values at or above `compression_threshold`
+bytes are transparently DEFLATE-compressed on `set` and decompressed on
+`get`/`get_bytes` (doc/adr/0013-\*.md):
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    compress=True,
+    compression_threshold=256,  # default; bytes, below which values are stored as-is
+)
+```
+
+**Every client that reads or writes a given set of keys must agree on
+`compress`.** This is a per-keyspace format decision, not a per-client
+preference — enabling it prefixes every value this client writes with a
+one-byte marker, so a client with `compress=False` reading one of those
+values gets the marker byte back as if it were part of the value (wrong,
+silently), and a client with `compress=True` reading a value written
+before compression was enabled anywhere risks misreading that value's
+first byte as the marker (a `DecompressionError`, or — if that byte
+happens to be the "uncompressed" marker by chance — a silently wrong
+read). There is no dual-mode migration path: only turn this on for a
+fresh keyspace, or only after every client touching an existing one has
+upgraded and enabled it together. Incompressible data (already-compressed
+media, random bytes) is passed through unchanged rather than bloated.
+
+## Notes
+
+- Requests are pipelined per connection (doc/adr/0016-*.md), matching
+  the TypeScript SDK: concurrent callers on the same connection each pay
+  only their own network latency, not everyone else's ahead of them.
+- This SDK speaks the current wire protocol (rendezvous hashing,
+  replication-aware `L`/`W`); it requires an up-to-date server.
+- `close()` is idempotent, but calling it again on an already-closed
+  client prints a warning to stderr — usually a sign the client's
+  lifecycle was mismanaged. Likewise, calling `connect()` again for the
+  same single address while a previous connection to it is still open
+  prints a warning ("was close() forgotten?"); this check is skipped for
+  multi-address configs, where concurrent clients sharing an address list
+  are legitimate.
+
+## License
+
+MIT

nanocached-0.1.0/README.md

@@ -0,0 +1,195 @@
+# nanocached (Python)
+
+asyncio client SDK for [nanocached](https://github.com/nanocached/nanocached),
+a tiny distributed cache. Talks to either a single `nanocached-node` or a
+`nanocached-discovery`-fronted cluster — the SDK figures out which from the
+server's own handshake, so the calling code is identical either way.
+
+Requires Python 3.11+. No runtime dependencies.
+
+## Install
+
+```sh
+pip install nanocached
+```
+
+## Quick start
+
+```python
+import asyncio
+from nanocached import NanocachedClient
+
+async def main():
+    # Point at a single node, or at a discovery server fronting a
+    # cluster — same call either way. `addresses` always takes a list;
+    # a one-element list is the single-target case.
+    client = await NanocachedClient.connect([("127.0.0.1", 8357)])
+
+    await client.set("greeting", "hello", ttl_seconds=60)
+    value = await client.get("greeting")   # str | None
+    print(value)                           # hello
+    existed = await client.delete("greeting")  # bool
+
+    client.close()
+
+asyncio.run(main())
+```
+
+Or use it as an async context manager, which closes the client for you:
+
+```python
+async with await NanocachedClient.connect([("127.0.0.1", 8357)]) as client:
+    await client.set("greeting", "hello")
+    print(await client.get("greeting"))
+```
+
+Keys may be `str` (encoded as UTF-8) or `bytes`; values may likewise be
+`str` or `bytes` on the way in. `get(key)` strictly decodes the stored
+value as UTF-8 and returns `str | None` — a value that isn't valid UTF-8
+raises `UnicodeDecodeError` rather than silently mangling it. Use
+`get_bytes(key) -> bytes | None` for the raw bytes.
+
+## Discovery replicas
+
+When the cluster runs more than one discovery server, pass them all in
+`addresses`; both the initial connect and every node-list refresh try them
+in order. An address that is warming up after a restart (answers `B`) is
+skipped like an unreachable one; if every address is warming up, `connect()`
+raises `DiscoveryBusyError` — retry shortly.
+
+```python
+client = await NanocachedClient.connect([("10.0.0.1", 8357), ("10.0.0.2", 8357)])
+```
+
+## Replication
+
+The cluster's replication factor R rides along with the node list, so the
+SDK needs no configuration: `set`/`delete` fan out to all R owners of a
+key (the primary's result decides; a dead replica never fails a write),
+and `get` asks the primary, falling over to the next owner only when the
+holder is unreachable. `client.replication` exposes the factor in use.
+
+## Fire-and-forget replica writes
+
+Off by default. `set`/`delete` normally wait for every replica leg to
+finish, same as the primary. Enabling `fire_and_forget_replicas` returns
+as soon as the primary acks, letting replica legs finish in the
+background (doc/adr/0014-*.md):
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    fire_and_forget_replicas=True,
+)
+```
+
+Unlike `compress`, this is a pure latency/durability trade for this
+client's own writes — it carries no wire format, and different clients
+may use different settings freely. At most 32 replica writes across the
+whole client run in the background at once; past that cap, further
+replica legs run synchronously exactly as with the option off (a
+graceful degrade, not a queue or a drop). `close()` gives any
+still-in-flight background replica writes a chance to finish before
+tearing down their connections.
+
+## Read repair
+
+Off by default. A clean miss (the key's first-reached owner reports it
+missing) is normally accepted as-is. Enabling `read_repair` probes the
+remaining owners before accepting that, and repairs the primary in the
+background if one still has the value (doc/adr/0015-*.md):
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    read_repair=True,
+)
+```
+
+Closes the narrow window after a primary restart where a replica still
+holds a key its (fresh) primary doesn't, at the cost of extra reads only
+on the misses that hit that window. The repair write carries no TTL —
+the wire protocol's `G` response never returns one to preserve — and,
+unlike fire-and-forget replica writes, is uncapped and not drained on
+`close()`: this only fires on an already-rare clean miss, and losing one
+costs nothing beyond staying in the window for one more read.
+
+## Reconnect and keep-alive
+
+`nanocached-node` closes connections idle for 60 seconds; the SDK keeps
+its connections warm automatically, pinging any connection that real
+traffic has left idle for 30 seconds — so an idle timeout never severs a
+healthy client, and a request that does find its connection dead (a node
+restart, a network blip) redials and retries once transparently (all
+operations are idempotent). There is nothing to configure.
+
+## Authentication and TLS
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    auth_secret="change-me",   # NANOCACHED_AUTH_SECRET on the server
+    tls=True,                  # verifies against the platform trust store
+)
+```
+
+For a self-signed or private-CA server, pass `ca` — a PEM file of trusted
+root certificate(s), which replaces the default trust store:
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    tls=True,
+    ca="cluster-ca.pem",
+)
+```
+
+`ca` is only meaningful when `tls=True`; if `tls=False` it is silently
+ignored. An unreadable or unparseable CA file is a connect-time error.
+
+## Value compression
+
+Off by default. When enabled, values at or above `compression_threshold`
+bytes are transparently DEFLATE-compressed on `set` and decompressed on
+`get`/`get_bytes` (doc/adr/0013-\*.md):
+
+```python
+client = await NanocachedClient.connect(
+    [("cache.internal", 8357)],
+    compress=True,
+    compression_threshold=256,  # default; bytes, below which values are stored as-is
+)
+```
+
+**Every client that reads or writes a given set of keys must agree on
+`compress`.** This is a per-keyspace format decision, not a per-client
+preference — enabling it prefixes every value this client writes with a
+one-byte marker, so a client with `compress=False` reading one of those
+values gets the marker byte back as if it were part of the value (wrong,
+silently), and a client with `compress=True` reading a value written
+before compression was enabled anywhere risks misreading that value's
+first byte as the marker (a `DecompressionError`, or — if that byte
+happens to be the "uncompressed" marker by chance — a silently wrong
+read). There is no dual-mode migration path: only turn this on for a
+fresh keyspace, or only after every client touching an existing one has
+upgraded and enabled it together. Incompressible data (already-compressed
+media, random bytes) is passed through unchanged rather than bloated.
+
+## Notes
+
+- Requests are pipelined per connection (doc/adr/0016-*.md), matching
+  the TypeScript SDK: concurrent callers on the same connection each pay
+  only their own network latency, not everyone else's ahead of them.
+- This SDK speaks the current wire protocol (rendezvous hashing,
+  replication-aware `L`/`W`); it requires an up-to-date server.
+- `close()` is idempotent, but calling it again on an already-closed
+  client prints a warning to stderr — usually a sign the client's
+  lifecycle was mismanaged. Likewise, calling `connect()` again for the
+  same single address while a previous connection to it is still open
+  prints a warning ("was close() forgotten?"); this check is skipped for
+  multi-address configs, where concurrent clients sharing an address list
+  are legitimate.
+
+## License
+
+MIT

nanocached-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nanocached"
+version = "0.1.0"
+description = "asyncio client SDK for nanocached, a tiny distributed cache with client-side replication"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Takashi Yamashina" }]
+keywords = ["nanocached", "cache", "distributed-cache", "rendezvous-hashing", "client", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://nanocached.org"
+Repository = "https://github.com/nanocached/nanocached"
+Issues = "https://github.com/nanocached/nanocached/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

nanocached-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nanocached-0.1.0/src/nanocached/__init__.py

@@ -0,0 +1,28 @@
+"""nanocached — asyncio client SDK for the nanocached distributed cache.
+
+See https://github.com/nanocached/nanocached for the server and protocol.
+"""
+
+from ._compression import DecompressionError
+from ._errors import (
+    AlreadyClosedError,
+    DiscoveryBusyError,
+    NanocachedError,
+    WrongNodeError,
+)
+from ._hashring import HashRing
+from ._identify import DiscoveredNode
+from .client import NanocachedClient
+
+__all__ = [
+    "AlreadyClosedError",
+    "DecompressionError",
+    "DiscoveredNode",
+    "DiscoveryBusyError",
+    "HashRing",
+    "NanocachedClient",
+    "NanocachedError",
+    "WrongNodeError",
+]
+
+__version__ = "1.0.0"

nanocached-0.1.0/src/nanocached/_compression.py

@@ -0,0 +1,92 @@
+"""doc/adr/0013-*.md: transparent, opt-in value compression. Values are
+prefixed with a one-byte marker once ``compress`` is enabled on a client —
+``0x00`` for stored-as-is (below threshold, or compression didn't shrink
+it), ``0x01`` for raw-DEFLATE-compressed (RFC 1951, no zlib/gzip
+wrapper). Never present when ``compress`` is off."""
+
+from __future__ import annotations
+
+import zlib
+
+from ._errors import NanocachedError
+
+_MARKER_RAW = 0x00
+_MARKER_DEFLATE = 0x01
+
+# Raw DEFLATE (no zlib header/checksum): wbits=-15 selects it on both the
+# compress and decompress side. See doc/adr/0013-*.md for why raw DEFLATE
+# was chosen over a zlib/gzip wrapper.
+_WBITS_RAW_DEFLATE = -15
+
+# Bounds a DEFLATE value's expanded output. The wire cap
+# (_MAX_VALUE_LENGTH) bounds only the compressed bytes received; without
+# this, a small, highly-repetitive value written by a compromised node
+# could expand to gigabytes and exhaust client memory on a plain get (a
+# decompression bomb). Far above any realistic cache value.
+_MAX_DECOMPRESSED_LENGTH = 64 * 1024 * 1024
+
+
+class DecompressionError(NanocachedError):
+    """Raised by get/get_bytes when a value with ``compress`` enabled
+    can't be interpreted — almost always a ``compress`` mismatch between
+    clients sharing this key (doc/adr/0013-*.md's compatibility caveat:
+    every client touching a given keyspace must agree on ``compress``),
+    not a transient failure."""
+
+
+def compress_value(value: bytes, threshold: int) -> bytes:
+    """Below ``threshold``, or when compressing doesn't actually shrink
+    the value (incompressible data), the marker byte alone is added and
+    the value is stored unchanged. Always returns a value with the marker
+    byte prefixed."""
+    if len(value) < threshold:
+        return bytes([_MARKER_RAW]) + value
+
+    # zlib.compress() always emits a zlib-wrapped stream; compressobj()
+    # with a negative wbits is what produces the header-less raw DEFLATE
+    # form this SDK's wire format uses (see the module docstring).
+    compressor = zlib.compressobj(6, zlib.DEFLATED, _WBITS_RAW_DEFLATE)
+    compressed = compressor.compress(value) + compressor.flush()
+
+    if len(compressed) < len(value):
+        return bytes([_MARKER_DEFLATE]) + compressed
+    return bytes([_MARKER_RAW]) + value
+
+
+def decompress_value(value: bytes) -> bytes:
+    """The get/get_bytes counterpart to compress_value(). Only ever called
+    when ``compress`` is enabled on this client — see doc/adr/0013-*.md."""
+    if len(value) == 0:
+        raise DecompressionError(
+            "nanocached: compress is enabled but this value has no marker byte "
+            "(it's empty) — was it written by a client with compress disabled?"
+        )
+
+    marker, body = value[0], value[1:]
+
+    if marker == _MARKER_RAW:
+        return body
+
+    if marker == _MARKER_DEFLATE:
+        try:
+            decompressor = zlib.decompressobj(_WBITS_RAW_DEFLATE)
+            # max_length caps output; a non-empty unconsumed_tail (or an
+            # over-cap result) means more would follow — a bomb — so we stop
+            # rather than let flush() expand the rest into memory.
+            out = decompressor.decompress(body, _MAX_DECOMPRESSED_LENGTH + 1)
+            if decompressor.unconsumed_tail or len(out) > _MAX_DECOMPRESSED_LENGTH:
+                raise DecompressionError(
+                    "nanocached: decompressed value exceeds the maximum size — "
+                    "possible decompression bomb"
+                )
+            return out + decompressor.flush()
+        except zlib.error as error:
+            raise DecompressionError(
+                "nanocached: failed to decompress a value marked as compressed — "
+                f"did every client sharing this key enable compress (doc/adr/0013-*.md)? ({error})"
+            ) from error
+
+    raise DecompressionError(
+        f"nanocached: unrecognized compression marker byte {marker} — was this value "
+        "written by a client with compress disabled (doc/adr/0013-*.md)?"
+    )