diff --git a/cchat.go b/cchat.go index b765003..9f12b31 100644 --- a/cchat.go +++ b/cchat.go @@ -54,8 +54,8 @@ // // Below is an example of checking for an extended interface. // -// if backlogger := server.AsBacklogger(); backlogger != nil { -// println("Server implements Backlogger.") +// if iconer := server.AsIconer(); iconer != nil { +// println("Server implements Iconer.") // } // // @@ -149,80 +149,24 @@ func (e ErrInvalidConfigAtField) Unwrap() error { return e.Err } -// Identifier requires ID() to return a uniquely identifiable string for -// whatever this is embedded into. Typically, servers and messages have IDs. It -// is worth mentioning that IDs should be consistent throughout the lifespan of -// the program or maybe even forever. -type Identifier interface { - ID() ID +// Actioner adds custom message actions into each message. Similarly to +// ServerMessageEditor, some of these methods may do IO. +type Actioner interface { + // DoAction 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. + DoAction(action string, id ID) error // Blocking + // MessageActions returns a list of possible actions 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() []string } -// Namer requires Name() to return the name of the object. Typically, this -// implies usernames for sessions or service names for services. -type Namer interface { - Name() text.Rich - AsIconer() Iconer // Optional -} - -// Iconer adds icon support into Namer, which in turn is returned by other -// interfaces. Typically, Service would return the service logo, Session would -// return the user's avatar, and Server would return the server icon. -// -// For session, the avatar should be the same as the one returned by messages -// sent by the current user. -type Iconer interface { - Icon(context.Context, IconContainer) (stop func(), err error) -} - -// Noncer adds nonce support. A nonce is defined in this context as a unique -// identifier from the frontend. This interface defines the common nonce getter. -// -// Nonces are useful for frontends to know if an incoming event is a reply from -// the server backend. As such, nonces should be roundtripped through the -// server. For example, IRC would use labeled responses. -// -// The Nonce method can return an empty string. This indicates that either the -// frontend or backend (or neither) supports nonces. -// -// Contrary to other interfaces that extend with an "Is" method, the Nonce -// method could return an empty string here. -type Noncer interface { - Nonce() string -} - -// Author is the interface for an identifiable author. The interface defines -// that an author always have an ID and a name. -// -// An example of where this interface is used would be in MessageCreate's Author -// method or embedded in Typer. The returned ID may or may not be used by the -// frontend, but backends must guarantee that the Author's ID is in fact a user -// ID. -// -// The frontend may use the ID to squash messages with the same author together. -type Author interface { - Identifier - Namer -} - -// A service is a complete service that's capable of multiple sessions. It has -// to implement the Authenticate() method, which returns an implementation of -// Authenticator. -// -// A service can implement SessionRestorer, which would indicate the frontend -// that it can restore past sessions. Sessions are saved using the SessionSaver -// interface that Session can implement. -// -// A service can also implement Configurator if it has additional -// configurations. The current API is a flat key-value map, which can be parsed -// by the backend itself into more meaningful data structures. All -// configurations must be optional, as frontends may not implement a -// configurator UI. -type Service interface { - Namer - - Authenticate() Authenticator - AsConfigurator() Configurator // Optional - AsSessionRestorer() SessionRestorer // Optional +// Attachments extends SendableMessage which adds attachments into the message. +// Backends that can use this interface should implement AttachmentSender. +type Attachments interface { + Attachments() []MessageAttachment } // The authenticator interface allows for a multistage initial authentication @@ -247,21 +191,90 @@ type Service interface { // break // success // } type Authenticator interface { - // AuthenticateForm should return a list of authentication entries for the - // frontend to render. - AuthenticateForm() []AuthenticateEntry // Authenticate will be called with a list of values with indices correspond to // the returned slice of AuthenticateEntry. Authenticate([]string) (Session, error) // Blocking + // AuthenticateForm should return a list of authentication entries for the + // frontend to render. + AuthenticateForm() []AuthenticateEntry } -// SessionRestorer extends Service and is called by the frontend to restore a -// saved session. The frontend may call this at any time, but it's usually on -// startup. +// Author is the interface for an identifiable author. The interface defines +// that an author always have an ID and a name. // -// To save a session, refer to SessionSaver. -type SessionRestorer interface { - RestoreSession(map[string]string) (Session, error) // Blocking +// An example of where this interface is used would be in MessageCreate's Author +// method or embedded in Typer. The returned ID may or may not be used by the +// frontend, but backends must guarantee that the Author's ID is in fact a user +// ID. +// +// The frontend may use the ID to squash messages with the same author together. +type Author interface { + Identifier + Namer +} + +// Backlogger adds message history capabilities into a message container. The +// backend should send old messages using the MessageCreate method of the +// MessageContainer, and the frontend should automatically sort messages based +// on the timestamp. +// +// As there is no stop callback, if the backend needs to fetch messages +// asynchronously, it is expected to use the context to know when to cancel. +// +// The frontend should usually call this method when the user scrolls to the +// top. It is expected to guarantee not to call MessagesBefore more than once on +// the same ID. This can usually be done by deactivating the UI. +// +// Note that the optional usage of contexts also apply here. The frontend should +// deactivate the UI when the backend is working. However, the frontend can +// accomodate this by not deactivating until another event is triggered, then +// freeze the UI until the method is cancelled. This works even when the backend +// does not use the context. +type Backlogger interface { + // MessagesBefore 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. + MessagesBefore(ctx context.Context, before ID, msgc MessagesContainer) error // Blocking +} + +// Commander is an optional interface that a session could implement for command +// support. This is different from just intercepting the SendMessage() API, as +// this extends globally to the entire session. +// +// A very primitive use of this API would be to provide additional features that +// are not in cchat through a very basic terminal interface. +type Commander interface { + // RunCommand executes the given command, with the slice being already split + // arguments, similar to os.Args. The function could return an output stream, in + // which the frontend must display it live and close it on EOF. + // + // The function can do IO, and outputs should be written to the given io.Writer. + // + // 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. + RunCommand([]string, io.Writer) error // Blocking + + // Asserters. + + AsCompleter() Completer // Optional +} + +// Completer adds autocompletion into the message composer. IO is not allowed, +// and the backend should do that only in goroutines and update its state for +// future calls. +// +// Frontends could utilize the split package inside utils for splitting words +// and index. This is the de-facto standard implementation for splitting words, +// thus backends can rely on their behaviors. +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 } // Configurator is an interface which the backend can implement for a primitive @@ -269,8 +282,376 @@ type SessionRestorer interface { // to do IO. The frontend should handle this appropriately, including running // them asynchronously. type Configurator interface { - Configuration() (map[string]string, error) // Blocking SetConfiguration(map[string]string) error // Blocking + Configuration() (map[string]string, error) // Blocking +} + +// Editor adds message editing to the messenger. Only EditMessage can do IO. +type Editor interface { + // EditMessage edits the message with the given ID to the given content, which + // is the edited string from RawMessageContent. This method can do IO. + EditMessage(id ID, content string) error // Blocking + // RawMessageContent gets the original message text for editing. This method + // must not do IO. + RawMessageContent(id ID) (string, error) + // MessageEditable returns whether or not a message can be edited by the client. + // This method must not do IO. + MessageEditable(id ID) bool +} + +// IconContainer is a generic interface for any container that can hold an +// image. It's typically used for icons that can update itself. Frontends should +// round these icons. For images that shouldn't be rounded, use ImageContainer. +// +// Methods may call SetIcon at any time in its main thread, so the frontend must +// do any I/O (including downloading the image) in another goroutine to avoid +// blocking the backend. +type IconContainer interface { + SetImage(url string) +} + +// Iconer adds icon support into Namer, which in turn is returned by other +// interfaces. Typically, Service would return the service logo, Session would +// return the user's avatar, and Server would return the server icon. +// +// For session, the avatar should be the same as the one returned by messages +// sent by the current user. +type Iconer interface { + Icon(context.Context, IconContainer) (stop func(), err error) +} + +// Identifier requires ID() to return a uniquely identifiable string for +// whatever this is embedded into. Typically, servers and messages have IDs. It +// is worth mentioning that IDs should be consistent throughout the lifespan of +// the program or maybe even forever. +type Identifier interface { + ID() ID +} + +// LabelContainer is a generic interface for any container that can hold texts. +// It's typically used for rich text labelling for usernames and server names. +// +// Methods that takes in a LabelContainer typically holds it in the state and +// may call SetLabel any time it wants. Thus, the frontend should synchronize +// calls with the main thread if needed. +type LabelContainer interface { + SetLabel(text.Rich) +} + +// ListMember represents a single member in the member list. This is a base +// interface that may implement more interfaces, such as Iconer for the user's +// avatar. +// +// Note that the frontend may give everyone an avatar regardless, or it may not +// show any avatars at all. +type ListMember interface { + Identifier + Namer + + // 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 +} + +// Lister is for servers that contain children servers. This is similar to +// guilds containing channels in Discord, or IRC servers containing channels. +// +// There isn't a similar stop callback API unlike other interfaces because all +// servers are expected to be listed. However, they could be hidden, such as +// collapsing a tree. +// +// The backend should call both the container and other icon and label +// containers, if any. +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(ServersContainer) (err error) +} + +// MemberDynamicSection represents a dynamically loaded member list section. The +// section behaves similarly to MemberSection, except the information displayed +// will be considered incomplete until LoadMore returns false. +// +// LoadLess can be called by the client to mark chunks as stale, which the +// server can then unsubscribe from. +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() 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() bool // Blocking +} + +// MemberListContainer is a generic interface for any container that can display +// a member list. This is similar to Discord's right-side member list or IRC's +// users list. Below is a visual representation of a typical member list +// container: +// +// +-MemberList-----------\ +// | +-Section------------| +// | | | +// | | Header - Total | +// | | | +// | | +-Member-----------| +// | | | Name | +// | | | Secondary | +// | | \__________________| +// | | | +// | | +-Member-----------| +// | | | Name | +// | | | Secondary | +// | | \__________________| +// \_\____________________/ +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. As such, backends must call SetSections first + // before SetMember on a new section. + 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) +} + +// MemberLister adds a member list into a message server. +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) (stop func(), err error) +} + +// MemberSection represents a member list section. The section name's content +// must be unique among other sections from the same list regardless of the rich +// segments. +type MemberSection interface { + Identifier + Namer + + // Total returns the total member count. + Total() int + + // Asserters. + + AsMemberDynamicSection() MemberDynamicSection // Optional +} + +// MessageCreate is the interface for an incoming message. +type MessageCreate interface { + MessageHeader + 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() + Content() text.Rich + Author() Author +} + +// MessageDelete is the interface for a message delete event. +type MessageDelete interface { + MessageHeader +} + +// MessageHeader implements the minimum interface for any message event. +type MessageHeader interface { + Identifier + + Time() time.Time +} + +// MessageUpdate is the interface for a message update (or edit) event. If the +// returned text.Rich returns true for Empty(), then the element shouldn't be +// changed. +type MessageUpdate interface { + MessageHeader + + Content() text.Rich + Author() Author +} + +// MessagesContainer is a view implementation that displays a list of messages +// live. This implements the 3 most common message events: CreateMessage, +// UpdateMessage and DeleteMessage. The frontend must handle all 3. +// +// Since this container interface extends a single Server, the frontend is +// allowed to have multiple views. This is usually done with tabs or splits, but +// the backend should update them all nonetheless. +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) +} + +// Messenger is for servers that contain messages. This is similar to Discord or +// IRC channels. +type Messenger interface { + // JoinServer joins a server that's capable of receiving messages. The server + // may not necessarily support sending messages. + JoinServer(context.Context, MessagesContainer) (stop func(), err error) + + // Asserters. + + AsSender() Sender // Optional + AsEditor() Editor // Optional + AsActioner() Actioner // Optional + AsNicknamer() Nicknamer // Optional + AsBacklogger() Backlogger // Optional + AsMemberLister() MemberLister // Optional + AsUnreadIndicator() UnreadIndicator // Optional + AsTypingIndicator() TypingIndicator // Optional +} + +// Namer requires Name() to return the name of the object. Typically, this +// implies usernames for sessions or service names for services. +type Namer interface { + Name() text.Rich + + // Asserters. + + AsIconer() Iconer // Optional +} + +// Nicknamer adds the current user's nickname. +// +// The frontend will not traverse up the server tree, meaning the backend must +// handle nickname inheritance. This also means that servers that don't +// implement ServerMessage also don't need to implement ServerNickname. By +// default, the session name should be used. +type Nicknamer interface { + Nickname(context.Context, LabelContainer) (stop func(), err error) +} + +// Noncer adds nonce support. A nonce is defined in this context as a unique +// identifier from the frontend. This interface defines the common nonce getter. +// +// Nonces are useful for frontends to know if an incoming event is a reply from +// the server backend. As such, nonces should be roundtripped through the +// server. For example, IRC would use labeled responses. +// +// The Nonce method can return an empty string. This indicates that either the +// frontend or backend (or neither) supports nonces. +// +// Contrary to other interfaces that extend with an "Is" method, the Nonce +// method could return an empty string here. +type Noncer interface { + Nonce() string +} + +// SendableMessage is the bare minimum interface of a sendable message, that is, +// a message that can be sent with SendMessage(). This allows the frontend to +// implement its own message data implementation. +// +// An example of extending this interface is MessageNonce, which is similar to +// IRCv3's labeled response extension or Discord's nonces. The frontend could +// implement this interface and check if incoming MessageCreate events implement +// the same interface. +type SendableMessage interface { + Content() string + + // Asserters. + + AsNoncer() Noncer // Optional + AsAttachments() Attachments // Optional +} + +// Sender adds message sending to a messenger. Messengers that don't implement +// MessageSender will be considered read-only. +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(SendableMessage) error // Blocking + + // Asserters. + + AsCompleter() Completer // Optional +} + +// Server is a single server-like entity that could translate to a guild, a +// channel, a chat-room, and such. A server must implement at least ServerList +// or ServerMessage, else the frontend must treat it as a no-op. +type Server interface { + Identifier + Namer + + // Asserters. + + AsLister() Lister // Optional + AsMessenger() Messenger // Optional + AsCommander() Commander // Optional + AsConfigurator() Configurator // Optional +} + +type ServerUpdate interface { + Server + + // PreviousID returns the ID of the item before this server. + PreviousID() ID +} + +// ServersContainer is any type of view that displays the list of servers. It +// should implement a SetServers([]Server) that the backend could use to call +// anytime the server list changes (at all). +// +// Typically, most frontends should implement this interface onto a tree node, +// as servers can be infinitely nested. Frontends should also reset the entire +// node and its children when SetServers is called again. +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. + SetServers([]Server) +} + +// A service is a complete service that's capable of multiple sessions. It has +// to implement the Authenticate() method, which returns an implementation of +// Authenticator. +// +// A service can implement SessionRestorer, which would indicate the frontend +// that it can restore past sessions. Sessions are saved using the SessionSaver +// interface that Session can implement. +// +// A service can also implement Configurator if it has additional +// configurations. The current API is a flat key-value map, which can be parsed +// by the backend itself into more meaningful data structures. All +// configurations must be optional, as frontends may not implement a +// configurator UI. +type Service interface { + Namer + + Authenticate() Authenticator + + // Asserters. + + AsConfigurator() Configurator // Optional + AsSessionRestorer() SessionRestorer // Optional } // A session is returned after authentication on the service. Session implements @@ -299,11 +680,23 @@ type Session interface { // 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() error // Blocking + Disconnect() error // Blocking + + // Asserters. + AsCommander() Commander // Optional AsSessionSaver() SessionSaver // Optional } +// SessionRestorer extends Service and is called by the frontend to restore a +// saved session. The frontend may call this at any time, but it's usually on +// startup. +// +// To save a session, refer to SessionSaver. +type SessionRestorer interface { + RestoreSession(map[string]string) (Session, error) // Blocking +} + // SessionSaver extends Session and is called by the frontend to save the // current session. This is typically called right after authentication, but a // frontend may call this any time, including when it's closing. @@ -317,136 +710,30 @@ type SessionSaver interface { SaveSession() map[string]string } -// Commander is an optional interface that a session could implement for command -// support. This is different from just intercepting the SendMessage() API, as -// this extends globally to the entire session. +// Typer is an individual user that's typing. This interface is used +// interchangably in TypingIndicator and thus ServerMessageTypingIndicator as +// well. +type Typer interface { + Author + + Time() time.Time +} + +// TypingContainer is a generic interface for any container that can display +// users typing in the current chatbox. The typing indicator must adhere to the +// TypingTimeout returned from ServerMessageTypingIndicator. The backend should +// assume that to be the case and send events appropriately. // -// A very primitive use of this API would be to provide additional features that -// are not in cchat through a very basic terminal interface. -type Commander interface { - // RunCommand executes the given command, with the slice being already split - // arguments, similar to os.Args. The function could return an output stream, in - // which the frontend must display it live and close it on EOF. - // - // The function can do IO, and outputs should be written to the given io.Writer. - // - // 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. - RunCommand([]string, io.Writer) error // Blocking - AsCompleter() Completer // Optional -} - -// Server is a single server-like entity that could translate to a guild, a -// channel, a chat-room, and such. A server must implement at least ServerList -// or ServerMessage, else the frontend must treat it as a no-op. -type Server interface { - Identifier - Namer - - AsLister() Lister // Optional - AsMessenger() Messenger // Optional - AsCommander() Commander // Optional - AsConfigurator() Configurator // Optional -} - -// Lister is for servers that contain children servers. This is similar to -// guilds containing channels in Discord, or IRC servers containing channels. -// -// There isn't a similar stop callback API unlike other interfaces because all -// servers are expected to be listed. However, they could be hidden, such as -// collapsing a tree. -// -// The backend should call both the container and other icon and label -// containers, if any. -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(ServersContainer) (err error) -} - -// Messenger is for servers that contain messages. This is similar to Discord or -// IRC channels. -type Messenger interface { - // JoinServer joins a server that's capable of receiving messages. The server - // may not necessarily support sending messages. - JoinServer(context.Context, MessagesContainer) (stop func(), err error) - AsSender() Sender // Optional - AsEditor() Editor // Optional - AsActioner() Actioner // Optional - AsNicknamer() Nicknamer // Optional - AsMemberLister() MemberLister // Optional - AsUnreadIndicator() UnreadIndicator // Optional - AsTypingIndicator() TypingIndicator // Optional -} - -// Sender adds message sending to a messenger. Messengers that don't implement -// MessageSender will be considered read-only. -type Sender interface { - // Send is called by the frontend to send a message to this channel. - Send(SendableMessage) error // Blocking - // CanAttach returns whether or not the client is allowed to upload files. - CanAttach() bool - AsCompleter() Completer // Optional -} - -// Editor adds message editing to the messenger. Only EditMessage can do IO. -type Editor interface { - // MessageEditable returns whether or not a message can be edited by the client. - // This method must not do IO. - MessageEditable(id ID) bool - // RawMessageContent gets the original message text for editing. This method - // must not do IO. - RawMessageContent(id ID) (string, error) - // EditMessage edits the message with the given ID to the given content, which - // is the edited string from RawMessageContent. This method can do IO. - EditMessage(id ID, content string) error // Blocking -} - -// Actioner adds custom message actions into each message. Similarly to -// ServerMessageEditor, some of these methods may do IO. -type Actioner interface { - // MessageActions returns a list of possible actions 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() []string - // DoAction 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. - DoAction(action string, id ID) error // Blocking -} - -// Nicknamer adds the current user's nickname. -// -// The frontend will not traverse up the server tree, meaning the backend must -// handle nickname inheritance. This also means that servers that don't -// implement ServerMessage also don't need to implement ServerNickname. By -// default, the session name should be used. -type Nicknamer interface { - Nickname(context.Context, LabelContainer) (stop func(), err error) -} - -// MemberLister adds a member list into a message server. -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) (stop func(), err error) -} - -// UnreadIndicator adds an unread state API for frontends to use. -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(UnreadContainer) (stop func(), err error) +// For more documentation, refer to TypingIndicator. +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(typerID ID) + // AddTyper appends the typer into the frontend's list of typers, or it pushes + // this typer on top of others. + AddTyper(typer Typer) } // TypingIndicator optionally extends ServerMessage to provide bidirectional @@ -457,15 +744,6 @@ type UnreadIndicator interface { // user ID, when RemoveTyper() is called by the backend or when the timeout // returned from TypingTimeout() has been reached. type TypingIndicator interface { - // 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() error // Blocking - // 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 // 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. @@ -474,114 +752,15 @@ type TypingIndicator interface { // handlers and not do any IO calls. Nonetheless, the client must treat it like // it does and call it asynchronously. TypingSubscribe(TypingContainer) (stop func(), err error) -} - -// Completer adds autocompletion into the message composer. IO is not allowed, -// and the backend should do that only in goroutines and update its state for -// future calls. -// -// Frontends could utilize the split package inside utils for splitting words -// and index. This is the de-facto standard implementation for splitting words, -// thus backends can rely on their behaviors. -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 -} - -// ServersContainer is any type of view that displays the list of servers. It -// should implement a SetServers([]Server) that the backend could use to call -// anytime the server list changes (at all). -// -// Typically, most frontends should implement this interface onto a tree node, -// as servers can be infinitely nested. Frontends should also reset the entire -// node and its children when SetServers is called again. -type ServersContainer interface { - // 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. - SetServers([]Server) - UpdateServer(ServerUpdate) -} - -type ServerUpdate interface { - Server - - // PreviousID returns the ID of the item before this server. - PreviousID() ID -} - -// MessagesContainer is a view implementation that displays a list of messages -// live. This implements the 3 most common message events: CreateMessage, -// UpdateMessage and DeleteMessage. The frontend must handle all 3. -// -// Since this container interface extends a single Server, the frontend is -// allowed to have multiple views. This is usually done with tabs or splits, but -// the backend should update them all nonetheless. -type MessagesContainer interface { - // 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) - UpdateMessage(MessageUpdate) - DeleteMessage(MessageDelete) -} - -// MessageHeader implements the minimum interface for any message event. -type MessageHeader interface { - Identifier - - Time() time.Time -} - -// MessageCreate is the interface for an incoming message. -type MessageCreate interface { - MessageHeader - Noncer - - Author() Author - Content() text.Rich - // Mentioned returns whether or not the message mentions the current user. If a - // backend does not implement mentioning, then false can be returned. - Mentioned() -} - -// MessageUpdate is the interface for a message update (or edit) event. If the -// returned text.Rich returns true for Empty(), then the element shouldn't be -// changed. -type MessageUpdate interface { - MessageHeader - - Author() Author - Content() text.Rich -} - -// MessageDelete is the interface for a message delete event. -type MessageDelete interface { - MessageHeader -} - -// LabelContainer is a generic interface for any container that can hold texts. -// It's typically used for rich text labelling for usernames and server names. -// -// Methods that takes in a LabelContainer typically holds it in the state and -// may call SetLabel any time it wants. Thus, the frontend should synchronize -// calls with the main thread if needed. -type LabelContainer interface { - SetLabel(text.Rich) -} - -// IconContainer is a generic interface for any container that can hold an -// image. It's typically used for icons that can update itself. Frontends should -// round these icons. For images that shouldn't be rounded, use ImageContainer. -// -// Methods may call SetIcon at any time in its main thread, so the frontend must -// do any I/O (including downloading the image) in another goroutine to avoid -// blocking the backend. -type IconContainer interface { - SetImage(url string) + // 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() error // Blocking } // UnreadContainer is an interface that a single server container (such as a @@ -604,139 +783,13 @@ type UnreadContainer interface { SetUnread(unread bool, mentioned bool) } -// TypingContainer is a generic interface for any container that can display -// users typing in the current chatbox. The typing indicator must adhere to the -// TypingTimeout returned from ServerMessageTypingIndicator. The backend should -// assume that to be the case and send events appropriately. -// -// For more documentation, refer to TypingIndicator. -type TypingContainer interface { - // AddTyper appends the typer into the frontend's list of typers, or it pushes - // this typer on top of others. - AddTyper(typer Typer) - // 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(typerID ID) -} - -// Typer is an individual user that's typing. This interface is used -// interchangably in TypingIndicator and thus ServerMessageTypingIndicator as -// well. -type Typer interface { - Author - - Time() time.Time -} - -// MemberListContainer is a generic interface for any container that can display -// a member list. This is similar to Discord's right-side member list or IRC's -// users list. Below is a visual representation of a typical member list -// container: -// -// +-MemberList-----------\ -// | +-Section------------| -// | | | -// | | Header - Total | -// | | | -// | | +-Member-----------| -// | | | Name | -// | | | Secondary | -// | | \__________________| -// | | | -// | | +-Member-----------| -// | | | Name | -// | | | Secondary | -// | | \__________________| -// \_\____________________/ -type MemberListContainer interface { - // 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) - // 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. As such, backends must call SetSections first - // before SetMember on a new section. - SetMember(sectionID ID, member ListMember) - // 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) -} - -// ListMember represents a single member in the member list. This is a base -// interface that may implement more interfaces, such as Iconer for the user's -// avatar. -// -// Note that the frontend may give everyone an avatar regardless, or it may not -// show any avatars at all. -type ListMember interface { - Identifier - Namer - - // 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 - // Secondary returns the subtext of this member. This could be anything, such as - // a user's custom status or away reason. - Secondary() text.Rich -} - -// MemberSection represents a member list section. The section name's content -// must be unique among other sections from the same list regardless of the rich -// segments. -type MemberSection interface { - Identifier - Namer - - // Total returns the total member count. - Total() int - AsMemberDynamicSection() MemberDynamicSection // Optional -} - -// MemberDynamicSection represents a dynamically loaded member list section. The -// section behaves similarly to MemberSection, except the information displayed -// will be considered incomplete until LoadMore returns false. -// -// LoadLess can be called by the client to mark chunks as stale, which the -// server can then unsubscribe from. -type MemberDynamicSection interface { - // LoadMore is a method which the client can call to ask for more members. This - // method can do IO. +// UnreadIndicator adds an unread state API for frontends to use. +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. // - // 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() bool // Blocking - // 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() bool // Blocking -} - -// SendableMessage is the bare minimum interface of a sendable message, that is, -// a message that can be sent with SendMessage(). This allows the frontend to -// implement its own message data implementation. -// -// An example of extending this interface is MessageNonce, which is similar to -// IRCv3's labeled response extension or Discord's nonces. The frontend could -// implement this interface and check if incoming MessageCreate events implement -// the same interface. -type SendableMessage interface { - Content() string - AsNoncer() Noncer // Optional - AsAttachments() Attachments // Optional -} - -// Attachments extends SendableMessage which adds attachments into the message. -// Backends that can use this interface should implement AttachmentSender. -type Attachments interface { - Attachments() []MessageAttachment + // 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(UnreadContainer) (stop func(), err error) } diff --git a/cmd/cchat-generator/generate_enum.go b/cmd/cchat-generator/generate_enum.go index 068f7ca..8fd31b7 100644 --- a/cmd/cchat-generator/generate_enum.go +++ b/cmd/cchat-generator/generate_enum.go @@ -1,11 +1,17 @@ package main import ( + "sort" + "github.com/dave/jennifer/jen" "github.com/diamondburned/cchat/repository" ) func generateEnums(enums []repository.Enumeration) jen.Code { + sort.Slice(enums, func(i, j int) bool { + return enums[i].Name < enums[j].Name + }) + var stmt = new(jen.Statement) for _, enum := range enums { diff --git a/cmd/cchat-generator/generate_interface.go b/cmd/cchat-generator/generate_interface.go index 472be92..254d766 100644 --- a/cmd/cchat-generator/generate_interface.go +++ b/cmd/cchat-generator/generate_interface.go @@ -1,11 +1,17 @@ package main import ( + "sort" + "github.com/dave/jennifer/jen" "github.com/diamondburned/cchat/repository" ) func generateInterfaces(ifaces []repository.Interface) jen.Code { + sort.Slice(ifaces, func(i, j int) bool { + return ifaces[i].Name < ifaces[j].Name + }) + var stmt = new(jen.Statement) for _, iface := range ifaces { @@ -23,7 +29,25 @@ func generateInterfaces(ifaces []repository.Interface) jen.Code { group.Line() } + // Put Asserter methods last. + sort.SliceStable(iface.Methods, func(i, j int) bool { + _, assert := iface.Methods[i].(repository.AsserterMethod) + return !assert + }) + + // Boolean to only write the Asserter comment once. + var writtenComment bool + for _, method := range iface.Methods { + if !writtenComment { + if _, ok := method.(repository.AsserterMethod); ok { + group.Line() + group.Comment("// Asserters.") + group.Line() + writtenComment = true + } + } + var stmt = new(jen.Statement) if comment := method.UnderlyingComment(); !comment.IsEmpty() { stmt.Comment(comment.GoString(1)) diff --git a/cmd/cchat-generator/generate_struct.go b/cmd/cchat-generator/generate_struct.go index d4bd24d..349cc81 100644 --- a/cmd/cchat-generator/generate_struct.go +++ b/cmd/cchat-generator/generate_struct.go @@ -1,11 +1,17 @@ package main import ( + "sort" + "github.com/dave/jennifer/jen" "github.com/diamondburned/cchat/repository" ) func generateStructs(structs []repository.Struct) jen.Code { + sort.Slice(structs, func(i, j int) bool { + return structs[i].Name < structs[j].Name + }) + var stmt = new(jen.Statement) for _, s := range structs { @@ -18,6 +24,10 @@ func generateStructs(structs []repository.Struct) jen.Code { } func generateErrorStructs(errStructs []repository.ErrorStruct) jen.Code { + sort.Slice(errStructs, func(i, j int) bool { + return errStructs[i].Name < errStructs[j].Name + }) + var stmt = new(jen.Statement) for _, errStruct := range errStructs { diff --git a/cmd/cchat-generator/generate_type.go b/cmd/cchat-generator/generate_type.go index cbd6999..1e03536 100644 --- a/cmd/cchat-generator/generate_type.go +++ b/cmd/cchat-generator/generate_type.go @@ -1,11 +1,17 @@ package main import ( + "sort" + "github.com/dave/jennifer/jen" "github.com/diamondburned/cchat/repository" ) func generateTypeAlises(aliases []repository.TypeAlias) jen.Code { + sort.Slice(aliases, func(i, j int) bool { + return aliases[i].Name < aliases[j].Name + }) + var stmt = new(jen.Statement) for _, alias := range aliases { diff --git a/repository/gob/repository.gob b/repository/gob/repository.gob index 6624070..4da324f 100644 Binary files a/repository/gob/repository.gob and b/repository/gob/repository.gob differ diff --git a/repository/main.go b/repository/main.go index 9845a36..2f35bee 100644 --- a/repository/main.go +++ b/repository/main.go @@ -191,7 +191,7 @@ var Main = Packages{ Mentioner implies that the segment can be clickable, and when clicked it should open up a dialog containing information from MentionInfo(). - + It is worth mentioning that frontends should assume whatever segment that Mentioner highlighted to be the display name of that user. This would allow frontends to flexibly layout the @@ -290,7 +290,7 @@ var Main = Packages{ Codeblocker is a codeblock that supports optional syntax highlighting using the language given. Note that as this is a block, it will appear separately from the rest of the paragraph. - + This interface is equivalent to Markdown's codeblock syntax. `}, Name: "Codeblocker", @@ -333,21 +333,21 @@ var Main = Packages{ Comment: Comment{` Package cchat is a set of stabilized interfaces for cchat implementations, joining the backend and frontend together. - + Backend - + Methods implemented by the backend that have frontend containers as arguments can do IO. Frontends must NOT rely on individual backend states and should always assume that they will block. - + Methods that do not return an error must NOT do any IO to prevent blocking the main thread. As such, ID() and Name() must never do any IO. Methods that do return an error may do IO, but they should be documented per method. - + Backend implementations have certain conditions that should be adhered to: - + - Storing MessagesContainer and ServersContainer are advised against; however, they should be done if need be. - Other containers such as LabelContainer and IconContainer @@ -361,46 +361,46 @@ var Main = Packages{ - Some methods that take in a container may take in a context as well. Although implementations don't have to use this context, it should try to. - + Note: IO in most cases usually refer to networking, but they should files and anything that is blocking, such as mutexes or semaphores. - + Note: As mentioned above, contexts are optional for both the frontend and backend. The frontend may use it for cancellation, and the backend may ignore it. - + Some interfaces can be extended. Interfaces that are extendable will have methods starting with "As" and returns another interface type. The implementation may or may not return the same struct as the interface, but the caller should not have to type assert it to a struct. They can also return nil, which should indicate the backend that the feature is not implemented. - + To avoid confusing, when said "A implements B," it is mostly assumed that A has a method named "AsB." It does not mean that A can be type-asserted to B. - + For future references, these "As" methods will be called asserter methods. - + Note: Backends must not do IO in the "As" methods. Most of the time, it should only conditionally check the local state and return value or nil. - + Below is an example of checking for an extended interface. - - if backlogger := server.AsBacklogger(); backlogger != nil { - println("Server implements Backlogger.") + + if iconer := server.AsIconer(); iconer != nil { + println("Server implements Iconer.") } - + Frontend - + Frontend contains all interfaces that a frontend can or must implement. The backend may call these methods any time from any goroutine. Thus, they should be thread-safe. They should also not block the call by doing so, as backends may call these methods in its own main thread. - + It is worth pointing out that frontend container interfaces will not have an error handling API, as frontends can do that themselves. Errors returned by backend methods will be errors from the @@ -558,7 +558,7 @@ var Main = Packages{ by other interfaces. Typically, Service would return the service logo, Session would return the user's avatar, and Server would return the server icon. - + For session, the avatar should be the same as the one returned by messages sent by the current user. `}, @@ -576,15 +576,15 @@ var Main = Packages{ Noncer adds nonce support. A nonce is defined in this context as a unique identifier from the frontend. This interface defines the common nonce getter. - + Nonces are useful for frontends to know if an incoming event is a reply from the server backend. As such, nonces should be roundtripped through the server. For example, IRC would use labeled responses. - + The Nonce method can return an empty string. This indicates that either the frontend or backend (or neither) supports nonces. - + Contrary to other interfaces that extend with an "Is" method, the Nonce method could return an empty string here. `}, @@ -599,12 +599,12 @@ var Main = Packages{ Comment: Comment{` Author is the interface for an identifiable author. The interface defines that an author always have an ID and a name. - + An example of where this interface is used would be in MessageCreate's Author method or embedded in Typer. The returned ID may or may not be used by the frontend, but backends must guarantee that the Author's ID is in fact a user ID. - + The frontend may use the ID to squash messages with the same author together. `}, @@ -618,12 +618,12 @@ var Main = Packages{ A service is a complete service that's capable of multiple sessions. It has to implement the Authenticate() method, which returns an implementation of Authenticator. - + A service can implement SessionRestorer, which would indicate the frontend that it can restore past sessions. Sessions are saved using the SessionSaver interface that Session can implement. - + A service can also implement Configurator if it has additional configurations. The current API is a flat key-value map, which can be parsed by the backend itself into more meaningful data @@ -704,7 +704,7 @@ var Main = Packages{ SessionRestorer extends Service and is called by the frontend to restore a saved session. The frontend may call this at any time, but it's usually on startup. - + To save a session, refer to SessionSaver. `}, Name: "SessionRestorer", @@ -743,7 +743,7 @@ var Main = Packages{ most of the time. It also implements ID(), which might be used by frontends to check against MessageAuthor.ID() and other things. - + A session can implement SessionSaver, which would allow the frontend to save the session into its keyring at any time. Whether the keyring is completely secure or not is up to the @@ -771,14 +771,14 @@ var Main = Packages{ Comment: Comment{` 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 @@ -797,10 +797,10 @@ var Main = Packages{ save the current session. This is typically called right after authentication, but a frontend may call this any time, including when it's closing. - + The frontend can ask to restore a session using SessionRestorer, which extends Service. - + The SaveSession method must not do IO; if there are any reasons that cause SaveSession to fail, then a nil map should be returned. @@ -818,7 +818,7 @@ var Main = Packages{ implement for command support. This is different from just intercepting the SendMessage() API, as this extends globally to the entire session. - + A very primitive use of this API would be to provide additional features that are not in cchat through a very basic terminal interface. @@ -833,10 +833,10 @@ var Main = Packages{ os.Args. The function could return an output stream, in which the frontend must display it live and close it on EOF. - + The function can do IO, and outputs should be written to the given io.Writer. - + 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 @@ -875,11 +875,11 @@ var Main = Packages{ Lister is for servers that contain children servers. This is similar to guilds containing channels in Discord, or IRC servers containing channels. - + There isn't a similar stop callback API unlike other interfaces because all servers are expected to be listed. However, they could be hidden, such as collapsing a tree. - + The backend should call both the container and other icon and label containers, if any. `}, @@ -922,6 +922,7 @@ var Main = Packages{ AsserterMethod{ChildType: "Editor"}, AsserterMethod{ChildType: "Actioner"}, AsserterMethod{ChildType: "Nicknamer"}, + AsserterMethod{ChildType: "Backlogger"}, AsserterMethod{ChildType: "MemberLister"}, AsserterMethod{ChildType: "UnreadIndicator"}, AsserterMethod{ChildType: "TypingIndicator"}, @@ -1018,7 +1019,7 @@ var Main = Packages{ MessageActions returns a list of possible actions 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. `}, Name: "Actions", @@ -1046,7 +1047,7 @@ var Main = Packages{ }, { Comment: Comment{` Nicknamer adds the current user's nickname. - + The frontend will not traverse up the server tree, meaning the backend must handle nickname inheritance. This also means that servers that don't implement ServerMessage also don't need to @@ -1062,6 +1063,51 @@ var Main = Packages{ HasStopFn: true, }, }, + }, { + Comment: Comment{` + Backlogger adds message history capabilities into a message + container. The backend should send old messages using the + MessageCreate method of the MessageContainer, and the frontend + should automatically sort messages based on the timestamp. + + As there is no stop callback, if the backend needs to fetch + messages asynchronously, it is expected to use the context to + know when to cancel. + + The frontend should usually call this method when the user + scrolls to the top. It is expected to guarantee not to call + MessagesBefore more than once on the same ID. This can usually + be done by deactivating the UI. + + Note that the optional usage of contexts also apply here. The + frontend should deactivate the UI when the backend is working. + However, the frontend can accomodate this by not deactivating + until another event is triggered, then freeze the UI until the + method is cancelled. This works even when the backend does not + use the context. + `}, + Name: "Backlogger", + Methods: []Method{ + IOMethod{ // technically a ContainerMethod. + method: method{ + Comment: Comment{` + MessagesBefore 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. + `}, + Name: "MessagesBefore", + }, + Parameters: []NamedType{ + {"ctx", "context.Context"}, + {"before", "ID"}, + {"msgc", "MessagesContainer"}, + }, + ReturnError: true, + }, + }, }, { Comment: Comment{` MemberLister adds a member list into a message server. @@ -1076,7 +1122,7 @@ var Main = Packages{ 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. `}, @@ -1100,7 +1146,7 @@ var Main = Packages{ 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. @@ -1116,7 +1162,7 @@ var Main = Packages{ TypingIndicator optionally extends ServerMessage to provide bidirectional typing indicating capabilities. This is similar to typing events on Discord and typing client tags on IRCv3. - + The client should remove a typer when a message is received with the same user ID, when RemoveTyper() is called by the backend or when the timeout returned from TypingTimeout() has been reached. @@ -1155,7 +1201,7 @@ var Main = Packages{ 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 @@ -1172,7 +1218,7 @@ var Main = Packages{ Completer adds autocompletion into the message composer. IO is not allowed, and the backend should do that only in goroutines and update its state for future calls. - + Frontends could utilize the split package inside utils for splitting words and index. This is the de-facto standard implementation for splitting words, thus backends can rely on @@ -1206,7 +1252,7 @@ var Main = Packages{ servers. It should implement a SetServers([]Server) that the backend could use to call anytime the server list changes (at all). - + Typically, most frontends should implement this interface onto a tree node, as servers can be infinitely nested. Frontends should also reset the entire node and its children when SetServers is @@ -1262,7 +1308,7 @@ var Main = Packages{ of messages live. This implements the 3 most common message events: CreateMessage, UpdateMessage and DeleteMessage. The frontend must handle all 3. - + Since this container interface extends a single Server, the frontend is allowed to have multiple views. This is usually done with tabs or splits, but the backend should update them all @@ -1365,7 +1411,7 @@ var Main = Packages{ LabelContainer is a generic interface for any container that can hold texts. It's typically used for rich text labelling for usernames and server names. - + Methods that takes in a LabelContainer typically holds it in the state and may call SetLabel any time it wants. Thus, the frontend should synchronize calls with the main thread if @@ -1386,7 +1432,7 @@ var Main = Packages{ hold an image. It's typically used for icons that can update itself. Frontends should round these icons. For images that shouldn't be rounded, use ImageContainer. - + Methods may call SetIcon at any time in its main thread, so the frontend must do any I/O (including downloading the image) in another goroutine to avoid blocking the backend. @@ -1403,13 +1449,13 @@ var Main = Packages{ UnreadContainer is an interface that a single server container (such as a button or a tree node) can implement if it's capable of indicating the read and mentioned status for that channel. - + Server containers that implement this has to implement both SetUnread and SetMentioned, and they should also represent those statuses differently. For example, a mentioned channel could have a red outline, while an unread channel could appear brighter. - + Server containers are expected to represent this information in their parent nodes as well. For example, if a server is unread, then its parent servers as well as the session node should @@ -1440,7 +1486,7 @@ var Main = Packages{ users typing in the current chatbox. The typing indicator must adhere to the TypingTimeout returned from ServerMessageTypingIndicator. The backend should assume that to be the case and send events appropriately. - + For more documentation, refer to TypingIndicator. `}, Name: "TypingContainer", @@ -1490,7 +1536,7 @@ var Main = Packages{ that can display a member list. This is similar to Discord's right-side member list or IRC's users list. Below is a visual representation of a typical member list container: - + +-MemberList-----------\ | +-Section------------| | | | @@ -1563,7 +1609,7 @@ var Main = Packages{ ListMember represents a single member in the member list. This is a base interface that may implement more interfaces, such as Iconer for the user's avatar. - + Note that the frontend may give everyone an avatar regardless, or it may not show any avatars at all. `}, @@ -1637,7 +1683,7 @@ var Main = Packages{ section. The section behaves similarly to MemberSection, except the information displayed will be considered incomplete until LoadMore returns false. - + LoadLess can be called by the client to mark chunks as stale, which the server can then unsubscribe from. `}, @@ -1648,7 +1694,7 @@ var Main = Packages{ Comment: Comment{` 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 @@ -1665,7 +1711,7 @@ var Main = Packages{ 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 @@ -1683,7 +1729,7 @@ var Main = Packages{ message, that is, a message that can be sent with SendMessage(). This allows the frontend to implement its own message data implementation. - + An example of extending this interface is MessageNonce, which is similar to IRCv3's labeled response extension or Discord's nonces. The frontend could implement this interface and check if diff --git a/text/text.go b/text/text.go index 50abe3b..2c5e19d 100644 --- a/text/text.go +++ b/text/text.go @@ -37,15 +37,62 @@ type Rich struct { Segments []Segment } -// Segment is the minimum requirement for a format segment. Frontends will use -// this to determine when the format starts and ends. They will also assert this -// interface to any other formatting interface, including Linker, Colorer and -// Attributor. +// Attributor is a rich text markup format that a segment could implement. This +// is to be applied directly onto the text. +type Attributor interface { + Mentioner + + Attribute() Attribute +} + +// Avatarer implies the segment should be replaced with a rounded-corners image. +// This works similarly to Imager. +type Avatarer interface { + Segment + + // AvatarText returns the underlying text of the image. Frontends could use this + // for hovering or displaying the text instead of the image. + AvatarText() string + // AvatarSize returns the requested dimension for the image. This function could + // return (0, 0), which the frontend should use the avatar's dimensions. + AvatarSize() (size int) + // Avatar returns the URL for the image. + Avatar() (url string) +} + +// Codeblocker is a codeblock that supports optional syntax highlighting using +// the language given. Note that as this is a block, it will appear separately +// from the rest of the paragraph. // -// Note that a segment may implement multiple interfaces. For example, a -// Mentioner may also implement Colorer. -type Segment interface { - Bounds() (start int, end int) +// This interface is equivalent to Markdown's codeblock syntax. +type Codeblocker interface { + Segment + + CodeblockLanguage() (language string) +} + +// Colorer is a text color format that a segment could implement. This is to be +// applied directly onto the text. +type Colorer interface { + Mentioner + + // Color returns a 24-bit RGB or 32-bit RGBA color. + Color() uint32 +} + +// Imager implies the segment should be replaced with a (possibly inlined) +// image. Only the starting bound matters, as images cannot substitute texts. +type Imager interface { + Segment + + // ImageText returns the underlying text of the image. Frontends could use this + // for hovering or displaying the text instead of the image. + ImageText() string + // ImageSize returns the requested dimension for the image. This function could + // return (0, 0), which the frontend should use the image's dimensions. + ImageSize() (w int, h int) + // Image returns the URL for the image. + Image() (url string) } // Linker is a hyperlink format that a segment could implement. This implies @@ -57,36 +104,6 @@ type Linker interface { Link() (url string) } -// Imager implies the segment should be replaced with a (possibly inlined) -// image. Only the starting bound matters, as images cannot substitute texts. -type Imager interface { - Segment - - // Image returns the URL for the image. - Image() (url string) - // ImageSize returns the requested dimension for the image. This function could - // return (0, 0), which the frontend should use the image's dimensions. - ImageSize() (w int, h int) - // ImageText returns the underlying text of the image. Frontends could use this - // for hovering or displaying the text instead of the image. - ImageText() string -} - -// Avatarer implies the segment should be replaced with a rounded-corners image. -// This works similarly to Imager. -type Avatarer interface { - Segment - - // Avatar returns the URL for the image. - Avatar() (url string) - // AvatarSize returns the requested dimension for the image. This function could - // return (0, 0), which the frontend should use the avatar's dimensions. - AvatarSize() (size int) - // AvatarText returns the underlying text of the image. Frontends could use this - // for hovering or displaying the text instead of the image. - AvatarText() string -} - // Mentioner implies that the segment can be clickable, and when clicked it // should open up a dialog containing information from MentionInfo(). // @@ -101,16 +118,6 @@ type Mentioner interface { MentionInfo() Rich } -// MentionerImage extends Mentioner to give the mentioned object an image. This -// interface allows the frontend to be more flexible in layouting. A Mentioner -// can only implement EITHER MentionedImage or MentionedAvatar. -type MentionerImage interface { - Mentioner - - // Image returns the mentioned object's image URL. - Image() (url string) -} - // MentionerAvatar extends Mentioner to give the mentioned object an avatar. // This interface allows the frontend to be more flexible in layouting. A // Mentioner can only implement EITHER MentionedImage or MentionedAvatar. @@ -121,32 +128,14 @@ type MentionerAvatar interface { Avatar() (url string) } -// Colorer is a text color format that a segment could implement. This is to be -// applied directly onto the text. -type Colorer interface { +// MentionerImage extends Mentioner to give the mentioned object an image. This +// interface allows the frontend to be more flexible in layouting. A Mentioner +// can only implement EITHER MentionedImage or MentionedAvatar. +type MentionerImage interface { Mentioner - // Color returns a 24-bit RGB or 32-bit RGBA color. - Color() uint32 -} - -// Attributor is a rich text markup format that a segment could implement. This -// is to be applied directly onto the text. -type Attributor interface { - Mentioner - - Attribute() Attribute -} - -// Codeblocker is a codeblock that supports optional syntax highlighting using -// the language given. Note that as this is a block, it will appear separately -// from the rest of the paragraph. -// -// This interface is equivalent to Markdown's codeblock syntax. -type Codeblocker interface { - Segment - - CodeblockLanguage() (language string) + // Image returns the mentioned object's image URL. + Image() (url string) } // Quoteblocker represents a quoteblock that behaves similarly to the blockquote @@ -160,3 +149,14 @@ type Quoteblocker interface { // information to format the quote properly. QuotePrefix() (prefix string) } + +// Segment is the minimum requirement for a format segment. Frontends will use +// this to determine when the format starts and ends. They will also assert this +// interface to any other formatting interface, including Linker, Colorer and +// Attributor. +// +// Note that a segment may implement multiple interfaces. For example, a +// Mentioner may also implement Colorer. +type Segment interface { + Bounds() (start int, end int) +}