Metadata-Version: 2.4
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
Dynamic: license-file

# 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).
