Satori RTM SDK for Go (Golang)
Use the Go SDK for the Satori platform to create applications that use the RTM to publish and subscribe.
Go SDK Installation
Use a go-get
tool (or any go-compatible package manager) to download the SDK:
go get github.com/satori-com/satori-rtm-sdk-go/rtm
Import the SDK in your go file:
import "github.com/satori-com/satori-rtm-sdk-go/rtm"
It is highly recommended to use tags to lock the SDK version for your project.
Documentation and Examples
Latest Go SDK documentation is here
Logging and Debugging
Go SDK logs information to STDOUT/STDERR. To enable debug level,
set DEBUG_SATORI_SDK environment variable to true
:
$ DEBUG_SATORI_SDK=true go run <your_program.go>
or
$ export DEBUG_SATORI_SDK=true
$ go run <your_program.go>
Debug level outputs all underlying communication with RTM, in addition to SDK execution info.
Example:
$ DEBUG_SATORI_SDK=true go run <your_app.go>
[info] 2017/04/18 15:28:38.8129 Creating new RTM object
[info] 2017/04/18 15:28:38.8131 Client: Enter Connecting
[info] 2017/04/18 15:28:38.8131 Connecting to wss://<endpoint>.satori.com
[info] 2017/04/18 15:28:39.5492 Auth: Starting authentication
[debg] 2017/04/18 15:28:39.5493 send> {"action":"auth/handshake","body":{"method":"role_secret","data":{"role":"<role>"}},"id":1}
[debg] 2017/04/18 15:28:39.7246 recv< {"action":"auth/handshake/ok","body":{"data":{"nonce":"<nonce>"}},"id":1}
[debg] 2017/04/18 15:28:39.7247 Auth: Handshake response: {"action":"auth/handshake/ok","body":{"data":{"nonce":"<nonce>"}},"id":1}
[debg] 2017/04/18 15:28:39.7247 Auth: Got nonce. Trying to authenticate
[debg] 2017/04/18 15:28:39.7247 send> {"action":"auth/authenticate","body":{"method":"role_secret","credentials":{"hash":"<generated_hash>"}},"id":2}
[debg] 2017/04/18 15:28:39.8958 recv< {"action":"auth/authenticate/ok","body":{},"id":2}
[info] 2017/04/18 15:28:39.8959 Auth: Successfully authenticated
[info] 2017/04/18 15:28:39.8959 Client: Enter Connected
[debg] 2017/04/18 15:28:39.8960 send> {"action":"rtm/write","body":{"channel":"channel-name","message":1},"id":3}
[debg] 2017/04/18 15:28:40.0750 recv< {"action":"rtm/write/ok","body":{"position":"1492522119:0"},"id":3}
Publish/Receive Binary Data
The SDK allows to publish and receive Binary data:
type Frame struct {
Id int,
Payload []uint8
}
frame := Frame{
Id 1,
Payload []uint8{42,14,11,255,100}
}
client.Publish("channel", frame)
You do not need to do something special to decode binary message:
// Inside listener OnData: func(data pdu.SubscriptionData)
for _, message := range data.Messages {
var frame Frame
json.Unmarshal(message, &frame)
fmt.Printf("%+v\n", frame)
}
Using Proxy
The SDK supports working through a proxy.
When creating a new client specify Proxy
in Options
. There are several ways how to do this:
// Use Environment variables to get Proxy URL: https://golang.org/pkg/net/http/#ProxyFromEnvironment
client, err := rtm.New("<your-endpoint>", "<your-appkey>", rtm.Options{
Proxy: http.ProxyFromEnvironment
})
// Use *url.URL directly
proxyUrl, _ := url.Parse("http://127.0.0.1:3128")
client, err := rtm.New("<your-endpoint>", "<your-appkey>", rtm.Options{
Proxy: http.ProxyURL(proxyUrl)
})
Tests and Coverage Report
Tests require a valid RTM endpoint; RTM credentials should be populated in credentials.json
.
The credentials.json
file must include the following key-value pairs:
{
"endpoint": "wss://<SATORI_HOST>/",
"appkey": "<APP_KEY>",
"auth_role_name": "<ROLE_NAME>",
"auth_role_secret_key": "<ROLE_SECRET_KEY>",
"auth_restricted_channel": "<CHANNEL_NAME>"
}
endpoint
is your customer-specific DNS name for RTM access.appkey
is your application key.auth_role_name
is a role name that permits to publish / subscribe toauth_restricted_channel
. Must be notdefault
.auth_role_secret_key
is a secret key forauth_role_name
.auth_restricted_channel
is a channel with subscribe and publish access forauth_role_name
role only.
You must use DevPortal to create role and set channel permissions.
After setting up credentials.json
, run SDK tests with the following commands:
$ go get github.com/satori-com/satori-sdk-go/rtm
$ CREDENTIALS=/full/path/to/credentials.json go test ./src/github.com/satori-com/satori-rtm-sdk-go/...
Coverage report
Use the -cover
flag to get Coverage report. The -coverprofile
flag produces debug profile file that
allows to analyse untested parts of SDK.
$ CREDENTIALS=/full/path/to/credentials.json go test ./src/github.com/satori-com/satori-rtm-sdk-go/rtm -cover -coverprofile cover.out
$ go tool cover -html=cover.out -o rtm.html
Now you can open the rtm.html
file to check uncovered parts of code.
Race conditions detection
Use the -race
flag to enable Race conditions detection. It is highly recommended to use this flag
when running the tests.
$ CREDENTIALS=/full/path/to/credentials.json go test ./src/github.com/satori-com/satori-rtm-sdk-go/... -race