go_chat_i_guess

type ChannelController interface {
	MessageEncoder

	// OnConnect is called whenever a channel detects that a user has just
	// joined it.
	//
	// If the channel doesn't have a `ChannelController`, it broadcasts the
	// message:
	//
	//     channel.NewSystemBroadcast(username + " entered " + channel.Name() + "...")
	OnConnect(channel ChatChannel, username string)

	// OnDisconnect is called whenever a channel detects that a user has
	// disconnected.
	//
	// Since this may be called with some internal objects locked, only a
	// few channel methods may be called from this function. For this
	// reason, the `RestrictedChatChannel` SHALL NOT be cast and used as a
	// `ChatChannel`!
	//
	// If the channel doesn't have a `ChannelController`, it broadcasts the
	// message:
	//
	//     channel.NewSystemBroadcast(username + " exited " + channel.Name() + "...")
	OnDisconnect(channel RestrictedChatChannel, username string)
}

type ChatChannel interface {
	io.Closer

	RestrictedChatChannel

	// GetUsers retrieve the list of connected users in this channel. If
	// `list` is supplied, the users are appended to the that list, so be
	// sure to empty it before calling this function.
	GetUsers(list []string) []string

	// Remove the user `username` from this channel.
	RemoveUser(username string) error

	// ConnectUser add a new user to the channel.
	//
	// It's entirely up to the caller to initialize the connection used by
	// this user, for example upgrading a HTTP request to a WebSocket
	// connection.
	//
	// The `channel` does properly synchronize this function, so it may be
	// called by different goroutines concurrently.
	//
	// On error, `conn` is left unchanged and must be closed by the caller.
	//
	// If `conn` is nil, then this function will panic!
	ConnectUser(username string, conn Conn) error

	// ConnectUser add a new user to the channel and blocks until the
	// user closes the connection to the server.
	//
	// The `channel` does properly synchronize this function, so it may be
	// called by different goroutines concurrently.
	//
	// On error, `conn` is left unchanged and must be closed by the caller.
	//
	// Differently from `ConnectUser`, this function handles messages
	// from the remote client in the calling goroutine. This may be
	// advantageous if the external server already spawns a new goroutine
	// to handle each new connection.
	//
	// If `conn` is nil, then this function will panic!
	ConnectUserAndWait(username string, conn Conn) error
}

type ChatError uint

type ChatServer interface {
	io.Closer

	// GetConf retrieve a copy of the server's configuration. As such,
	// changing it won't cause any change to the configurations of the
	// running server.
	GetConf() ServerConf

	// RequestToken generate a token temporarily associating the user identified
	// by `username` may connect to a `channel`.
	//
	// This token should be requested from an authenticated and secure channel.
	// Then, the returned token may be sent in a 'Connect()' to identify the
	// user and the desired channel.
	//
	// RequestToken should only fail if it somehow fails to generate a token.
	RequestToken(username, channel string) (string, error)

	// CreateChannel create and start the channel with the given `name`.
	//
	// Channels are uniquely identified by their names. Also, the chat
	// server automatically removes a closed channel, regardless whether
	// it was manually closed or whether it timed out.
	CreateChannel(name string) error

	// GetChannel retrieve the channel named `name`.
	GetChannel(name string) (ChatChannel, error)

	// Connect a user to a channel, previously associated to `token`, using
	// `conn` to communicate with this user.
	//
	// On error, the token must be re-generated.
	//
	// If `conn` is nil, then this function will panic!
	Connect(token string, conn Conn) error

	// ConnectAndWait connect a user to a channel, previously associated to
	// `token`, using `conn` to communicate with this user.
	//
	// Differently from `Connect`, this blocks until `conn` gets closed.
	// This may be usefull if the called already spawns a new goroutine to
	// handle each new incoming connection.
	//
	// On error, the token must be re-generated.
	//
	// If `conn` is nil, then this function will panic!
	ConnectAndWait(token string, conn Conn) error
}

type Conn interface {
	io.Closer

	// Recv blocks until a new message was received.
	Recv() (string, error)

	// SendStr send `msg`, previously formatted by the caller.
	//
	// Note that the server may send an empty message to check if this
	// connection is still active.
	SendStr(msg string) error
}

type MessageEncoder interface {
	// Encode the message described in the parameter into the string that
	// will be sent to the channel.
	//
	// Returning the empty string will cancel sending the message, which
	// may be useful for command processing. It may also be used to reply
	// directly, and exclusively, to the sender after processing the
	// message.
	//
	// `from` is set internally by the `ChatChannel`, based on the `Conn`
	// that received this message and forwarded it to the server. Using it
	// to determine whether the requesting user is allowed to do some
	// operation should be safe, as long as users are properly
	// authenticated before generating their connection token.
	Encode(channel ChatChannel, date time.Time, msg, from, to string) string
}

type RestrictedChatChannel interface {
	// Name retrieve the channel's name.
	Name() string

	// NewBroadcast queue a new broadcast message from a specific sender,
	// setting its `Date` to the current time and setting the message's
	// `Message` and sender (its `From`) as `msg` and `from`, respectively.
	NewBroadcast(msg, from string)

	// NewSystemBroadcast queue a new system message (i.e., a message
	// without a sender), setting its `Date` to the current time and
	// setting `Message` to `msg`.
	NewSystemBroadcast(msg string)

	// NewSystemWhisper queue a new system message (i.e., a message without
	// a sender) to a specific receiver, setting its `Date` to the current
	// time and setting `Message` to `msg`.
	NewSystemWhisper(msg, to string)

	// IsClosed check if the channel is closed.
	IsClosed() bool
}

type ServerConf struct {
	// Size for the read buffer on new connections.
	ReadBuf int

	// Size for the write buffer on new connections.
	WriteBuf int

	// For how long a given token should exist before being used or expiring.
	TokenDeadline time.Duration

	// Delay between executions of the token cleanup routine.
	TokenCleanupDelay time.Duration

	// For how long a given channel may stay idle (without receiving any
	// connection). After this timeout expires, the channel sends a message
	// to every user, to check whether they are still connected.
	//
	// If no user is connected to the channel when it times out, the
	// channel will be automatically closed!
	ChannelIdleTimeout time.Duration

	// Delay between executions of the channel cleanup routine.
	ChannelCleanupDelay time.Duration

	// Controller optionally processes and encodes messages received by
	// this server's channels.
	//
	// This may optionally implement `ChannelController` as well!
	Controller MessageEncoder

	// Logger used by the chat server to report events. If this is nil, no
	// message shall be logged!
	Logger *log.Logger

	// Whether debug messages should be logged.
	DebugLog bool
}