{"id":44745705,"url":"https://github.com/nytroxdev/veltix","last_synced_at":"2026-03-14T22:45:57.125Z","repository":{"id":337115881,"uuid":"1151260799","full_name":"NytroxDev/Veltix","owner":"NytroxDev","description":"The networking library you always wanted","archived":false,"fork":false,"pushed_at":"2026-02-07T23:28:11.000Z","size":53,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-08T04:57:39.543Z","etag":null,"topics":["networking","protocol","python","tcp","zero-dependencies"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NytroxDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T08:46:17.000Z","updated_at":"2026-02-07T23:28:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NytroxDev/Veltix","commit_stats":null,"previous_names":["nytroxdev/veltix"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/NytroxDev/Veltix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NytroxDev%2FVeltix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NytroxDev%2FVeltix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NytroxDev%2FVeltix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NytroxDev%2FVeltix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NytroxDev","download_url":"https://codeload.github.com/NytroxDev/Veltix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NytroxDev%2FVeltix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29490360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T19:29:10.908Z","status":"ssl_error","status_checked_at":"2026-02-15T19:29:10.419Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["networking","protocol","python","tcp","zero-dependencies"],"created_at":"2026-02-15T22:00:58.337Z","updated_at":"2026-03-14T22:45:57.118Z","avatar_url":"https://github.com/NytroxDev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Veltix\n\nA modern, lightweight TCP networking library for Python — simple enough for beginners, solid enough for production.\n\n[![PyPI](https://img.shields.io/pypi/v/veltix?cacheSeconds=300)](https://pypi.org/project/veltix/)\n[![Python](https://img.shields.io/pypi/pyversions/veltix?cacheSeconds=300)](https://pypi.org/project/veltix/)\n[![License](https://img.shields.io/github/license/NytroxDev/Veltix?cacheSeconds=300)](https://github.com/NytroxDev/Veltix/blob/main/LICENSE)\n[![Downloads](https://static.pepy.tech/personalized-badge/veltix?period=total\u0026units=NONE\u0026left_color=BLACK\u0026right_color=BLUE\u0026left_text=downloads)](https://pepy.tech/projects/veltix)\n[![Security Policy](https://img.shields.io/badge/security-policy-blue)](SECURITY.md)\n\nVeltix provides a clean abstraction layer over TCP sockets, handling the low-level complexity so you can focus on your\napplication logic. It ships with message integrity verification, a structured binary protocol, request/response\ncorrelation, automatic connection handshake, decorator-based message routing, auto-reconnect, and production-ready\nlogging — all with zero external dependencies.\n\n**Performance highlights:** 55k+ msg/s throughput • 0.011ms average latency • 84KB idle memory • 100% success rate\n\n---\n\n## Table of Contents\n\n- [Why Veltix](#why-veltix)\n- [Features](#features)\n- [Performance](#performance)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Integrated Logger](#integrated-logger)\n- [Request/Response Pattern](#requestresponse-pattern)\n- [Built-in Ping/Pong](#built-in-pingpong)\n- [Advanced Features](#advanced-features)\n- [Comparison](#comparison)\n- [Roadmap](#roadmap)\n- [Migration Guide](#migration-guide)\n- [Examples](#examples)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why Veltix\n\nWorking directly with Python's `socket` module or `asyncio` forces you to manage framing, concurrency, error handling,\nand protocol design from scratch. Heavier frameworks like Twisted introduce steep learning curves and large dependency\ntrees.\n\nVeltix sits in between: a focused library that handles the hard parts — connection management, message integrity,\nthreading, handshake, routing, and request correlation — while keeping the API surface small and the codebase readable.\n\n**Designed for:**\n\n- Developers who want structured TCP communication without dealing with `asyncio` internals\n- Teams that need a maintainable, dependency-free networking layer in production\n- Real-time applications and simulations\n- Rapid prototyping of client/server applications\n- Custom protocol experimentation\n\n---\n\n## Features\n\n- **Simple API** — Get a working client/server in under 30 lines\n- **High Performance** — 55k+ messages/second, 0.011ms latency\n- **Message integrity** — Built-in SHA-256 payload verification\n- **Custom binary protocol** — Lightweight framing with TCP stream handling\n- **Zero dependencies** — Pure Python standard library only\n- **Multi-threaded** — Concurrent client handling out of the box\n- **Automatic handshake** — HELLO/HELLO_ACK with version compatibility check on every connection\n- **Thread-safe callbacks** — All callbacks run in a thread pool, slow handlers never block reception\n- **Message routing** — `@server.route(MY_TYPE)` / `@client.route(MY_TYPE)` decorators for per-type handlers\n- **Auto-reconnect** — Configurable retry with `DisconnectState` callbacks\n- **Request/Response pattern** — `send_and_wait()` with configurable timeout\n- **Built-in ping/pong** — Bidirectional latency measurement\n- **Integrated logger** — Colorized, file-rotating, thread-safe logging\n- **Performance modes** — `LOW` / `BALANCED` / `HIGH` presets for CPU/reactivity trade-off\n- **Socket abstraction** — Swappable socket backends via `SocketCore` (Threading now, Selectors and Rust coming)\n- **Client tags** — Attach arbitrary metadata to connected clients\n- **Extensible** — Custom message types and event callbacks\n- **Defensive design** — Strict validation and controlled failure handling\n\n---\n\n## Performance\n\n\u003e Benchmarked on Python 3.14.3 — 12-core CPU, 30.5 GB RAM, Linux. All tests run locally (loopback).\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    VELTIX PERFORMANCE RESULTS                       │\n├─────────────────────┬───────────────────────────────────────────────┤\n│  MEMORY             │                                               │\n│  Idle server        │      84 KB                                    │\n│  Per client         │      78 KB                                    │\n│  50 clients total   │    28.89 MB                                   │\n├─────────────────────┼───────────────────────────────────────────────┤\n│  LATENCY (local)    │                                               │\n│  Average            │   0.011 ms                                    │\n│  P95                │   0.000 ms                                    │\n│  P99                │   1.000 ms                                    │\n│  Max                │   1.000 ms                                    │\n├─────────────────────┼───────────────────────────────────────────────┤\n│  FPS SIMULATION     │                                               │\n│  64 players @64Hz   │   4,490 msg/s  –  100% success               │\n│  128 players @20Hz  │   2,813 msg/s  –  100% success               │\n├─────────────────────┼───────────────────────────────────────────────┤\n│  BURST THROUGHPUT   │                                               │\n│  Send               │  55,606 msg/s                                 │\n│  Receive            │  43,497 msg/s                                 │\n│  Data               │    2.65 MB/s                                  │\n├─────────────────────┼───────────────────────────────────────────────┤\n│  CONCURRENT STRESS  │                                               │\n│  100 clients        │  33,482 msg/s  –  100% success               │\n└─────────────────────┴───────────────────────────────────────────────┘\n```\n\n**Ping/Pong** — 2,000 iterations, 100% success rate, 23,181 ping/s throughput.\n\n**FPS simulation** — Veltix sustains a full 64-player game server at 64 tick/s and a 128-player server at 20 tick/s with\nzero message loss.\n\n**Burst throughput** — 10,000 × 64-byte messages processed in 0.230s.\n\n**Concurrent stress** — 100 simultaneous clients each firing 100 messages; all 10,000 delivered with 100% success in\n0.299s.\n\nTo run the benchmark suite yourself:\n\n```bash\npython benchmark.py\n\n# Save results to JSON for sharing\npython benchmark.py --save results.json\n```\n\n---\n\n## Installation\n\n```bash\npip install veltix\n```\n\n**Requirements:** Python 3.10+, no additional dependencies.\n\n---\n\n## Quick Start\n\nThe following example implements a basic echo server and client.\n\n**Server (`server.py`):**\n\n```python\nfrom veltix import Server, ClientInfo, ServerConfig, Response, MessageType, Request, Events\n\nCHAT = MessageType(code=200, name=\"chat\")\n\nconfig = ServerConfig(host=\"0.0.0.0\", port=8080)\nserver = Server(config)\nsender = server.get_sender()\n\n\ndef on_message(client: ClientInfo, response: Response):\n    print(f\"[{client.addr[0]}] {response.content.decode()}\")\n    reply = Request(CHAT, f\"Echo: {response.content.decode()}\".encode())\n    sender.broadcast(reply, server.get_all_clients_sockets())\n\n\nserver.set_callback(Events.ON_RECV, on_message)\nserver.start()\n\ninput(\"Press Enter to stop...\")\nserver.close_all()\n```\n\n**Client (`client.py`):**\n\n```python\nfrom veltix import Client, Response, ClientConfig, MessageType, Request, Events\n\nCHAT = MessageType(code=200, name=\"chat\")\n\nconfig = ClientConfig(server_addr=\"127.0.0.1\", port=8080)\nclient = Client(config)\nsender = client.get_sender()\n\n\ndef on_message(response: Response):\n    print(f\"Server: {response.content.decode()}\")\n\n\nclient.set_callback(Events.ON_RECV, on_message)\nclient.connect()  # Blocks until handshake is complete — safe to send immediately\n\nmsg = Request(CHAT, b\"Hello Server!\")\nsender.send(msg)\n\ninput(\"Press Enter to disconnect...\")\nclient.disconnect()\n```\n\n```bash\npython server.py\npython client.py  # In a separate terminal\n```\n\n---\n\n## Integrated Logger\n\nVeltix includes a production-ready logging system with colorized output, automatic file rotation, and thread safety. It\nfollows a singleton pattern so the same instance is shared across your application.\n\n### Basic Usage\n\n```python\nfrom veltix import Logger, LogLevel\n\nlogger = Logger.get_instance()\n\nlogger.trace(\"Detailed trace information\")\nlogger.debug(\"Debug information\")\nlogger.info(\"General information\")\nlogger.success(\"Operation successful\")\nlogger.warning(\"Warning message\")\nlogger.error(\"Error occurred\")\nlogger.critical(\"Critical failure\")\n```\n\n### Configuration\n\n```python\nfrom veltix import Logger, LoggerConfig, LogLevel\nfrom pathlib import Path\n\nconfig = LoggerConfig(\n    level=LogLevel.DEBUG,\n    enabled=True,\n    use_colors=True,\n    show_timestamp=True,\n    show_caller=True,\n    show_level=True,\n    file_path=Path(\"logs/veltix.log\"),\n    file_rotation_size=10 * 1024 * 1024,  # 10 MB\n    file_backup_count=5,\n    async_write=False,\n    buffer_size=100,\n)\n\nlogger = Logger.get_instance(config)\n```\n\n### Output Format\n\n```\n[14:23:45.123] INFO  [server.py:45] Server listening on 0.0.0.0:8080\n[14:23:46.456] OK    [client.py:78] Successfully connected to server\n[14:23:47.789] DEBUG [sender.py:92] Sent 156 bytes via client (request_id: a3f2...)\n[14:23:48.012] WARN  [network.py:34] Connection issue: ConnectionResetError\n[14:23:49.345] ERROR [request.py:89] Parse error: Hash mismatch — corrupted data\n```\n\n### Available Log Levels\n\n| Level      | Severity |\n|------------|----------|\n| `TRACE`    | 5        |\n| `DEBUG`    | 10       |\n| `INFO`     | 20       |\n| `SUCCESS`  | 25       |\n| `WARNING`  | 30       |\n| `ERROR`    | 40       |\n| `CRITICAL` | 50       |\n\n```python\n# Change level at runtime\nlogger.set_level(LogLevel.WARNING)\n```\n\n---\n\n## Request/Response Pattern\n\n`send_and_wait()` enables synchronous request/response communication over TCP. The client blocks until the server\nreplies with a matching `request_id`, or the timeout elapses.\n\n**Client:**\n\n```python\nfrom veltix import Client, ClientConfig, MessageType, Request\n\nECHO = MessageType(code=201, name=\"echo\")\nclient = Client(ClientConfig(server_addr=\"127.0.0.1\", port=8080))\nclient.connect()\n\nrequest = Request(ECHO, b\"Hello Server!\")\nresponse = client.send_and_wait(request, timeout=5.0)\n\nif response:\n    print(f\"Response: {response.content.decode()}\")\n    print(f\"Latency: {response.latency}ms\")\nelse:\n    print(\"Request timed out\")\n\nclient.disconnect()\n```\n\n**Server:**\n\n```python\nfrom veltix import Server, ServerConfig, MessageType, Request, Events\n\nECHO = MessageType(code=201, name=\"echo\")\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080))\n\n\ndef on_message(client, response):\n    reply = Request(response.type, response.content, request_id=response.request_id)\n    server.get_sender().send(reply, client=client.conn)\n\n\nserver.set_callback(Events.ON_RECV, on_message)\nserver.start()\n\ninput(\"Press Enter to stop...\")\nserver.close_all()\n```\n\n---\n\n## Built-in Ping/Pong\n\nVeltix handles PING/PONG internally. No manual implementation required.\n\n**Client pinging the server:**\n\n```python\nfrom veltix import Client, ClientConfig\n\nclient = Client(ClientConfig(server_addr=\"127.0.0.1\", port=8080))\nclient.connect()\n\nlatency = client.ping_server(timeout=2.0)\nprint(f\"Latency: {latency}ms\" if latency else \"Ping timed out\")\n\nclient.disconnect()\n```\n\n**Server pinging a client:**\n\n```python\nfrom veltix import Server, ServerConfig, Events\n\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080))\n\n\ndef on_connect(client):\n    latency = server.ping_client(client, timeout=2.0)\n    if latency:\n        print(f\"Client {client.addr} latency: {latency}ms\")\n\n\nserver.set_callback(Events.ON_CONNECT, on_connect)\nserver.start()\n\ninput(\"Press Enter to stop...\")\nserver.close_all()\n```\n\n---\n\n## Advanced Features\n\n### Message Routing\n\nUse `@server.route()` and `@client.route()` to handle specific message types directly, without a global `on_recv`.\nRoutes take priority over `on_recv` and run in the thread pool.\n\n```python\nfrom veltix import Server, ServerConfig, MessageType, Response\nfrom veltix.server.client_info import ClientInfo\n\nCHAT = MessageType(code=200, name=\"chat\")\nSTATUS = MessageType(code=201, name=\"status\")\n\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080))\n\n\n@server.route(CHAT)\ndef on_chat(response: Response, client: ClientInfo):\n    print(f\"[{client.addr[0]}] {response.content.decode()}\")\n\n\n@server.route(STATUS)\ndef on_status(response: Response, client: ClientInfo):\n    print(f\"Status from {client.addr[0]}: {response.content.decode()}\")\n\n\nserver.start()\n```\n\n```python\nfrom veltix import Client, ClientConfig, MessageType, Response\n\nCHAT = MessageType(code=200, name=\"chat\")\n\nclient = Client(ClientConfig(server_addr=\"127.0.0.1\", port=8080))\n\n\n@client.route(CHAT)\ndef on_chat(response: Response, client=None):\n    print(f\"Server: {response.content.decode()}\")\n\n\nclient.connect()\n```\n\nRoutes can also be registered programmatically:\n\n```python\nserver.request_handler.register_route(CHAT, on_chat)\nserver.request_handler.unregister_route(CHAT)\n```\n\n### Client Tags\n\nAttach arbitrary metadata to connected clients for tracking, filtering, or access control.\n\n```python\nfrom veltix import Server, ServerConfig, ClientInfo, Events\n\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080))\n\n\ndef on_connect(client: ClientInfo):\n    client.add_tag(\"guest\")\n\n\ndef on_message(client: ClientInfo, response):\n    if client.has_tag(\"guest\"):\n        # Authenticate and upgrade\n        client.remove_tag(\"guest\")\n        client.add_tag(\"authenticated\", value=\"admin\")\n\n    if client.has_all_tags([\"authenticated\", \"admin\"]):\n        print(f\"Admin message from {client.addr[0]}\")\n\n\nserver.set_callback(Events.ON_CONNECT, on_connect)\nserver.set_callback(Events.ON_RECV, on_message)\nserver.start()\n```\n\nAvailable tag methods on `ClientInfo`:\n\n```python\nclient.add_tag(\"authenticated\")  # Add a tag (returns False if already exists)\nclient.add_tag(\"role\", value=\"admin\")  # Add a tag with a value\nclient.has_tag(\"authenticated\")  # Check for a single tag\nclient.has_all_tags([\"auth\", \"admin\"])  # Check all tags are present (AND)\nclient.has_any_tags([\"admin\", \"mod\"])  # Check at least one tag is present (OR)\nclient.get_tag(\"role\")  # Retrieve a tag value\nclient.remove_tag(\"guest\")  # Remove a tag\nclient.clear_tags()  # Remove all tags\n```\n\n### Socket Backend\n\nVeltix abstracts the socket layer behind a `SocketCore` enum. The default is `THREADING` — future versions will add\n`ASYNC` (selectors-based, v1.7.0) and `RUST` (Tokio via PyO3, v3.0.0).\n\n```python\nfrom veltix import ServerConfig, ClientConfig, SocketCore\n\n# Default — one thread per client\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080, socket_core=SocketCore.THREADING))\n\n# Coming in v1.7.0 — selectors-based, same API\n# server = Server(ServerConfig(host=\"0.0.0.0\", port=8080, socket_core=SocketCore.ASYNC))\n```\n\nSwitching backends requires no changes to application code.\n\n### Auto-Reconnect\n\nEnable automatic reconnection by setting `retry` in `ClientConfig`. The `on_disconnect` callback receives a\n`DisconnectState` with full context at every attempt.\n\n```python\nfrom veltix import Client, ClientConfig, Events\nfrom veltix.client.client import DisconnectState\n\nclient = Client(ClientConfig(\n    server_addr=\"127.0.0.1\",\n    port=8080,\n    retry=5,  # number of reconnection attempts\n    retry_delay=1.0,  # seconds between attempts\n))\n\n\ndef on_disconnect(state: DisconnectState):\n    if state.permanent:\n        print(f\"Permanently disconnected — reason: {state.reason.name}\")\n    else:\n        print(f\"Retrying... attempt {state.attempt}/{state.retry_max}\")\n\n\nclient.set_callback(Events.ON_DISCONNECT, on_disconnect)\nclient.connect()\n\n# Cancel retries at any time\nclient.stop_retry()\n\n# Force a new attempt, optionally overriding retry_max\nclient.retry(max_=10)\n```\n\n### Performance Mode\n\n```python\nfrom veltix import ServerConfig, ClientConfig, PerformanceMode\n\n# LOW    — socket timeout 1.0s, minimal CPU\n# BALANCED — socket timeout 0.5s, default\n# HIGH   — socket timeout 0.1s, fast disconnection detection\n\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080, performance_mode=PerformanceMode.HIGH))\nclient = Client(ClientConfig(server_addr=\"127.0.0.1\", port=8080, performance_mode=PerformanceMode.HIGH))\n```\n\n### Buffer Size\n\n```python\nfrom veltix import ServerConfig, ClientConfig, BufferSize\n\n# SMALL  — 1KB  (default)\n# MEDIUM — 8KB\n# LARGE  — 64KB\n# HUGE   — 1MB\n\nserver = Server(ServerConfig(host=\"0.0.0.0\", port=8080, buffer_size=BufferSize.LARGE))\n```\n\n### Custom Message Types\n\nMessage type codes are divided into ranges by convention:\n\n```python\nfrom veltix import MessageType\n\n# System messages (0–199)\nPING = MessageType(0, \"ping\", \"System ping\")\n\n# Application messages (200–499)\nCHAT = MessageType(200, \"chat\", \"Chat message\")\nFILE_TRANSFER = MessageType(201, \"file\", \"File transfer\")\n\n# Plugin messages (500+)\nCUSTOM = MessageType(500, \"plugin\", \"Custom plugin message\")\n```\n\n### Event Callbacks\n\n```python\nfrom veltix import Server, Events\n\nserver = Server(config)\n\nserver.set_callback(Events.ON_CONNECT, lambda client: print(f\"Connected: {client.addr}\"))\nserver.set_callback(Events.ON_RECV, lambda client, msg: print(f\"Message from {client.addr}\"))\nserver.set_callback(Events.ON_DISCONNECT, lambda client: print(f\"Disconnected: {client.addr}\"))\n```\n\n### Client Callbacks\n\n```python\nfrom veltix import Client, ClientConfig, Events\nfrom veltix.client.client import DisconnectState\n\nclient = Client(ClientConfig(server_addr=\"127.0.0.1\", port=8080))\n\nclient.set_callback(Events.ON_CONNECT, lambda: print(\"Connected and handshake complete!\"))\nclient.set_callback(Events.ON_RECV, lambda response: print(response.content.decode()))\nclient.set_callback(Events.ON_DISCONNECT, lambda state: print(f\"Disconnected — permanent={state.permanent}\"))\n\nclient.connect()\n```\n\n### Configuring the Thread Pool\n\n```python\nfrom veltix import ServerConfig, ClientConfig\n\n# Increase workers for high-concurrency workloads with slow callbacks\nserver_config = ServerConfig(host=\"0.0.0.0\", port=8080, max_workers=8)\nclient_config = ClientConfig(server_addr=\"127.0.0.1\", port=8080, max_workers=8)\n```\n\n### Broadcasting\n\n```python\n# Broadcast to all connected clients\nmessage = Request(CHAT, b\"Server announcement\")\nsender.broadcast(message, server.get_all_clients_sockets())\n\n# Broadcast with exclusion\nsender.broadcast(message, server.get_all_clients_sockets(), except_clients=[client.conn])\n```\n\n### Utilities\n\n```python\nfrom veltix import format_bytes, encode_json, decode_json, encode_utf8, decode_utf8\n\n# Human-readable byte formatting\nformat_bytes(148_000)  # \"144.5 KB\"\nformat_bytes(3_000_000)  # \"2.86 MB\"\n\n# JSON helpers\ndata = encode_json({\"key\": \"value\"})  # bytes\nobj = decode_json(data)  # dict\n\n# UTF-8 helpers\nraw = encode_utf8(\"hello\")  # bytes\ntext = decode_utf8(raw)  # str\n```\n\n---\n\n## Comparison\n\n| Feature                | Veltix | `socket` | `asyncio` | Twisted |\n|------------------------|:------:|:--------:|:---------:|:-------:|\n| Simple API             |   ✓    |    ✗     |     ~     |    ✗    |\n| High Performance       |   ✓    |    ~     |     ✓     |    ~    |\n| Zero dependencies      |   ✓    |    ✓     |     ✓     |    ✗    |\n| Custom protocol        |   ✓    |    ✗     |     ✗     |    ~    |\n| Message integrity      |   ✓    |    ✗     |     ✗     |    ✗    |\n| Multi-threading        |   ✓    |    ✗     |     ✗     |    ✓    |\n| Request/Response       |   ✓    |    ✗     |     ~     |    ✓    |\n| Built-in ping/pong     |   ✓    |    ✗     |     ✗     |    ✗    |\n| Automatic handshake    |   ✓    |    ✗     |     ✗     |    ✗    |\n| Message routing        |   ✓    |    ✗     |     ✗     |    ~    |\n| Auto-reconnect         |   ✓    |    ✗     |     ~     |    ✓    |\n| Non-blocking callbacks |   ✓    |    ✗     |     ✓     |    ✓    |\n| Integrated logger      |   ✓    |    ✗     |     ~     |    ✓    |\n| Client tags            |   ✓    |    ✗     |     ✗     |    ✗    |\n| Swappable socket core  |   ✓    |    ✗     |     ✗     |    ✗    |\n\n---\n\n## Roadmap\n\n### v1.4.0 — Handshake \u0026 Callbacks ✓ *(Released March 2026)*\n\n- HELLO/HELLO_ACK handshake with version compatibility check\n- Thread pool for non-blocking callback execution (`CallbackExecutor`)\n- Blocking `connect()` — safe to send immediately after connecting\n- `on_connect` / `on_disconnect` callbacks on Client\n\n### v1.5.0 — Routing \u0026 Reconnect ✓ *(Released March 2026)*\n\n- Decorator-based message routing (`@server.route(MY_TYPE)`, `@client.route(MY_TYPE)`)\n- Auto-reconnect with configurable retry and `DisconnectState` callbacks\n- `PerformanceMode` presets for CPU/reactivity trade-off\n- `BufferSize` presets for common buffer configurations\n\n### v1.6.0 — Socket Abstraction \u0026 Tags ✓ *(Released March 2026)*\n\n- `BaseSocket` Protocol — universal socket interface\n- `ThreadingSocket` — current implementation behind clean abstraction\n- `SocketCore` enum — swappable socket backends with zero API changes\n- `ClientInfo` tags — arbitrary metadata on connected clients\n- `veltix.utils` — encoding helpers and `format_bytes`\n- `max_connection = -1` — unlimited connections by default\n- Benchmark suite with JSON export for community sharing\n\n### v1.7.0 — Selectors *(June 2026)*\n\n- `AsyncSocket` — selectors-based I/O, replaces one-thread-per-client\n- Same API, 4–8× throughput improvement expected\n- Switch via `SocketCore.ASYNC`\n\n### v1.8.0 — Plugin System *(August 2026)*\n\n- `VeltixBasePlugin` — extensible plugin architecture\n- Permission system for plugin event access\n- `server.register_plugin()` / `client.register_plugin()`\n- `server.attach(TYPE, plugin, mode)` — route message types to plugins\n\n### v2.0.0 — Encryption *(September 2026)*\n\n- End-to-end encryption: ChaCha20 + X25519 + Ed25519\n- Automatic key exchange and perfect forward secrecy\n\n### v3.0.0 — Rust Core *(2027)*\n\n- PyO3 bindings\n- 10–100× throughput improvement\n- `SocketCore.RUST`\n\n---\n\n## Migration Guide\n\n### v1.5.0 → v1.6.0\n\nNo breaking changes to public API.\n\n- `ClientInfo` now has tag methods: `add_tag()`, `has_tag()`, `has_all_tags()`, `has_any_tags()`, `get_tag()`,\n  `remove_tag()`, `clear_tags()`\n- `ServerConfig.max_connection` default changed from `2` to `-1` (unlimited)\n- New `ServerConfig` / `ClientConfig` field: `socket_core` (default: `SocketCore.THREADING`)\n- `veltix.utils` now exports encoding helpers and `format_bytes`\n- Benchmark suite now supports `--save results.json`\n\n### v1.4.0 → v1.5.0\n\n**Breaking change:** `on_disconnect` on the client now receives a `DisconnectState` argument.\n\n```python\n# Before (v1.4.0)\nclient.set_callback(Events.ON_DISCONNECT, lambda: print(\"Disconnected\"))\n\n# After (v1.5.0)\nclient.set_callback(Events.ON_DISCONNECT, lambda state: print(f\"Disconnected — permanent={state.permanent}\"))\n```\n\nNew optional fields in `ClientConfig`: `retry`, `retry_delay`, `performance_mode`, `buffer_size`.\n\nNew optional fields in `ServerConfig`: `performance_mode`, `buffer_size`.\n\n### v1.3.0 → v1.4.0\n\nNo breaking changes to public API.\n\n- `on_connect` (server-side) now fires after the handshake is complete — `client.handshake_done` is always `True` when\n  it fires.\n- `connect()` (client-side) now blocks until the handshake is done. It is safe to send messages immediately after it\n  returns.\n- New `ClientConfig` fields: `handshake_timeout` (default: `5.0`), `max_workers` (default: `4`)\n- New `ServerConfig` fields: `handshake_timeout` (default: `5.0`), `max_workers` (default: `4`)\n\n### v1.2.x → v1.3.0\n\nNo breaking changes to public API.\n\n### v1.1.x → v1.2.0\n\n```python\n# Before\nfrom veltix import Bindings\n\nserver.bind(Bindings.ON_RECV, callback)\n\n# After\nfrom veltix import Events\n\nserver.set_callback(Events.ON_RECV, callback)\n```\n\n---\n\n## Examples\n\nFull examples are available in the [`examples/`](examples/) directory:\n\n- **Echo Server** — `send_and_wait()` with request correlation\n- **Chat Server** — Broadcast messaging in under 80 lines\n- **Ping Example** — Bidirectional latency measurement\n\n---\n\n## Security\n\nMessage integrity is enforced via SHA-256 payload verification on every message. If you discover a vulnerability, please\nreport it responsibly through our [Security Policy](SECURITY.md).\n\n---\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request.\n\n- **Bug reports:** [Open an issue](https://github.com/NytroxDev/Veltix/issues)\n- **Discussions:** [Join the Discord](https://discord.gg/NrEjSHtfMp)\n- **Pull requests:** Follow the contribution guide\n\n### Core Team\n\n- **Nytrox** — Creator \u0026 Lead Developer\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n## Links\n\n- **GitHub:** [NytroxDev/Veltix](https://github.com/NytroxDev/Veltix)\n- **PyPI:** [pypi.org/project/veltix](https://pypi.org/project/veltix)\n- **Documentation:** https://nytroxdev.github.io/Veltix/\n- **Discord:** [discord.gg/NrEjSHtfMp](https://discord.gg/NrEjSHtfMp)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnytroxdev%2Fveltix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnytroxdev%2Fveltix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnytroxdev%2Fveltix/lists"}