Server Guide¶

Configuration¶

from veltix import Server, ServerConfig, PerformanceMode, BufferSize

config = ServerConfig(
    host="0.0.0.0",  # Listening address
    port=8080,  # Listening port
    buffer_size=BufferSize.SMALL,  # Receive buffer size (default: 1KB)
    max_connection=10,  # Max simultaneous clients
    max_message_size=10 * 1024 * 1024,  # 10MB max message size
    handshake_timeout=5.0,  # Handshake timeout in seconds
    max_workers=4,  # Thread pool size for callbacks
    performance_mode=PerformanceMode.BALANCED,  # CPU/reactivity trade-off
)

server = Server(config)

Starting the server¶

server.start()  # Non-blocking, runs in background thread

Routing¶

Use @server.route() to handle specific message types directly. Routes take priority over on_recv and run in the thread pool.

from veltix import MessageType, Request

CHAT = MessageType(code=200, name="chat")
STATUS = MessageType(code=201, name="status")


@server.route(CHAT)
def on_chat(response, client):
    print(f"[{client.addr[0]}] {response.content.decode()}")


@server.route(STATUS)
def on_status(response, client):
    print(f"Status from {client.addr[0]}: {response.content.decode()}")

Routes can also be registered and removed programmatically:

server.request_handler.register_route(CHAT, on_chat)
server.request_handler.unregister_route(CHAT)

Callbacks¶

from veltix import Events

server.set_callback(Events.ON_CONNECT, lambda client: print(f"Connected: {client.addr}"))
server.set_callback(Events.ON_RECV, lambda client, msg: print(msg.content.decode()))
server.set_callback(Events.ON_DISCONNECT, lambda client: print(f"Disconnected: {client.addr}"))

Note

on_connect fires only after the handshake is complete. client.handshake_done is always True when it fires.

Tip

Use @server.route() for per-type handlers. on_recv is the fallback for unrouted messages.

Sending messages¶

# Send to a specific client
server.get_sender().send(request, client=client.conn)

# Broadcast to all clients
server.get_sender().broadcast(request, server.get_all_clients_sockets())

# Broadcast with exclusion
server.get_sender().broadcast(request, server.get_all_clients_sockets(), except_clients=[client.conn])

Ping¶

# Synchronous
latency = server.ping_client(client, timeout=2.0)

# Asynchronous (safe from within on_connect)
server.ping_client_async(client, callback=lambda ms: print(f"{ms}ms"), timeout=2.0)

Shutdown¶

server.close_all()