dqlite-wire 0.1.0__tar.gz

dqlite_wire-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dqlite-wire
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v6
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

dqlite_wire-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# Distribution
+dist/
+build/

dqlite_wire-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,79 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://github.com/astral-sh/uv)
+
+## Setup
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv --python 3.13
+uv pip install -e ".[dev]"
+```
+
+## Development Tools
+
+This project uses modern Python tooling:
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| **pytest** | Testing framework | `pytest` |
+| **ruff** | Linter (replaces flake8, isort, etc.) | `ruff check` |
+| **ruff format** | Code formatter (replaces black) | `ruff format` |
+| **mypy** | Static type checker | `mypy src` |
+
+## Running Tests
+
+```bash
+# Run all tests
+.venv/bin/pytest
+
+# Run with verbose output
+.venv/bin/pytest -v
+
+# Run with coverage
+.venv/bin/pytest --cov=dqlitewire
+```
+
+## Linting
+
+```bash
+# Check for issues
+.venv/bin/ruff check src tests
+
+# Auto-fix issues
+.venv/bin/ruff check --fix src tests
+```
+
+## Formatting
+
+```bash
+# Format all files
+.venv/bin/ruff format src tests
+
+# Check formatting without modifying
+.venv/bin/ruff format --check src tests
+```
+
+## Type Checking
+
+```bash
+# Run mypy with strict mode
+.venv/bin/mypy src
+```
+
+## Pre-commit Workflow
+
+Before committing, run all checks:
+
+```bash
+.venv/bin/ruff format src tests
+.venv/bin/ruff check --fix src tests
+.venv/bin/mypy src
+.venv/bin/pytest
+```

dqlite_wire-0.1.0/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.

dqlite_wire-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,37 @@
+# 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/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dqlite-wire"
+version = "0.1.0"
+description = "Pure Python wire protocol implementation for dqlite"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [{ name = "Antoine Leclair", email = "antoineleclair@gmail.com" }]
+keywords = ["dqlite", "sqlite", "distributed", "database", "wire-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/letsdiscodev/python-dqlite-wire"
+Repository = "https://github.com/letsdiscodev/python-dqlite-wire"
+Issues = "https://github.com/letsdiscodev/python-dqlite-wire/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=4.0", "mypy>=1.0", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dqlitewire"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["dqlitewire"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

dqlite_wire-0.1.0/src/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"

dqlite_wire-0.1.0/src/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

dqlite_wire-0.1.0/src/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()