cchat

type Actioner interface {
	// Do executes a message action on the given messageID, which would be taken
	// from MessageHeader.ID(). This method is allowed to do IO; the frontend should
	// take care of running it asynchronously.
	Do(ctx context.Context, action string, id ID) error // Blocking
	// MessageActions returns a list of possible actions to a message in pretty
	// strings that the frontend will use to directly display. This method must not
	// do IO.
	//
	// The string slice returned can be nil or empty.
	Actions(id ID) []string
}

type Attacher interface {
	Attachments() []MessageAttachment
}

type AuthenticateEntry struct {
	Name        string
	Placeholder string
	Description string
	Secret      bool
	Multiline   bool
}

type AuthenticateError interface {
	// NextStage optionally returns a slice of Authenticator interfaces if the
	// authentication process requires another stage. It works similarly to
	// Service's Authenticate method, both of which returns a slice of
	// Authenticators.
	//
	// If the error returned is an actual error, and that the user should retry any
	// of the authentication fields, then NextStage could return nil to signify the
	// error. The frontend could reliably check nil on this field to determine
	// whether or not it should recreate the authentication fields.
	NextStage() []Authenticator
	// Error returns the error as a string. This method makes AuthenticateError
	// satisfy the built-in error interface.
	Error() string
}

type Authenticator interface {
	// Authenticate will be called with a list of values with indices correspond to
	// the returned slice of AuthenticateEntry.
	Authenticate(context.Context, []string) (Session, AuthenticateError) // Blocking
	// AuthenticateForm should return a list of authentication entries for the
	// frontend to render.
	AuthenticateForm() []AuthenticateEntry
	// Description returns the description of this authenticator method.
	Description() text.Rich
	// Name returns a short and concise name of this Authenticator method. The name
	// should not include the name of the Service.
	Name() text.Rich
}

type Backlogger interface {
	// Backlog fetches messages before the given message ID into the
	// MessagesContainer.
	//
	// This method is technically a ContainerMethod, but is listed as an IOMethod
	// because of the additional message ID parameter.
	Backlog(ctx context.Context, before ID, msgc MessagesContainer) error // Blocking
}

type Commander interface {
	// Run executes the given command, with the slice being already split arguments,
	// similar to os.Args. The function can return both a []byte and an error value.
	// The frontend should render the byte slice's value first, then display the
	// error.
	//
	// This function can do IO.
	//
	// The client should make guarantees that an empty string (and thus a
	// zero-length string slice) should be ignored. The backend should be able to
	// assume that the argument slice is always length 1 or more.
	//
	//
	// Words
	//
	// This interface and everything else inside this interface must abide by shell
	// rules when splitting words. This is in contrary to the default behavior
	// elsewhere, such as in Sender's Completer, where words are split by whitespace
	// without care for quotes.
	//
	// For example, provided this string:
	//
	//    echo "This is a string"
	//
	// This is the correct output:
	//
	//    []string{"echo", "This is a string"}
	//
	// This is the incorrect output:
	//
	//    []string{"echo", "\"This", "is", "a", "string\""}
	//
	// A helper function for this kind of behavior is available in package split,
	// under the ArgsIndexed function. This implementation also provides the rough
	// specifications.
	Run(ctx context.Context, words []string) ([]byte, error) // Blocking

	AsCompleter() Completer // Optional
}

type Completer interface {
	// Complete returns the list of possible completion entries for the given word
	// list and the current word index. It takes in a list of whitespace-split slice
	// of string as well as the position of the cursor relative to the given string
	// slice.
	Complete(words []string, current int64) []CompletionEntry
}

type CompletionEntry struct {
	Raw       string
	Text      text.Rich
	Secondary text.Rich
	IconURL   string
	Image     bool
}

type Configurator interface {
	SetConfiguration(map[string]string) error
	Configuration() map[string]string
}

type Editor interface {
	// Edit edits the message with the given ID to the given content, which is the
	// edited string from RawMessageContent. This method can do IO.
	Edit(ctx context.Context, id ID, content string) error // Blocking
	// RawContent gets the original message text for editing. This method must not
	// do IO.
	RawContent(id ID) (string, error)
	// IsEditable returns whether or not a message can be edited by the client. This
	// method must not do IO.
	IsEditable(id ID) bool
}

