magpie-bridge 0.1.0__tar.gz

magpie_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albert Moky
+
+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.

magpie_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.1
+Name: magpie_bridge
+Version: 0.1.0
+Summary: Reliable UDP Relay Network protocol library
+Author: Albert Moky
+License: MIT
+Project-URL: Homepage, https://github.com/moky/magpie-bridge
+Project-URL: Repository, https://github.com/moky/magpie-bridge
+Project-URL: Issues, https://github.com/moky/magpie-bridge/issues
+Keywords: udp,relay,network,protocol,magpie-bridge
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# magpie-bridge (Python)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/magpie-bridge/)
+
+Reliable UDP Relay Network — wire protocol library for Python.
+
+This package implements the Magpie Bridge protocol codec: packet packing,
+unpacking, validation, message segmentation, and acknowledgement helpers.
+
+> [中文文档](README.zh-CN.md)
+
+## Installation
+
+```bash
+pip install magpie-bridge
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/moky/magpie-bridge.git
+cd magpie-bridge/python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from magpie_bridge import Packet, split_message, build_ack, TYPE_MINI
+
+# Build and send a small packet
+pkt = Packet(TYPE_MINI, target_bid=42, source_bid=7, sn=1, body=b"hello")
+data = pkt.pack()              # bytes ready for UDP send
+
+# Parse a received packet
+received = Packet.unpack(data)
+print(received.body)           # b"hello"
+
+# Split a large message into segments
+message = b"x" * 5000
+segments = split_message(message, sn=2, source_bid=7, target_bid=42)
+for seg in segments:
+    send(seg.pack())
+
+# Build an acknowledgement
+ack = build_ack(received)
+send(ack.pack())               # body=b"OK", bids swapped
+```
+
+## Protocol Overview
+
+| Field             | Size   | Description                          |
+| ----------------- | ------ | ------------------------------------ |
+| Magic Code        | 4 B    | `MB\x00\x01` (Magpie Bridge v1)      |
+| Type              | 1 B    | packet type + parameter width        |
+| Head Length       | 1 B    | 20 / 22 / 24 / 28                    |
+| Body Length       | 2 B    | body size in octets                  |
+| Target Bridge ID  | 4 B    | destination bid                      |
+| Source Bridge ID  | 4 B    | originator bid                       |
+| Serial Number     | 4 B    | message identity                     |
+| index / count     | 0/2/4/8 B | segment ordinal / total segments  |
+| Body              | 0..1200 B | application payload               |
+
+- Maximum UDP payload (MSS): **1232** octets (1280 - 40 - 8, dual-stack safe).
+- Maximum body size: **1200** octets.
+- See `../docs/design-protocol.md` for the full specification.
+
+## API Reference
+
+### `Packet`
+
+```python
+Packet(type, target_bid, source_bid, sn, index=None, count=None, body=b"")
+```
+
+- `pack() -> bytes` — serialize.
+- `Packet.unpack(data: bytes) -> Packet` — parse.
+- `validate() -> bool` — check whether the packet is well-formed.
+- `message_id -> int` — deduplication key (`sn` for data packets,
+  `(sn << (type & 0x0F)) | index` for ACKs).
+- `head_length`, `param_width`, `is_ack` — derived properties.
+
+### Helpers
+
+- `select_type(message_size) -> int` — choose Type by message size.
+- `split_message(data, sn, source_bid, target_bid) -> list[Packet]`.
+- `build_ack(packet) -> Packet` — build a `b"OK"` acknowledgement.
+- `build_control(body, sn, source_bid=0, target_bid=0) -> Packet` — build a
+  control packet (SYN/ACK/PING/PONG/FIN) with Type 0.
+
+### Exceptions
+
+- `ProtocolError` — raised on invalid packets or parsing failures.
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"   # or: pip install pytest
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

magpie_bridge-0.1.0/README.md

