Routing

Message routing lets you handle specific message types with dedicated callbacks, without a global on_recv. Routes take priority over on_recv and run in the thread pool.

Server routing

from veltix import Server, ServerConfig, MessageType, Response, ClientInfo

CHAT = MessageType("chat")
STATUS = MessageType("status")

server = Server(ServerConfig(host="0.0.0.0", port=8080))


@server.route(CHAT)
def on_chat(client: ClientInfo, response: Response):
    print(f"[{client.ip}] {response.text}")


@server.route(STATUS)
def on_status(client: ClientInfo, response: Response):
    print(f"Status from {client.ip}: {response.text}")


server.start()

Client routing

from veltix import Client, ClientConfig, MessageType, Response

CHAT = MessageType("chat")

client = Client(ClientConfig(server_addr="127.0.0.1", port=8080))


@client.route(CHAT)
def on_chat(response: Response):
    print(f"Server: {response.text}")


client.connect()

Priority over on_recv

Routes take priority over the global on_recv. If a message matches a route, on_recv is not called.

message received
    → route matches? → call route callback
    → no route?      → call on_recv (if set)
    → no on_recv?    → log warning, drop

@server.route(CHAT)
def on_chat(client, response):
    ...  # called for CHAT messages


server.on_recv(fallback)  # called for everything else

Programmatic registration

# Register
server.request_handler.register_route(CHAT, on_chat)  # returns False if already registered

# Unregister — falls back to on_recv after this
server.request_handler.unregister_route(CHAT)  # returns False if not registered

Thread pool

Route callbacks run in the same thread pool as on_recv — a slow route handler never blocks the recv loop.

Warning

Registering the same type twice returns False and keeps the original. Unregister first if you want to replace a route.