plasmite 1.3.0__py3-none-win_amd64.whl

plasmite/__init__.py

@@ -0,0 +1,1454 @@
+"""
+Purpose: Provide Python bindings for the libplasmite C ABI (v0).
+Key Exports: Client, Pool, Stream, Durability, ErrorKind, PlasmiteError.
+Role: Minimal, ergonomic wrapper around include/plasmite.h for Python users.
+Invariants: JSON bytes in/out; native operations and close serialize per handle.
+Invariants: Errors preserve stable kinds and context fields.
+Notes: Uses ctypes and links to libplasmite resolved at runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from ctypes import (
+    CDLL,
+    POINTER,
+    Structure,
+    byref,
+    c_char_p,
+    c_int,
+    c_size_t,
+    c_uint32,
+    c_uint64,
+    c_uint8,
+    c_void_p,
+    cast,
+    sizeof,
+)
+from datetime import datetime, timezone
+from enum import IntEnum
+from functools import wraps
+from threading import Lock, RLock
+import json
+import os
+import re
+from pathlib import Path
+import sys
+import time as _time
+from typing import Any, Generator, Iterable, Optional
+
+
+class ErrorKind(IntEnum):
+    INTERNAL = 1
+    USAGE = 2
+    NOT_FOUND = 3
+    ALREADY_EXISTS = 4
+    BUSY = 5
+    PERMISSION = 6
+    CORRUPT = 7
+    IO = 8
+    RETENTION_GAP = 9
+
+
+class Durability(IntEnum):
+    FAST = 0
+    FLUSH = 1
+
+
+class PlasmiteError(RuntimeError):
+    def __init__(
+        self,
+        kind: ErrorKind,
+        message: str,
+        path: str | None = None,
+        seq: int | None = None,
+        offset: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.kind = kind
+        self.path = path
+        self.seq = seq
+        self.offset = offset
+
+
+class NotFoundError(PlasmiteError):
+    pass
+
+
+class AlreadyExistsError(PlasmiteError):
+    pass
+
+
+class BusyError(PlasmiteError):
+    pass
+
+
+class PermissionDeniedError(PlasmiteError):
+    pass
+
+
+class CorruptError(PlasmiteError):
+    pass
+
+
+class IoError(PlasmiteError):
+    pass
+
+
+class UsageError(PlasmiteError):
+    pass
+
+
+class InternalError(PlasmiteError):
+    pass
+
+
+class RetentionGapError(PlasmiteError):
+    pass
+
+
+@dataclass(frozen=True)
+class MessageMeta:
+    tags: list[str]
+
+
+@dataclass(frozen=True)
+class Message:
+    seq: int
+    time: datetime
+    time_rfc3339: str
+    data: Any
+    meta: MessageMeta
+    raw: bytes
+
+    @property
+    def tags(self) -> list[str]:
+        return self.meta.tags
+
+
+class plsm_client_t(Structure):
+    pass
+
+
+class plsm_pool_t(Structure):
+    pass
+
+
+class plsm_stream_t(Structure):
+    pass
+
+
+class plsm_lite3_stream_t(Structure):
+    pass
+
+
+class plsm_udp_client_t(Structure):
+    pass
+
+
+class plsm_udp_pool_t(Structure):
+    pass
+
+
+class plsm_udp_follow_t(Structure):
+    pass
+
+
+class plsm_buf_t(Structure):
+    _fields_ = [
+        ("data", c_void_p),
+        ("len", c_size_t),
+    ]
+
+
+class plsm_udp_event_t(Structure):
+    _fields_ = [
+        ("kind", c_uint32),
+        ("reason", c_uint32),
+        ("seq", c_uint64),
+        ("timestamp_ns", c_uint64),
+        ("first", c_uint64),
+        ("last", c_uint64),
+        ("start_seq", c_uint64),
+        ("next_seq", c_uint64),
+        ("end_seq", c_uint64),
+        ("has_end", c_uint8),
+        ("terminal", c_uint8),
+        ("retention_gap", c_uint8),
+        ("reserved", c_uint8),
+        ("payload", plsm_buf_t),
+    ]
+
+
+class plsm_lite3_frame_t(Structure):
+    _fields_ = [
+        ("seq", c_uint64),
+        ("timestamp_ns", c_uint64),
+        ("flags", c_uint32),
+        ("payload", plsm_buf_t),
+    ]
+
+
+class plsm_error_t(Structure):
+    _fields_ = [
+        ("kind", c_int),
+        ("message", c_char_p),
+        ("path", c_char_p),
+        ("seq", c_uint64),
+        ("offset", c_uint64),
+        ("has_seq", c_uint8),
+        ("has_offset", c_uint8),
+    ]
+
+
+class plsm_stream_options_t(Structure):
+    _fields_ = [
+        ("struct_size", c_uint32),
+        ("gap_policy", c_uint32),
+        ("since_seq", c_uint64),
+        ("max_messages", c_uint64),
+        ("timeout_ms", c_uint64),
+        ("has_since", c_uint32),
+        ("has_max", c_uint32),
+        ("has_timeout", c_uint32),
+        ("reserved", c_uint32),
+    ]
+
+
+def _load_lib() -> CDLL:
+    env_dir = os.environ.get("PLASMITE_LIB_DIR")
+    if env_dir:
+        candidates = [
+            os.path.join(env_dir, name)
+            for name in ("plasmite.dll", "libplasmite.dylib", "libplasmite.so")
+        ]
+        for candidate in candidates:
+            if os.path.exists(candidate):
+                return CDLL(candidate)
+    native_dir = Path(__file__).resolve().parent / "_native"
+    for candidate in (
+        native_dir / "plasmite.dll",
+        native_dir / "libplasmite.dylib",
+        native_dir / "libplasmite.so",
+    ):
+        if candidate.exists():
+            return CDLL(str(candidate))
+    for name in ("plasmite.dll", "plasmite", "libplasmite"):
+        try:
+            return CDLL(name)
+        except OSError:
+            continue
+    raise OSError(
+        "libplasmite not found; set PLASMITE_LIB_DIR or build target/debug/libplasmite.*"
+    )
+
+
+_LIB = _load_lib()
+
+DEFAULT_POOL_SIZE_BYTES = 1024 * 1024
+DEFAULT_POOL_SIZE = DEFAULT_POOL_SIZE_BYTES
+_UINT64_MAX = (1 << 64) - 1
+
+
+def default_pool_dir() -> str:
+    # Compute lazily so tests/tools can override HOME in-process without re-importing.
+    # `expanduser("~")` consults HOME at call time on Unix.
+    return os.path.join(os.path.expanduser("~"), ".plasmite", "pools")
+
+
+DEFAULT_POOL_DIR = default_pool_dir()
+
+_LIB.plsm_client_new.argtypes = [c_char_p, POINTER(POINTER(plsm_client_t)), POINTER(POINTER(plsm_error_t))]
+_LIB.plsm_client_new.restype = c_int
+_LIB.plsm_client_free.argtypes = [POINTER(plsm_client_t)]
+_LIB.plsm_client_free.restype = None
+
+_LIB.plsm_pool_create.argtypes = [
+    POINTER(plsm_client_t),
+    c_char_p,
+    c_uint64,
+    POINTER(POINTER(plsm_pool_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_pool_create.restype = c_int
+_LIB.plsm_pool_open.argtypes = [
+    POINTER(plsm_client_t),
+    c_char_p,
+    POINTER(POINTER(plsm_pool_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_pool_open.restype = c_int
+_LIB.plsm_pool_free.argtypes = [POINTER(plsm_pool_t)]
+_LIB.plsm_pool_free.restype = None
+
+_LIB.plsm_pool_append_json.argtypes = [
+    POINTER(plsm_pool_t),
+    POINTER(c_uint8),
+    c_size_t,
+    POINTER(c_char_p),
+    c_size_t,
+    c_uint32,
+    POINTER(plsm_buf_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_pool_append_json.restype = c_int
+
+_LIB.plsm_pool_append_lite3.argtypes = [
+    POINTER(plsm_pool_t),
+    POINTER(c_uint8),
+    c_size_t,
+    c_uint32,
+    POINTER(c_uint64),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_pool_append_lite3.restype = c_int
+
+_LIB.plsm_pool_get_json.argtypes = [
+    POINTER(plsm_pool_t),
+    c_uint64,
+    POINTER(plsm_buf_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_pool_get_json.restype = c_int
+
+_LIB.plsm_pool_get_lite3.argtypes = [
+    POINTER(plsm_pool_t),
+    c_uint64,
+    POINTER(plsm_lite3_frame_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_pool_get_lite3.restype = c_int
+
+_LIB.plsm_stream_open.argtypes = [
+    POINTER(plsm_pool_t),
+    c_uint64,
+    c_uint32,
+    c_uint64,
+    c_uint32,
+    c_uint64,
+    c_uint32,
+    POINTER(POINTER(plsm_stream_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_stream_open.restype = c_int
+_LIB.plsm_stream_open_ex.argtypes = [
+    POINTER(plsm_pool_t),
+    POINTER(plsm_stream_options_t),
+    POINTER(POINTER(plsm_stream_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_stream_open_ex.restype = c_int
+
+_LIB.plsm_lite3_stream_open.argtypes = [
+    POINTER(plsm_pool_t),
+    c_uint64,
+    c_uint32,
+    c_uint64,
+    c_uint32,
+    c_uint64,
+    c_uint32,
+    POINTER(POINTER(plsm_lite3_stream_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_lite3_stream_open.restype = c_int
+_LIB.plsm_lite3_stream_open_ex.argtypes = [
+    POINTER(plsm_pool_t),
+    POINTER(plsm_stream_options_t),
+    POINTER(POINTER(plsm_lite3_stream_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_lite3_stream_open_ex.restype = c_int
+
+_LIB.plsm_stream_next.argtypes = [
+    POINTER(plsm_stream_t),
+    POINTER(plsm_buf_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_stream_next.restype = c_int
+
+_LIB.plsm_lite3_stream_next.argtypes = [
+    POINTER(plsm_lite3_stream_t),
+    POINTER(plsm_lite3_frame_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_lite3_stream_next.restype = c_int
+
+_LIB.plsm_stream_free.argtypes = [POINTER(plsm_stream_t)]
+_LIB.plsm_stream_free.restype = None
+
+_LIB.plsm_lite3_stream_free.argtypes = [POINTER(plsm_lite3_stream_t)]
+_LIB.plsm_lite3_stream_free.restype = None
+
+_LIB.plsm_buf_free.argtypes = [POINTER(plsm_buf_t)]
+_LIB.plsm_buf_free.restype = None
+
+_LIB.plsm_lite3_frame_free.argtypes = [POINTER(plsm_lite3_frame_t)]
+_LIB.plsm_lite3_frame_free.restype = None
+
+_LIB.plsm_error_free.argtypes = [POINTER(plsm_error_t)]
+_LIB.plsm_error_free.restype = None
+
+_LIB.plsm_udp_client_new.argtypes = [
+    c_char_p,
+    POINTER(POINTER(plsm_udp_client_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_client_new.restype = c_int
+_LIB.plsm_udp_client_free.argtypes = [POINTER(plsm_udp_client_t)]
+_LIB.plsm_udp_client_free.restype = None
+_LIB.plsm_udp_client_open_pool.argtypes = [
+    POINTER(plsm_udp_client_t),
+    c_char_p,
+    POINTER(POINTER(plsm_udp_pool_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_client_open_pool.restype = c_int
+_LIB.plsm_udp_pool_free.argtypes = [POINTER(plsm_udp_pool_t)]
+_LIB.plsm_udp_pool_free.restype = None
+_LIB.plsm_udp_pool_send_json.argtypes = [
+    POINTER(plsm_udp_pool_t),
+    POINTER(c_uint8),
+    c_size_t,
+    POINTER(c_char_p),
+    c_size_t,
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_pool_send_json.restype = c_int
+_LIB.plsm_udp_pool_send_lite3.argtypes = [
+    POINTER(plsm_udp_pool_t),
+    POINTER(c_uint8),
+    c_size_t,
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_pool_send_lite3.restype = c_int
+_LIB.plsm_udp_pool_follow.argtypes = [
+    POINTER(plsm_udp_pool_t),
+    c_uint32,
+    c_uint64,
+    c_uint32,
+    POINTER(POINTER(plsm_udp_follow_t)),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_pool_follow.restype = c_int
+_LIB.plsm_udp_follow_next.argtypes = [
+    POINTER(plsm_udp_follow_t),
+    c_uint64,
+    POINTER(plsm_udp_event_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_follow_next.restype = c_int
+_LIB.plsm_udp_follow_cancel.argtypes = [POINTER(plsm_udp_follow_t)]
+_LIB.plsm_udp_follow_cancel.restype = None
+_LIB.plsm_udp_follow_close.argtypes = [POINTER(plsm_udp_follow_t)]
+_LIB.plsm_udp_follow_close.restype = None
+_LIB.plsm_udp_event_free.argtypes = [POINTER(plsm_udp_event_t)]
+_LIB.plsm_udp_event_free.restype = None
+_LIB.plsm_udp_event_message.argtypes = [
+    POINTER(plsm_udp_event_t),
+    POINTER(plsm_buf_t),
+    POINTER(POINTER(plsm_error_t)),
+]
+_LIB.plsm_udp_event_message.restype = c_int
+
+_ERROR_KIND_TO_CLASS: dict[ErrorKind, type[PlasmiteError]] = {
+    ErrorKind.INTERNAL: InternalError,
+    ErrorKind.USAGE: UsageError,
+    ErrorKind.NOT_FOUND: NotFoundError,
+    ErrorKind.ALREADY_EXISTS: AlreadyExistsError,
+    ErrorKind.BUSY: BusyError,
+    ErrorKind.PERMISSION: PermissionDeniedError,
+    ErrorKind.CORRUPT: CorruptError,
+    ErrorKind.IO: IoError,
+    ErrorKind.RETENTION_GAP: RetentionGapError,
+}
+
+
+def _take_error(err_ptr: POINTER(plsm_error_t) | None) -> PlasmiteError:
+    if not err_ptr:
+        return PlasmiteError(ErrorKind.INTERNAL, "plasmite: unknown error")
+    err = err_ptr.contents
+    raw_kind = int(err.kind)
+    message = err.message.decode("utf-8") if err.message else ""
+    path = err.path.decode("utf-8") if err.path else None
+    seq = int(err.seq) if err.has_seq else None
+    offset = int(err.offset) if err.has_offset else None
+    _LIB.plsm_error_free(err_ptr)
+    try:
+        kind = ErrorKind(raw_kind)
+    except ValueError:
+        kind = ErrorKind.INTERNAL
+    if not message:
+        message = _default_error_message(kind)
+    error_cls = _ERROR_KIND_TO_CLASS.get(kind, PlasmiteError)
+    return error_cls(kind, message, path, seq, offset)
+
+
+def _default_error_message(kind: ErrorKind) -> str:
+    mapping = {
+        ErrorKind.INTERNAL: "internal error",
+        ErrorKind.USAGE: "usage error",
+        ErrorKind.NOT_FOUND: "not found",
+        ErrorKind.ALREADY_EXISTS: "already exists",
+        ErrorKind.BUSY: "busy",
+        ErrorKind.PERMISSION: "permission denied",
+        ErrorKind.CORRUPT: "corrupt",
+        ErrorKind.IO: "io error",
+        ErrorKind.RETENTION_GAP: "retention gap",
+    }
+    return mapping.get(kind, "error")
+
+
+def _buf_to_bytes(buf: plsm_buf_t) -> bytes:
+    if not buf.data or buf.len == 0:
+        _LIB.plsm_buf_free(byref(buf))
+        return b""
+    data = (c_uint8 * buf.len).from_address(buf.data)
+    out = bytes(data)
+    _LIB.plsm_buf_free(byref(buf))
+    return out
+
+
+def _frame_to_py(frame: plsm_lite3_frame_t) -> Lite3Frame:
+    seq = int(frame.seq)
+    timestamp_ns = int(frame.timestamp_ns)
+    flags = int(frame.flags)
+    payload = b""
+    if frame.payload.data and frame.payload.len:
+        data = (c_uint8 * frame.payload.len).from_address(frame.payload.data)
+        payload = bytes(data)
+    _LIB.plsm_lite3_frame_free(byref(frame))
+    return Lite3Frame(seq=seq, timestamp_ns=timestamp_ns, flags=flags, payload=payload)
+
+
+def _tag_array(values: Iterable[str]) -> tuple[POINTER(c_char_p), list[bytes]]:
+    encoded = [value.encode("utf-8") for value in values]
+    if not encoded:
+        return POINTER(c_char_p)(), encoded
+    arr = (c_char_p * len(encoded))()
+    for idx, val in enumerate(encoded):
+        arr[idx] = val
+    return arr, encoded
+
+
+def _closed_error(target: str) -> PlasmiteError:
+    return PlasmiteError(ErrorKind.USAGE, f"plasmite: {target} is closed")
+
+
+def _require_open(ptr: object, target: str) -> None:
+    if not ptr:
+        raise _closed_error(target)
+
+
+def _serialized_handle(method):
+    """Keep handle checks, native calls, and owned-result cleanup together."""
+    @wraps(method)
+    def locked(self, *args, **kwargs):
+        with self._lock:
+            return method(self, *args, **kwargs)
+
+    return locked
+
+
+def _ensure_bytes(payload: bytes | bytearray | memoryview, name: str) -> bytes:
+    if isinstance(payload, bytes):
+        return payload
+    if isinstance(payload, (bytearray, memoryview)):
+        return bytes(payload)
+    raise TypeError(f"{name} must be bytes-like")
+
+
+def _ensure_non_negative_int(value: int, name: str) -> int:
+    if not isinstance(value, int):
+        raise TypeError(f"{name} must be an int")
+    if value < 0:
+        raise ValueError(f"{name} must be >= 0")
+    if value > _UINT64_MAX:
+        raise ValueError(f"{name} must fit an unsigned 64-bit integer")
+    return value
+
+
+def _optional_non_negative_int(value: Optional[int], name: str) -> Optional[int]:
+    if value is None:
+        return None
+    return _ensure_non_negative_int(value, name)
+
+
+def _stream_options(
+    since_seq: Optional[int],
+    max_messages: Optional[int],
+    timeout_ms: Optional[int],
+    error_on_gap: bool,
+) -> plsm_stream_options_t:
+    options = plsm_stream_options_t()
+    options.struct_size = sizeof(plsm_stream_options_t)
+    options.gap_policy = 1 if error_on_gap else 0
+    options.since_seq = since_seq or 0
+    options.max_messages = max_messages or 0
+    options.timeout_ms = timeout_ms or 0
+    options.has_since = 1 if since_seq is not None else 0
+    options.has_max = 1 if max_messages is not None else 0
+    options.has_timeout = 1 if timeout_ms is not None else 0
+    return options
+
+
+class Client:
+    def __init__(self, pool_dir: str | None = None) -> None:
+        self._lock = RLock()
+        self._ptr = None
+        if pool_dir is None:
+            pool_dir = default_pool_dir()
+        if not pool_dir:
+            raise ValueError("pool_dir is required")
+        out_client = POINTER(plsm_client_t)()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_client_new(pool_dir.encode("utf-8"), byref(out_client), byref(out_err))
+        if rc != 0:
+            raise _take_error(out_err)
+        self._ptr = out_client
+
+    @_serialized_handle
+    def create_pool(
+        self,
+        pool_ref: str,
+        size_bytes: int = DEFAULT_POOL_SIZE_BYTES,
+    ) -> Pool:
+        _require_open(self._ptr, "client")
+        if not pool_ref:
+            raise ValueError("pool_ref is required")
+        size_bytes = _ensure_non_negative_int(size_bytes, "size_bytes")
+        out_pool = POINTER(plsm_pool_t)()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_pool_create(
+            self._ptr,
+            pool_ref.encode("utf-8"),
+            c_uint64(size_bytes),
+            byref(out_pool),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+        return Pool(out_pool)
+
+    @_serialized_handle
+    def open_pool(self, pool_ref: str) -> Pool:
+        _require_open(self._ptr, "client")
+        if not pool_ref:
+            raise ValueError("pool_ref is required")
+        out_pool = POINTER(plsm_pool_t)()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_pool_open(
+            self._ptr,
+            pool_ref.encode("utf-8"),
+            byref(out_pool),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+        return Pool(out_pool)
+
+    def pool(
+        self,
+        pool_ref: str,
+        size_bytes: int = DEFAULT_POOL_SIZE_BYTES,
+    ) -> Pool:
+        try:
+            return self.open_pool(pool_ref)
+        except NotFoundError:
+            return self.create_pool(pool_ref, size_bytes)
+
+    @_serialized_handle
+    def close(self) -> None:
+        if getattr(self, "_ptr", None):
+            _LIB.plsm_client_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> Client:
+        with self._lock:
+            _require_open(self._ptr, "client")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+@dataclass(frozen=True)
+class Lite3Frame:
+    seq: int
+    timestamp_ns: int
+    flags: int
+    payload: bytes
+
+    @property
+    def time(self) -> datetime:
+        seconds, nanoseconds = divmod(self.timestamp_ns, 1_000_000_000)
+        return datetime.fromtimestamp(seconds, tz=timezone.utc).replace(
+            microsecond=nanoseconds // 1_000
+        )
+
+
+class Pool:
+    def __init__(self, ptr: POINTER(plsm_pool_t)) -> None:
+        self._lock = RLock()
+        self._ptr = ptr
+
+    @_serialized_handle
+    def append_json(self, payload: bytes, tags: Iterable[str], durability: Durability) -> bytes:
+        _require_open(self._ptr, "pool")
+        payload = _ensure_bytes(payload, "payload")
+        if not payload:
+            raise ValueError("payload is required")
+        buf = plsm_buf_t()
+        out_err = POINTER(plsm_error_t)()
+        arr, _keep = _tag_array(tags)
+        payload_buf = (c_uint8 * len(payload)).from_buffer_copy(payload)
+        rc = _LIB.plsm_pool_append_json(
+            self._ptr,
+            payload_buf,
+            c_size_t(len(payload)),
+            arr,
+            c_size_t(len(_keep)),
+            c_uint32(int(durability)),
+            byref(buf),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+        return _buf_to_bytes(buf)
+
+    def append(
+        self,
+        value,
+        tags: Optional[Iterable[str]] = None,
+        durability: Durability = Durability.FAST,
+    ) -> Message:
+        payload = self.append_json(
+            json.dumps(value).encode("utf-8"),
+            [] if tags is None else tags,
+            durability,
+        )
+        return parse_message(payload)
+
+    @_serialized_handle
+    def append_lite3(self, payload: bytes, durability: Durability) -> int:
+        _require_open(self._ptr, "pool")
+        payload = _ensure_bytes(payload, "payload")
+        if not payload:
+            raise ValueError("payload is required")
+        out_seq = c_uint64()
+        out_err = POINTER(plsm_error_t)()
+        payload_buf = (c_uint8 * len(payload)).from_buffer_copy(payload)
+        rc = _LIB.plsm_pool_append_lite3(
+            self._ptr,
+            payload_buf,
+            c_size_t(len(payload)),
+            c_uint32(int(durability)),
+            byref(out_seq),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+        return int(out_seq.value)
+
+    @_serialized_handle
+    def get_json(self, seq: int) -> bytes:
+        _require_open(self._ptr, "pool")
+        seq = _ensure_non_negative_int(seq, "seq")
+        buf = plsm_buf_t()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_pool_get_json(self._ptr, c_uint64(seq), byref(buf), byref(out_err))
+        if rc != 0:
+            raise _take_error(out_err)
+        return _buf_to_bytes(buf)
+
+    def get(self, seq: int) -> Message:
+        return parse_message(self.get_json(seq))
+
+    @_serialized_handle
+    def get_lite3(self, seq: int) -> Lite3Frame:
+        _require_open(self._ptr, "pool")
+        seq = _ensure_non_negative_int(seq, "seq")
+        frame = plsm_lite3_frame_t()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_pool_get_lite3(self._ptr, c_uint64(seq), byref(frame), byref(out_err))
+        if rc != 0:
+            raise _take_error(out_err)
+        return _frame_to_py(frame)
+
+    @_serialized_handle
+    def open_stream(
+        self,
+        since_seq: Optional[int] = None,
+        max_messages: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+        error_on_gap: bool = False,
+    ) -> Stream:
+        _require_open(self._ptr, "pool")
+        since_seq = _optional_non_negative_int(since_seq, "since_seq")
+        max_messages = _optional_non_negative_int(max_messages, "max_messages")
+        timeout_ms = _optional_non_negative_int(timeout_ms, "timeout_ms")
+        out_stream = POINTER(plsm_stream_t)()
+        out_err = POINTER(plsm_error_t)()
+        if error_on_gap:
+            options = _stream_options(since_seq, max_messages, timeout_ms, True)
+            rc = _LIB.plsm_stream_open_ex(
+                self._ptr,
+                byref(options),
+                byref(out_stream),
+                byref(out_err),
+            )
+        else:
+            rc = _LIB.plsm_stream_open(
+                self._ptr,
+                c_uint64(since_seq or 0),
+                c_uint32(1 if since_seq is not None else 0),
+                c_uint64(max_messages or 0),
+                c_uint32(1 if max_messages is not None else 0),
+                c_uint64(timeout_ms or 0),
+                c_uint32(1 if timeout_ms is not None else 0),
+                byref(out_stream),
+                byref(out_err),
+            )
+        if rc != 0:
+            raise _take_error(out_err)
+        return Stream(out_stream)
+
+    @_serialized_handle
+    def open_lite3_stream(
+        self,
+        since_seq: Optional[int] = None,
+        max_messages: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+        error_on_gap: bool = False,
+    ) -> Lite3Stream:
+        _require_open(self._ptr, "pool")
+        since_seq = _optional_non_negative_int(since_seq, "since_seq")
+        max_messages = _optional_non_negative_int(max_messages, "max_messages")
+        timeout_ms = _optional_non_negative_int(timeout_ms, "timeout_ms")
+        out_stream = POINTER(plsm_lite3_stream_t)()
+        out_err = POINTER(plsm_error_t)()
+        if error_on_gap:
+            options = _stream_options(since_seq, max_messages, timeout_ms, True)
+            rc = _LIB.plsm_lite3_stream_open_ex(
+                self._ptr,
+                byref(options),
+                byref(out_stream),
+                byref(out_err),
+            )
+        else:
+            rc = _LIB.plsm_lite3_stream_open(
+                self._ptr,
+                c_uint64(since_seq or 0),
+                c_uint32(1 if since_seq is not None else 0),
+                c_uint64(max_messages or 0),
+                c_uint32(1 if max_messages is not None else 0),
+                c_uint64(timeout_ms or 0),
+                c_uint32(1 if timeout_ms is not None else 0),
+                byref(out_stream),
+                byref(out_err),
+            )
+        if rc != 0:
+            raise _take_error(out_err)
+        return Lite3Stream(out_stream)
+
+    def replay(
+        self,
+        speed: float = 1.0,
+        since_seq: Optional[int] = None,
+        max_messages: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+        tags: Optional[Iterable[str]] = None,
+    ) -> Generator[Message, None, None]:
+        """Replay messages with original timing scaled by speed.
+
+        Yields Message objects with inter-message delays derived from
+        each message's ``time``. The first message is yielded
+        immediately; subsequent messages are delayed by
+        ``(current_time - prev_time) / speed``.
+        """
+        if speed <= 0:
+            raise ValueError("speed must be positive")
+
+        required_tags = list(tags or [])
+        stream_max_messages = (
+            None if (max_messages is not None and required_tags) else max_messages
+        )
+
+        stream = self.open_stream(
+            since_seq=since_seq,
+            max_messages=stream_max_messages,
+            timeout_ms=timeout_ms,
+        )
+        try:
+            prev_dt: Optional[datetime] = None
+            delivered = 0
+            filter_by_tags = bool(required_tags)
+            while True:
+                msg = stream.next_json()
+                if msg is None:
+                    break
+                message = parse_message(msg)
+                if filter_by_tags and not _message_has_tags(message, required_tags):
+                    continue
+                cur_dt = message.time
+                if prev_dt is not None and cur_dt is not None:
+                    delta = (cur_dt - prev_dt).total_seconds() / speed
+                    if delta > 0:
+                        _time.sleep(delta)
+                if cur_dt is not None:
+                    prev_dt = cur_dt
+                delivered += 1
+                yield message
+                if max_messages is not None and delivered >= max_messages:
+                    break
+        finally:
+            stream.close()
+
+    def tail(
+        self,
+        since_seq: Optional[int] = None,
+        max_messages: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+        tags: Optional[Iterable[str]] = None,
+        error_on_gap: bool = False,
+    ) -> Generator[Message, None, None]:
+        """Tail JSON messages and optionally filter by exact tags."""
+        required_tags = list(tags or [])
+        stream_max_messages = (
+            None if (max_messages is not None and required_tags) else max_messages
+        )
+        stream = self.open_stream(
+            since_seq=since_seq,
+            max_messages=stream_max_messages,
+            timeout_ms=timeout_ms,
+            error_on_gap=error_on_gap,
+        )
+        try:
+            delivered = 0
+            filter_by_tags = bool(required_tags)
+            while True:
+                msg = stream.next_json()
+                if msg is None:
+                    break
+                message = parse_message(msg)
+                if filter_by_tags:
+                    if not _message_has_tags(message, required_tags):
+                        continue
+                delivered += 1
+                yield message
+                if max_messages is not None and delivered >= max_messages:
+                    break
+        finally:
+            stream.close()
+
+    @_serialized_handle
+    def close(self) -> None:
+        if getattr(self, "_ptr", None):
+            _LIB.plsm_pool_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> Pool:
+        with self._lock:
+            _require_open(self._ptr, "pool")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+class Stream:
+    def __init__(self, ptr: POINTER(plsm_stream_t)) -> None:
+        self._lock = RLock()
+        self._ptr = ptr
+
+    @_serialized_handle
+    def next_json(self) -> Optional[bytes]:
+        _require_open(self._ptr, "stream")
+        buf = plsm_buf_t()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_stream_next(self._ptr, byref(buf), byref(out_err))
+        if rc == 1:
+            return _buf_to_bytes(buf)
+        if rc == 0:
+            return None
+        raise _take_error(out_err)
+
+    def __iter__(self) -> Stream:
+        return self
+
+    def __next__(self) -> bytes:
+        message = self.next_json()
+        if message is None:
+            raise StopIteration
+        return message
+
+    @_serialized_handle
+    def close(self) -> None:
+        if getattr(self, "_ptr", None):
+            _LIB.plsm_stream_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> Stream:
+        with self._lock:
+            _require_open(self._ptr, "stream")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+class Lite3Stream:
+    def __init__(self, ptr: POINTER(plsm_lite3_stream_t)) -> None:
+        self._lock = RLock()
+        self._ptr = ptr
+
+    @_serialized_handle
+    def next(self) -> Optional[Lite3Frame]:
+        _require_open(self._ptr, "stream")
+        frame = plsm_lite3_frame_t()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_lite3_stream_next(self._ptr, byref(frame), byref(out_err))
+        if rc == 1:
+            return _frame_to_py(frame)
+        if rc == 0:
+            return None
+        raise _take_error(out_err)
+
+    def __iter__(self) -> Lite3Stream:
+        return self
+
+    def __next__(self) -> Lite3Frame:
+        frame = self.next()
+        if frame is None:
+            raise StopIteration
+        return frame
+
+    @_serialized_handle
+    def close(self) -> None:
+        if getattr(self, "_ptr", None):
+            _LIB.plsm_lite3_stream_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> Lite3Stream:
+        with self._lock:
+            _require_open(self._ptr, "stream")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+@dataclass(frozen=True)
+class UdpStart:
+    """A UDP follow start position. Use the named constructors."""
+
+    kind: int
+    value: int = 0
+
+    @classmethod
+    def new(cls) -> UdpStart:
+        return cls(0)
+
+    @classmethod
+    def last(cls, count: int) -> UdpStart:
+        return cls(1, _ensure_non_negative_int(count, "count"))
+
+    @classmethod
+    def since_ns(cls, timestamp_ns: int) -> UdpStart:
+        return cls(2, _ensure_non_negative_int(timestamp_ns, "timestamp_ns"))
+
+    @classmethod
+    def sequence(cls, seq: int) -> UdpStart:
+        return cls(3, _ensure_non_negative_int(seq, "seq"))
+
+
+@dataclass(frozen=True)
+class UdpFollowOptions:
+    start: UdpStart = UdpStart(0)
+    live: bool = True
+
+
+@dataclass(frozen=True)
+class UdpFrame:
+    seq: int
+    timestamp_ns: int
+    payload: bytes
+
+    @property
+    def time(self) -> datetime:
+        seconds, nanoseconds = divmod(self.timestamp_ns, 1_000_000_000)
+        return datetime.fromtimestamp(seconds, tz=timezone.utc).replace(
+            microsecond=nanoseconds // 1_000
+        )
+
+    def message(self) -> Message:
+        payload_buf = (c_uint8 * len(self.payload)).from_buffer_copy(self.payload)
+        event = plsm_udp_event_t()
+        event.kind = 1
+        event.seq = self.seq
+        event.timestamp_ns = self.timestamp_ns
+        event.payload.data = cast(payload_buf, c_void_p) if self.payload else None
+        event.payload.len = len(self.payload)
+        out_message = plsm_buf_t()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_udp_event_message(byref(event), byref(out_message), byref(out_err))
+        if rc != 0:
+            raise _take_error(out_err)
+        return parse_message(_buf_to_bytes(out_message))
+
+
+@dataclass(frozen=True)
+class UdpGap:
+    first: int
+    last: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class UdpProgress:
+    start_seq: int
+    next_seq: int
+    end_seq: int | None
+    terminal: bool
+    retention_gap: bool
+
+
+UdpEvent = UdpFrame | UdpGap | UdpProgress
+
+
+class UdpClient:
+    """Client for one explicit UDP endpoint."""
+
+    def __init__(self, endpoint: str) -> None:
+        self._lock = RLock()
+        self._ptr = None
+        if not endpoint:
+            raise ValueError("endpoint is required")
+        out_client = POINTER(plsm_udp_client_t)()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_udp_client_new(endpoint.encode("utf-8"), byref(out_client), byref(out_err))
+        if rc != 0:
+            raise _take_error(out_err)
+        self._ptr = out_client
+
+    @_serialized_handle
+    def open_pool(self, pool_name: str) -> UdpPool:
+        _require_open(self._ptr, "UDP client")
+        if not pool_name:
+            raise ValueError("pool_name is required")
+        out_pool = POINTER(plsm_udp_pool_t)()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_udp_client_open_pool(
+            self._ptr,
+            pool_name.encode("utf-8"),
+            byref(out_pool),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+        return UdpPool(out_pool)
+
+    @_serialized_handle
+    def close(self) -> None:
+        if self._ptr:
+            _LIB.plsm_udp_client_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> UdpClient:
+        with self._lock:
+            _require_open(self._ptr, "UDP client")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+class UdpPool:
+    """A named pool on one UDP endpoint."""
+
+    def __init__(self, ptr: POINTER(plsm_udp_pool_t)) -> None:
+        self._lock = RLock()
+        self._ptr = ptr
+
+    @_serialized_handle
+    def send_json(self, value: Any, tags: Iterable[str] = ()) -> None:
+        _require_open(self._ptr, "UDP pool")
+        payload = json.dumps(value, separators=(",", ":")).encode("utf-8")
+        payload_buf = (c_uint8 * len(payload)).from_buffer_copy(payload)
+        tag_arr, keepalive = _tag_array(tags)
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_udp_pool_send_json(
+            self._ptr,
+            payload_buf,
+            c_size_t(len(payload)),
+            tag_arr,
+            c_size_t(len(keepalive)),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+
+    @_serialized_handle
+    def send_lite3(self, payload: bytes | bytearray | memoryview) -> None:
+        _require_open(self._ptr, "UDP pool")
+        payload = _ensure_bytes(payload, "payload")
+        if not payload:
+            raise ValueError("payload is required")
+        payload_buf = (c_uint8 * len(payload)).from_buffer_copy(payload)
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_udp_pool_send_lite3(
+            self._ptr,
+            payload_buf,
+            c_size_t(len(payload)),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+
+    @_serialized_handle
+    def follow(self, options: UdpFollowOptions | None = None) -> UdpFollow:
+        _require_open(self._ptr, "UDP pool")
+        options = options or UdpFollowOptions()
+        if not isinstance(options, UdpFollowOptions):
+            raise TypeError("options must be UdpFollowOptions")
+        start = options.start
+        if not isinstance(start, UdpStart) or start.kind not in (0, 1, 2, 3):
+            raise ValueError("invalid UDP follow start")
+        start_value = _ensure_non_negative_int(start.value, "start.value")
+        out_follow = POINTER(plsm_udp_follow_t)()
+        out_err = POINTER(plsm_error_t)()
+        rc = _LIB.plsm_udp_pool_follow(
+            self._ptr,
+            c_uint32(start.kind),
+            c_uint64(start_value),
+            c_uint32(1 if options.live else 0),
+            byref(out_follow),
+            byref(out_err),
+        )
+        if rc != 0:
+            raise _take_error(out_err)
+        return UdpFollow(out_follow)
+
+    @_serialized_handle
+    def close(self) -> None:
+        if self._ptr:
+            _LIB.plsm_udp_pool_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> UdpPool:
+        with self._lock:
+            _require_open(self._ptr, "UDP pool")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+class UdpFollow:
+    """Best-effort UDP event stream. Close cancels a blocked wait."""
+
+    def __init__(self, ptr: POINTER(plsm_udp_follow_t)) -> None:
+        self._state_lock = RLock()
+        self._read_lock = Lock()
+        self._ptr = ptr
+        self._closing = False
+        self._cancelled = False
+
+    def next_event(self, timeout_ms: int | None = None) -> UdpEvent | None:
+        timeout_ms = _optional_non_negative_int(timeout_ms, "timeout_ms")
+        with self._read_lock:
+            with self._state_lock:
+                _require_open(self._ptr, "UDP follow")
+                if self._closing or self._cancelled:
+                    return None
+                ptr = self._ptr
+            remaining = timeout_ms
+            while True:
+                event = plsm_udp_event_t()
+                out_err = POINTER(plsm_error_t)()
+                wait_ms = 1000 if remaining is None else remaining
+                rc = _LIB.plsm_udp_follow_next(
+                    ptr,
+                    c_uint64(wait_ms),
+                    byref(event),
+                    byref(out_err),
+                )
+                if rc == 1:
+                    return _udp_event_to_python(event)
+                if rc == 2 or rc == 3:
+                    with self._state_lock:
+                        self._cancelled = rc == 3
+                    return None
+                if rc < 0:
+                    raise _take_error(out_err)
+                if remaining is not None:
+                    if remaining == 0:
+                        return None
+                    remaining -= wait_ms
+                    if remaining <= 0:
+                        return None
+
+    def events(self) -> Generator[UdpEvent, None, None]:
+        while True:
+            event = self.next_event()
+            if event is None:
+                return
+            yield event
+
+    def __iter__(self) -> UdpFollow:
+        return self
+
+    def __next__(self) -> UdpEvent:
+        event = self.next_event()
+        if event is None:
+            raise StopIteration
+        return event
+
+    def cancel(self) -> None:
+        with self._state_lock:
+            if self._ptr and not self._cancelled:
+                _LIB.plsm_udp_follow_cancel(self._ptr)
+                self._cancelled = True
+
+    def close(self) -> None:
+        with self._state_lock:
+            ptr = self._ptr
+            if not ptr:
+                return
+            self._closing = True
+            _LIB.plsm_udp_follow_cancel(ptr)
+        with self._read_lock:
+            with self._state_lock:
+                if self._ptr:
+                    _LIB.plsm_udp_follow_close(self._ptr)
+                    self._ptr = None
+                    self._cancelled = True
+
+    def __enter__(self) -> UdpFollow:
+        with self._state_lock:
+            _require_open(self._ptr, "UDP follow")
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+def _udp_event_to_python(event: plsm_udp_event_t) -> UdpEvent:
+    try:
+        if event.kind == 1:
+            payload = b""
+            if event.payload.data and event.payload.len:
+                payload = bytes((c_uint8 * event.payload.len).from_address(event.payload.data))
+            return UdpFrame(int(event.seq), int(event.timestamp_ns), payload)
+        if event.kind == 2:
+            reasons = {0: "unknown", 1: "oversized", 2: "retention", 3: "pressure"}
+            return UdpGap(int(event.first), int(event.last), reasons.get(int(event.reason), "unknown"))
+        if event.kind == 3:
+            return UdpProgress(
+                int(event.start_seq),
+                int(event.next_seq),
+                int(event.end_seq) if event.has_end else None,
+                bool(event.terminal),
+                bool(event.retention_gap),
+            )
+        raise PlasmiteError(ErrorKind.INTERNAL, f"plasmite: unknown UDP event kind {event.kind}")
+    finally:
+        _LIB.plsm_udp_event_free(byref(event))
+
+
+def _parse_rfc3339_utc(raw_time: str) -> datetime:
+    # Python 3.10 accepts only 3 or 6 fractional digits. datetime keeps
+    # microseconds; the original nanosecond timestamp remains in Message.raw.
+    raw_time = re.sub(r"\.(\d+)", lambda match: "." + match[1][:6].ljust(6, "0"), raw_time)
+    parsed = datetime.fromisoformat(raw_time.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        raise ValueError("message time must include timezone")
+    return parsed.astimezone(timezone.utc)
+
+
+def parse_message(payload: bytes) -> Message:
+    raw = _ensure_bytes(payload, "payload")
+    parsed = json.loads(raw.decode("utf-8"))
+    if not isinstance(parsed, dict):
+        raise ValueError("message payload must decode to an object")
+    raw_time = parsed.get("time")
+    if not isinstance(raw_time, str):
+        raise ValueError("message time must be an RFC3339 string")
+    meta = parsed.get("meta", {})
+    tags = meta.get("tags") if isinstance(meta, dict) else None
+    if not isinstance(tags, list):
+        tags = []
+    tag_list = [str(tag) for tag in tags]
+    seq = parsed.get("seq")
+    if not isinstance(seq, int):
+        raise ValueError("message seq must be an int")
+    return Message(
+        seq=seq,
+        time=_parse_rfc3339_utc(raw_time),
+        time_rfc3339=raw_time,
+        data=parsed.get("data"),
+        meta=MessageMeta(tags=tag_list),
+        raw=raw,
+    )
+
+
+def _message_has_tags(message: Message, required_tags: list[str]) -> bool:
+    if not required_tags:
+        return True
+    return all(tag in message.tags for tag in required_tags)
+
+
+__all__ = [
+    "Client",
+    "Pool",
+    "Message",
+    "MessageMeta",
+    "Stream",
+    "Lite3Frame",
+    "Lite3Stream",
+    "UdpClient",
+    "UdpPool",
+    "UdpFollow",
+    "UdpStart",
+    "UdpFollowOptions",
+    "UdpFrame",
+    "UdpGap",
+    "UdpProgress",
+    "Durability",
+    "ErrorKind",
+    "PlasmiteError",
+    "NotFoundError",
+    "AlreadyExistsError",
+    "BusyError",
+    "PermissionDeniedError",
+    "CorruptError",
+    "IoError",
+    "UsageError",
+    "InternalError",
+    "RetentionGapError",
+    "DEFAULT_POOL_DIR",
+    "DEFAULT_POOL_SIZE",
+    "DEFAULT_POOL_SIZE_BYTES",
+    "default_pool_dir",
+    "parse_message",
+]