Ably Go
A Go client library for www.ably.io, the realtime messaging service.
Installation
~ $ go get -u github.com/ably/ably-go/ably
Using the Realtime API
Creating a client
client, err := ably.NewRealtimeClient(ably.NewClientOptions("xxx:xxx"))
if err != nil {
panic(err)
}
channel := client.Channels.Get("test")
Subscribing to a channel for all events
sub, err := channel.Subscribe()
if err != nil {
panic(err)
}
for msg := range sub.MessageChannel() {
fmt.Println("Received message:", msg)
}
EventName1
and EventName2
events
Subscribing to a channel for sub, err := channel.Subscribe("EventName1", "EventName2")
if err != nil {
panic(err)
}
for msg := range sub.MessageChannel() {
fmt.Println("Received message:", msg)
}
Publishing to a channel
// send request to a server
res, err := channel.Publish("EventName1", "EventData1")
if err != nil {
panic(err)
}
// await confirmation
if err = res.Wait(); err != nil {
panic(err)
}
Announcing presence on a channel
// send request to a server
res, err := channel.Presence.Enter("presence data")
if err != nil {
panic(err)
}
// await confirmation
if err = res.Wait(); err != nil {
panic(err)
}
Announcing presence on a channel on behalf of other client
// send request to a server
res, err := channel.Presence.EnterClient("clientID", "presence data")
if err != nil {
panic(err)
}
// await confirmation
if err = res.Wait(); err != nil {
panic(err)
}
Getting all clients present on a channel
clients, err := channel.Presence.Get(true)
if err != nil {
panic(err)
}
for _, client := range clients {
fmt.Println("Present client:", client)
}
Subscribing to all presence messages
sub, err := channel.Presence.Subscribe()
if err != nil {
panic(err)
}
for msg := range sub.PresenceChannel() {
fmt.Println("Presence event:", msg)
}
Subscribing to 'Enter' presence messages only
sub, err := channel.Presence.Subscribe(proto.PresenceEnter)
if err != nil {
panic(err)
}
for msg := range sub.PresenceChannel() {
fmt.Println("Presence event:", msg)
}
Using the REST API
Introduction
All examples assume a client and/or channel has been created as follows:
client, err := ably.NewRestClient(ably.NewClientOptions("xxx:xxx"))
if err != nil {
panic(err)
}
channel := client.Channel("test")
Publishing a message to a channel
err = channel.Publish("HelloEvent", "Hello!")
if err != nil {
panic(err)
}
Querying the History
page, err := channel.History(nil)
for ; err == nil; page, err = page.Next() {
for _, message := range page.Messages() {
fmt.Println(message)
}
}
if err != nil {
panic(err)
}
Presence on a channel
page, err := channel.Presence.Get(nil)
for ; err == nil; page, err = page.Next() {
for _, presence := range page.PresenceMessages() {
fmt.Println(presence)
}
}
if err != nil {
panic(err)
}
Querying the Presence History
page, err := channel.Presence.History(nil)
for ; err == nil; page, err = page.Next() {
for _, presence := range page.PresenceMessages() {
fmt.Println(presence)
}
}
if err != nil {
panic(err)
}
Generate Token and Token Request
client.Auth.RequestToken()
client.Auth.CreateTokenRequest()
Fetching your application's stats
page, err := client.Stats(&ably.PaginateParams{})
for ; err == nil; page, err = page.Next() {
for _, stat := range page.Stats() {
fmt.Println(stat)
}
}
if err != nil {
panic(err)
}
Known limitations (work in progress)
As the library is actively developed couple of features are not there yet:
- Realtime connection recovery is not implemented
- Realtime connection failure handling is not implemented
- ChannelsOptions and CipherParams are not supported when creating a Channel
- Realtime Ping function is not implemented
Support and feedback
Please visit http://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
You can also view the community reported Github issues.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Ensure you have added suitable tests and the test suite is passing (
make test
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
License
Copyright (c) 2016 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.