Overview

FastSocket is a Python library designed for rapid development and production use. It supports multi-connection handling out of the box and offers three security modes — plain, RSA, and a hybrid TLS-like mode (RSA key exchange + AES-256-GCM + HMAC) — without the complexity of managing raw sockets or TLS certificates.

Features

Installation

pip install fastsocket

Requirements: Python 3.8+, pycryptodome (installed automatically).

To install from source:

git clone https://github.com/giulicrenna/FastSocket.git
cd FastSocket
pip install -e .

Quick Start

TCP Server

from fastsocket import FastSocketServer, SocketConfig, Queue

def handle_messages(messages: Queue):
    while not messages.empty():
        msg, addr = messages.get()
        print(f"[{addr}] {msg}")
        server.send_msg_stream(f"Echo: {msg}")

config = SocketConfig(host="localhost", port=8080)
server = FastSocketServer(config)
server.on_new_message(handle_messages)
server.start()

# Graceful shutdown
# server.stop()

TCP Client

from fastsocket import FastSocketClient, SocketConfig

def on_message(msg: str):
    print("Server:", msg)

# Auto-reconnect and disconnect callback (new in 2.1.0)
client = FastSocketClient(
    SocketConfig(host="localhost", port=8080),
    auto_reconnect=True,
    reconnect_delay=2.0,
)
client.on_new_message(on_message)
client.on_disconnect(lambda: print("Connection lost, reconnecting…"))
client.start()
client.send_to_server("Hello FastSocket")

# Graceful shutdown
# client.stop()

Hybrid TLS Mode (RSA + AES-256-GCM + HMAC)

from fastsocket import TLSSocketServer, TLSSocketClient, SocketConfig

# Server
server = TLSSocketServer(SocketConfig(host="localhost", port=9443), shared_secret="strong-secret")
server.on_new_message(lambda q: print(q.get()))
server.start()

# Client (auto_reconnect supported)
client = TLSSocketClient(
    SocketConfig(host="localhost", port=9443),
    shared_secret="strong-secret",
    auto_reconnect=True,
)
client.on_new_message(lambda msg: print(msg))
client.on_disconnect(lambda: print("TLS connection lost"))
client.start()

UDP

from fastsocket import FastSocketUDPServer, SocketConfig
import socket

config = SocketConfig(host="0.0.0.0", port=9000, type=socket.SOCK_DGRAM)
server = FastSocketUDPServer(config, enable_broadcast=True)
server.start()

Available Classes

Servers

All servers expose stop() for graceful shutdown.

Clients

FastSocketClient and TLSSocketClient support on_disconnect and auto_reconnect. All clients expose stop() / close().

Utilities

What's new in 2.1.1

• Package renamed — pip install fastsocket (was FastSocket). Import also updated: from fastsocket import ....

What's new in 2.1.0

• Busy-loop fix — message handler threads now sleep when queues are idle instead of spinning at 100% CPU.
• stop() API — every server and client can now be shut down cleanly.
• on_disconnect + auto-reconnect — TCP clients notify user code on disconnect and can reconnect automatically (including full TLS handshake re-negotiation).
• Race condition fix — UDP server dict access is now protected by a lock.
• RSA size guard — oversized messages raise BadEncryptionInput instead of a cryptic pycryptodome error.
• Performance — FileTransfer uses framing for metadata (no more byte-by-byte reads); ChunkManager uses bytearray to avoid O(n²) copies.

See the full Changelog for details.

Documentation

Full documentation is available at giulicrenna.github.io/FastSocket, including:

• Getting Started — Installation & Quickstart
• TCP Guide
• UDP Guide
• Secure (RSA) Guide
• Hybrid TLS Guide
• ChunkManager Guide
• File Transfer Guide
• Error Handling
• API Reference

Roadmap

• Native TLS/SSL support (via Python ssl stdlib)
• async/await API (asyncio)
• Message compression (zlib / lz4)
• Exportable metrics (Prometheus / JSON)
• WebSocket support
• Channel multiplexing over a single connection
• Bindings for other languages (Go, Rust)

See the full Roadmap for details.

Contributing

Pull requests are welcome. Before submitting, make sure tests pass and code follows PEP 8.

git clone https://github.com/giulicrenna/FastSocket.git
cd FastSocket
pip install -e ".[dev]"
pytest tests/

See Contributing Guide for full instructions.

Contact

Author: Giuliano Crenna
Email: giulicrenna@gmail.com
GitHub: github.com/giulicrenna

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See the LICENSE file for details.