slackio

README

slackio

slackio implements real-time Slack communication behind Go's io.Reader and io.Writer interfaces.

Usage

Simply import the package as go.alexhamlin.co/slackio. See the linked GoDoc above for additional usage details.

This project supports the (experimental) Go modules feature for dependency management. Using Go 1.11+ in module mode will help ensure that you are using supported versions of all dependencies.

Example

A small program is provided in the example/ directory to demonstrate the capabilities of slackio. To learn more, see the example GoDoc.

Development

1. git clone https://github.com/ahamlinman/slackio.git
2. make test, etc.

Status and Stability

As of November 2017, the key desired functionalities of package slackio have been implemented. Feature development is on an indefinite hiatus, but maintenance updates (e.g. bug fixes) may be made from time to time.

Until v1.0.0 is tagged (no guarantees about when or if this will happen), this project adheres to a scheme based on Semantic Versioning as follows:

• MINOR updates could potentially (but not necessarily) contain breaking changes
• PATCH updates will not contain breaking changes

All notable changes will be documented in CHANGELOG.md.

License

MIT (see LICENSE.txt)

Documentation

Overview

Package slackio implements real-time communication with Slack behind io.Reader and io.Writer interfaces.

To get started with slackio, construct a Client instance using a Slack API key. Then, create Reader and Writer instances as necessary using this Client. See the Reader and Writer examples for more details.

Index

• Variables
• func LineBatcher(r io.Reader) (<-chan string, <-chan error)
• type Batcher
  • func NewIntervalBatcher(b Batcher, d time.Duration, delim string) Batcher
• type Client
  • func NewClient(apiToken string) *Client
  • func (c *Client) Close() error
  • func (c *Client) SendMessage(m Message)
  • func (c *Client) Subscribe(ch chan<- Message) error
  • func (c *Client) SubscribeAt(id int, ch chan<- Message) error
  • func (c *Client) Unsubscribe(ch chan<- Message) error
• type Message
• type ReadClient
• type Reader
  • func NewReader(client ReadClient, channelID string) *Reader
  • func (c *Reader) Close() error
  • func (c *Reader) Read(p []byte) (int, error)
• type WriteClient
• type Writer
  • func NewWriter(client WriteClient, channelID string, batcher Batcher) *Writer
  • func (c *Writer) Close() error
  • func (c *Writer) Write(p []byte) (int, error)

Examples

• Reader
• Writer

Variables

var ErrAlreadySubscribed = errors.New("slackio: channel already subscribed")

ErrAlreadySubscribed is returned when an attempt is made to subscribe a channel that already has a subscription.

var ErrNotSubscribed = errors.New("slackio: channel not subscribed")

ErrNotSubscribed is returned when an attempt is made to unsubscribe a channel that is not currently subscribed.

Functions

func LineBatcher

func LineBatcher(r io.Reader) (<-chan string, <-chan error)

LineBatcher is a Batcher that emits individual, unmodified lines of output. Input that terminates with EOF before a newline is found will be emitted as if it were terminated by a newline.

Types

type Batcher

type Batcher func(io.Reader) (<-chan string, <-chan error)

Batcher is a type for functions that emit the output of an io.Reader in distinct "batches." Batchers may also introduce additional formatting or modification before an output batch is emitted.

Consumers of the batcher should range over its output channel. After the output channel has closed, consumers should read a single error value from the error channel. Batcher implementations should buffer the error channel so that bad consumers don't create goroutine leaks.

var DefaultBatcher Batcher = NewIntervalBatcher(LineBatcher, 100*time.Millisecond, "\n")

DefaultBatcher batches lines of input over a timespan of 0.1 seconds. This is intended as a reasonable default for applications that occasionally write a chunk of multiline output.

func NewIntervalBatcher

func NewIntervalBatcher(b Batcher, d time.Duration, delim string) Batcher

NewIntervalBatcher returns a Batcher that collects the output of an upstream Batcher over a defined interval. When the upstream Batcher first emits an output batch, it is collected into a buffer and a timer is started lasting for the given duration. As more output is emitted while the timer is running, it is appended to the buffer with individual batches separated by the provided delimiter. When the timer expires, or when the upstream batcher terminates, the buffer is flushed to the output channel if it is non-blank. The buffer is cleared and the process repeats while the upstream batcher is running.

The batching interval can be adjusted based on the nature of the expected output, though it is recommended that it be kept short.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implements an ability to send and receive Slack messages using a real-time API. For readers, it presents a long-running stream of a user's incoming Slack messages that may be consumed using multiple independent channels. For writers, it allows instant sending of a message to a given channel.

