Networked access

Go client

Call registered reads and writes from Go through generated structs, keep a query result current, and route calls across a replication group.

github.com/assetcorp/sirannon-db/packages/go connects a Go 1.26 or later program to a Sirannon server over WebSocket or HTTP. The client returns every integer in a row as an int64 and every BLOB as a []byte, so your program reads a value beyond 2^53 exactly as SQLite stores it. Its one dependency outside the standard library is github.com/coder/websocket.

Build main.go step by step against the server.ts from registered operations, which serves the orders database and authenticates every request as the account u_maria.

Install the module

Create a module in a go folder beside operations.ts and server.ts, and add the client to it. The examples on this page use version 0.1.0 of the client.

cd go
go mod init example.com/orders
go get github.com/assetcorp/sirannon-db/packages/go@v0.1.0

Generate the references from the server's operations

The server refuses SQL unless you start it with acceptSql: true, so a Go program calls the operations that the server registers. sirannon-codegen writes a typed reference for each of them. In the workspace that holds operations.ts and server.ts, write the references into an operations package inside the module:

pnpm exec sirannon-codegen --registry ./operations.ts --go ./go/operations/operations.go --go-package operations

The 0.4.1 generator writes this complete file from that registry:

operations/operations.go
// Code generated by sirannon-codegen. DO NOT EDIT.
 
package operations
 
import sirannon "github.com/assetcorp/sirannon-db/packages/go"
 
const RegistryDigest = "8848da8cd5d9537501dbf824f7bdaf25a64c3fec419376367088c832787c529d"
 
type OrdersMyOrdersRow struct {
	ID     any `json:"id"`
	Total  any `json:"total"`
	Status any `json:"status"`
}
 
type OrdersOrdersByStatusArgs struct {
	Status any `json:"status"`
}
 
type OrdersOrdersByStatusRow struct {
	ID     any `json:"id"`
	Total  any `json:"total"`
	Status any `json:"status"`
}
 
type OrdersPlaceOrderArgs struct {
	Total any `json:"total"`
}
 
var (
	OrdersMyOrders       = sirannon.ReadRef[sirannon.NoArgs, OrdersMyOrdersRow]{Name: "myOrders"}
	OrdersOrdersByStatus = sirannon.ReadRef[OrdersOrdersByStatusArgs, OrdersOrdersByStatusRow]{Name: "ordersByStatus"}
	OrdersPlaceOrder     = sirannon.WriteRef[OrdersPlaceOrderArgs]{Name: "placeOrder"}
)

The generator writes each operation as a sirannon.ReadRef or a sirannon.WriteRef variable, whose name joins the database and the operation in PascalCase. It writes the arguments and rows of each operation as structs with JSON tags, and an operation that takes no caller arguments, such as myOrders, takes sirannon.NoArgs. Every field takes the type any, because the registry declares the names of the arguments and columns without their types. When an argument has a name that a JSON tag cannot hold, the generator types the arguments of that operation as a map[string]any, and it types the rows as a sirannon.Row when a column has such a name.

A Go project that has no copy of the server's source can generate the same file from a manifest. Add --manifest when you generate the references in the server's workspace, and commit the manifest that the generator writes:

pnpm exec sirannon-codegen --registry ./operations.ts --go ./go/operations/operations.go --go-package operations --manifest ./operations.json

The Go project can then generate its references from that manifest through pnpm, without a Node project:

pnpm --package=@delali/sirannon-db@0.4.1 dlx sirannon-codegen --from-manifest ./operations.json --go ./operations/operations.go --go-package operations

Read and write through the references

Delete the data folder beside server.ts and start the server with a secret SIRANNON_TOKEN, so that the database holds only the three orders that server.ts inserts. Save this complete main.go in the go folder and start it with go run . and the same SIRANNON_TOKEN:

main.go
package main
 
import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"
 
	sirannon "github.com/assetcorp/sirannon-db/packages/go"
 
	"example.com/orders/operations"
)
 
func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}
 
func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	if token == "" {
		return errors.New("set SIRANNON_TOKEN to the application credential")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
 
	client, err := sirannon.New("http://127.0.0.1:9876", sirannon.Options{
		Headers: map[string]string{"Authorization": "Bearer " + token},
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}
 
	pending, err := sirannon.Query(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", pending)
	results, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 2750})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", results)
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)
	return nil
}

The server fills ownerId with u_maria on every call, so both reads leave out order 2, which u_ravi owns. sirannon.Execute returns one ExecuteResult for each statement of the write, which gives placeOrder one result for its insert and one for its counter update. The compiler refuses an argument or a column that the generated struct lacks, so a misspelt field fails go build before the program sends anything.

