dqlite-wire 0.1.0__py3-none-any.whl

dqlite_wire-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: dqlite-wire
+Version: 0.1.0
+Summary: Pure Python wire protocol implementation for dqlite
+Project-URL: Homepage, https://github.com/letsdiscodev/python-dqlite-wire
+Project-URL: Repository, https://github.com/letsdiscodev/python-dqlite-wire
+Project-URL: Issues, https://github.com/letsdiscodev/python-dqlite-wire/issues
+Author-email: Antoine Leclair <antoineleclair@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: database,distributed,dqlite,sqlite,wire-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dqlite-wire
+
+Pure Python wire protocol implementation for [dqlite](https://dqlite.io/), Canonical's distributed SQLite.
+
+## Installation
+
+```bash
+pip install dqlite-wire
+```
+
+## Usage
+
+```python
+from dqlitewire import MessageEncoder, MessageDecoder
+from dqlitewire.messages import LeaderRequest, ClientRequest
+
+# Encode a message
+encoder = MessageEncoder()
+data = encoder.encode(LeaderRequest())
+
+# Decode a message
+decoder = MessageDecoder()
+decoder.feed(data)
+message = decoder.decode()
+```
+
+## Protocol Reference
+
+Based on the [dqlite wire protocol specification](https://canonical.com/dqlite/docs/reference/wire-protocol).
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

dqlite_wire-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+dqlitewire/__init__.py,sha256=Nw4v-fI4v_ZlOKb5CkJtP7ceWGxt0U-qYAygzEswPUY,615
+dqlitewire/buffer.py,sha256=SlDlwEj8YqO265bjCD3d2JJXNkMCyTWQJmmjxPDV2rE,3537
+dqlitewire/codec.py,sha256=hIQIgqVPxLYmwsc3-eXOTNh_7cUPooDi-C7JOfCkhQY,5106
+dqlitewire/constants.py,sha256=_3Nb4WUGIGb8QQ3CBCV_iNWc_sl_zHV1KD8MFX0Hv5A,1359
+dqlitewire/exceptions.py,sha256=7tQFsoWklMDa3D-cu20RPTD-xbK-eTOzGuICOsDgMsA,307
+dqlitewire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dqlitewire/tuples.py,sha256=qDDZw0GP-5a2nycyW8bmT8tRW5Oe58J0ZvX1j6zKoeQ,5058
+dqlitewire/types.py,sha256=bYxsT3rWHH3NOHTitn2706B4nG017jxiRDfJ9cIYvww,6218
+dqlitewire/messages/__init__.py,sha256=WqKHX47CL8yOwYCEAWH65lyHMEBK_w_OTaugUfNoyNY,1597
+dqlitewire/messages/base.py,sha256=02aFW78sL7_Co2BI37DAZe_OqSDsK-NyiOEz3wJqbTE,2118
+dqlitewire/messages/requests.py,sha256=6e73eFMn7OiKG0yWwLkEuBxO_-BB-09Qs0KDAoxjUq8,11719
+dqlitewire/messages/responses.py,sha256=XrxiKFMzUT5GC8wpOoe-KjHXQ3F4cBZP7uDw7KYvADI,9847
+dqlite_wire-0.1.0.dist-info/METADATA,sha256=ik1rWoFJ7EEBjmjiDV4EHK6lNfHPOjTL60iBSen0ynM,1907
+dqlite_wire-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dqlite_wire-0.1.0.dist-info/licenses/LICENSE.md,sha256=25ur0qy0m17OgHzc1Ve3NeLumyjGGgVBrN-JL3znfDg,1090
+dqlite_wire-0.1.0.dist-info/RECORD,,

dqlite_wire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dqlite_wire-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Leclair and Greg Sadetsky
+
+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.

dqlitewire/__init__.py

@@ -0,0 +1,27 @@
+"""Pure Python wire protocol implementation for dqlite."""
+
+from dqlitewire.buffer import ReadBuffer, WriteBuffer
+from dqlitewire.codec import MessageDecoder, MessageEncoder
+from dqlitewire.constants import (
+    PROTOCOL_VERSION,
+    RequestType,
+    ResponseType,
+    ValueType,
+)
+from dqlitewire.exceptions import DecodeError, EncodeError, ProtocolError
+
+__all__ = [
+    "MessageDecoder",
+    "MessageEncoder",
+    "PROTOCOL_VERSION",
+    "ProtocolError",
+    "DecodeError",
+    "EncodeError",
+    "ReadBuffer",
+    "WriteBuffer",
+    "RequestType",
+    "ResponseType",
+    "ValueType",
+]
+
+__version__ = "0.1.0"

dqlitewire/buffer.py

@@ -0,0 +1,119 @@
+"""Buffer utilities for streaming protocol data."""
+
+from dqlitewire.constants import HEADER_SIZE, WORD_SIZE
+
+
+class WriteBuffer:
+    """Buffer for building wire protocol messages."""
+
+    def __init__(self) -> None:
+        self._data = bytearray()
+
+    def write(self, data: bytes) -> None:
+        """Append data to buffer."""
+        self._data.extend(data)
+
+    def write_padded(self, data: bytes) -> None:
+        """Append data with padding to word boundary."""
+        self._data.extend(data)
+        remainder = len(data) % WORD_SIZE
+        if remainder:
+            self._data.extend(b"\x00" * (WORD_SIZE - remainder))
+
+    def getvalue(self) -> bytes:
+        """Get buffer contents."""
+        return bytes(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def clear(self) -> None:
+        """Clear the buffer."""
+        self._data.clear()
+
+
+class ReadBuffer:
+    """Buffer for reading wire protocol messages from a stream.
+
+    Handles partial reads and message framing.
+    """
+
+    def __init__(self) -> None:
+        self._data = bytearray()
+        self._pos = 0
+
+    def feed(self, data: bytes) -> None:
+        """Add received data to the buffer."""
+        self._data.extend(data)
+
+    def has_message(self) -> bool:
+        """Check if a complete message is available."""
+        available = len(self._data) - self._pos
+
+        if available < HEADER_SIZE:
+            return False
+
+        # Read size from header (first 4 bytes = size in words)
+        size_words = int.from_bytes(self._data[self._pos : self._pos + 4], "little")
+        total_size = HEADER_SIZE + (size_words * WORD_SIZE)
+
+        return available >= total_size
+
+    def peek_header(self) -> tuple[int, int, int] | None:
+        """Peek at the message header without consuming it.
+
+        Returns (size_in_words, message_type, schema_version) or None if not enough data.
+        """
+        available = len(self._data) - self._pos
+
+        if available < HEADER_SIZE:
+            return None
+
+        size_words = int.from_bytes(self._data[self._pos : self._pos + 4], "little")
+        msg_type = self._data[self._pos + 4]
+        schema_version = self._data[self._pos + 5]
+
+        return size_words, msg_type, schema_version
+
+    def read_message(self) -> bytes | None:
+        """Read a complete message from the buffer.
+
+        Returns the message data (including header) or None if not enough data.
+        """
+        if not self.has_message():
+            return None
+
+        size_words = int.from_bytes(self._data[self._pos : self._pos + 4], "little")
+        total_size = HEADER_SIZE + (size_words * WORD_SIZE)
+
+        message = bytes(self._data[self._pos : self._pos + total_size])
+        self._pos += total_size
+
+        # Compact buffer if we've consumed a lot
+        if self._pos > 4096:
+            self._data = self._data[self._pos :]
+            self._pos = 0
+
+        return message
+
+    def read_bytes(self, n: int) -> bytes | None:
+        """Read exactly n bytes from the buffer.
+
+        Returns None if not enough data available.
+        """
+        available = len(self._data) - self._pos
+        if available < n:
+            return None
+
+        data = bytes(self._data[self._pos : self._pos + n])
+        self._pos += n
+        return data
+
+    def available(self) -> int:
+        """Return number of bytes available to read."""
+        return len(self._data) - self._pos
+
+    def clear(self) -> None:
+        """Clear the buffer."""
+        self._data.clear()
+        self._pos = 0

dqlitewire/codec.py

@@ -0,0 +1,168 @@
+"""Message encoder and decoder for dqlite wire protocol."""
+
+from dqlitewire.buffer import ReadBuffer, WriteBuffer
+from dqlitewire.constants import HEADER_SIZE, PROTOCOL_VERSION, RequestType, ResponseType
+from dqlitewire.exceptions import DecodeError
+from dqlitewire.messages.base import Header, Message
+from dqlitewire.messages.requests import (
+    AddRequest,
+    AssignRequest,
+    ClientRequest,
+    ClusterRequest,
+    ConnectRequest,
+    DescribeRequest,
+    DumpRequest,
+    ExecRequest,
+    ExecSqlRequest,
+    FinalizeRequest,
+    HeartbeatRequest,
+    InterruptRequest,
+    LeaderRequest,
+    OpenRequest,
+    PrepareRequest,
+    QueryRequest,
+    QuerySqlRequest,
+    RemoveRequest,
+    TransferRequest,
+    WeightRequest,
+)
+from dqlitewire.messages.responses import (
+    DbResponse,
+    DescriptionResponse,
+    EmptyResponse,
+    FailureResponse,
+    FilesResponse,
+    LeaderResponse,
+    MetadataResponse,
+    ResultResponse,
+    RowsResponse,
+    ServersResponse,
+    StmtResponse,
+    WelcomeResponse,
+)
+
+# Mapping from type codes to message classes
+REQUEST_TYPES: dict[int, type[Message]] = {
+    RequestType.LEADER: LeaderRequest,
+    RequestType.CLIENT: ClientRequest,
+    RequestType.HEARTBEAT: HeartbeatRequest,
+    RequestType.OPEN: OpenRequest,
+    RequestType.PREPARE: PrepareRequest,
+    RequestType.EXEC: ExecRequest,
+    RequestType.QUERY: QueryRequest,
+    RequestType.FINALIZE: FinalizeRequest,
+    RequestType.EXEC_SQL: ExecSqlRequest,
+    RequestType.QUERY_SQL: QuerySqlRequest,
+    RequestType.INTERRUPT: InterruptRequest,
+    RequestType.CONNECT: ConnectRequest,
+    RequestType.ADD: AddRequest,
+    RequestType.ASSIGN: AssignRequest,
+    RequestType.REMOVE: RemoveRequest,
+    RequestType.DUMP: DumpRequest,
+    RequestType.CLUSTER: ClusterRequest,
+    RequestType.TRANSFER: TransferRequest,
+    RequestType.DESCRIBE: DescribeRequest,
+    RequestType.WEIGHT: WeightRequest,
+}
+
+RESPONSE_TYPES: dict[int, type[Message]] = {
+    ResponseType.FAILURE: FailureResponse,
+    ResponseType.LEADER: LeaderResponse,
+    ResponseType.WELCOME: WelcomeResponse,
+    ResponseType.DB: DbResponse,
+    ResponseType.STMT: StmtResponse,
+    ResponseType.RESULT: ResultResponse,
+    ResponseType.ROWS: RowsResponse,
+    ResponseType.EMPTY: EmptyResponse,
+    ResponseType.FILES: FilesResponse,
+    ResponseType.SERVERS: ServersResponse,
+    ResponseType.METADATA: MetadataResponse,
+    ResponseType.DESCRIPTION: DescriptionResponse,
+}
+
+
+class MessageEncoder:
+    """Encodes messages to wire protocol format."""
+
+    def __init__(self) -> None:
+        self._buffer = WriteBuffer()
+
+    def encode(self, message: Message) -> bytes:
+        """Encode a message to bytes."""
+        return message.encode()
+
+    def encode_handshake(self) -> bytes:
+        """Encode the protocol version handshake.
+
+        Must be sent before any other message.
+        """
+        return PROTOCOL_VERSION.to_bytes(8, "little")
+
+
+class MessageDecoder:
+    """Decodes messages from wire protocol format."""
+
+    def __init__(self, is_request: bool = False) -> None:
+        """Initialize decoder.
+
+        Args:
+            is_request: If True, decode as request messages.
+                       If False (default), decode as response messages.
+        """
+        self._buffer = ReadBuffer()
+        self._is_request = is_request
+        self._type_map = REQUEST_TYPES if is_request else RESPONSE_TYPES
+
+    def feed(self, data: bytes) -> None:
+        """Feed data to the decoder."""
+        self._buffer.feed(data)
+
+    def has_message(self) -> bool:
+        """Check if a complete message is available."""
+        return self._buffer.has_message()
+
+    def decode(self) -> Message | None:
+        """Decode the next message from the buffer.
+
+        Returns None if no complete message is available.
+        """
+        data = self._buffer.read_message()
+        if data is None:
+            return None
+
+        return self.decode_bytes(data)
+
+    def decode_bytes(self, data: bytes) -> Message:
+        """Decode a message from bytes."""
+        if len(data) < HEADER_SIZE:
+            raise DecodeError(f"Message too short: {len(data)} bytes")
+
+        header = Header.decode(data[:HEADER_SIZE])
+        body = data[HEADER_SIZE:]
+
+        msg_class = self._type_map.get(header.msg_type)
+        if msg_class is None:
+            raise DecodeError(f"Unknown message type: {header.msg_type}")
+
+        return msg_class.decode_body(body)
+
+    def decode_handshake(self) -> int | None:
+        """Decode protocol version handshake.
+
+        Returns the protocol version or None if not enough data.
+        """
+        data = self._buffer.read_bytes(8)
+        if data is None:
+            return None
+        return int.from_bytes(data, "little")
+
+
+def decode_message(data: bytes, is_request: bool = False) -> Message:
+    """Convenience function to decode a single message."""
+    decoder = MessageDecoder(is_request=is_request)
+    return decoder.decode_bytes(data)
+
+
+def encode_message(message: Message) -> bytes:
+    """Convenience function to encode a single message."""
+    return message.encode()

dqlitewire/constants.py

@@ -0,0 +1,72 @@
+"""Protocol constants for dqlite wire protocol."""
+
+from enum import IntEnum
+
+# Protocol version
+PROTOCOL_VERSION = 1
+
+# Word size in bytes (all messages are padded to 8-byte boundaries)
+WORD_SIZE = 8
+
+# Header size in bytes
+HEADER_SIZE = 8
+
+# Row markers
+ROW_DONE_MARKER = 0xFFFFFFFFFFFFFFFF
+ROW_PART_MARKER = 0xEEEEEEEEEEEEEEEE
+
+
+class RequestType(IntEnum):
+    """Client to server message types."""
+
+    LEADER = 0
+    CLIENT = 1
+    HEARTBEAT = 2
+    OPEN = 3
+    PREPARE = 4
+    EXEC = 5
+    QUERY = 6
+    FINALIZE = 7
+    EXEC_SQL = 8
+    QUERY_SQL = 9
+    INTERRUPT = 10
+    CONNECT = 11
+    ADD = 12
+    ASSIGN = 13
+    REMOVE = 14
+    DUMP = 15
+    CLUSTER = 16
+    TRANSFER = 17
+    DESCRIBE = 18
+    WEIGHT = 19
+
+
+class ResponseType(IntEnum):
+    """Server to client message types."""
+
+    FAILURE = 0
+    LEADER = 1  # Also called NODE
+    WELCOME = 2
+    NODE_LEGACY = 3
+    DB = 4
+    STMT = 5
+    RESULT = 6
+    ROWS = 7
+    EMPTY = 8
+    FILES = 9
+    SERVERS = 10  # Also called CLUSTER or NODES
+    METADATA = 11
+    DESCRIPTION = 12
+
+
+class ValueType(IntEnum):
+    """Value types for parameters and row values."""
+
+    INTEGER = 1
+    FLOAT = 2
+    TEXT = 3
+    BLOB = 4
+    NULL = 5
+    UNIXTIME = 9  # Unix time (deprecated, maps to INTEGER)
+    ISO8601 = 10  # ISO8601 string (maps to TEXT)
+    BOOLEAN = 11  # Boolean (maps to INTEGER)

dqlitewire/exceptions.py

@@ -0,0 +1,19 @@
+"""Exceptions for dqlite wire protocol."""
+
+
+class ProtocolError(Exception):
+    """Base exception for protocol errors."""
+
+    pass
+
+
+class EncodeError(ProtocolError):
+    """Error during message encoding."""
+
+    pass
+
+
+class DecodeError(ProtocolError):
+    """Error during message decoding."""
+
+    pass

dqlitewire/messages/__init__.py

@@ -0,0 +1,79 @@
+"""Message types for dqlite wire protocol."""
+
+from dqlitewire.messages.base import Header, Message
+from dqlitewire.messages.requests import (
+    AddRequest,
+    AssignRequest,
+    ClientRequest,
+    ClusterRequest,
+    ConnectRequest,
+    DescribeRequest,
+    DumpRequest,
+    ExecRequest,
+    ExecSqlRequest,
+    FinalizeRequest,
+    HeartbeatRequest,
+    InterruptRequest,
+    LeaderRequest,
+    OpenRequest,
+    PrepareRequest,
+    QueryRequest,
+    QuerySqlRequest,
+    RemoveRequest,
+    TransferRequest,
+    WeightRequest,
+)
+from dqlitewire.messages.responses import (
+    DbResponse,
+    DescriptionResponse,
+    EmptyResponse,
+    FailureResponse,
+    FilesResponse,
+    LeaderResponse,
+    MetadataResponse,
+    ResultResponse,
+    RowsResponse,
+    ServersResponse,
+    StmtResponse,
+    WelcomeResponse,
+)
+
+__all__ = [
+    # Base
+    "Header",
+    "Message",
+    # Requests
+    "LeaderRequest",
+    "ClientRequest",
+    "HeartbeatRequest",
+    "OpenRequest",
+    "PrepareRequest",
+    "ExecRequest",
+    "QueryRequest",
+    "FinalizeRequest",
+    "ExecSqlRequest",
+    "QuerySqlRequest",
+    "InterruptRequest",
+    "ConnectRequest",
+    "AddRequest",
+    "AssignRequest",
+    "RemoveRequest",
+    "DumpRequest",
+    "ClusterRequest",
+    "TransferRequest",
+    "DescribeRequest",
+    "WeightRequest",
+    # Responses
+    "FailureResponse",
+    "LeaderResponse",
+    "WelcomeResponse",
+    "DbResponse",
+    "StmtResponse",
+    "ResultResponse",
+    "RowsResponse",
+    "EmptyResponse",
+    "FilesResponse",
+    "ServersResponse",
+    "MetadataResponse",
+    "DescriptionResponse",
+]

dqlitewire/messages/base.py

@@ -0,0 +1,75 @@
+"""Base message types for dqlite wire protocol."""
+
+import struct
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import ClassVar
+
+from dqlitewire.constants import HEADER_SIZE, WORD_SIZE
+
+
+@dataclass
+class Header:
+    """Message header.
+
+    Format (8 bytes):
+    - size: uint32 - Size of message body in words (8-byte units)
+    - type: uint8 - Message type code
+    - schema: uint8 - Schema version (currently always 0)
+    - reserved: uint16 - Reserved (always 0)
+    """
+
+    size_words: int
+    msg_type: int
+    schema: int = 0
+    reserved: int = 0
+
+    def encode(self) -> bytes:
+        """Encode header to bytes."""
+        return struct.pack(
+            "<IBBH",
+            self.size_words,
+            self.msg_type,
+            self.schema,
+            self.reserved,
+        )
+
+    @classmethod
+    def decode(cls, data: bytes) -> "Header":
+        """Decode header from bytes."""
+        if len(data) < HEADER_SIZE:
+            raise ValueError(f"Need {HEADER_SIZE} bytes for header, got {len(data)}")
+        size_words, msg_type, schema, reserved = struct.unpack("<IBBH", data[:HEADER_SIZE])
+        return cls(size_words, msg_type, schema, reserved)
+
+    @property
+    def body_size(self) -> int:
+        """Size of message body in bytes."""
+        return self.size_words * WORD_SIZE
+
+
+class Message(ABC):
+    """Base class for all protocol messages."""
+
+    MSG_TYPE: ClassVar[int]
+
+    @abstractmethod
+    def encode_body(self) -> bytes:
+        """Encode message body (without header)."""
+        ...
+
+    def encode(self) -> bytes:
+        """Encode complete message with header."""
+        body = self.encode_body()
+        # Ensure body is word-aligned
+        if len(body) % WORD_SIZE != 0:
+            body += b"\x00" * (WORD_SIZE - (len(body) % WORD_SIZE))
+        size_words = len(body) // WORD_SIZE
+        header = Header(size_words, self.MSG_TYPE)
+        return header.encode() + body
+
+    @classmethod
+    @abstractmethod
+    def decode_body(cls, data: bytes) -> "Message":
+        """Decode message from body data (without header)."""
+        ...