pyrak
An async implementation of the RakNet protocol in pure Python.
Built on anyio (works with both asyncio and trio). A single RakPeer can act
as a client, a server, or both at once.
Status: MVP. Verified against a real MCPE client (see TODO.md).
Features
- Offline handshake and connection:
OpenConnectionRequest1/2,ConnectionRequest,NewIncomingConnection, MTU negotiation, protocol version check, IP bans - All reliability modes:
UNRELIABLE,UNRELIABLE_SEQUENCED,RELIABLE,RELIABLE_ORDERED,RELIABLE_SEQUENCED - Ordering channels, send priorities, splitting of large messages, ACK/NAK and retransmission
- Connected/unconnected ping (RTT, and MOTD via
UnconnectedPong), timeouts and graceful disconnect - Declarative wire types on rombob; your own messages are carried as
UserMessage ReliabilityLayerhas no sockets and no clock (time is passed in), so it is easy to test
Not implemented yet: congestion control, security/cookie handshake, ack receipts, NAT punchthrough.
Installation
Requires Python 3.11+.
pip install pyrak
Or install the latest unreleased code straight from Git:
pip install git+https://github.com/loudblow/rombob.git@main
The rombob dependency is pulled from a GitHub release.
Server
import anyio
from pyrak import (
RELIABLE_ORDERED,
ConnectionLost,
DisconnectionNotification,
NewIncomingConnection,
RakPeer,
UserMessage,
)
async def main() -> None:
async with RakPeer(max_connections=10, max_incoming_connections=10) as server:
server.payload = "MCPE;pyrak;122;;0;10;0;hello;Creative;1;19132;19133;" # MOTD
await server.listen(("0.0.0.0", 19132))
async for packet in server: # packet.address, packet.guid, packet.message
match packet.message:
case NewIncomingConnection():
print(f"{packet.address} connected")
case UserMessage(id=0x86, payload=data):
# echo back to the same client
await server.send(
packet.guid, UserMessage(0x87, data), RELIABLE_ORDERED
)
case DisconnectionNotification() | ConnectionLost():
print(f"{packet.address} left")
anyio.run(main)
examples/mcpe_server.py is a server that shows up in the server list of a real
Minecraft PE client and receives its first game packet (0xFE):
poetry run python examples/mcpe_server.py 19132
Client
import anyio
from pyrak import RELIABLE_ORDERED, RakPeer, UserMessage
async def main() -> None:
async with RakPeer(max_connections=1) as client:
server = ("127.0.0.1", 19132)
# unconnected ping: fetch the server's MOTD
pong = await client.ping(server)
print("MOTD:", pong.payload if pong else "no answer")
session = await client.connect(server) # waits for the handshake
print("RTT, ms:", await client.ping(server, connected=True))
await client.send(server, UserMessage(0x86, b"hello"), RELIABLE_ORDERED)
# or raw bytes: the first byte is the message id
await client.send(server, b"\x86hello", RELIABLE_ORDERED, channel=1)
packet = await client.receive()
print(packet.message)
await client.disconnect(session)
anyio.run(main)
Connection failures (ConnectionBannedError, IncompatibleProtocolVersionError,
NoFreeIncomingConnectionsError, AlreadyConnectedError, ...) are defined in pyrak.errors.
Management
server.ban("1.2.3.4", duration=60_000) # ban for 60 seconds (0 = permanent)
server.unban("1.2.3.4")
server.sessions # active sessions
await server.disconnect(packet.guid) # close a session gracefully
await server.shutdown(block_duration=500)
Development
make install # set up the environment
make test # tests with coverage
make lint # ruff via pre-commit
make build # build the package
Single test: poetry run pytest -v -s tests/test_peer.py::test_ban
Layout:
| Path | Purpose |
|---|---|
src/pyrak/peer.py |
RakPeer: async client/server, sockets, offline handshake |
src/pyrak/session.py |
Session: connection state on top of ReliabilityLayer |
src/pyrak/reliability_layer.py |
reliability, ordering, split, ACK; no sockets, no clock |
src/pyrak/types/ |
declarative wire types on rombob |
docs/raknet_protocol.md |
protocol documentation |
Metadata
Release files for pyrak 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyrak-0.1.0.tar.gz | 31.7 kB | Without provenance | Details for pyrak-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyrak-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pyrak-0.1.0-py3-none-any.whl |
Total release size: 67.9 kB
Release files / pyrak-0.1.0.tar.gz
| Download URL | pyrak-0.1.0.tar.gz |
|---|---|
| Size | 31.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1634cc644ee473295c37bd74fb9ce729cdf68ffba59922bd029ce47f5067ccac
|
|
BLAKE2b-256 checksum How to use checksums |
ca3d28e89f220e9593c87b61f07d8effd2c8142ce5b4601871ec534624ff7504
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.14.2 Darwin/24.6.0
|
Release files / pyrak-0.1.0-py3-none-any.whl
| Download URL | pyrak-0.1.0-py3-none-any.whl |
|---|---|
| Size | 36.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
637cb1fb1c21772a1b4f7934ed2d00b46306919768fa20d8cd90843af8b74565
|
|
BLAKE2b-256 checksum How to use checksums |
88010ac1144d8b025f9e4165694df067f1894c89eed3a1e351480eb74f99d1fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.14.2 Darwin/24.6.0
|
Security for pyrak 0.1.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.