The client returns the error of a failed write without sending the write again. When the reply to a write goes missing, the server can still commit the write, so check the orders before your program repeats it.

Keep the pending orders current

sirannon.Live opens a live query on a registered read and returns once the server confirms it. Each time the table changes, the server sends edits to those rows. Once the client applies an edit, in the order in which the server sends them, it calls every listener with a LiveUpdate. Delete the data folder and start the server again, then start the extended file:

main.go
package main
 
import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"
 
	sirannon "github.com/assetcorp/sirannon-db/packages/go"
 
	"example.com/orders/operations"
)
 
func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}
 
func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	if token == "" {
		return errors.New("set SIRANNON_TOKEN to the application credential")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
 
	client, err := sirannon.New("http://127.0.0.1:9876", sirannon.Options{
		Headers: map[string]string{"Authorization": "Bearer " + token},
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}
 
	pending, err := sirannon.Query(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", pending)
	results, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 2750})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", results)
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)
 
	live, err := sirannon.Live(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"}) 
	if err != nil {
		return err
	}
	defer live.Close(ctx)
	fmt.Println("live", orderIDs(live.State().Rows))
	updated := make(chan struct{}, 1)
	stop := live.Subscribe(func(update sirannon.LiveUpdate[operations.OrdersOrdersByStatusRow]) {
		if update.Kind == sirannon.LiveUpdateOps {
			fmt.Println("live", orderIDs(update.State.Rows))
			select {
			case updated <- struct{}{}:
			default:
			}
		}
	})
	defer stop()
	if _, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 6400}); err != nil {
		return err
	}
	select {
	case <-updated:
	case <-ctx.Done():
		return ctx.Err()
	}
	return nil
}
 
func orderIDs(rows []operations.OrdersOrdersByStatusRow) []any { 
	ids := make([]any, 0, len(rows))
	for _, row := range rows {
		ids = append(ids, row.ID)
	}
	return ids
}

update.Kind holds LiveUpdateRows for a fresh result, LiveUpdateOps for edits, LiveUpdateRevalidating while the connection is down, and LiveUpdateError for a failure, so the listener prints only after an edit. The client calls listeners one at a time on a separate goroutine, so the program waits on a channel before it closes the query. After a reconnection, the client subscribes again and replaces the rows with a fresh result. When a listener panics, the client recovers and passes the panic to the OnError handler as a *sirannon.CallbackPanic.

Live queries and table subscriptions need the WebSocket transport, which the client uses unless you set Options.Transport to sirannon.TransportHTTP. Over HTTP, both fail with TRANSPORT_ERROR.

Handle what the server refuses

The client returns every failure as a *sirannon.Error, whose Code, Message, Details, and Status hold what the server sent. errors.As reaches all four fields, and sirannon.ErrorCode(err) returns the code alone. Delete the data folder and start the server again, then start the file with two refused calls at its end:

main.go
package main
 
import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"
 
	sirannon "github.com/assetcorp/sirannon-db/packages/go"
 
	"example.com/orders/operations"
)
 
func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}
 
func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	if token == "" {
		return errors.New("set SIRANNON_TOKEN to the application credential")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
 
	client, err := sirannon.New("http://127.0.0.1:9876", sirannon.Options{
		Headers: map[string]string{"Authorization": "Bearer " + token},
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}
 
	pending, err := sirannon.Query(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", pending)
	results, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 2750})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", results)
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)
 
	live, err := sirannon.Live(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	defer live.Close(ctx)
	fmt.Println("live", orderIDs(live.State().Rows))
	updated := make(chan struct{}, 1)
	stop := live.Subscribe(func(update sirannon.LiveUpdate[operations.OrdersOrdersByStatusRow]) {
		if update.Kind == sirannon.LiveUpdateOps {
			fmt.Println("live", orderIDs(update.State.Rows))
			select {
			case updated <- struct{}{}:
			default:
			}
		}
	})
	defer stop()
	if _, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 6400}); err != nil {
		return err
	}
	select {
	case <-updated:
	case <-ctx.Done():
		return ctx.Err()
	}
 
	_, err = db.Query(ctx, "SELECT id, total FROM orders", nil) 
	fmt.Println(err)
	_, err = db.On("orders").Subscribe(ctx, func(event sirannon.ChangeEvent) {})
	var refusal *sirannon.Error
	if errors.As(err, &refusal) {
		fmt.Println(refusal.Code, refusal.Status)
	}
	return nil
}
 
func orderIDs(rows []operations.OrdersOrdersByStatusRow) []any {
	ids := make([]any, 0, len(rows))
	for _, row := range rows {
		ids = append(ids, row.ID)
	}
	return ids
}