type ErrInvalidConfigAtField struct {
	Key string
	Err error
}

type ID = string

type Identifier interface {
	ID() ID
}

type LabelContainer interface {
	SetLabel(text.Rich)
}

type ListMember interface {
	Identifier

	// Secondary returns the subtext of this member. This could be anything, such as
	// a user's custom status or away reason.
	Secondary() text.Rich
	// Status returns the status of the member. The backend does not have to show
	// offline members with the offline status if it doesn't want to show offline
	// menbers at all.
	Status() Status
	// Name returns the username or the nickname of the member, whichever the
	// backend should prefer.
	Name() text.Rich
}

type Lister interface {
	// Servers should call SetServers() on the given ServersContainer to render all
	// servers. This function can do IO, and the frontend should run this in a
	// goroutine.
	Servers(context.Context, ServersContainer) error
	// Columnate is optionally used by servers to tell the frontend whether or not
	// its children should be put onto a new column instead of underneath it within
	// the same tree. If the method returns false, then the frontend can treat its
	// children as normal and show it as children within the same tree.
	//
	// For example, in Discord, guilds can be placed in guild folders, but guilds
	// and guild folders are put in the same column while guilds are actually
	// children of the folders. To replicate this behavior, guild folders should
	// return false, and guilds should return true. Both channels and categories can
	// return false.
	Columnate() bool
}

type MemberDynamicSection interface {
	// LoadLess is a method which the client must call after it is done displaying
	// entries that were added from calling LoadMore.
	//
	// The client can call this method exactly as many times as it has called
	// LoadMore. However, false should be returned if the client should stop, and
	// future calls without LoadMore should still return false.
	LoadLess(context.Context) bool // Blocking
	// LoadMore is a method which the client can call to ask for more members. This
	// method can do IO.
	//
	// Clients may call this method on the last section in the section slice;
	// however, calling this method on any section is allowed. Clients may not call
	// this method if the number of members in this section is equal to Total.
	LoadMore(context.Context) bool // Blocking
}

type MemberListContainer interface {
	// RemoveMember removes a member from a section. If neither the member nor the
	// section exists, then the client should ignore it.
	RemoveMember(sectionID ID, memberID ID)
	// SetMember adds or updates (or upsert) a member into a section. This operation
	// must not change the section's member count. As such, changes should be done
	// separately in SetSection. If the section does not exist, then the client
	// should ignore this member, so, backends must call SetSections first before
	// SetMember on a new section.
	//
	// Typically, the backend should try and avoid calling this method and instead
	// update the labeler in the name. This method should only be used for adding
	// members.
	SetMember(sectionID ID, member ListMember)
	// SetSections (re)sets the list of sections to be the given slice. Members from
	// the old section list should be transferred over to the new section entry if
	// the section name's content is the same. Old sections that don't appear in the
	// new slice should be removed.
	SetSections(sections []MemberSection)
}

type MemberLister interface {
	// ListMembers assigns the given container to the channel's member list. The
	// given context may be used to provide HTTP request cancellations, but
	// frontends must not rely solely on this, as the general context rules applies.
	//
	// Further behavioral documentations may be in Messenger's JoinServer method.
	ListMembers(context.Context, MemberListContainer) error
}

type MemberSection interface {
	Identifier
	Namer

	// Total returns the total member count.
	Total() int

	AsMemberDynamicSection() MemberDynamicSection // Optional
}

type MessageAttachment struct {
	io.Reader
	Name string
}

type MessageCreate interface {
	MessageHeader
	// Noncer is optional.
	Noncer

	// Mentioned returns whether or not the message mentions the current user. If a
	// backend does not implement mentioning, then false can be returned.
	Mentioned() bool
	Content() text.Rich
	Author() User
}

type MessageDelete interface {
	MessageHeader
}

type MessageHeader interface {
	Identifier

	Time() time.Time
}

type MessageUpdate interface {
	MessageHeader

	Content() text.Rich
}

