veltix 1.4.0

A simple, zero-dependency TCP networking library with message integrity and request/response patterns

Veltix

A modern, lightweight TCP networking library for Python — simple enough for beginners, solid enough for production.

Veltix provides a clean abstraction layer over TCP sockets, handling the low-level complexity so you can focus on your application logic. It ships with message integrity verification, a structured binary protocol, request/response correlation, automatic connection handshake, and production-ready logging — all with zero external dependencies.

Performance highlights: 50k+ msg/s throughput • 0.011ms average latency • 148KB idle memory • 100% success rate

---

Table of Contents

• Why Veltix
• Features
• Performance
• Installation
• Quick Start
• Integrated Logger
• Request/Response Pattern
• Built-in Ping/Pong
• Advanced Features
• Comparison
• Roadmap
• Migration Guide
• Examples
• Security
• Contributing
• License

---

Why Veltix

Working directly with Python's socket module or asyncio forces you to manage framing, concurrency, error handling, and protocol design from scratch. Heavier frameworks like Twisted introduce steep learning curves and large dependency trees.

Veltix sits in between: a focused library that handles the hard parts — connection management, message integrity, threading, handshake, and request correlation — while keeping the API surface small and the codebase readable.

Designed for:

• Developers who want structured TCP communication without dealing with asyncio internals
• Teams that need a maintainable, dependency-free networking layer in production
• Real-time applications and simulations
• Rapid prototyping of client/server applications
• Custom protocol experimentation

---

Features

• Simple API — Get a working client/server in under 30 lines
• High Performance — 50k+ messages/second, 0.011ms latency
• Message integrity — Built-in SHA-256 payload verification
• Custom binary protocol — Lightweight framing with TCP stream handling
• Zero dependencies — Pure Python standard library only
• Multi-threaded — Concurrent client handling out of the box
• Automatic handshake — HELLO/HELLO_ACK with version compatibility check on every connection
• Thread-safe callbacks — on_recv runs in a thread pool, slow callbacks never block reception
• Request/Response pattern — send_and_wait() with configurable timeout
• Built-in ping/pong — Bidirectional latency measurement
• Integrated logger — Colorized, file-rotating, thread-safe logging
• Memory Efficient — 148KB idle server, 52KB per client
• Extensible — Custom message types and event callbacks
• Defensive design — Strict validation and controlled failure handling

---

Performance

Benchmarked on Python 3.14.2 — 12-core CPU, 30.5 GB RAM, Linux. All tests run locally (loopback).

┌─────────────────────────────────────────────────────────────────────┐
│                    VELTIX PERFORMANCE RESULTS                       │
├─────────────────────┬───────────────────────────────────────────────┤
│  MEMORY             │                                               │
│  Idle server        │     148 KB                                    │
│  Per client         │    52.4 KB                                    │
│  50 clients total   │    29.6 MB                                    │
├─────────────────────┼───────────────────────────────────────────────┤
│  LATENCY (local)    │                                               │
│  Average            │   0.012 ms                                    │
│  P95                │   0.000 ms                                    │
│  P99                │   1.000 ms                                    │
│  Max                │   1.000 ms                                    │
├─────────────────────┼───────────────────────────────────────────────┤
│  FPS SIMULATION     │                                               │
│  64 players @64Hz   │   4,489 msg/s  –  100% success               │
│  128 players @20Hz  │   2,813 msg/s  –  100% success               │
├─────────────────────┼───────────────────────────────────────────────┤
│  BURST THROUGHPUT   │                                               │
│  Send               │  67,236 msg/s                                 │
│  Receive            │  50,304 msg/s                                 │
│  Data               │    3.07 MB/s                                  │
├─────────────────────┼───────────────────────────────────────────────┤
│  CONCURRENT STRESS  │                                               │
│  100 clients        │  40,402 msg/s  –  100% success               │
└─────────────────────┴───────────────────────────────────────────────┘

Ping/Pong — 2,000 iterations, 100% success rate, 22,222 ping/s throughput.

FPS simulation — Veltix sustains a full 64-player game server at 64 tick/s and a 128-player server at 20 tick/s with zero message loss.

Burst throughput — 10,000 × 64-byte messages processed in 0.199s.

Concurrent stress — 100 simultaneous clients each firing 100 messages; all 10,000 delivered with 100% success in 0.248s.

To run the benchmark suite yourself:

python benchmark.py

---

Installation

pip install veltix

Requirements: Python 3.10+, no additional dependencies.

