Server

veltix.server.server.Server

TCP server for the Veltix protocol.

Accepts incoming client connections, drives the HELLO/HELLO_ACK handshake, and dispatches received messages through the request handler.

Each client runs in a dedicated thread. Slow callbacks never block message reception — all user-defined handlers execute in a thread pool managed by the underlying RequestHandler.

Usage::

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

def on_message(client: ClientInfo, response: Response) -> None:
    server.get_sender().send(Request(CHAT, b"Hello"), client=client.conn)

server.set_callback(Events.ON_RECV, on_message)
server.start()

__init__

__init__(config: ServerConfig) -> None

Initialize the TCP server.

Parameters:

Name	Type	Description	Default
config	ServerConfig	Server configuration.	required

set_callback

set_callback(
    event: Union[str, Events], func: Callable
) -> None

Bind a callback function to a server event.

Parameters:

Name	Type	Description	Default
event	Union[str, Events]	Event type (Events enum or string).	required
func	Callable	Callback function: - ON_RECV: func(client: ClientInfo, response: Response) - ON_CONNECT: func(client: ClientInfo) - ON_DISCONNECT: func(client: ClientInfo)	required

route

route(type_: MessageType) -> Callable

Decorator to register a route callback for a specific message type.

Usage

@server.route(MY_TYPE) def on_my_type(client: ClientInfo, response: Response) -> None: ...

Parameters:

Name	Type	Description	Default
type_	MessageType	Message type to intercept.	required

Returns:

Type	Description
Callable	Decorator function.

get_sender

get_sender() -> Sender

Return the sender instance for sending data to clients.

send_and_wait

send_and_wait(
    request: Request,
    client: ClientInfo,
    timeout: float = 5.0,
) -> Optional[Response]

Send a request to a client and block until the matching response is received.

Parameters:

Name	Type	Description	Default
request	Request	Request to send.	required
client	ClientInfo	Target client.	required
timeout	float	Maximum time to wait for a response in seconds (default: 5.0).	5.0

Returns:

Type	Description
Optional[Response]	Matching Response, or None on timeout or send failure.

ping_client

ping_client(
    client: ClientInfo, timeout: float = 5.0
) -> Optional[float]

Ping a client and measure round-trip latency.

Parameters:

Name	Type	Description	Default
client	ClientInfo	Client to ping.	required
timeout	float	Timeout in seconds (default: 5.0).	5.0

Returns:

Type	Description
Optional[float]	Latency in milliseconds, or None on timeout.

ping_client_async

ping_client_async(
    client: ClientInfo,
    callback: Callable[[Optional[float]], None],
    timeout: float = 5.0,
) -> None

Ping a client asynchronously and call callback with the result.

Parameters:

Name	Type	Description	Default
client	ClientInfo	Client to ping.	required
callback	Callable[[Optional[float]], None]	Called with latency in ms, or None on timeout.	required
timeout	float	Timeout in seconds (default: 5.0).	5.0

close_client

close_client(
    client: ClientInfo, id_: Optional[int] = None
) -> bool

Forcefully close a specific client connection.

get_clients_sockets_by_tag

get_clients_sockets_by_tag(
    tag: str, value=None
) -> list[BaseSocket]

Get all clients that have a specific tag, optionally matching a value.

start

start(_on_th: bool = False) -> None

Start the server and begin accepting connections.

Non-blocking — starts a background thread and returns immediately.

Parameters:

Name	Type	Description	Default
_on_th	bool	Internal parameter, do not use.	False

close_all

close_all() -> None

Stop the server and close all client connections.

veltix.server.config.ServerConfig dataclass

TCP server configuration.

Attributes:

Name	Type	Description
host	str	Server listening address (default: '0.0.0.0').
port	int	Server listening port (default: 8080).
buffer_size	int	Buffer size for receiving data in bytes. Use BufferSize enum for common presets (default: BufferSize.SMALL). Can also be set to any custom integer value.
max_connection	int	Maximum number of simultaneous connections (default: -1 = unlimited).
max_message_size	int	Maximum allowed message size in bytes (default: 10MB).
handshake_timeout	float	Maximum time to wait for handshake completion in seconds (default: 5.0).
max_workers	int	Number of worker threads for callback execution (default: 4). Increase if your on_recv callback is slow or blocking.
socket_core	SocketCore	Socket implementation to use (default: THREADING). Switch to ASYNC (v1.7.0) or RUST (v3.0.0) without changing any other code.

veltix.server.client_info.ClientInfo