@@ -0,0 +1,106 @@
+# magpie-bridge (Python)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/magpie-bridge/)
+
+Reliable UDP Relay Network — wire protocol library for Python.
+
+This package implements the Magpie Bridge protocol codec: packet packing,
+unpacking, validation, message segmentation, and acknowledgement helpers.
+
+> [中文文档](README.zh-CN.md)
+
+## Installation
+
+```bash
+pip install magpie-bridge
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/moky/magpie-bridge.git
+cd magpie-bridge/python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from magpie_bridge import Packet, split_message, build_ack, TYPE_MINI
+
+# Build and send a small packet
+pkt = Packet(TYPE_MINI, target_bid=42, source_bid=7, sn=1, body=b"hello")
+data = pkt.pack()              # bytes ready for UDP send
+
+# Parse a received packet
+received = Packet.unpack(data)
+print(received.body)           # b"hello"
+
+# Split a large message into segments
+message = b"x" * 5000
+segments = split_message(message, sn=2, source_bid=7, target_bid=42)
+for seg in segments:
+    send(seg.pack())
+
+# Build an acknowledgement
+ack = build_ack(received)
+send(ack.pack())               # body=b"OK", bids swapped
+```
+
+## Protocol Overview
+
+| Field             | Size   | Description                          |
+| ----------------- | ------ | ------------------------------------ |
+| Magic Code        | 4 B    | `MB\x00\x01` (Magpie Bridge v1)      |
+| Type              | 1 B    | packet type + parameter width        |
+| Head Length       | 1 B    | 20 / 22 / 24 / 28                    |
+| Body Length       | 2 B    | body size in octets                  |
+| Target Bridge ID  | 4 B    | destination bid                      |
+| Source Bridge ID  | 4 B    | originator bid                       |
+| Serial Number     | 4 B    | message identity                     |
+| index / count     | 0/2/4/8 B | segment ordinal / total segments  |
+| Body              | 0..1200 B | application payload               |
+
+- Maximum UDP payload (MSS): **1232** octets (1280 - 40 - 8, dual-stack safe).
+- Maximum body size: **1200** octets.
+- See `../docs/design-protocol.md` for the full specification.
+
+## API Reference
+
+### `Packet`
+
+```python
+Packet(type, target_bid, source_bid, sn, index=None, count=None, body=b"")
+```
+
+- `pack() -> bytes` — serialize.
+- `Packet.unpack(data: bytes) -> Packet` — parse.
+- `validate() -> bool` — check whether the packet is well-formed.
+- `message_id -> int` — deduplication key (`sn` for data packets,
+  `(sn << (type & 0x0F)) | index` for ACKs).
+- `head_length`, `param_width`, `is_ack` — derived properties.
+
+### Helpers
+
+- `select_type(message_size) -> int` — choose Type by message size.
+- `split_message(data, sn, source_bid, target_bid) -> list[Packet]`.
+- `build_ack(packet) -> Packet` — build a `b"OK"` acknowledgement.
+- `build_control(body, sn, source_bid=0, target_bid=0) -> Packet` — build a
+  control packet (SYN/ACK/PING/PONG/FIN) with Type 0.
+
+### Exceptions
+
+- `ProtocolError` — raised on invalid packets or parsing failures.
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"   # or: pip install pytest
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

magpie_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "magpie_bridge"
+version = "0.1.0"
+description = "Reliable UDP Relay Network protocol library"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Albert Moky"},
+]
+requires-python = ">=3.8"
+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.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Networking",
+]
+keywords = ["udp", "relay", "network", "protocol", "magpie-bridge"]
+
+[project.urls]
+Homepage = "https://github.com/moky/magpie-bridge"
+Repository = "https://github.com/moky/magpie-bridge"
+Issues = "https://github.com/moky/magpie-bridge/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

magpie_bridge-0.1.0/setup.cfg

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

magpie_bridge-0.1.0/src/magpie_bridge/__init__.py

