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(response: Response, client: ClientInfo) -> 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.

get_all_clients_sockets

get_all_clients_sockets() -> list[BaseSocket]

Return a list of all connected client sockets.

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

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.

close_client

close_client(client: ClientInfo) -> bool

Close a client connection and remove it from the list.

Parameters:

Name	Type	Description	Default
client	ClientInfo	The client to disconnect.	required

Returns:

Type	Description
bool	True if the client was found and removed, False otherwise.

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.
performance_mode	PerformanceMode	Controls internal timing parameters (default: BALANCED).
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 dataclass

Information about a connected client.

Attributes:

Name	Type	Description
conn	BaseSocket	Socket connection to the client.
addr	tuple[str, int]	Client address tuple (host, port).
ip	str	Client IP address (property).
port	int	Client port (property).
thread_id	int	Internal thread identifier.
handshake_done	bool	Whether the handshake has been completed.
tags	dict[str, Any]	Key-value store for arbitrary client metadata. Values default to None when added without an explicit value.

ip property

ip: str

Client IP address.

port property

port: int

Client port.

add_tag

add_tag(name: str, value: Optional[Any] = None) -> bool

Add a tag to the client.

Does nothing if the tag already exists.

Parameters:

Name	Type	Description	Default
name	str	Tag name.	required
value	Optional[Any]	Optional value associated with the tag (default: None).	None

Returns:

Type	Description
bool	True if the tag was added, False if it already existed.

has_tag

has_tag(name: str) -> bool

Check whether the client has a specific tag.

Parameters:

Name	Type	Description	Default
name	str	Tag name to look up.	required

Returns:

Type	Description
bool	True if the tag exists, False otherwise.

has_all_tags

has_all_tags(names: list[str]) -> bool

Check whether the client has all the specified tags.

Parameters:

Name	Type	Description	Default
names	list[str]	List of tag names that must all be present.	required

Returns:

Type	Description
bool	True if every tag in the list exists, False otherwise.

has_any_tags

has_any_tags(names: list[str]) -> bool

Check whether the client has at least one of the specified tags.

Parameters:

Name	Type	Description	Default
names	list[str]	List of tag names to check.	required

Returns:

Type	Description
bool	True if at least one tag in the list exists, False otherwise.

get_tag

get_tag(name: str) -> Optional[Any]

Retrieve the value associated with a tag.

Parameters:

Name	Type	Description	Default
name	str	Tag name to look up.	required

Returns:

Type	Description
Optional[Any]	The tag value, or None if the tag does not exist.

remove_tag

remove_tag(name: str) -> bool

Remove a tag from the client.

Does nothing if the tag does not exist.

Parameters:

Name	Type	Description	Default
name	str	Tag name to remove.	required

Returns:

Type	Description
bool	True if the tag was removed, False if it did not exist.

clear_tags

clear_tags() -> None

Remove all tags from the client.