The client refuses the statement itself, because the server's capabilities leave out query.sql, so the client sends no request for it. The server refuses the table subscription, since a subscription to a whole table can deliver rows that no registered read returns. Status holds 0, because the server sends that refusal over WebSocket, where no HTTP answer holds a status.

A server that you start with acceptSql: true, or with an onBeforeSubscribe hook that authorises each table and filter, accepts a call such as db.On("orders").Filter(map[string]any{"status": "pending"}).Subscribe(ctx, callback, sirannon.OnReset(reload)). Such a subscription delivers each change once, in the order of the server's change log. While 1024 callbacks wait, the client pauses reading from the connection until they catch up. After a dropped connection, the client reconnects every Options.ReconnectInterval and resumes from the last change that it delivered. When the server holds no history after that change, the client calls the OnReset handler, so read the table again in that handler. Subscription resumption describes the cursor that the server keeps.

The sirannon.Code constants, such as CodeConnectionError, CodeTimeout, and CodeTransportError, hold the codes that the client returns when it fails before the server answers. Error codes lists the codes that the server sends.

Route calls across a replication group

sirannon.NewTopology returns a client that sends writes to the primary of a replication group and sends reads to the node that ReadPreference selects. Save this complete replicas/main.go in the go folder, set SIRANNON_PRIMARY_URL and a comma-separated SIRANNON_REPLICA_URLS to the addresses of your nodes, and start it with go run ./replicas:

replicas/main.go
package main
 
import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"
	"time"
 
	sirannon "github.com/assetcorp/sirannon-db/packages/go"
 
	"example.com/orders/operations"
)
 
func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}
 
func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	primary := os.Getenv("SIRANNON_PRIMARY_URL")
	replicas := os.Getenv("SIRANNON_REPLICA_URLS")
	if token == "" || primary == "" || replicas == "" {
		return errors.New("set SIRANNON_TOKEN, SIRANNON_PRIMARY_URL, and SIRANNON_REPLICA_URLS")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
 
	client, err := sirannon.NewTopology(sirannon.TopologyOptions{
		Options:        sirannon.Options{Headers: map[string]string{"Authorization": "Bearer " + token}},
		Primary:        primary,
		Replicas:       strings.Split(replicas, ","),
		ReadPreference: sirannon.ReadFromReplica,
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}
 
	if _, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 1800}); err != nil {
		return err
	}
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)
	return nil
}

This example needs a replication group, so it has no fixed result panel. The program prints the orders of u_maria from a replica, which can answer before it holds the new order.

ReadPreference takes ReadFromPrimary, ReadFromReplica, or ReadFromNearest, and with ReadFromNearest the client measures the latency of each node. With Discovery: sirannon.DiscoveryCoordinator and a list of Endpoints, the client fetches the group's routing from GET /db/{id}/cluster and sends calls to the new primary after a failover. When the client cannot reach the node for a read, it sets that node aside for five seconds and sends the read once more to another node. A write reaches the server twice only when your program sends it twice, because the client returns the error of a failed write without sending it again. Topology-aware routing describes the same routing for the TypeScript client.

Call any route of the server

*sirannon.Client has a typed method for every route that Sirannon describes in openapi.json, such as GetCapabilities, GetHealth, and GetBackupStatus. Each method takes the route's path parameters and request body, and it returns a model of the route's response. The client has no device sync controller, so a Go program that syncs a device calls the device sync routes itself.

Client options

sirannon.New takes the server's address and a sirannon.Options, whose unset fields take these defaults.

FieldDefaultBehaviour
TransportTransportWebSocketThe client also accepts TransportHTTP, which serves every call except live queries and subscriptions.
HeadersnoneThe client sends these headers with every HTTP request and WebSocket handshake.
WebSocketProtocolsnoneThe client offers these subprotocols after sirannon.v1.
DisableAutoReconnectfalseWith true, the client leaves a dropped WebSocket connection closed.
ReconnectIntervalone secondThe client waits this long before it reconnects a dropped WebSocket connection.
RequestTimeout30 secondsThe client waits this long for each call and handshake, and with NoTimeout it waits for as long as the context of the call allows.
MaxResponseBytes64 MiBThe client refuses a larger answer, and with NoResponseLimit it reads whatever the server sends.
HTTPClienta client that follows no redirectsThe client sends every HTTP request and WebSocket handshake through this *http.Client.

sirannon.TopologyOptions embeds Options and adds Endpoints, Primary, Replicas, ReadPreference, Discovery, and ReadConcern. When the server closes a WebSocket connection with 4401 or 4403, the client stops reconnecting and passes that error to the OnError handler, because the same credential fails every later try. The Python client offers the same calls and routing.