Christian Nennemann
cbb76af6b1
Covers all official SDKs (Rust, Go, Python, TypeScript, C FFI), the v2 wire format with method ID tables, authentication flow, and a build-your-own-SDK guide with implementation checklist.
121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# Python SDK
|
|
|
|
The Python SDK provides both async QUIC transport and synchronous Rust FFI backends.
|
|
|
|
Location: `sdks/python/`
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
pip install quicproquo
|
|
```
|
|
|
|
## Transport Backends
|
|
|
|
### Async QUIC (pure Python)
|
|
|
|
Uses [aioquic](https://github.com/aiortc/aioquic) for native QUIC transport with the v2 protobuf wire format. No Rust build required.
|
|
|
|
```python
|
|
import asyncio
|
|
from quicproquo import QpqClient, ConnectOptions
|
|
|
|
async def main():
|
|
client = await QpqClient.connect(ConnectOptions(
|
|
addr="127.0.0.1:5001",
|
|
ca_cert_path="ca.pem",
|
|
))
|
|
|
|
health = await client.health()
|
|
print(f"Server: {health.status}")
|
|
|
|
# OPAQUE auth (requires external OPAQUE library)
|
|
resp = await client.login_start("alice", opaque_request)
|
|
token = await client.login_finish("alice", finalization, identity_key)
|
|
|
|
# Messaging
|
|
key, proof = await client.resolve_user("bob")
|
|
seq, proof = await client.send(key, b"hello")
|
|
messages = await client.receive_wait(my_key, timeout_ms=5000)
|
|
|
|
await client.close()
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
### Rust FFI (synchronous)
|
|
|
|
Wraps `libquicproquo_ffi` via CFFI for full Rust crypto stack at native speed.
|
|
|
|
```sh
|
|
cargo build --release -p quicproquo-ffi
|
|
```
|
|
|
|
```python
|
|
from quicproquo import QpqClient, ConnectOptions
|
|
|
|
client = QpqClient.connect_ffi(ConnectOptions(
|
|
addr="127.0.0.1:5001",
|
|
ca_cert_path="ca.pem",
|
|
))
|
|
|
|
client.ffi_login("alice", "password123")
|
|
client.ffi_send("bob", b"hello")
|
|
messages = client.ffi_receive(timeout_ms=5000)
|
|
client.close_sync()
|
|
```
|
|
|
|
## Async API (QUIC)
|
|
|
|
| Method | Description |
|
|
|---|---|
|
|
| `QpqClient.connect(opts)` | Connect via QUIC |
|
|
| `client.health()` | Health check |
|
|
| `client.register_start(username, request)` | OPAQUE register start |
|
|
| `client.register_finish(username, upload, key)` | OPAQUE register finish |
|
|
| `client.login_start(username, request)` | OPAQUE login start |
|
|
| `client.login_finish(username, finalization, key)` | OPAQUE login finish |
|
|
| `client.resolve_user(username)` | Look up identity key |
|
|
| `client.resolve_identity(key)` | Reverse look up username |
|
|
| `client.create_channel(peer_key)` | Create DM channel |
|
|
| `client.send(recipient_key, payload)` | Send message |
|
|
| `client.receive(recipient_key)` | Fetch messages |
|
|
| `client.receive_wait(recipient_key, timeout_ms=5000)` | Long-poll |
|
|
| `client.ack(recipient_key, seq_up_to)` | Acknowledge messages |
|
|
| `client.upload_key_package(key, package)` | Upload MLS key package |
|
|
| `client.fetch_key_package(key)` | Fetch MLS key package |
|
|
| `client.upload_hybrid_key(key, hybrid_pk)` | Upload hybrid key |
|
|
| `client.fetch_hybrid_key(key)` | Fetch hybrid key |
|
|
| `client.delete_account()` | Delete account |
|
|
| `client.close()` | Disconnect (async) |
|
|
|
|
## FFI API (synchronous)
|
|
|
|
| Method | Description |
|
|
|---|---|
|
|
| `QpqClient.connect_ffi(opts)` | Connect via Rust FFI |
|
|
| `client.ffi_login(username, password)` | Full OPAQUE login |
|
|
| `client.ffi_send(recipient, message)` | Send by username |
|
|
| `client.ffi_receive(timeout_ms=5000)` | Receive messages |
|
|
| `client.close_sync()` | Disconnect (sync) |
|
|
|
|
## Exceptions
|
|
|
|
| Exception | Description |
|
|
|---|---|
|
|
| `QpqError` | Base exception for all SDK errors |
|
|
| `AuthError` | OPAQUE authentication failed |
|
|
| `TimeoutError` | Operation timed out |
|
|
| `ConnectionError` | Server connection failure |
|
|
|
|
## Structure
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `quicproquo/client.py` | High-level client API |
|
|
| `quicproquo/transport.py` | QUIC transport (aioquic) |
|
|
| `quicproquo/ffi.py` | Rust FFI transport (CFFI) |
|
|
| `quicproquo/proto.py` | Protobuf encode/decode |
|
|
| `quicproquo/wire.py` | v2 wire format framing |
|
|
| `quicproquo/types.py` | Data types and exceptions |
|