---

Quick Start

The following example implements a basic echo server and client.

Server (server.py):

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

CHAT = MessageType(code=200, name="chat")

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


def on_message(client: ClientInfo, response: Response):
    print(f"[{client.addr[0]}] {response.content.decode()}")
    reply = Request(CHAT, f"Echo: {response.content.decode()}".encode())
    sender.broadcast(reply, server.get_all_clients_sockets())


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

input("Press Enter to stop...")
server.close_all()

Client (client.py):

from veltix import Client, Response, ClientConfig, MessageType, Request, Events

CHAT = MessageType(code=200, name="chat")

config = ClientConfig(server_addr="127.0.0.1", port=8080)
client = Client(config)
sender = client.get_sender()


def on_message(response: Response):
    print(f"Server: {response.content.decode()}")


client.set_callback(Events.ON_RECV, on_message)
client.connect()  # Blocks until handshake is complete — safe to send immediately

msg = Request(CHAT, b"Hello Server!")
sender.send(msg)

input("Press Enter to disconnect...")
client.disconnect()

python server.py
python client.py  # In a separate terminal

---

Integrated Logger

Veltix includes a production-ready logging system with colorized output, automatic file rotation, and thread safety. It follows a singleton pattern so the same instance is shared across your application.

Basic Usage

from veltix import Logger, LogLevel

logger = Logger.get_instance()

logger.trace("Detailed trace information")
logger.debug("Debug information")
logger.info("General information")
logger.success("Operation successful")
logger.warning("Warning message")
logger.error("Error occurred")
logger.critical("Critical failure")

Configuration

from veltix import Logger, LoggerConfig, LogLevel
from pathlib import Path

config = LoggerConfig(
    level=LogLevel.DEBUG,
    enabled=True,
    use_colors=True,
    show_timestamp=True,
    show_caller=True,
    show_level=True,
    file_path=Path("logs/veltix.log"),
    file_rotation_size=10 * 1024 * 1024,  # 10 MB
    file_backup_count=5,
    async_write=False,
    buffer_size=100,
)

logger = Logger.get_instance(config)

Output Format

[14:23:45.123] INFO  [server.py:45] Server listening on 0.0.0.0:8080
[14:23:46.456] OK    [client.py:78] Successfully connected to server
[14:23:47.789] DEBUG [sender.py:92] Sent 156 bytes via client (request_id: a3f2...)
[14:23:48.012] WARN  [network.py:34] Connection issue: ConnectionResetError
[14:23:49.345] ERROR [request.py:89] Parse error: Hash mismatch — corrupted data

Available Log Levels

Level	Severity
TRACE	5
DEBUG	10
INFO	20
SUCCESS	25
WARNING	30
ERROR	40
CRITICAL	50

# Change level at runtime
logger.set_level(LogLevel.WARNING)

---

Request/Response Pattern

send_and_wait() enables synchronous request/response communication over TCP. The client blocks until the server replies with a matching request_id, or the timeout elapses.

Client:

from veltix import Client, ClientConfig, MessageType, Request

ECHO = MessageType(code=201, name="echo")
client = Client(ClientConfig(server_addr="127.0.0.1", port=8080))
client.connect()

request = Request(ECHO, b"Hello Server!")
response = client.send_and_wait(request, timeout=5.0)

if response:
    print(f"Response: {response.content.decode()}")
    print(f"Latency: {response.latency}ms")
else:
    print("Request timed out")

client.disconnect()

Server:

from veltix import Server, ServerConfig, MessageType, Request, Events

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


def on_message(client, response):
    reply = Request(response.type, response.content, request_id=response.request_id)
    server.get_sender().send(reply, client=client.conn)


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

input("Press Enter to stop...")
server.close_all()

---

Built-in Ping/Pong

Veltix handles PING/PONG internally. No manual implementation required.

Client pinging the server:

from veltix import Client, ClientConfig

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

latency = client.ping_server(timeout=2.0)
print(f"Latency: {latency}ms" if latency else "Ping timed out")

client.disconnect()

Server pinging a client:

from veltix import Server, ServerConfig, Events

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


def on_connect(client):
    latency = server.ping_client(client, timeout=2.0)
    if latency:
        print(f"Client {client.addr} latency: {latency}ms")


server.set_callback(Events.ON_CONNECT, on_connect)
server.start()

input("Press Enter to stop...")
server.close_all()

---

Advanced Features

Custom Message Types

