arbor

README

Arbor-Go

This is a Golang library implementation of the Arbor chat protocol. It allows you to send and recieve messages over any io.ReadCloser and io.WriteCloser.

Contribute

PRs and suggestions welcome!

Documentation

Overview

Package arbor is an implementation of the Arbor chat protocol.

This package provides tools for reading and writing Arbor protocol messages from io.Readers and io.Writers, as well as a simple concurrent storage data structure that might be useful to clients or servers.

Index

• Constants
• func MakeMessageReader(conn io.ReadCloser) <-chan *ProtocolMessage
• func MakeMessageWriter(conn io.Writer) chan<- *ProtocolMessage
• func NoopRWCloser(in io.ReadWriter) io.ReadWriteCloser
• type ChatMessage
  • func NewChatMessage(content string) (*ChatMessage, error)
  • func (m *ChatMessage) AssignID() error
  • func (m *ChatMessage) Equals(other *ChatMessage) bool
  • func (m *ChatMessage) Reply(content string) (*ChatMessage, error)
• type ProtocolMessage
  • func (m *ProtocolMessage) Equals(other *ProtocolMessage) bool
  • func (m *ProtocolMessage) MarshalJSON() ([]byte, error)
  • func (m *ProtocolMessage) String() string
• type ProtocolReadWriter
  • func NewProtocolReadWriter(wrap io.ReadWriteCloser) (*ProtocolReadWriter, error)
  • func (c *ProtocolReadWriter) Close() (err error)
• type ProtocolReader
  • func NewProtocolReader(source io.Reader) (*ProtocolReader, error)
  • func (r *ProtocolReader) Read(into *ProtocolMessage) error
• type ProtocolWriter
  • func NewProtocolWriter(destination io.Writer) (*ProtocolWriter, error)
  • func (w *ProtocolWriter) Write(target *ProtocolMessage) error
• type ReadWriteCloser
• type ReadWriter
• type Reader
• type Store
  • func NewStore() *Store
  • func (s *Store) Add(msg *ChatMessage)
  • func (s *Store) Get(uuid string) *ChatMessage
• type Writer

Constants

const (
	// WelcomeType should be used as the `Type` field of a WELCOME ProtocolMessage
	WelcomeType = 0
	// QueryType should be used as the `Type` field of a QUERY ProtocolMessage
	QueryType = 1
	// NewMessageType should be used as the `Type` field of a NEW_MESSAGE ProtocolMessage
	NewMessageType = 2
)

Functions

func MakeMessageReader

func MakeMessageReader(conn io.ReadCloser) <-chan *ProtocolMessage

MakeMessageReader wraps the io.ReadCloser and returns a channel of ProtocolMessage pointers. Any JSON received over the io.ReadCloser will be unmarshalled into an ProtocolMessage struct and sent over the returned channel. If invalid JSON is received, the ReadCloser will close the io.ReadCloser and the returned channel.

func MakeMessageWriter

func MakeMessageWriter(conn io.Writer) chan<- *ProtocolMessage

MakeMessageWriter wraps the io.Writer and returns a channel of ProtocolMessage pointers. Any ProtocolMessage sent over that channel will be written onto the io.Writer as JSON. This function handles all marshalling. If a message fails to marshal for any reason, or if a write error occurs, the returned channel will be closed and no further messages will be written to the io.Writer.

func NoopRWCloser

func NoopRWCloser(in io.ReadWriter) io.ReadWriteCloser

NoopRWCloser wraps an io.ReadWriter with an implementation of io.Closer's Close() method that does nothing. It's like ioutil.NoopCloser but for io.ReadWriters instead of just io.Readers.

Types

type ChatMessage

type ChatMessage struct {
	UUID      string
	Parent    string
	Content   string
	Username  string
	Timestamp int64
}

ChatMessage represents a single chat message sent between users.

func NewChatMessage

func NewChatMessage(content string) (*ChatMessage, error)

NewChatMessage constructs a ChatMessage with the provided content. It's not necessary to create messages with this function, but it sets the timestamp for you.

func (*ChatMessage) AssignID

func (m *ChatMessage) AssignID() error

AssignID generates a new UUID and sets it as the ID for the message.

func (*ChatMessage) Equals

func (m *ChatMessage) Equals(other *ChatMessage) bool

Equals compares all message fields to determine whether two messages are the same.

func (*ChatMessage) Reply

func (m *ChatMessage) Reply(content string) (*ChatMessage, error)

Reply returns a new message with the given content that has its parent, content, and timestamp already configured.

