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

2.6 KiB

Raw Blame History

Go SDK

The Go SDK provides a native QUIC client with Cap'n Proto serialization.

Location: sdks/go/

Installation

go get quicproquo.dev/sdk/go

Quick Start

package main

import (
    "context"
    "fmt"
    "quicproquo.dev/sdk/go/qpq"
)

func main() {
    ctx := context.Background()

    client, err := qpq.Connect(ctx, qpq.Options{
        Addr:               "127.0.0.1:5001",
        InsecureSkipVerify: true, // dev only
    })
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // Health check
    status, _ := client.Health(ctx)
    fmt.Println("Server:", status)

    // OPAQUE login (requires external OPAQUE library)
    resp, _ := client.LoginStart(ctx, "alice", opaqueRequest)
    // ... process resp with OPAQUE library ...
    client.LoginFinish(ctx, "alice", finalization, identityKey)

    // Resolve user
    key, _ := client.ResolveUser(ctx, "bob")

    // Create channel
    chID, wasNew, _ := client.CreateChannel(ctx, key)

    // Send
    seq, _ := client.Send(ctx, key, []byte("hello"))

    // Receive (long-poll)
    msgs, _ := client.ReceiveWait(ctx, myKey, 5000)
    for _, m := range msgs {
        fmt.Printf("[%d] %s\n", m.Seq, m.Data)
    }
}

API

Method	Description
`qpq.Connect(ctx, opts)`	Connect to server
`client.Close()`	Disconnect
`client.Health(ctx)`	Health check
`client.SetSessionToken(token)`	Set pre-existing token
`client.RegisterStart(ctx, username, request)`	OPAQUE register start
`client.RegisterFinish(ctx, username, upload, key)`	OPAQUE register finish
`client.LoginStart(ctx, username, request)`	OPAQUE login start
`client.LoginFinish(ctx, username, finalization, key)`	OPAQUE login finish
`client.ResolveUser(ctx, username)`	Look up identity key
`client.CreateChannel(ctx, peerKey)`	Create DM channel
`client.Send(ctx, recipientKey, payload)`	Send message
`client.SendWithTTL(ctx, recipientKey, payload, ttl)`	Disappearing message
`client.Receive(ctx, recipientKey)`	Fetch messages
`client.ReceiveWait(ctx, recipientKey, timeoutMs)`	Long-poll
`client.DeleteAccount(ctx)`	Delete account

Structure

qpq/ -- High-level client API
transport/ -- QUIC + TLS 1.3 transport, Cap'n Proto RPC framing
proto/node/ -- Generated Cap'n Proto Go types
cmd/example/ -- Example usage

Transport

The Go SDK uses quic-go for QUIC transport and capnproto.org/go/capnp/v3 for Cap'n Proto RPC. The transport layer handles:

TLS 1.3 with configurable CA certificates
Cap'n Proto RPC bootstrap over QUIC streams
Automatic connection management

2.6 KiB Raw Blame History