Message type codes are divided into ranges by convention:

from veltix import MessageType

# System messages (0–199)
PING = MessageType(0, "ping", "System ping")

# Application messages (200–499)
CHAT = MessageType(200, "chat", "Chat message")
FILE_TRANSFER = MessageType(201, "file", "File transfer")

# Plugin messages (500+)
CUSTOM = MessageType(500, "plugin", "Custom plugin message")

Event Callbacks

from veltix import Server, Events

server = Server(config)

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

Client Callbacks

from veltix import Client, ClientConfig, Events

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

client.set_callback(Events.ON_CONNECT, lambda: print("Connected and handshake complete!"))
client.set_callback(Events.ON_RECV, lambda response: print(response.content.decode()))
client.set_callback(Events.ON_DISCONNECT, lambda: print("Disconnected"))

client.connect()

Configuring the Thread Pool

from veltix import ServerConfig, ClientConfig

# Increase workers for high-concurrency workloads with slow callbacks
server_config = ServerConfig(host="0.0.0.0", port=8080, max_workers=8)
client_config = ClientConfig(server_addr="127.0.0.1", port=8080, max_workers=8)

Broadcasting

# Broadcast to all connected clients
message = Request(CHAT, b"Server announcement")
sender.broadcast(message, server.get_all_clients_sockets())

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

---

Comparison

Feature	Veltix	socket	asyncio	Twisted
Simple API	✓	✗	~	✗
High Performance	✓	~	✓	~
Zero dependencies	✓	✓	✓	✗
Custom protocol	✓	✗	✗	~
Message integrity	✓	✗	✗	✗
Multi-threading	✓	✗	✗	✓
Request/Response	✓	✗	~	✓
Built-in ping/pong	✓	✗	✗	✗
Automatic handshake	✓	✗	✗	✗
Non-blocking callbacks	✓	✗	✓	✓
Integrated logger	✓	✗	~	✓

---

Roadmap

v1.4.0 — Handshake & Callbacks ✓ (Released March 2026)

• HELLO/HELLO_ACK handshake with version compatibility check
• Thread pool for non-blocking callback execution (CallbackExecutor)
• Blocking connect() — safe to send immediately after connecting
• on_connect / on_disconnect callbacks on Client

v1.5.0 — Routing (April 2026)

• Decorator-based message routing (@server.route(MY_TYPE))
• Per-type handlers as an alternative to the global on_recv

v1.6.0 — Plugin System (May 2026)

• Extensible plugin architecture
• Request.from_plugin() factory
• CallbackManager base class for plugin developers

v1.7.0 — Event Loop (June 2026)

• Selectors-based async I/O
• Replace daemon threads
• Further performance improvements

v2.0.0 — Encryption (September 2026)

• End-to-end encryption: ChaCha20 + X25519 + Ed25519
• Automatic key exchange and perfect forward secrecy

v3.0.0 — Rust Core (2027)

• PyO3 bindings
• 10–100× throughput improvement

---

Migration Guide

v1.3.0 → v1.4.0

No breaking changes to public API.

• on_connect (server-side) now fires after the handshake is complete — client.handshake_done is always True when it fires.
• connect() (client-side) now blocks until the handshake is done. It is safe to send messages immediately after it returns.
• New ClientConfig fields: handshake_timeout (default: 5.0), max_workers (default: 4)
• New ServerConfig fields: handshake_timeout (default: 5.0), max_workers (default: 4)

v1.2.x → v1.3.0

No breaking changes to public API.

v1.1.x → v1.2.0

# Before
from veltix import Bindings

server.bind(Bindings.ON_RECV, callback)

# After
from veltix import Events

server.set_callback(Events.ON_RECV, callback)

---

Examples

Full examples are available in the examples/ directory:

• Echo Server — send_and_wait() with request correlation
• Chat Server — Broadcast messaging in under 80 lines
• Ping Example — Bidirectional latency measurement

---

Security

Message integrity is enforced via SHA-256 payload verification on every message. If you discover a vulnerability, please report it responsibly through our Security Policy.

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request.

• Bug reports: Open an issue
• Discussions: Join the Discord
• Pull requests: Follow the contribution guide

Core Team

• Nytrox — Creator & Lead Developer

---

License

MIT License — see LICENSE for details.

---

Links

• GitHub: NytroxDev/Veltix
• PyPI: pypi.org/project/veltix
• Documentation: Coming soon
• Discord: discord.gg/NrEjSHtfMp