type MessagesContainer interface {
	DeleteMessage(MessageDelete)
	UpdateMessage(MessageUpdate)
	// CreateMessage inserts a message into the container. The frontend must
	// guarantee that the messages are in order based on what's returned from
	// Time().
	CreateMessage(MessageCreate)
}

type Messenger interface {
	// JoinServer joins a server that's capable of receiving messages. The server
	// may not necessarily support sending messages.
	//
	// Frontends must never call JoinServer on the same server more than twice
	// without calling the stop function first. This is the best of both worlds, as
	// it greatly reduces complexity on both sides in most cases, therefore the
	// backend can safely assume that there will only ever be one active JoinServer.
	// If the frontend wishes to do this, it must keep its own shared message
	// buffer.
	JoinServer(context.Context, MessagesContainer) error

	AsSender() Sender                   // Optional
	AsEditor() Editor                   // Optional
	AsActioner() Actioner               // Optional
	AsNicknamer() Nicknamer             // Optional
	AsBacklogger() Backlogger           // Optional
	AsMemberLister() MemberLister       // Optional
	AsUnreadIndicator() UnreadIndicator // Optional
	AsTypingIndicator() TypingIndicator // Optional
}

type Namer interface {
	// Name sets the given container to contain the name of the parent context. The
	// method has no stop method; stopping is implied to be dependent on the parent
	// context. As such, it's only used for updating.
	Name(context.Context, LabelContainer) error
}

type Nicknamer interface {
	Namer
}

type Noncer interface {
	Nonce() string
}

type ReadContainer interface {
	// DeleteIndications deletes a list of unused users/authors associated with
	// their read indicators. The backend can use this to free up users/authors that
	// are no longer in the server, for example when they are offline or have left
	// the server.
	DeleteIndications(authorIDs []ID)
	// AddIndications adds a map of users/authors to the respective message ID of
	// the server that implements ReadIndicator.
	AddIndications([]ReadIndication)
}

type ReadIndication struct {
	User      User
	MessageID ID
}

type ReadIndicator interface {
	// ReadIndicate subscribes the given container for read activities. The backend
	// must keep track of which read states to send over to not overwhelm the
	// frontend, and the frontend must either keep track of them, or it should not
	// display it at all.
	ReadIndicate(context.Context, ReadContainer) error
}

type Replier interface {
	ReplyingTo() ID
}

type SendableMessage interface {
	Content() string

	AsNoncer() Noncer     // Optional
	AsReplier() Replier   // Optional
	AsAttacher() Attacher // Optional
}

type Sender interface {
	// CanAttach returns whether or not the client is allowed to upload files.
	CanAttach() bool
	// Send is called by the frontend to send a message to this channel.
	Send(context.Context, SendableMessage) error // Blocking

	AsCompleter() Completer // Optional
}

type Server interface {
	Identifier
	Namer

	AsLister() Lister             // Optional
	AsMessenger() Messenger       // Optional
	AsCommander() Commander       // Optional
	AsConfigurator() Configurator // Optional
}

type ServerUpdate interface {
	// Server embeds a complete server. Unlike MessageUpdate, which only returns
	// data on methods that are changed, ServerUpdate's methods must return the
	// complete data even if they stay the same. As such, zero-value returns are
	// treated as not updated, including the name.
	Server

	// PreviousID returns the ID of the item, either to be replaced or to be
	// inserted in front of.
	//
	// If replace is true, then the returned ID is the ID of the item to be
	// replaced, and the frontend should only try to use the ID as-is to find the
	// old server and replace.
	//
	// If replace is false, then the returned ID will be the ID of the item in front
	// of the embedded server. If the ID is empty or the frontend cannot find the
	// server from this ID, then it should assume and prepend the server to the
	// start.
	PreviousID() (serverID ID, replace bool)
}

type ServersContainer interface {
	UpdateServer(ServerUpdate)
	// SetServer is called by the backend service to request a reset of the server
	// list. The frontend can choose to call Servers() on each of the given servers,
	// or it can call that later. The backend should handle both cases.
	//
	// If the backend sets a nil server slice, then the frontend should take that as
	// an unavailable server list rather than an empty server list. The server list
	// should only be considered empty if it's an empty non-nil slice. An
	// unavailable list, on the other hand, can be treated as backend issues, e.g. a
	// connection issue.
	SetServers([]Server)
}

