docs: comprehensive update for sprints 1-9

Update README, ROADMAP, and mdBook to reflect all sprint deliverables: rich messaging, file transfer, disappearing messages, Go/TypeScript SDKs, C FFI, mesh networking (identity, store-and-forward, broadcast), and security hardening. Add 6 new mdBook guides (REPL reference, Go SDK, TypeScript SDK + browser demo, rich messaging, file transfer, mesh networking). Check off 16 completed ROADMAP items across phases 3-9.
2026-03-04 02:10:20 +01:00
parent 4454458e38
commit 4694a3098b
13 changed files with 1084 additions and 134 deletions
--- a/docs/src/getting-started/go-sdk.md
+++ b/docs/src/getting-started/go-sdk.md
@@ -0,0 +1,152 @@
+# Go SDK
+
+The Go SDK (`sdks/go/`) provides a native QUIC + Cap'n Proto client for
+quicproquo, giving Go applications full access to the messaging API without
+any HTTP translation layer.
+
+## Prerequisites
+
+- Go 1.21+
+- A running qpq server
+
+## Installation
+
+```go
+import "quicproquo.dev/sdk/go/qpq"
+```
+
+## Quick start
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "quicproquo.dev/sdk/go/qpq"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Connect to the server
+    client, err := qpq.Connect(ctx, qpq.Options{
+        Addr:               "127.0.0.1:7000",
+        InsecureSkipVerify: true, // development only
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Health check
+    status, err := client.Health(ctx)
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println("Server status:", status)
+
+    // OPAQUE authentication
+    if err := client.LoginStart(ctx, "alice", "secret"); err != nil {
+        log.Fatal(err)
+    }
+    if err := client.LoginFinish(ctx); err != nil {
+        log.Fatal(err)
+    }
+
+    // Resolve a peer
+    peerKey, err := client.ResolveUser(ctx, "bob")
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Create a DM channel
+    channelID, err := client.CreateChannel(ctx, peerKey)
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println("Channel:", channelID)
+
+    // Send a message
+    if err := client.Send(ctx, peerKey, []byte("Hello from Go!")); err != nil {
+        log.Fatal(err)
+    }
+
+    // Send a disappearing message (1 hour TTL)
+    if err := client.SendWithTTL(ctx, peerKey, []byte("This vanishes"), 3600); err != nil {
+        log.Fatal(err)
+    }
+
+    // Receive messages
+    msgs, err := client.Receive(ctx, peerKey)
+    if err != nil {
+        log.Fatal(err)
+    }
+    for _, m := range msgs {
+        fmt.Println("Received:", string(m))
+    }
+}
+```
+
+## API reference
+
+| Method | Description |
+|---|---|
+| `Connect(ctx, opts)` | Establish QUIC connection to server |
+| `Health(ctx)` | Server readiness probe |
+| `RegisterStart/Finish(ctx, user, pass)` | OPAQUE registration |
+| `LoginStart/Finish(ctx, user, pass)` | OPAQUE login |
+| `ResolveUser(ctx, username)` | Look up a user's identity key |
+| `CreateChannel(ctx, peerKey)` | Create a 1:1 DM channel |
+| `Send(ctx, recipientKey, payload)` | Send a message |
+| `SendWithTTL(ctx, recipientKey, payload, ttlSecs)` | Send a disappearing message |
+| `Receive(ctx, recipientKey)` | Fetch queued messages |
+| `ReceiveWait(ctx, recipientKey, timeoutMs)` | Long-poll for messages (default 5 s timeout) |
+| `DeleteAccount(ctx)` | Delete the authenticated account |
+
+## Transport details
+
+- **Protocol:** QUIC with TLS 1.3 via `quic-go`
+- **ALPN:** `"capnp"` (same as the Rust client)
+- **Serialisation:** Cap'n Proto RPC over a single bidirectional stream
+- **Idle timeout:** 300 seconds
+- **Auth:** Session token stored in client, sent with every RPC via the `Auth` struct
+
+## Connection options
+
+```go
+type Options struct {
+    Addr               string // "host:port"
+    CACertPath         string // path to CA cert (DER format)
+    InsecureSkipVerify bool   // skip TLS verification (dev only!)
+    Token              string // pre-existing auth token (optional)
+}
+```
+
+## Project structure
+
+```
+sdks/go/
+├── proto/         # Generated Cap'n Proto types from node.capnp
+├── transport/     # QUIC transport layer (quic-go + TLS 1.3)
+├── qpq/           # High-level client API (QpqClient)
+├── cmd/example/   # Example CLI program
+├── go.mod
+└── README.md
+```
+
+## Running the example
+
+```bash
+cd sdks/go/cmd/example
+go run main.go
+```
+
+## Regenerating proto types
+
+If you modify `schemas/node.capnp`, regenerate the Go types:
+
+```bash
+capnp compile -ogo sdks/go/proto/node.capnp
+```