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.
96 lines
2.6 KiB
Markdown
96 lines
2.6 KiB
Markdown
# Go SDK
|
|
|
|
The Go SDK provides a native QUIC client with Cap'n Proto serialization.
|
|
|
|
Location: `sdks/go/`
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
go get quicproquo.dev/sdk/go
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```go
|
|
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
|