magpie-bridge (Python)

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.

中文文档

Installation

pip install magpie-bridge

Or install from source:

git clone https://github.com/moky/magpie-bridge.git
cd magpie-bridge/python
pip install -e .

Quick Start

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

• 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

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

cd python
pip install -e ".[dev]"   # or: pip install pytest
pytest

License

MIT — see LICENSE.