Go SDK

Connect Go services, workers, and tools to Celeris with goroutines and contexts, and sign credentials on trusted servers.

The Go SDK brings Celeris to Go programs: backend services, workers, command-line tools, and desktop applications. It behaves like the JavaScript SDK, with Go names, context.Context, and returned errors.

Each channel connection automatically joins a segment named default. Access it with channel.DefaultSegment(). That stream does not need an explicit subscription. Use additional named segments when you need separate topics. Messaging explains the listener and permission setup.

Two modules

github.com/useceleris/sdk-go-client (package celeris) manages connections, messages, subscriptions, and presence.
github.com/useceleris/sdk-go-server (package celerisserver) signs credentials from your application's access decisions. It runs on trusted servers only.

go get github.com/useceleris/sdk-go-client
go get github.com/useceleris/sdk-go-server

Add the server module only where the signing secret can live. It depends on the client for the credential types and errors only. The client does not include signing facilities.

Both modules need Go 1.27 or newer. The client's only runtime dependency is github.com/coder/websocket. The server signs with the standard library. The guides import them as celeris "github.com/useceleris/sdk-go-client" and celerisserver "github.com/useceleris/sdk-go-server".

Follow the guides

Connection and lifecycle: obtain credentials, connect, observe state, recover, and clean up.
Messaging: subscribe, publish, receive, and understand delivery.
Payload formats: text, JSON, and custom serializers.
Presence: list connections and watch presence events.
Errors and troubleshooting: handle failures where the SDK reports them.
Server-side usage: sign credentials, and connect from a trusted backend.

Read Reconnection and Recovery for the shared explanation of retries, replay, and application reconciliation. Exact signatures live in the Go client API and Go server API.

Goroutines and contexts in brief

A client, its channels, and their segments are safe for concurrent use from any goroutine.
Listeners are plain functions. The SDK runs them one at a time, in the order the events happened, and never under an SDK lock. A listener can call Publish, Subscribe, Close, or Connect. The events those calls cause follow after the listener returns. Call PresenceList from a goroutine of your own. Inside a listener, that call always times out.
ctx bounds only the call that receives it. A cancellation abandons a Connect, withdraws a Publish that the SDK did not write yet, or ends a PresenceList. It never closes the channel.

Work with SDK values

Timestamps delivered with messages, notices, and presence are int64 Unix-millisecond values. Convert one with time.UnixMilli(timestamp). Presence counts are int32 values. Timeouts and replay lookbacks are time.Duration values. Payloads are []byte values.

Vocabulary

Term	Meaning
Channel reference	Name of a communication space inside your application
Channel	Owns one connection once connected
Segment	Named stream carried over that channel's socket
Listener	Your function for an event. Registration returns a removal function
Subscription	Held interest in messages or presence. Release it with `Cancel()`
Credential provider	Your function that obtains fresh signed access for each connection attempt

Changelog Connection and Lifecycle