room

Documentation

Overview

Package room provides a framework for REx servers and clients to communicate using arbitrary messages.

Index

• func Broadcast(ctx context.Context, content Content) error
• func LookupRoom(r *Room, servers chan<- *ServerDisco) error
• type Bus
  • func NewBus(ctx context.Context, handlers ...Handler) *Bus
  • func (b *Bus) AddHandler(h Handler)
  • func (b *Bus) Event(c Content) error
  • func (b *Bus) Message(session string, c Content) error
  • func (b *Bus) Subscribe(start int) *Subscription
  • func (b *Bus) Unsubscribe(s *Subscription)
• type Client
  • func NewClient(h EventHandler) *Client
  • func NewClientRestore(h EventHandler, session string) *Client
  • func (c *Client) CreateSession(ctx context.Context, name string) error
  • func (c *Client) Run(ctx context.Context, start int) (next int, err error)
  • func (c *Client) Send(ctx context.Context, content Content) error
• type Content
  • func Bytes(b []byte) Content
  • func String(s string) Content
• type Discovery
  • func DiscoveryServer(zc *ZoneConfig) (Discovery, error)
• type Event
• type EventHandler
• type Handler
• type Msg
• type Room
• type Server
  • func NewServer(config *ServerConfig) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Event(c Content)
  • func (s *Server) Run() error
  • func (s *Server) Start() error
  • func (s *Server) Wait() error
• type ServerConfig
• type ServerDisco
• type Subscription
  • func (s *Subscription) Event() Event
  • func (s *Subscription) Next(timeout <-chan time.Time) (ok bool)
• type Time
• type ZoneConfig
  • func NewZoneConfig(s *Server) (*ZoneConfig, error)
  • func (zc *ZoneConfig) Instance() string

Functions

func Broadcast

func Broadcast(ctx context.Context, content Content) error

Broadcast sends a broadcast event to all clients connected to the Bus associated with ctx.

func LookupRoom

func LookupRoom(r *Room, servers chan<- *ServerDisco) error

LookupRoom finds server applications with rooms that look like r. LookupRoom ignores the instance name of advertised services and relies only on the service identifier.

BUG? Not sure how mdns lookup handled channels when an error is encountered.

Types

type Bus

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

Bus is the communication bus for a Server.

func NewBus

func NewBus(ctx context.Context, handlers ...Handler) *Bus

NewBus initializes and returns a new Bus.

func (*Bus) AddHandler

func (b *Bus) AddHandler(h Handler)

AddHandler changes the bus message handler.

func (*Bus) Event

func (b *Bus) Event(c Content) error

Event broadcasts an event to all Subscription.

func (*Bus) Message

func (b *Bus) Message(session string, c Content) error

Message is called by a subscriber to signal back to the bus owner via b.handler.

func (*Bus) Subscribe

func (b *Bus) Subscribe(start int) *Subscription

Subscribe returns a new Subscription that new events from b.

func (*Bus) Unsubscribe

func (b *Bus) Unsubscribe(s *Subscription)

Unsubscribe removes s from the recipients of b's events. After Unsubscribe returns no further events will be received in calls to s.Next().

type Client

type Client struct {
	Host    string
	Port    int
	Handler EventHandler
	HTTP    *http.Client
	Now     func() Time
	Session string
}

Client is an interface to a remote REx server.

func NewClient

func NewClient(h EventHandler) *Client

NewClient allocates and returns a new client with its Handler set to h.

func NewClientRestore

func NewClientRestore(h EventHandler, session string) *Client

NewClientRestore behaves like NewClient but sets the client's Session to session as well.

func (*Client) CreateSession

func (c *Client) CreateSession(ctx context.Context, name string) error

CreateSession initializes c.Session by registering an identifier with the remote bus. If the value is already set no registration is performed.

func (*Client) Run

func (c *Client) Run(ctx context.Context, start int) (next int, err error)

Run processes events received from the remote bus.

func (*Client) Send

func (c *Client) Send(ctx context.Context, content Content) error

Send sends a message to the remote server using the given session identifier.

type Content

type Content interface {
	// Data returns the event content is a slice of bytes (even if the content
	// is stored as a string).  Applications should use whichever of Data or
	// Text methods they need and any translation necessary will happen as fast
	// as possible.
	Data() []byte

	// Text is like Data but returns a string representation of event data and
	// may be optmized to do that.
	Text() string
}