@@ -0,0 +1,47 @@
+"""Magpie Bridge protocol library.
+
+Reliable UDP Relay Network wire protocol codec.
+"""
+
+from .constants import (
+    ACK_BIT,
+    HEAD_FIXED,
+    MAGIC,
+    MAX_BODY,
+    MSS,
+    TYPE_ACK_LARGE,
+    TYPE_ACK_MEDIUM,
+    TYPE_ACK_MINI,
+    TYPE_ACK_SMALL,
+    TYPE_LARGE,
+    TYPE_MEDIUM,
+    TYPE_MINI,
+    TYPE_SMALL,
+)
+from .errors import ProtocolError
+from .protocol import Packet, build_ack, build_control, select_type, split_message
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "ACK_BIT",
+    "HEAD_FIXED",
+    "MAGIC",
+    "MAX_BODY",
+    "MSS",
+    "Packet",
+    "ProtocolError",
+    "TYPE_ACK_LARGE",
+    "TYPE_ACK_MEDIUM",
+    "TYPE_ACK_MINI",
+    "TYPE_ACK_SMALL",
+    "TYPE_LARGE",
+    "TYPE_MEDIUM",
+    "TYPE_MINI",
+    "TYPE_SMALL",
+    "build_ack",
+    "build_control",
+    "select_type",
+    "split_message",
+]

magpie_bridge-0.1.0/src/magpie_bridge/constants.py

@@ -0,0 +1,34 @@
+"""Protocol constants for Magpie Bridge."""
+
+# Magic code: 'M', 'B', 0x00, 0x01 (Magpie Bridge v1)
+MAGIC = b"MB\x00\x01"
+
+# Fixed head size (octets), before the optional parameter area
+HEAD_FIXED = 20
+
+# Maximum UDP payload size (octets), dual-stack safe: 1280 - 40 - 8
+MSS = 1232
+
+# Maximum body size (octets): MSS - 32 (reserved head budget)
+MAX_BODY = 1200
+
+# High bit of Type marks an acknowledgement (reply) packet
+ACK_BIT = 0x80
+
+# Data packet types (low nibble = parameter width in octets)
+TYPE_MINI = 0x00      # no parameter area, miniature single packet
+TYPE_SMALL = 0x01     # 1-octet parameters, 1 <= K < 256
+TYPE_MEDIUM = 0x02    # 2-octet parameters, 256 <= K < 65536
+TYPE_LARGE = 0x04     # 4-octet parameters, 65536 <= K < 2^32
+
+# Acknowledgement packet types
+TYPE_ACK_MINI = 0x80
+TYPE_ACK_SMALL = 0x81
+TYPE_ACK_MEDIUM = 0x82
+TYPE_ACK_LARGE = 0x84
+
+# Mapping from low nibble to parameter width (octets)
+PARAM_WIDTH = {0: 0, 1: 1, 2: 2, 4: 4}
+
+# Mapping from low nibble to total head length (octets)
+HEAD_LENGTH = {0: 20, 1: 22, 2: 24, 4: 28}

magpie_bridge-0.1.0/src/magpie_bridge/errors.py

@@ -0,0 +1,5 @@
+"""Protocol exceptions for Magpie Bridge."""
+
+
+class ProtocolError(Exception):
+    """Raised when a packet fails validation or cannot be parsed."""

magpie_bridge-0.1.0/src/magpie_bridge/protocol.py

