Go SDK for S2

The Go SDK provides ergonomic wrappers and utilities to interact with the S2 API.

Getting started

1. Create a new Go project:

   mkdir s2-example
   cd s2-example
   go mod init example.com/s2-example

2. Add the SDK dependency:

   go get github.com/s2-streamstore/s2-sdk-go/s2@latest

3. Generate an authentication token by logging onto the web console at s2.dev.

4. Set the token as an environment variable:

   export S2_ACCESS_TOKEN="<your auth token>"

5. Create a simple program:

   package main
   
   import (
       "context"
       "fmt"
       "log"
       "os"
   
       "github.com/s2-streamstore/s2-sdk-go/s2"
   )
   
   func main() {
       client := s2.New(os.Getenv("S2_ACCESS_TOKEN"), nil)
   
       basins := client.Basins.Iter(context.Background(), nil)
       for basins.Next() {
           fmt.Printf("Basin: %s\n", basins.Value().Name)
       }
       if err := basins.Err(); err != nil {
           log.Fatal(err)
       }
   }

   Run with go run main.go.

Examples

The examples/ directory contains various examples:

Example	Description
unary	Simple append and read operations
append_session	High-throughput streaming appends
batched_append_session	Batched appends
read_session	Streaming reads with backpressure
list_iter	Iterating over basins, streams, and tokens
access_tokens	Issuing and revoking access tokens
starwars	Stream Star Wars ASCII animation through S2

Run any example:

# edit the code to set an appropriate basin and stream
export S2_ACCESS_TOKEN="<your auth token>"
go run ./examples/unary

Starwars

For a fun demo, try streaming the Star Wars ASCII animation through S2:

# edit the code to set an appropriate basin and stream
export S2_ACCESS_TOKEN="<your auth token>"
go run ./examples/starwars -basin "<basin name>" -stream "<stream name>"

SDK Docs and Reference

Head over to pkg.go.dev for detailed documentation and package reference.

Feedback

We use Github Issues to track feature requests and issues with the SDK. If you wish to provide feedback, report a bug or request a feature, feel free to open a Github issue.

Contributing

Developers are welcome to submit Pull Requests on the repository. If there is no tracking issue for the bug or feature request corresponding to the PR, we encourage you to open one for discussion before submitting the PR.

Reach out to us

Join our Discord server. We would love to hear from you.

You can also email us at hi@s2.dev.

License

This project is licensed under the MIT License.