Skip to main content

Magpie Bridge (Python)

License: MIT

Reliable UDP Relay Network protocol library (Python).

Modules

  • magpie_bridge/protocol/ — protocol definitions (commands, types, formulas)
  • magpie_bridge/ — packet classes and packet factories (SDK layer)
  • magpie_bridge/bridge/ — relay server and server-side tools

Install

pip install magpie-bridge

Requires Python 3.6+. The base package has no third-party runtime dependencies (pure standard library).

The encrypted handshake mode (MIP 320) additionally needs the cryptography package — install it through the enigma extra:

pip install magpie-bridge[enigma]    # base package + cryptography

Without it, the SDK still works: packet packing/parsing and the plain-handshake mode are unaffected; only the encrypted handshake mode is unavailable (Enigma.encrypt/decrypt raise an explicit RuntimeError).

Server

After installation, start the relay server with:

magpie-bridge [--host=<ADDR>] [--port=<NUM>] [--config=<FILE>] [--log-dir=/tmp]

All arguments are named and optional:

  • --host: bind address (default: INI host, otherwise 0.0.0.0);
  • --port: UDP listen port (default: INI port, otherwise 9527); CLI --host/--port override the same-named INI keys;
  • --config: config file path (default: /etc/magpie/config.ini; when the file, the section or a key is missing, the code default is used);
  • --log-dir: log directory (default empty: no log file is written).

Unknown arguments print the usage and exit.

Logs

Without --log-dir, records go to the console (stdout) only.

With --log-dir=<dir>, the records are written to the console and to a daily-rotating log file under the directory:

  • file: <dir>/magpie-bridge.log (rotates at midnight, 30 days retained);
  • records are colorized by level — ERROR red, WARNING yellow, DEBUG gray, INFO in the terminal's default color — so tail -f renders them directly;
  • the file contains ANSI escape codes; strip them with sed 's/\x1b\[[0-9;]*m//g' before feeding line-based analysis tools.

Configuration

The config file is an INI file with a single section [magpie-bridge]:

[magpie-bridge]
host = 0.0.0.0
port = 9527
socket_buffer_length = 4194304
# forward threads
forwarders = 8
forward_limit_per_window = 4096
forward_window = 0.1
# bid record
record_active_timeout = 60.0
record_expires = 86400.0
record_recycle_interval = 600.0
max_records = 65536
allowlist_max_entries = 256
bid_allocation_retries = 16
# security
handshake_token_timeout = 60.0
handshake_min_payload = 512
unconfirmed_reply_buckets = 1024
reply_rate_limit = 10
noop_immunity_window = 2.0
# secrets
app_secret_file = /etc/magpie/private/enigma.json
app_secret_reload_interval = 600.0
server_secret_rotate_interval = 600.0
# task queue
waiting_queue_size = 4096
manager_queue_size = 1024
forwarder_queue_size = 65536

Time values are floating-point seconds; capacity values are integers (packet counts, except socket_buffer_length which is bytes).

The server validates every datagram before relaying: it drops invalid packets (bad magic / lengths), packets from broadcast or multicast sources (amplification attack protection), packets whose source socket does not match the recorded bid, and packets whose target bid is missing, unpermitted or inactive.

Message Packets

from magpie_bridge import (BridgePacketFactory, DirectPacketFactory,
                           ReliablePacket)

bridge = BridgePacketFactory()
direct = DirectPacketFactory()

# handshake with the server
syn = bridge.syn(request=payload)                  # SYN? (source=0)
syn_ack = bridge.syn_ack(response=payload, target=bid)  # SYN! from the server
ack = bridge.ack(response=payload, source=bid)    # ACK! to the server

# normal data (relayed by the server; C=0 saves 4 bytes)
data = bridge.data(payload, target=target, source=source,
                   sn=sn, index=0, count=1)
signed = data.sign(secret)                        # ReliablePacket: 32-byte
                                                  # attachment
copy = bridge.copy(data)                          # COPY acknowledgement

# direct client-to-client packets (no bids, no attachment)
d = direct.data(payload, sn=sn, index=0, count=1)

# parse a received packet (B-bit filtered per factory)
magpie = bridge.parse(data_bytes)

Tests

cd sdk-py
/usr/bin/python3 -m unittest discover -s tests

Metadata

Release files for magpie-bridge 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for magpie-bridge 0.2.0
File Interpreter ABI Platform Actions
magpie_bridge-0.2.0-py3-none-any.whl Python 3 none any Details for magpie_bridge-0.2.0-py3-none-any.whl

Release files / magpie_bridge-0.2.0-py3-none-any.whl

Download URL magpie_bridge-0.2.0-py3-none-any.whl
Size 66.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2c803c103d14c14c77780ed6c764e1bb5b0aba5399d9283e5dff8659a611574f
BLAKE2b-256 checksum
How to use checksums
e71014895990fd73ee7e5183cbc4335ef526b1608bd758e84806cef3a168b8fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/68.0.0 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.0b3

Security for magpie-bridge 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page