@@ -0,0 +1,225 @@
+"""Magpie Bridge protocol packet codec.
+
+Implements packing, unpacking, validation and helpers for the wire protocol
+defined in docs/design-protocol.md.
+"""
+
+import struct
+from typing import List, Optional
+
+from .constants import (
+    ACK_BIT,
+    HEAD_FIXED,
+    MAGIC,
+    MAX_BODY,
+    MSS,
+    PARAM_WIDTH,
+    TYPE_LARGE,
+    TYPE_MEDIUM,
+    TYPE_MINI,
+    TYPE_SMALL,
+)
+from .errors import ProtocolError
+
+
+class Packet:
+    """A single Magpie Bridge protocol frame (head + body)."""
+
+    def __init__(
+        self,
+        type: int = TYPE_MINI,
+        target_bid: int = 0,
+        source_bid: int = 0,
+        sn: int = 0,
+        index: Optional[int] = None,
+        count: Optional[int] = None,
+        body: bytes = b"",
+    ) -> None:
+        self.type = type
+        self.target_bid = target_bid
+        self.source_bid = source_bid
+        self.sn = sn
+        self.index = index
+        self.count = count
+        self.body = bytes(body)
+
+    # -- derived properties ------------------------------------------------
+
+    @property
+    def param_width(self) -> int:
+        """Width (octets) of each parameter (index, count)."""
+        low = self.type & 0x0F
+        if low not in PARAM_WIDTH:
+            raise ProtocolError(f"invalid type low nibble: {low}")
+        return PARAM_WIDTH[low]
+
+    @property
+    def head_length(self) -> int:
+        """Total head length including the parameter area."""
+        return HEAD_FIXED + 2 * self.param_width
+
+    @property
+    def is_ack(self) -> bool:
+        """True when the high bit of Type is set."""
+        return bool(self.type & ACK_BIT)
+
+    @property
+    def message_id(self) -> int:
+        """Deduplication key combining sn and index.
+
+        For data packets the key is sn alone; for acknowledgement packets
+        the key is (sn << (type & 0x0F)) | index.
+        """
+        if self.type & ACK_BIT == 0:
+            return self.sn
+        return (self.sn << (self.type & 0x0F)) | (self.index or 0)
+
+    # -- pack / unpack -----------------------------------------------------
+
+    def pack(self) -> bytes:
+        """Serialize the packet to bytes. Raises ProtocolError on invalid state."""
+        w = self.param_width
+        body = self.body
+
+        if len(body) > MAX_BODY:
+            raise ProtocolError(f"body too large: {len(body)} > {MAX_BODY}")
+        if self.head_length + len(body) > MSS:
+            raise ProtocolError(
+                f"packet too large: {self.head_length + len(body)} > {MSS}"
+            )
+
+        if w:
+            if self.index is None or self.count is None:
+                raise ProtocolError("index and count are required for segmented packets")
+            if not (0 <= self.index < self.count):
+                raise ProtocolError(
+                    f"invalid index/count: {self.index}/{self.count}"
+                )
+            max_val = (1 << (8 * w)) - 1
+            if self.index > max_val or self.count > max_val:
+                raise ProtocolError("index/count exceeds parameter width")
+
+        head = bytearray()
+        head += MAGIC
+        head.append(self.type & 0xFF)
+        head.append(self.head_length & 0xFF)
+        head += struct.pack(">H", len(body))
+        head += struct.pack(
+            ">III",
+            self.target_bid & 0xFFFFFFFF,
+            self.source_bid & 0xFFFFFFFF,
+            self.sn & 0xFFFFFFFF,
+        )
+        if w:
+            head += self.index.to_bytes(w, "big")
+            head += self.count.to_bytes(w, "big")
+        return bytes(head) + body
+
+    @classmethod
+    def unpack(cls, data: bytes) -> "Packet":
+        """Parse bytes into a Packet. Raises ProtocolError on malformed input."""
+        if len(data) < HEAD_FIXED:
+            raise ProtocolError(f"packet too short: {len(data)} < {HEAD_FIXED}")
+        if data[0:4] != MAGIC:
+            raise ProtocolError("bad magic code")
+
+        type_ = data[4]
+        head_len = data[5]
+        body_len = struct.unpack(">H", data[6:8])[0]
+
+        if head_len + body_len != len(data):
+            raise ProtocolError(
+                f"length mismatch: head={head_len} body={body_len} total={len(data)}"
+            )
+
+        low = type_ & 0x0F
+        if low not in PARAM_WIDTH:
+            raise ProtocolError(f"invalid type low nibble: {low}")
+        w = PARAM_WIDTH[low]
+        expected_head = HEAD_FIXED + 2 * w
+        if head_len != expected_head:
+            raise ProtocolError(
+                f"head length mismatch: {head_len} != {expected_head}"
+            )
+
+        target, source, sn = struct.unpack(">III", data[8:20])
+        index = count = None
+        if w:
+            index = int.from_bytes(data[20:20 + w], "big")
+            count = int.from_bytes(data[20 + w:20 + 2 * w], "big")
+
+        body = data[head_len:head_len + body_len]
+        return cls(type_, target, source, sn, index, count, body)
+
+    def validate(self) -> bool:
+        """Return True if the packet can be packed without error."""
+        try:
+            self.pack()
+            return True
+        except ProtocolError:
+            return False
+
+    def __repr__(self) -> str:
+        return (
+            f"Packet(type=0x{self.type:02x}, target={self.target_bid}, "
+            f"source={self.source_bid}, sn={self.sn}, "
+            f"index={self.index}, count={self.count}, body={len(self.body)}B)"
+        )
+
+
+# -- helpers ---------------------------------------------------------------
+
+
+def select_type(message_size: int) -> int:
+    """Select the data packet Type for a message of size K (octets)."""
+    if message_size <= 0:
+        return TYPE_MINI
+    if message_size < 256:
+        return TYPE_SMALL
+    if message_size < 65536:
+        return TYPE_MEDIUM
+    return TYPE_LARGE
+
+
+def split_message(
+    data: bytes,
+    sn: int,
+    source_bid: int,
+    target_bid: int,
+) -> List[Packet]:
+    """Split a message into one or more packets (max MAX_BODY octets each)."""
+    if not data:
+        return [Packet(TYPE_MINI, target_bid, source_bid, sn, body=b"")]
+
+    type_ = select_type(len(data))
+    count = (len(data) + MAX_BODY - 1) // MAX_BODY
+    packets: List[Packet] = []
+    for i in range(count):
+        chunk = data[i * MAX_BODY:(i + 1) * MAX_BODY]
+        packets.append(
+            Packet(type_, target_bid, source_bid, sn, i, count, chunk)
+        )
+    return packets
+
+
+def build_ack(packet: Packet) -> Packet:
+    """Build a data acknowledgement (body = b'OK') for the given packet."""
+    return Packet(
+        type=packet.type | ACK_BIT,
+        target_bid=packet.source_bid,
+        source_bid=packet.target_bid,
+        sn=packet.sn,
+        index=packet.index,
+        count=packet.count,
+        body=b"OK",
+    )
+
+
+def build_control(
+    body: bytes,
+    sn: int,
+    source_bid: int = 0,
+    target_bid: int = 0,
+) -> Packet:
+    """Build a control packet (SYN/ACK/PING/PONG/FIN) using Type 0 (mini)."""
+    return Packet(TYPE_MINI, target_bid, source_bid, sn, body=body)

