Veltix¶

Python TCP, without the boilerplate.

Sync, thread-friendly, zero dependencies : TCP done right. Veltix handles framing, threading, handshake, routing, and reconnection so you can focus on your application logic.

Mature & tested : 638 tests · CI on Python 3.11-3.14 · v3.0.0 Rust-powered hot path

Why Veltix?¶

I wrote Veltix because I got tired of rewriting the same networking boilerplate every time I needed two programs to talk to each other.

Raw sockets are powerful, but they leave framing, request routing, handshakes, reconnection, and thread management entirely up to you. asyncio solves part of the problem, but adopting it often means committing your whole application to an async architecture. Twisted is incredibly capable, but it comes with its own programming model and can feel more like learning a framework than writing plain Python.

I wanted something different: a lightweight library that handles the repetitive networking work without forcing a particular architecture. Define your message types, register your handlers, and focus on your application instead of socket plumbing.

That's the idea behind Veltix: modern TCP communication with a simple, synchronous API, sensible defaults, and zero runtime dependencies.

Raw Socket vs Veltix¶

Echo server with raw sockets (15 lines):

import socket
import threading


def handle_client(conn, addr):
    while True:
        data = conn.recv(1024)
        if not data:
            break
        conn.sendall(data)
    conn.close()


server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server.bind(("0.0.0.0", 8080))
server.listen(5)

while True:
    conn, addr = server.accept()
    threading.Thread(target=handle_client, args=(conn, addr)).start()

Same thing with Veltix (7 lines):

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

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


@server.route(ECHO)
def on_echo(client: ClientInfo, response: Response) -> None:
    server.send(Request(ECHO, response.content, request_id=response.request_id), client)


server.start()

No manual framing. No thread management. No boilerplate.

Features¶

Core

Zero runtime dependencies : Python stdlib + optional Rust engine
Rust-powered hot path : framing / parse / compile in native Rust, automatic pure-Python fallback
Binary protocol with CRC32 integrity verification
Automatic JSON raw-socket handshake with version compatibility
Thread-safe callback execution : slow handlers never block reception

API

FastAPI-style routing : @server.route(MY_TYPE) / @client.route(MY_TYPE)
send_and_wait() : built-in request/response correlation with timeout
Text & JSON payloads : Request(MY_TYPE, text="hello") / Request(MY_TYPE, json={"k": "v"})
Content decoding : response.text, response.json, response.is_json, response.is_text
Convenience send : server.send() / client.send() - no need to touch Sender directly
Built-in ping/pong : bidirectional latency measurement
Client tags : attach arbitrary metadata to connected clients

Reliability

Auto-reconnect : configurable retry with DisconnectState callbacks
SMALL / MEDIUM / LARGE buffer size presets
Swappable socket backends via SocketCore (Threading or Async/Selectors)

Developer Experience

Integrated logger : colorized, file-rotating, thread-safe
638 tests, CI on Python 3.11 / 3.12 / 3.13 / 3.14 (Rust engine and pure-Python fallback)

Performance¶

Rust engine vs Python fallback (v3.0.0) - Python 3.14.7, 12-core CPU, 5-run averages:

Metric	Rust engine	Python fallback	Gain
Concurrent stress (100 clients)	137,995 msg/s	106,486 msg/s	+30%
Latency P99	0.066 ms	0.096 ms	-31%
FPS 64 tick stdev	0.175 ms	0.343 ms	-49%
Burst send	71,376 msg/s	59,408 msg/s	+20%

Socket backends, pure-Python path (Python 3.14.7, 12-core CPU, 30.5 GB RAM, loopback):

Metric	Threading	Async
Concurrent stress (100 clients)	51,505 msg/s	108,084 msg/s (2.1x)
Burst send	64,158 msg/s	60,358 msg/s
Average latency	0.041 ms	0.050 ms
Idle server memory	60.8 KB	≈0 (noise floor)

Full details : Performance

Comparison¶

Feature	Veltix	`socket`	`asyncio`	Twisted
High-level API	✓	✗	~	✗
Zero dependencies	✓	✓	✓	✗
No async required	✓	✓	✗	✗
Message framing	✓	✗	✗	~
Message integrity	✓	✗	✗	✗
Automatic handshake	✓	✗	✗	✗
Request/Response	✓	✗	~	✓
Message routing	✓	✗	✗	~
Auto-reconnect	✓	✗	~	✓
Non-blocking callbacks	✓	✗	✓	✓
Built-in ping/pong	✓	✗	✗	✗
Client tags	✓	✗	✗	✗
Swappable backends	✓	✗	✗	✗
Integrated logger	✓	✗	~	✓
Content decoding	✓	✗	✗	✗

✓ Built-in ~ Possible but requires manual setup ✗ Not provided (you implement it yourself)