type Service interface {
	// Identifier returns the unique identifier for the service. There is no
	// enforced representation, but services are recommended to follow the Reverse
	// Domain Name Notation for consistency. An example of that would be:
	//
	//    com.github.diamondburned.cchat-discord
	//    com.github.username.service
	Identifier
	// Namer returns the name of the service.
	Namer

	Authenticate() []Authenticator

	AsConfigurator() Configurator       // Optional
	AsSessionRestorer() SessionRestorer // Optional
}

type Session interface {
	// Identifier should typically return the user ID.
	Identifier
	// Namer gives the name of the session, which is typically the username.
	Namer
	Lister

	// Disconnect asks the service to disconnect. It does not necessarily mean
	// removing the service.
	//
	// The frontend must cancel the active ServerMessage before disconnecting. The
	// backend can rely on this behavior.
	//
	// The frontend will reuse the stored session data from SessionSaver to
	// reconnect.
	//
	// When this function fails, the frontend may display the error upfront.
	// However, it will treat the session as actually disconnected. If needed, the
	// backend must implement reconnection by itself.
	Disconnect(context.Context) error // Blocking, Disposer

	AsCommander() Commander       // Optional
	AsSessionSaver() SessionSaver // Optional
}

type SessionRestorer interface {
	RestoreSession(context.Context, map[string]string) (Session, error) // Blocking
}

type SessionSaver interface {
	SaveSession() map[string]string
}

type Status uint8

type TypingContainer interface {
	// RemoveTyper explicitly removes the typer with the given user ID from the list
	// of typers. This function is usually not needed, as the client will take care
	// of removing them after TypingTimeout has been reached or other conditions
	// listed in ServerMessageTypingIndicator are met.
	RemoveTyper(authorID ID)
	// AddTyper appends the typer (author) into the frontend's list of typers, or it
	// pushes this typer on top of others. The frontend should assume current time
	// every time AddTyper is called.
	AddTyper(User)
}

type TypingIndicator interface {
	// TypingSubscribe subscribes the given indicator to typing events sent by the
	// backend. The added event handlers have to be removed by the backend when the
	// stop() callback is called.
	//
	// This method does not take in a context, as it's supposed to only use event
	// handlers and not do any IO calls. Nonetheless, the client must treat it like
	// it does and call it asynchronously.
	TypingSubscribe(context.Context, TypingContainer) error
	// TypingTimeout returns the interval between typing events sent by the client
	// as well as the timeout before the client should remove the typer. Typically,
	// a constant should be returned.
	TypingTimeout() time.Duration
	// Typing is called by the client to indicate that the user is typing. This
	// function can do IO calls, and the client must take care of calling it in a
	// goroutine (or an asynchronous queue) as well as throttling it to
	// TypingTimeout.
	Typing(context.Context) error // Blocking
}

type UnreadContainer interface {
	// SetUnread sets the container's unread state to the given boolean. The
	// frontend may choose how to represent this.
	SetUnread(unread bool, mentioned bool)
}

type UnreadIndicator interface {
	// UnreadIndicate subscribes the given unread indicator for unread and mention
	// events. Examples include when a new message is arrived and the backend needs
	// to indicate that it's unread.
	//
	// This function must provide a way to remove callbacks, as clients must call
	// this when the old server is destroyed, such as when Servers is called.
	UnreadIndicate(context.Context, UnreadContainer) error
	// MarkRead marks a message in the server messenger as read. Backends that
	// implement the UnreadIndicator interface must give control of marking messages
	// as read to the frontend if possible.
	//
	// This method is assumed to be a setter method that does not error out, because
	// the frontend has no use in knowing the error. As such, marking messages as
	// read is best-effort. The backend is in charge of synchronizing the read state
	// with the server and coordinating it with reasonable rate limits, if needed.
	MarkRead(messageID ID)
}

type User interface {
	Identifier
	Namer
}