magpie_bridge-0.1.0/src/magpie_bridge.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.1
+Name: magpie-bridge
+Version: 0.1.0
+Summary: Reliable UDP Relay Network protocol library
+Author: Albert Moky
+License: MIT
+Project-URL: Homepage, https://github.com/moky/magpie-bridge
+Project-URL: Repository, https://github.com/moky/magpie-bridge
+Project-URL: Issues, https://github.com/moky/magpie-bridge/issues
+Keywords: udp,relay,network,protocol,magpie-bridge
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# magpie-bridge (Python)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/magpie-bridge/)
+
+Reliable UDP Relay Network — wire protocol library for Python.
+
+This package implements the Magpie Bridge protocol codec: packet packing,
+unpacking, validation, message segmentation, and acknowledgement helpers.
+
+> [中文文档](README.zh-CN.md)
+
+## Installation
+
+```bash
+pip install magpie-bridge
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/moky/magpie-bridge.git
+cd magpie-bridge/python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from magpie_bridge import Packet, split_message, build_ack, TYPE_MINI
+
+# Build and send a small packet
+pkt = Packet(TYPE_MINI, target_bid=42, source_bid=7, sn=1, body=b"hello")
+data = pkt.pack()              # bytes ready for UDP send
+
+# Parse a received packet
+received = Packet.unpack(data)
+print(received.body)           # b"hello"
+
+# Split a large message into segments
+message = b"x" * 5000
+segments = split_message(message, sn=2, source_bid=7, target_bid=42)
+for seg in segments:
+    send(seg.pack())
+
+# Build an acknowledgement
+ack = build_ack(received)
+send(ack.pack())               # body=b"OK", bids swapped
+```
+
+## Protocol Overview
+
+| Field             | Size   | Description                          |
+| ----------------- | ------ | ------------------------------------ |
+| Magic Code        | 4 B    | `MB\x00\x01` (Magpie Bridge v1)      |
+| Type              | 1 B    | packet type + parameter width        |
+| Head Length       | 1 B    | 20 / 22 / 24 / 28                    |
+| Body Length       | 2 B    | body size in octets                  |
+| Target Bridge ID  | 4 B    | destination bid                      |
+| Source Bridge ID  | 4 B    | originator bid                       |
+| Serial Number     | 4 B    | message identity                     |
+| index / count     | 0/2/4/8 B | segment ordinal / total segments  |
+| Body              | 0..1200 B | application payload               |
+
+- Maximum UDP payload (MSS): **1232** octets (1280 - 40 - 8, dual-stack safe).
+- Maximum body size: **1200** octets.
+- See `../docs/design-protocol.md` for the full specification.
+
+## API Reference
+
+### `Packet`
+
+```python
+Packet(type, target_bid, source_bid, sn, index=None, count=None, body=b"")
+```
+
+- `pack() -> bytes` — serialize.
+- `Packet.unpack(data: bytes) -> Packet` — parse.
+- `validate() -> bool` — check whether the packet is well-formed.
+- `message_id -> int` — deduplication key (`sn` for data packets,
+  `(sn << (type & 0x0F)) | index` for ACKs).
+- `head_length`, `param_width`, `is_ack` — derived properties.
+
+### Helpers
+
+- `select_type(message_size) -> int` — choose Type by message size.
+- `split_message(data, sn, source_bid, target_bid) -> list[Packet]`.
+- `build_ack(packet) -> Packet` — build a `b"OK"` acknowledgement.
+- `build_control(body, sn, source_bid=0, target_bid=0) -> Packet` — build a
+  control packet (SYN/ACK/PING/PONG/FIN) with Type 0.
+
+### Exceptions
+
+- `ProtocolError` — raised on invalid packets or parsing failures.
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"   # or: pip install pytest
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