type ProtocolMessage

type ProtocolMessage struct {
	// Root is only used in WELCOME messages and identifies the root of this server's message tree
	Root string
	// Recent is only used in WELCOME messages and provides a list of recently-sent message ids
	Recent []string
	// The type of the message, should be one of the constants defined in this
	// package.
	Type uint8
	// Major is only used in WELCOME messages and identifies the major version number of the protocol version in use
	Major uint8
	// Minor is only used in WELCOME messages and identifies the minor version number of the protocol version in use
	Minor uint8
	// Message is the actual chat message content, if any. This is currently only
	// used in NEW_MESSAGE messages
	*ChatMessage
}

ProtocolMessage represents a message in the Arbor chat protocol. This may or may not contain a chat message sent between users.

func (*ProtocolMessage) Equals

func (m *ProtocolMessage) Equals(other *ProtocolMessage) bool

Equals returns true if other is equivalent to the message (has the same data or is the same message)

func (*ProtocolMessage) MarshalJSON

func (m *ProtocolMessage) MarshalJSON() ([]byte, error)

MarshalJSON transforms a ProtocolMessage into JSON

func (*ProtocolMessage) String

func (m *ProtocolMessage) String() string

String returns a JSON representation of the message as a string.

type ProtocolReadWriter

type ProtocolReadWriter struct {
	*ProtocolReader
	*ProtocolWriter
	// contains filtered or unexported fields
}

ProtocolReadWriter can read and write arbor protocol messages (as JSON) from an io.ReadWriter

func NewProtocolReadWriter

func NewProtocolReadWriter(wrap io.ReadWriteCloser) (*ProtocolReadWriter, error)

NewProtocolReadWriter wraps the given io.ReadWriter so that it is possible to both read and write arbor protocol messages to it.

func (*ProtocolReadWriter) Close

func (c *ProtocolReadWriter) Close() (err error)

Close both closes the io.ReadWriteCloser wrapped by this ProtocolReadWriter and tears down all protocol-related internal structure. Once you close a ProtocolReadWriter, you must create a new one in order to use it again.

type ProtocolReader

type ProtocolReader struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ProtocolReader reads arbor protocol messages (as JSON) from an io.Reader

func NewProtocolReader

func NewProtocolReader(source io.Reader) (*ProtocolReader, error)

NewProtocolReader wraps the source to make serializing *ProtocolMessages easy.

func (*ProtocolReader) Read

func (r *ProtocolReader) Read(into *ProtocolMessage) error

Read attempts to read a JSON-serialized ProtocolMessage from the Reader's source into the provided ProtocolMessage. If the provided message is nil, it will error. This method will block until a ProtocolMessage becomes available.

type ProtocolWriter

type ProtocolWriter struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ProtocolWriter writes arbor protocol messages (as JSON) to an io.Reader

func NewProtocolWriter

func NewProtocolWriter(destination io.Writer) (*ProtocolWriter, error)

NewProtocolWriter creates a ProtocolWriter by wrapping a destination io.Writer

func (*ProtocolWriter) Write

func (w *ProtocolWriter) Write(target *ProtocolMessage) error

Write persists the given arbor protocol message into the ProtocolWriter's backing io.Writer

type ReadWriteCloser

type ReadWriteCloser interface {
	ReadWriter
	io.Closer
}

ReadWriteCloser defines the behavior of types that can both emit and consume arbor protocol messages that have a logical "Close" operation (file/socket wrappers, for instance)

type ReadWriter

type ReadWriter interface {
	Reader
	Writer
}

ReadWriter defines the behavior of types that can both emit and consume arbor protocol messages

type Reader

type Reader interface {
	// Populates the provided ProtocolMessage pointer with the contents of a newly read message
	Read(*ProtocolMessage) error
}

Reader defines the behavior of types that can emit arbor protocol messages

type Store

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

Store is a data structure that holds ChatMessages and allows them to be easily looked up by their identifiers. It is safe for concurrent use.

func NewStore

func NewStore() *Store

NewStore creates a Store that is ready to be used.

func (*Store) Add

func (s *Store) Add(msg *ChatMessage)

Add inserts the given message into the store.

func (*Store) Get

func (s *Store) Get(uuid string) *ChatMessage

Get retrieves the message with a UUID from the store.

type Writer

type Writer interface {
	// Consumes the provided ProtocolMessage without modifying it
	Write(*ProtocolMessage) error
}

Writer defines the behavior of types that can consume arbor protocol messages