Purpose

Relayd is a stateless byte relay server written in Python. This server acts as a generic relay that forwards data from one client to another. It does not care about client application types (e.g., chat, real-time audio, offline audio, or other data).

Protocol

Only two commands are supported: login and transfer. For the same ClientID, there is always only one active connection: old connections are kicked out, and new connections are accepted (last-write-wins). If the ToClientID connection is offline, data transfers to it are discarded. If the server determines that the protocol format is incorrect, the connection has been inactive for a long time, or the connection state is incorrect, it can disconnect the connection without informing the client of the reason.

login

Field	Size	Type	Description	Type Check
Magic	4 bytes	literal(b'RELY')		Y
Version	1 byte	literal(0x01)	protocol version	Y
CMD	1 byte	literal(0x01)	login	Y
ClientIDLen	1 byte	uint8	A(1-255)	Y
ClientID	A bytes	UTF-8 bytes	e.g.: UUID	N

transfer

Field	Size	Type	Description	Type Check
Magic	4 bytes	literal(b'RELY')		Y
Version	1 byte	literal(0x01)	protocol version	Y
CMD	1 byte	literal(0x09)	transfer	Y
FromClientIDLen	1 byte	uint8	A(1-255)	Y
FromClientID	A bytes	UTF-8 bytes	e.g.: UUID	N
ToClientIDLen	1 byte	uint8	B(0-255), 0 for heartbeat	Y
ToClientID	B bytes	UTF-8 bytes	e.g.: UUID	N
PayloadLen	4 bytes	uint32 big-endian	N(0-4294967295)	Y
Payload	N bytes	opaque bytes		N

Server Usage

Requirements

• Python 3.10 or newer

Start the Server

• Use default port 33333:
  • python -m relayd
• Use a custom port:
  • python -m relayd 40000

Client Usage (Quick Chat Test)

An interactive test client is provided to verify relay behavior quickly.

Start One Client

From repository root:

• python -m relayd.client --host 127.0.0.1 --port 33333 --client-id alice --to-client-id bob

Optional (if your shell is already in relayd/):

• python client.py --host 127.0.0.1 --port 33333 --client-id alice --to-client-id bob

Start Two Clients for End-to-End Test

1. Terminal A:
   • python -m relayd.client --host 127.0.0.1 --port 33333 --client-id alice --to-client-id bob
2. Terminal B:
   • python -m relayd.client --host 127.0.0.1 --port 33333 --client-id bob --to-client-id alice

After both clients are connected and logged in:

• Type text and press Enter to send.
• Messages should appear in the other terminal.
• Type /quit (or /exit) to close a client.

Runtime Behavior

• The server binds to 0.0.0.0 on the chosen port.
• A connection must login before sending transfer frames.
• ToClientIDLen == 0 is treated as a heartbeat frame and is not forwarded.
• If another connection logs in with the same ClientID, the old one is closed immediately.
• Transfer data to offline destinations is discarded.
• Connections with protocol violations or long inactivity are disconnected.

Implementation Notes

• Built with asyncio stream APIs for high-concurrency I/O.
• The current implementation applies an 8 MiB per-frame payload safety limit to protect memory.