magpie_bridge-0.1.0/src/magpie_bridge.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/magpie_bridge/__init__.py
+src/magpie_bridge/constants.py
+src/magpie_bridge/errors.py
+src/magpie_bridge/protocol.py
+src/magpie_bridge.egg-info/PKG-INFO
+src/magpie_bridge.egg-info/SOURCES.txt
+src/magpie_bridge.egg-info/dependency_links.txt
+src/magpie_bridge.egg-info/top_level.txt
+tests/test_protocol.py

magpie_bridge-0.1.0/src/magpie_bridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

magpie_bridge-0.1.0/src/magpie_bridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+magpie_bridge

magpie_bridge-0.1.0/tests/test_protocol.py

@@ -0,0 +1,150 @@
+"""Tests for the Magpie Bridge protocol codec."""
+
+import pytest
+
+from magpie_bridge import (
+    MAX_BODY,
+    MSS,
+    Packet,
+    ProtocolError,
+    TYPE_LARGE,
+    TYPE_MEDIUM,
+    TYPE_MINI,
+    TYPE_SMALL,
+    build_ack,
+    build_control,
+    select_type,
+    split_message,
+)
+
+
+class TestPacketPackUnpack:
+    def test_mini_packet_roundtrip(self):
+        pkt = Packet(TYPE_MINI, 1, 2, 100, body=b"hello")
+        data = pkt.pack()
+        assert data[0:4] == b"MB\x00\x01"
+        assert len(data) == 20 + 5
+        restored = Packet.unpack(data)
+        assert restored.type == TYPE_MINI
+        assert restored.target_bid == 1
+        assert restored.source_bid == 2
+        assert restored.sn == 100
+        assert restored.index is None
+        assert restored.count is None
+        assert restored.body == b"hello"
+
+    def test_segmented_packet_roundtrip(self):
+        pkt = Packet(TYPE_SMALL, 10, 20, 5, index=0, count=3, body=b"abc")
+        data = pkt.pack()
+        assert len(data) == 22 + 3
+        restored = Packet.unpack(data)
+        assert restored.type == TYPE_SMALL
+        assert restored.head_length == 22
+        assert restored.index == 0
+        assert restored.count == 3
+        assert restored.body == b"abc"
+
+    def test_medium_and_large_widths(self):
+        for type_, width in [(TYPE_MEDIUM, 2), (TYPE_LARGE, 4)]:
+            pkt = Packet(type_, 1, 2, 7, index=5, count=10, body=b"x")
+            data = pkt.pack()
+            assert len(data) == 20 + 2 * width + 1
+            restored = Packet.unpack(data)
+            assert restored.index == 5
+            assert restored.count == 10
+
+    def test_bad_magic_raises(self):
+        data = b"XXXX" + b"\x00" * 16
+        with pytest.raises(ProtocolError):
+            Packet.unpack(data)
+
+    def test_too_short_raises(self):
+        with pytest.raises(ProtocolError):
+            Packet.unpack(b"MB\x00\x01")
+
+    def test_length_mismatch_raises(self):
+        pkt = Packet(TYPE_MINI, 1, 2, 1, body=b"ok")
+        data = pkt.pack()
+        with pytest.raises(ProtocolError):
+            Packet.unpack(data + b"extra")
+
+    def test_body_too_large_raises(self):
+        pkt = Packet(TYPE_MINI, 1, 2, 1, body=b"x" * (MAX_BODY + 1))
+        with pytest.raises(ProtocolError):
+            pkt.pack()
+
+    def test_invalid_index_raises(self):
+        pkt = Packet(TYPE_SMALL, 1, 2, 1, index=5, count=3, body=b"x")
+        with pytest.raises(ProtocolError):
+            pkt.pack()
+
+    def test_validate(self):
+        good = Packet(TYPE_MINI, 1, 2, 1, body=b"ok")
+        bad = Packet(TYPE_SMALL, 1, 2, 1, index=5, count=3, body=b"x")
+        assert good.validate() is True
+        assert bad.validate() is False
+
+
+class TestHelpers:
+    def test_select_type(self):
+        assert select_type(0) == TYPE_MINI
+        assert select_type(100) == TYPE_SMALL
+        assert select_type(255) == TYPE_SMALL
+        assert select_type(256) == TYPE_MEDIUM
+        assert select_type(65535) == TYPE_MEDIUM
+        assert select_type(65536) == TYPE_LARGE
+
+    def test_split_message_single(self):
+        data = b"hello world"
+        packets = split_message(data, 42, 1, 2)
+        assert len(packets) == 1
+        assert packets[0].count == 1
+        assert packets[0].index == 0
+        assert packets[0].body == data
+
+    def test_split_message_empty(self):
+        packets = split_message(b"", 1, 1, 2)
+        assert len(packets) == 1
+        assert packets[0].type == TYPE_MINI
+        assert packets[0].body == b""
+
+    def test_split_message_multiple(self):
+        data = b"x" * (MAX_BODY * 2 + 10)
+        packets = split_message(data, 7, 1, 2)
+        assert len(packets) == 3
+        assert packets[0].count == 3
+        assert packets[-1].body == b"x" * 10
+        for i, pkt in enumerate(packets):
+            assert pkt.index == i
+            assert pkt.sn == 7
+
+    def test_build_ack(self):
+        pkt = Packet(TYPE_SMALL, 10, 20, 5, index=1, count=3, body=b"abc")
+        ack = build_ack(pkt)
+        assert ack.type == 0x81
+        assert ack.target_bid == 20
+        assert ack.source_bid == 10
+        assert ack.sn == 5
+        assert ack.index == 1
+        assert ack.count == 3
+        assert ack.body == b"OK"
+
+    def test_build_control(self):
+        pkt = build_control(b"SYN", 1, source_bid=0, target_bid=0)
+        assert pkt.type == TYPE_MINI
+        assert pkt.body == b"SYN"
+        assert pkt.head_length == 20
+
+    def test_message_id_data_packet(self):
+        pkt = Packet(TYPE_SMALL, 1, 2, 100, index=3, count=5, body=b"x")
+        assert pkt.message_id == 100
+
+    def test_message_id_ack_packet(self):
+        pkt = Packet(0x81, 1, 2, 100, index=3, count=5, body=b"OK")
+        assert pkt.message_id == (100 << 1) | 3
+
+    def test_max_body_fits_mss(self):
+        body = b"y" * MAX_BODY
+        pkt = Packet(TYPE_LARGE, 1, 2, 1, index=0, count=1, body=body)
+        data = pkt.pack()
+        assert len(data) <= MSS