silverhamu-service-client 0.2.0__tar.gz

silverhamu_service_client-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+/target/
+/artifacts/
+/.secrets/
+/data/
+.env
+*.ndb
+*.catbak
+*.accounts
+*.accounts.owner
+*.account-owner
+*.wal
+__pycache__/
+*.pyc
+/apps/**/bin/
+/apps/**/obj/
+/apps/.vs/
+/dotnet/**/bin/
+/dotnet/**/obj/
+**/TestResults/
+/AGENTS.md

silverhamu_service_client-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 dhq_boiler and contributors
+Copyright (c) 2026 NewDBMS contributors (imported SQL, desktop and online backup components)
+
+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.

silverhamu_service_client-0.2.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: silverhamu-service-client
+Version: 0.2.0
+Summary: Python client for the silverhamu TCP service with durable writes, transactions and TLS account authentication
+Project-URL: Repository, https://github.com/dhq-boiler/SilverHamu
+Project-URL: Documentation, https://github.com/dhq-boiler/SilverHamu/blob/main/docs/service.md
+Author: dhq_boiler and contributors
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# silverhamu for Python
+
+Install the package in a Python 3.10 or newer environment. The client uses the Python standard library at runtime.
+
+```sh
+python -m pip install silverhamu-service-client==0.2.0
+```
+
+Connect to a running silverhamu service and set `CATDB_TOKEN` to its shared token. [Starting a server](https://github.com/dhq-boiler/SilverHamu#quick-start)
+
+```python
+import os
+from silverhamu_client import Client
+
+with Client("127.0.0.1", 7400, os.environ["CATDB_TOKEN"]) as db:
+    version = db.put_commit(b"hello", b"world")
+    assert db.get_latest(b"hello") == b"world"
+```
+
+For TLS account authentication, pass `username=`, `password=` and optionally `database=` and `cafile=` to the constructor. The hostname must match the certificate. A missing key returns `None`. An empty stored value returns `b""`. Commit versions are decimal strings.
+
+Use `begin()`, `get()`, `put()`, `delete()`, `commit()` and `rollback()` for a transaction. Use `begin(read_only=True)` for a pinned snapshot. The `request(op=..., **fields)` method also supports the wire operations, including paginated scans. Server rejections raise `SilverHamuError` with a `code` attribute. After a lost reply, open a new client and inspect the result before retrying a write.
+
+For a replicated service, supply its cluster ID, client token and the configured **client** endpoints. The helper authenticates to these addresses and probes for an elected leader.
+
+```python
+seeds = [("127.0.0.1", 7401), ("127.0.0.1", 7402), ("127.0.0.1", 7403)]
+
+def connect():
+    return Client.connect_leader(seeds, os.environ["CATDB_TOKEN"],
+                                 cluster_id="books", discovery_timeout=10)
+
+with connect() as db:
+    value = db.get_latest(b"book/42")
+```
+
+Following an election or connection failure, call `connect()` again. A new connection has a new transaction context. Discovery verifies the cluster ID and confirms the reported leader can reach a quorum with a read-only ping. If a write reply is lost or reports `commit_uncertain`, inspect the application's committed state on the new leader before deciding whether to resubmit it.

silverhamu_service_client-0.2.0/clients/python/README.md

@@ -0,0 +1,37 @@
+# silverhamu for Python
+
+Install the package in a Python 3.10 or newer environment. The client uses the Python standard library at runtime.
+
+```sh
+python -m pip install silverhamu-service-client==0.2.0
+```
+
+Connect to a running silverhamu service and set `CATDB_TOKEN` to its shared token. [Starting a server](https://github.com/dhq-boiler/SilverHamu#quick-start)
+
+```python
+import os
+from silverhamu_client import Client
+
+with Client("127.0.0.1", 7400, os.environ["CATDB_TOKEN"]) as db:
+    version = db.put_commit(b"hello", b"world")
+    assert db.get_latest(b"hello") == b"world"
+```
+
+For TLS account authentication, pass `username=`, `password=` and optionally `database=` and `cafile=` to the constructor. The hostname must match the certificate. A missing key returns `None`. An empty stored value returns `b""`. Commit versions are decimal strings.
+
+Use `begin()`, `get()`, `put()`, `delete()`, `commit()` and `rollback()` for a transaction. Use `begin(read_only=True)` for a pinned snapshot. The `request(op=..., **fields)` method also supports the wire operations, including paginated scans. Server rejections raise `SilverHamuError` with a `code` attribute. After a lost reply, open a new client and inspect the result before retrying a write.
+
+For a replicated service, supply its cluster ID, client token and the configured **client** endpoints. The helper authenticates to these addresses and probes for an elected leader.
+
+```python
+seeds = [("127.0.0.1", 7401), ("127.0.0.1", 7402), ("127.0.0.1", 7403)]
+
+def connect():
+    return Client.connect_leader(seeds, os.environ["CATDB_TOKEN"],
+                                 cluster_id="books", discovery_timeout=10)
+
+with connect() as db:
+    value = db.get_latest(b"book/42")
+```
+
+Following an election or connection failure, call `connect()` again. A new connection has a new transaction context. Discovery verifies the cluster ID and confirms the reported leader can reach a quorum with a read-only ping. If a write reply is lost or reports `commit_uncertain`, inspect the application's committed state on the new leader before deciding whether to resubmit it.

silverhamu_service_client-0.2.0/clients/python/src/silverhamu_client/__init__.py

@@ -0,0 +1,108 @@
+"""Synchronous client for the silverhamu service."""
+
+from binascii import unhexlify
+from threading import RLock
+
+from ._wire import Client as _WireClient
+
+__all__ = ["Client", "SilverHamuError"]
+
+
+class SilverHamuError(Exception):
+    """Server rejection. The code is the error identifier from the wire."""
+
+    def __init__(self, code):
+        self.code = code
+        super().__init__(code)
+
+
+def _hex(value):
+    if not isinstance(value, (bytes, bytearray, memoryview)):
+        raise TypeError("expected a bytes-like key or value")
+    return value.hex()
+
+
+class Client(_WireClient):
+    """One connection and transaction context. Use a separate client per transaction."""
+
+    def __init__(self, host, port, token=None, timeout=10, *, username=None, password=None,
+                 database="main", cafile=None, _discovery_deadline=None):
+        if username is not None and password is None:
+            raise ValueError("account authentication requires a password")
+        self._lock = RLock()
+        self._closed = False
+        super().__init__(host, port, token, timeout, username=username, password=password,
+                         database=database, cafile=cafile, _discovery_deadline=_discovery_deadline)
+
+    def request(self, **fields):
+        """Send a wire operation. Versions in responses are decimal strings."""
+        body = self._encode(fields)
+        with self._lock:
+            if self._closed:
+                raise ConnectionError("silverhamu client is closed")
+            try:
+                response = self._exchange(body)
+                if not isinstance(response, dict) or type(response.get("ok")) is not bool:
+                    raise ValueError("invalid response envelope")
+                if not response["ok"]:
+                    if not isinstance(response.get("error"), str):
+                        raise ValueError("invalid error response")
+                    if response["error"] == "unauthorized":
+                        self.close()
+                    raise SilverHamuError(response["error"])
+                if fields.get("op") == "auth" and response.get("protocol") != fields["version"]:
+                    raise ValueError("unexpected authentication protocol")
+                if fields.get("op") in {"ping", "begin", "begin_read", "commit", "put_commit", "delete_commit"}:
+                    version = response.get("version")
+                    if not isinstance(version, str) or not version.isascii() or not version.isdecimal():
+                        raise ValueError("invalid silverhamu version")
+                return response
+            except (OSError, ValueError) as error:
+                self.close()
+                raise ConnectionError("silverhamu connection discarded; a submitted write may have committed") from error
+
+    def close(self):
+        with self._lock:
+            if not self._closed:
+                self._closed = True
+                super().close()
+
+    def _get(self, op, key):
+        with self._lock:
+            response = self.request(op=op, key=_hex(key))
+            try:
+                value = response["value"]
+                return None if value is None else unhexlify(value)
+            except (KeyError, TypeError, ValueError) as error:
+                self.close()
+                raise ConnectionError("invalid silverhamu value; connection discarded") from error
+
+    def ping(self):
+        return self.request(op="ping")["version"]
+
+    def get_latest(self, key):
+        return self._get("get_latest", key)
+
+    def put_commit(self, key, value):
+        return self.request(op="put_commit", key=_hex(key), value=_hex(value))["version"]
+
+    def delete_commit(self, key):
+        return self.request(op="delete_commit", key=_hex(key))["version"]
+
+    def begin(self, *, read_only=False):
+        return self.request(op="begin_read" if read_only else "begin")["version"]
+
+    def get(self, key):
+        return self._get("get", key)
+
+    def put(self, key, value):
+        self.request(op="put", key=_hex(key), value=_hex(value))
+
+    def delete(self, key):
+        self.request(op="delete", key=_hex(key))
+
+    def commit(self):
+        return self.request(op="commit")["version"]
+
+    def rollback(self):
+        self.request(op="rollback")

silverhamu_service_client-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.26,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "silverhamu-service-client"
+version = "0.2.0"
+description = "Python client for the silverhamu TCP service with durable writes, transactions and TLS account authentication"
+authors = [{ name = "dhq_boiler and contributors" }]
+readme = "clients/python/README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Repository = "https://github.com/dhq-boiler/SilverHamu"
+Documentation = "https://github.com/dhq-boiler/SilverHamu/blob/main/docs/service.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["clients/python/src/silverhamu_client"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"scripts/silverhamu-client.py" = "silverhamu_client/_wire.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["/clients/python/src/silverhamu_client", "/clients/python/README.md", "/scripts/silverhamu-client.py", "/LICENSE", "/pyproject.toml"]

silverhamu_service_client-0.2.0/scripts/silverhamu-client.py

@@ -0,0 +1,196 @@
+"""Experimental silverhamu v1 client. Requests are JSON lines on stdin; values are hex."""
+import argparse
+import getpass
+import json
+import math
+import pathlib
+import socket
+import ssl
+import struct
+import sys
+import time
+
+
+class Client:
+    _discovery_deadline = None
+
+    @classmethod
+    def connect_leader(cls, seeds, token, *, cluster_id, timeout=10, discovery_timeout=10):
+        """Probe configured client endpoints for a leader. Never submits or replays a write."""
+        if not isinstance(cluster_id, str) or not cluster_id:
+            raise ValueError("cluster_id must be a nonempty string")
+        if not math.isfinite(timeout) or timeout <= 0 or not math.isfinite(discovery_timeout) or discovery_timeout <= 0:
+            raise ValueError("timeouts must be positive and finite")
+        endpoints = list(dict.fromkeys((host, port) for host, port in seeds))
+        if not endpoints or any(not isinstance(host, str) or not host or type(port) is not int
+                                or not 0 < port <= 65535 for host, port in endpoints):
+            raise ValueError("seeds must contain (host, port) client endpoints")
+        deadline = time.monotonic() + discovery_timeout
+        while time.monotonic() < deadline:
+            for host, port in endpoints:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                client = None
+                try:
+                    # Leave time for the other configured nodes when one address is unreachable.
+                    probe_time = min(timeout, remaining, max(0.1, discovery_timeout / len(endpoints)))
+                    client = cls(host, port, token, timeout=probe_time, _discovery_deadline=time.monotonic() + probe_time)
+                    status = client.request(op="cluster_status")
+                    if not isinstance(status, dict) or status.get("ok") is not True:
+                        raise RuntimeError("endpoint rejected cluster_status")
+                    if status.get("cluster_id") != cluster_id:
+                        raise ValueError("seed belongs to a different silverhamu cluster")
+                    role = status.get("role")
+                    if role not in ("candidate", "follower", "leader"):
+                        raise ValueError("invalid cluster_status role")
+                    if role == "leader":
+                        if not isinstance(status.get("node_id"), str) or status["node_id"] != status.get("leader_id"):
+                            raise ValueError("inconsistent leader identity")
+                        # An isolated former leader can still report its old role. A ping needs a quorum.
+                        health = client._exchange(client._encode({"op": "ping"}))
+                        if isinstance(health, dict) and health.get("ok") is False and health.get("error") in (
+                                "not_leader", "quorum_unavailable", "resource_exhausted", "request_timeout"):
+                            continue
+                        version = health.get("version") if isinstance(health, dict) and health.get("ok") is True else None
+                        if not isinstance(version, str) or not version.isascii() or not version.isdecimal():
+                            raise ValueError("invalid leader ping")
+                        client._discovery_deadline = None
+                        client.socket.settimeout(timeout)
+                        leader, client = client, None
+                        return leader
+                except OSError:
+                    pass
+                finally:
+                    if client is not None:
+                        client.close()
+            remaining = deadline - time.monotonic()
+            if remaining > 0:
+                time.sleep(min(0.1, remaining))
+        raise TimeoutError("no leader found among the configured silverhamu endpoints")
+
+    def __init__(self, host, port, token=None, timeout=10, *, username=None, password=None,
+                 database="main", cafile=None, _discovery_deadline=None):
+        if (token is None) == (username is None):
+            raise ValueError("choose token or account authentication")
+        if token is not None and (password is not None or cafile is not None or database != "main"):
+            raise ValueError("TLS account options cannot be used with a token")
+        self._discovery_deadline = _discovery_deadline
+        self.socket = socket.create_connection((host, port), timeout)
+        try:
+            if username is not None:
+                context = ssl.create_default_context(cafile=cafile)
+                context.minimum_version = ssl.TLSVersion.TLSv1_3
+                self.socket = context.wrap_socket(self.socket, server_hostname=host)
+                response = self.request(op="auth", version=2, database=database,
+                                        username=username, password=password)
+            else:
+                response = self.request(op="auth", version=1, token=token)
+            if not response.get("ok"):
+                raise RuntimeError("silverhamu authentication failed")
+            self.account_id = response.get("account_id")
+        except BaseException:
+            self.close()
+            raise
+
+    def receive_exact(self, count):
+        chunks = bytearray()
+        while len(chunks) < count:
+            self._limit_discovery_wait()
+            chunk = self.socket.recv(count - len(chunks))
+            if not chunk:
+                raise ConnectionError("connection closed; a submitted commit may have completed")
+            chunks.extend(chunk)
+        return chunks
+
+    def _limit_discovery_wait(self):
+        if self._discovery_deadline is not None:
+            remaining = self._discovery_deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("silverhamu discovery probe timed out")
+            self.socket.settimeout(remaining)
+
+    @staticmethod
+    def _encode(request):
+        body = json.dumps(request, separators=(",", ":")).encode()
+        if len(body) > 1024 * 1024:
+            raise ValueError("request exceeds 1 MiB")
+        return body
+
+    def request(self, **request):
+        return self._exchange(self._encode(request))
+
+    def _exchange(self, body):
+        self._limit_discovery_wait()
+        self.socket.sendall(struct.pack("!I", len(body)) + body)
+        size = struct.unpack("!I", self.receive_exact(4))[0]
+        if not 0 < size <= 2 * 1024 * 1024 + 8192:
+            raise ValueError("invalid response size")
+        return json.loads(self.receive_exact(size).decode("utf-8"))
+
+    def close(self):
+        self.socket.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=7400)
+    auth = parser.add_mutually_exclusive_group(required=True)
+    auth.add_argument("--token-file", type=pathlib.Path)
+    auth.add_argument("--user")
+    parser.add_argument("--password-file", type=pathlib.Path)
+    parser.add_argument("--ca-file")
+    parser.add_argument("--database", default="main")
+    parser.add_argument("--create-user")
+    parser.add_argument("--role", choices=("reader","writer","admin"))
+    args = parser.parse_args()
+    if args.password_file and not args.user:
+        parser.error("--password-file requires --user")
+    if bool(args.create_user) != bool(args.role) or (args.create_user and not args.user):
+        parser.error("--create-user and --role require account authentication and each other")
+    token = args.token_file.read_text(encoding="utf-8").rstrip("\r\n") if args.token_file else None
+    password = None
+    if args.user:
+        if args.password_file:
+            with args.password_file.open("rb") as source:
+                secret = source.read(1027)
+            if len(secret) > 1026:
+                raise ValueError("password file too large")
+            password = secret.decode("utf-8")
+            if password.endswith("\n"):
+                password = password[:-1].removesuffix("\r")
+        else:
+            password = getpass.getpass("Account password: ")
+    with Client(args.host, args.port, token, username=args.user, password=password,
+                database=args.database, cafile=args.ca_file) as client:
+        if args.create_user:
+            new_password = getpass.getpass("New user's password: ")
+            if new_password != getpass.getpass("Confirm new password: "):
+                raise ValueError("passwords differ")
+            response = client.request(op="create_user", username=args.create_user,
+                                      password=new_password, role=args.role)
+            print(json.dumps(response))
+            return 0 if response.get("ok") else 1
+        for line in sys.stdin:
+            if not line.strip():
+                continue
+            response = client.request(**json.loads(line))
+            print(json.dumps(response, ensure_ascii=False), flush=True)
+            if not response.get("ok"):
+                return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"silverhamu-client: {error}", file=sys.stderr)
+        sys.exit(1)