Files

Christian Nennemann cbb76af6b1 docs(sdk): add comprehensive SDK documentation and wire format reference

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.

2026-03-04 20:55:24 +01:00

3.6 KiB

Raw Blame History

Python SDK

The Python SDK provides both async QUIC transport and synchronous Rust FFI backends.

Location: sdks/python/

Installation

pip install quicproquo

Transport Backends

Async QUIC (pure Python)

Uses aioquic for native QUIC transport with the v2 protobuf wire format. No Rust build required.

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.

cargo build --release -p quicproquo-ffi

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

3.6 KiB Raw Blame History