Skip to main content

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
  • ReliabilityLayer has 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)

Source distribution for pyrak 0.1.0
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)

Table of built distributions (wheels) for pyrak 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

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