Content is application data that is transmitted over a bus.

func Bytes

func Bytes(b []byte) Content

Bytes returns a Content containing the b as its data.

func String

func String(s string) Content

String returns a Content containing the s as its data.

type Discovery

type Discovery interface {
	Close() error
	// contains filtered or unexported methods
}

Discovery is an opaque type that contains an mDNS discovery server.

func DiscoveryServer

func DiscoveryServer(zc *ZoneConfig) (Discovery, error)

DiscoveryServer returns a new Discovery server that is advertizing the Room in zc.

type Event

type Event interface {
	Index() uint64

	Time() Time

	Content
}

Event is a broadcast message from the server to all clients. Unlike Msg an event does not have an associated session identifier because it is intended for all clients.

type EventHandler

type EventHandler interface {
	HandleEvent(context.Context, *Client, Event)
}

EventHandler is part of the client's event loop.

type Handler

type Handler interface {
	HandleMessage(ctx context.Context, msg Msg)
}

Handler is a bus message handler.

type Msg

type Msg interface {
	// Session returns an identifier for the client (session) that originated
	// the message.
	Session() string

	Time() Time

	Content
}

Msg is a piece of data originating from a client application.

type Room

type Room struct {
	Name    string
	Service string
}

Room represents a single shared enivornment managed by a server. The service is advertised using mDNS an must conform to the format specified in RFC 6763 Section 7. The Name may contain any unicode text excluding ASCII control characters but is recommended to not contain '\n' bytes for display purposes. An mDNS instance identifier will be generated from the given name, the time and the process identifier.

type Server

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

Server is a server used by a TV application to run a game or collaborative procedure.

func NewServer

func NewServer(config *ServerConfig) *Server

NewServer initializes a new server, but does not start serving clients.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the string address the bus is listening on for HTTP requests.

func (*Server) Event

func (s *Server) Event(c Content)

Event broadcasts c to all connected clients, giving it the next unused event index.

func (*Server) Run

func (s *Server) Run() error

Run binds to a random port, begins broadcasting service metadata using mDNS, and begins streaming client events and dispatching client messages. Typically, Run never returns a value. If any critical error is encountered it will be returned.

Run is equivalent to calling Start, followed by s.Wait.

func (*Server) Start

func (s *Server) Start() error

Start binds the server to a port and beigns allowing clients to connect. Start must not be called more than once.

func (*Server) Wait

func (s *Server) Wait() error

Wait returns when the server has terminated. Wait must not be called more than once.

type ServerConfig

type ServerConfig struct {
	Room *Room
	Bus  *Bus

	// Addr is an optional address to bind.  If empty, the address of ":0" will
	// be used.
	Addr string
}

ServerConfig controls how a server advertises itself to potential clients as well as miscelaneous communication behaviors.

type ServerDisco

type ServerDisco struct {
	Room    *Room
	TCPAddr *net.TCPAddr
	Entry   *mdns.ServiceEntry
}

ServerDisco is a running instance of Room accesable at Addr.

type Subscription

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

Subscription represents a remote client that needs to receive messages from a Bus.

func (*Subscription) Event

func (s *Subscription) Event() Event

Event returns the last received Event.

func (*Subscription) Next

func (s *Subscription) Next(timeout <-chan time.Time) (ok bool)

Next waits for the next event to be received over the channel and returns it. If the subscription is terminated, or values is received over timeout Next will return a value value. Otherwise Next returns true and Event will return the event received.

type Time

type Time interface{}

Time has not been figured out yet. It is definitely an abstract time. I would like it if all events and messages had unique identifiers.

type ZoneConfig

type ZoneConfig struct {
	Room *Room
	Port int
	IPs  []net.IP
	TXT  []string
}

ZoneConfig configures mDNS for a Room.

func NewZoneConfig

func NewZoneConfig(s *Server) (*ZoneConfig, error)

NewZoneConfig returns a default mDNS zone configuration derived from s.

func (*ZoneConfig) Instance

func (zc *ZoneConfig) Instance() string

Instance returns the mdns instance identifier corresponding to zc.Room.Name.