A Client instance encapsulates a WebSocket connection to Slack. Users of slackio should create a single Client and share it across Reader and Writer instances.

func NewClient

func NewClient(apiToken string) *Client

NewClient returns a new Client and connects it to Slack using the given API token. Invalid API tokens will result in a panic while attempting to establish the connection.

func (*Client) Close

func (c *Client) Close() error

Close terminates all subscriptions within this Client and disconnects from Slack. The behavior of Subscribe, SubscribeAt, and Unsubscribe for a closed Client is undefined.

func (*Client) SendMessage

func (c *Client) SendMessage(m Message)

SendMessage sends the given Message to its associated Slack channel.

func (*Client) Subscribe

func (c *Client) Subscribe(ch chan<- Message) error

Subscribe creates a new subscription for the given channel within this Client, starting immediately after the latest message in the client's overall message stream. See the SubscribeAt documentation for more details.

func (*Client) SubscribeAt

func (c *Client) SubscribeAt(id int, ch chan<- Message) error

SubscribeAt creates a new subscription for the given channel within this Client, starting at the specified point in the client's overall message stream. Each message sent into the channel will have an ID indicating its relative position in the stream. IDs begin at 0 and increment by 1 for each new message, and are unique within a single Client instance.

Each Client maintains a bounded number of past messages from the overall stream. If a subscriber falls behind this buffer, or is subscribed using an ID that is no longer in the buffer, that subscriber will transparently be skipped forward to the earliest message still remaining in the buffer. All intervening messages will be lost. If necessary, subscribers can detect this behavior by watching for message ID increases larger than 1.

Subscriptions using IDs that have not yet appeared in the stream are supported. The subscription will begin once a new message has been assigned the requested ID and inserted into the stream.

As a special case, a negative ID will begin the subscription immediately after the latest message in the stream.

If the given channel already has an active subscription, ErrAlreadySubscribed will be returned.

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(ch chan<- Message) error

Unsubscribe terminates the subscription for the given channel within this Client. After Unsubscribe returns, the channel will no longer receive any messages and may safely be closed. If the given channel was not previously subscribed, ErrNotSubscribed will be returned.

type Message

type Message struct {
	ID        int
	ChannelID string
	Text      string
}

Message is the type for messages received from and sent to a single Slack channel.

type ReadClient

type ReadClient interface {
	Subscribe(chan<- Message) error
	Unsubscribe(chan<- Message) error
}

ReadClient represents objects that allow subscription to a stream of slackio Messages. Note that in slackio, Client implements this interface.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads messages from the main body of one or more Slack channels.

Example

// Stream messages from all of a user's Slack channels to stdout

client := NewClient("xoxb-slack-api-token")
reader := NewReader(client, "")

io.Copy(os.Stdout, reader)

func NewReader

func NewReader(client ReadClient, channelID string) *Reader

NewReader returns a new Reader. If channelID is non-blank, the Reader will only output text from a single channel. Otherwise, it will output text from all channels together in a single stream.

func (*Reader) Close

func (c *Reader) Close() error

Close disconnects this Reader from Slack and shuts down internal buffers. After calling Close, the next call to Read will result in an EOF.

func (*Reader) Read

func (c *Reader) Read(p []byte) (int, error)

Read returns text from the main body of one or more Slack channels (i.e. excluding threads), buffered by line. Single messages will be terminated with an appended newline. Messages with explicit line breaks are equivalent to multiple single messages in succession.

type WriteClient

type WriteClient interface {
	SendMessage(Message)
}

WriteClient represents objects that can send slackio Messages. Note that in slackio, Client implements this interface.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer writes messages to the main body of a single Slack channel.

Example

// Write a short message to a Slack channel

client := NewClient("xoxb-slack-api-token")
writer := NewWriter(client, "C12345678", nil)

_, err := writer.Write([]byte("hi\n"))
if err != nil {
	fmt.Println(err.Error())
}

func NewWriter

func NewWriter(client WriteClient, channelID string, batcher Batcher) *Writer

NewWriter returns a new Writer. channelID must be non-blank, or NewWriter will panic. If batcher is nil, DefaultBatcher will be used as the Batcher.

func (*Writer) Close

func (c *Writer) Close() error

Close disconnects this Writer from Slack and shuts down internal buffers. After calling Close, the next call to Write will result in an error.

func (*Writer) Write

func (c *Writer) Write(p []byte) (int, error)

Write submits text to the main body of a Slack channel, with message boundaries determined by the Writer's Batcher.