Metadata-Version: 2.4
Name: serversocket
Version: 0.1.2
Summary: A modern full-duplex communication protocol with multiplexing and backpressure
Author-email: CookieX-a <i-tec-i@outlook.com>
License: MIT
Keywords: websocket,realtime,networking,multiplexing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8
Requires-Dist: redis>=4.5
Requires-Dist: cryptography>=41.0
Dynamic: license-file

# ServerSocket

A modern full-duplex communication protocol and Python library that fixes the pain points of native WebSocket: **multiplexing, backpressure, automatic reconnection, secure authentication.**

## Features

- Binary frame protocol with message fragmentation up to 16 MB
- Multiple independent streams over a single TCP connection
- Sliding‑window flow control – await send() blocks automatically
- Challenge‑response authentication, token never appears in the URL
- Heartbeat & automatic reconnection with exponential backoff
- Graceful shutdown (GOAWAY) and connection migration (FD passing)
- Stateless gateway for easy FaaS / Serverless integration
- Pure Python, supports Python 3.8+

## Installation

```bash
pip install serversocket
```

Quick Start

Server

```python
from serversocket import ServerSocket

async def auth(conn, client_resp, challenge):
    import hmac, hashlib
    expected = hmac.new(b"mysecret", challenge, hashlib.sha256).digest()
    return hmac.compare_digest(client_resp, expected)

server = ServerSocket(authenticator=auth)

@server.on_stream("echo")
async def echo_handler(ch):
    async for msg in ch:
        print(f"Received: {msg.decode()}")
        await ch.send(msg)

import asyncio
asyncio.run(server.serve())
```

Client

```python
from serversocket import connect

async def main():
    client = await connect("ss://localhost:8765", token="mysecret")
    echo = await client.open_stream("echo")
    await echo.send(b"Hello!")
    resp = await echo.recv()
    print(resp.decode())
    await client.goaway()

import asyncio
asyncio.run(main())
```

CLI

```bash
serversocket-cli ss://localhost:8765 -t mysecret -n echo -d "ping"
```

Examples

Runnable demos are in the examples/ directory:

· examples/echo_server.py
· examples/echo_client.py

Documentation

· Protocol specification: docs/protocol.md
· API overview: docs/api.md

License

MIT © CookieX-a
