Revolt Frontend

Welcome to the developer documentation for the Revolt frontend.

This is very much incomplete and needs more work!

Feature Matrix

Comparison of implemented features across Revolt's clients.

Category	Subcategory	Feature		Revite	Frontend	Android	iOS	Priority
Authorisation	Login		Log into an account	✅	✅	✅	✅	P0 Must
			Create an account	✅	✅	✅	✅	P0 Must
			Send password reset	✅	✅	❌	✅	P0 Must
			Resend email verification	✅	✅	❌	✅	P0 Must
			Confirm password reset	✅	❌	❌	❌	Unapplicable
			Confirm email verification	✅	❌	⛔	❌	Unapplicable
			Confirm account deletion	✅	❌	⛔	❌	Unapplicable
	Multi-Factor Authentication		Use Password	✅	✅	✅	✅	P0 Must
			Use TOTP	✅	✅	✅	✅	P0 Must
			Use Recovery	✅	✅	✅	✅	P0 Must
	Session Lifecycle		Spec Compliant	❌	🚧	✅	❌	P0 Must
Home	General	Home	Launch Page	✅	✅	✅	✅	P0 Must
			Saved Notes	✅	✅	✅	✅	P0 Must
		Friends	List Friends & Blocked	✅	✅	✅	✅	P0 Must
			List Pending Requests	✅	🚧	✅	✅	P0 Must
			Accept Requests	✅	🚧	✅	✅	P0 Must
			Send Requests	✅	🚧	✅	✅	P0 Must
			Remove / Block Users	✅	🚧	✅	✅	P0 Must
			Unblock Users	✅	🚧	✅	✅	P0 Must
			Quick Actions for Users	✅	✅	✅	✅	P0 Must
		User Profile	Show Profile	✅	❌	✅	✅	P0 Must
			Mutual Friends	✅	❌	❌	❌	P1 Preferred
			Mutual Groups	✅	❌	❌	❌	P1 Preferred
			Mutual Servers	✅	❌	❌	❌	P1 Preferred
		Groups	List Conversations	✅	✅	✅	✅	P0 Must
			Create Group	✅	✅	✅	✅	P0 Must
			Show Group Members	✅	✅	✅	✅	P0 Must
			Edit Settings	✅	❌	✅	❌	P0 Must
Servers	Server List		User Home	✅	✅	✅	✅	P0 Must
			Unread Conversations	✅	✅	✅	✅	P0 Must
			List Servers	✅	✅	✅	✅	P0 Must
			Reorder Servers	✅	🚧	❌	❌	P1 Preferred
			Create Server	✅	✅	✅	❌	P0 Must
			Join Server	✅	✅	✅	✅	P0 Must
			Revolt Discover	✅	❌	✅	✅	P0 Must
	Roles		Coloured Usernames	✅	✅	✅	✅	P0 Must
	Users		Change Server Avatar	✅	❌	❌	❌	P1 Preferred
			Change Nickname	✅	✅	❌	❌	P1 Preferred
	Settings	Basic Information	Update Information	✅	❌	❌	❌	P1 Preferred
			Update Icon	✅	❌	❌	❌	P1 Preferred
			Update Banner	✅	❌	❌	❌	P1 Preferred
			Update System Message Targets	✅	❌	❌	❌	P1 Preferred
			Update Categories	✅	❌	❌	❌	P1 Preferred
		Roles	Create Role	✅	❌	❌	❌	P1 Preferred
			List Roles	✅	❌	❌	❌	P1 Preferred
			Delete Role	✅	❌	❌	❌	P1 Preferred
			Update Role Information	✅	❌	❌	❌	P1 Preferred
			Update Permissions	✅	❌	❌	❌	P1 Preferred
		Customisation	Create Emoji	✅	❌	❌	❌	P2 Best Effort
			List Emoji	✅	❌	❌	❌	P2 Best Effort
			Delete Emoji	✅	❌	❌	❌	P2 Best Effort
		Users	List Members	✅	❌	❌	❌	P2 Best Effort
			Set Roles	✅	❌	❌	❌	P2 Best Effort
			Create Invite	✅	✅	✅	✅	P0 Must
			List Invite	✅	❌	❌	❌	P2 Best Effort
			Delete Invite	✅	❌	❌	❌	P2 Best Effort
		Bans	List Bans	✅	❌	❌	❌	P1 Preferred
			Pardon User	✅	❌	❌	❌	P1 Preferred
		Delete Server		✅	✅	❌	❌	P1 Preferred
Channels	Interface	Channel Information	View Channel Description	✅	❌	✅	✅	P1 Preferred
			Age Gate	✅	❌	✅	✅	P0 Must
	Server	Left Sidebar	Server Information	✅	✅	✅	✅	P0 Must
			View Server Description	✅	❌	✅	✅	P1 Preferred
			List Channels	✅	✅	✅	✅	P0 Must
			Channel Categories	✅	✅	✅	✅	P0 Must
			Channel Icons	✅	✅	✅	✅	P1 Preferred
		Member List	View Members	✅	✅	✅	✅	P0 Must
			Hoisted Roles	✅	✅	✅	✅	P0 Must
	Messaging (Text Channel)	Read Messages	Load Recent Messages	✅	✅	✅	✅	P0 Must
			Inline Badges	🚧	✅	✅	🚧	P1 Preferred
			Inline Pronouns	❌	🚧	❌	❌	Unapplicable
			Masquerade	✅	✅	✅	✅	P1 Preferred
			Show Mentions	✅	✅	✅	✅	P0 Must
			Show Channel Links	✅	✅	✅	✅	P0 Must
			Show Server Links	❌	❌	❌	❌	P3 Unimportant
			Show Message Links	❌	❌	❌	❌	P3 Unimportant
			Show Replies	✅	✅	✅	✅	P0 Must
			Show Reactions	✅	✅	✅	✅	P0 Must
			Attachments	✅	🚧	✅	✅	P0 Must
			Embeds	✅	🚧	✅	✅	P0 Must
			System	✅	✅	✅	🚧	P1 Preferred
			Invites	✅	❌	❌	❌	P1 Preferred
		Quick Actions	Reply	✅	✅	✅	✅	P0 Must
			React	✅	❌	✅	✅	P1 Preferred
			Copy Text	✅	✅	✅	✅	P0 Must
			Copy Link	✅	✅	✅	✅	P0 Must
			Copy ID	✅	✅	✅	✅	P0 Must
			Mark as unread	✅	✅	✅	❌	P1 Preferred
			Quote	✅	⛔	⛔	⛔	P3 Unimportant
			Edit	✅	❌	✅	✅	P0 Must
			Delete	✅	✅	✅	✅	P0 Must
		Read Chat History	Load Older Messages	✅	✅	✅	✅	P0 Must
			Jump to End	✅	✅	✅	❌	P1 Preferred
			Jump to Message	✅	✅	❌	✅	P2 Best Effort
			Search Messages	✅	❌	❌	❌	P2 Best Effort
		Message Composition	Send Messages	✅	✅	✅	✅	P0 Must
			Reply to Messages	✅	✅	✅	✅	P0 Must
			Pick Emoji	✅	❌	✅	✅	P2 Best Effort
			Pick GIF	❌	🚧	❌	❌	P3 Unimportant
			Autocomplete Channel	✅	🚧	✅	✅	P1 Preferred
			Autocomplete User	✅	🚧	✅	✅	P1 Preferred
			Autocomplete Emoji	✅	🚧	✅	✅	P1 Preferred
			Send Files	✅	✅	✅	✅	P0 Must
			Preview files to send	✅	🚧	❌	✅	P1 Preferred
			Show messages being sent	✅	❌	❌	❌	P1 Preferred
			Retry sending failed messages	✅	❌	❌	❌	P2 Best Effort
			Show attachments being sent	✅	❌	❌	❌	P2 Best Effort
			Cancel message being sent	❌	❌	❌	❌	P3 Unimportant
	Settings		Update Information	✅	❌	❌	❌	P2 Best Effort
			Set Icon	✅	❌	❌	❌	P2 Best Effort
			Edit Role Permissions	✅	❌	❌	❌	P2 Best Effort
			Edit Group Permissions	✅	❌	❌	❌	P2 Best Effort
Markdown	RSM		Basic Styles	✅	✅	✅	✅	P0 Must
			Code Blocks	✅	✅	✅	❌	P1 Preferred
			Code Formatting	✅	❌	✅	❌	P1 Preferred
			Block Quotes	✅	✅	❌	❌	P1 Preferred
			Spoilers	✅	✅	❌	❌	P1 Preferred
			Links	✅	✅	✅	✅	P1 Preferred
			Headings	✅	✅	❌	❌	P2 Best Effort
			Tables	✅	✅	❌	❌	P2 Best Effort
			Lists	✅	✅	❌	❌	P2 Best Effort
			KaTeX	✅	❌	❌	❌	P2 Best Effort
			Timestamps	✅	✅	✅	❌	P2 Best Effort
			Unicode Emoji	❌	✅	✅	✅	P1 Preferred
			Custom Emoji	✅	✅	✅	🚧	P1 Preferred
User Safety	Reporting		Report Message	✅	✅	✅	✅	P0 Must
			Report Server	✅	✅	✅	❌	P0 Must
			Report User	✅	✅	✅	❌	P0 Must
Settings	User	Account	Update Username	✅	❌	❌	✅	P1 Preferred
			Update Email	✅	❌	❌	✅	P1 Preferred
			Update Password	✅	❌	❌	✅	P1 Preferred
			Configure MFA Recovery	✅	❌	❌	✅	P2 Best Effort
			Configure MFA TOTP	✅	❌	❌	✅	P2 Best Effort
			Disable Account	✅	✅	❌	✅	P0 Must
			Delete Account	✅	✅	❌	✅	P0 Must
		Profile	Update Avatar	✅	❌	✅	❌	P1 Preferred
			Update Background	✅	❌	✅	❌	P1 Preferred
			Update Bio	✅	❌	✅	❌	P1 Preferred
		Sessions	List Sessions	✅	❌	✅	✅	P2 Best Effort
			Delete Session	✅	❌	✅	✅	P2 Best Effort
			Log out all other sessions	✅	❌	✅	❌	P2 Best Effort
	Client	Appearance	Customise Theme	✅	❌	✅	✅	P2 Best Effort
			Customise Font	✅	❌	⛔	⛔	P3 Unimportant
			Customise Emoji Pack	✅	❌	⛔	⛔	P3 Unimportant
		Notifications	Desktop	✅	❌	⛔	⛔	P0 Must
			Web Push	✅	⛔	⛔	N/A	P0 Must
			Desktop Native Push	⛔	❌	⛔	⛔	P3 Unimportant
			Mobile Native Push	⛔	⛔	❌	✅	P0 Must
		Language		✅	❌	✅	✅	P2 Best Effort
		Settings Sync		✅	❌	✅	❌	P0 Must
		Desktop	Start with Computer	✅	❌	N/A	N/A	P2 Best Effort
			Minimise to Tray	✅	❌	N/A	N/A	P2 Best Effort
	Revolt	Bots	Create Bot	✅	❌	❌	❌	P3 Unimportant
			List Bots	✅	❌	❌	❌	P3 Unimportant
			Update Information	✅	❌	❌	❌	P3 Unimportant
			Update Icon	✅	❌	❌	❌	P3 Unimportant
			Invite to Server / Group	✅	❌	❌	❌	P3 Unimportant
	Misc	Feedback Information		✅	❌	✅	✅	P1 Preferred
		Changelogs		✅	❌	✅	❌	P2 Best Effort
		Source code		✅	✅	✅	✅	Unapplicable
		Log out		✅	✅	✅	✅	P0 Must

Session Lifecycle

To ensure reliability for users on Revolt, clients should implement the following rigid specification for maintaing a session. At a high-level, it should be implemented as a state machine.

flowchart TD
subgraph LOGGED_IN[Logged In - Display Client UI]
CONNECTED
CONNECTING
RECONNECTING
DISCONNECTED
OFFLINE
...
end

subgraph LOGGED_OUT[Logged Out - Display Auth Flow or Loading Indicator]
READY
LOGGING_IN
ONBOARDING
DISPOSE
ERROR
end

READY -->|LOGIN_UNCACHED| LOGGING_IN
READY -->|LOGIN_CACHED| CONNECTING
LOGGING_IN -->|NO_USER| ONBOARDING
LOGGING_IN -->|PERMANENT_FAILURE| ERROR
LOGGING_IN -->|TEMPORARY_FAILURE| ERROR
ONBOARDING -->|CANCEL| DISPOSE
DISPOSE -->|READY| READY
ERROR -->|DISMISS| DISPOSE

LOGGING_IN -->|SOCKET_CONNECTED| CONNECTED
RECONNECTING -->|SOCKET_CONNECTED| CONNECTED
CONNECTING -->|SOCKET_CONNECTED| CONNECTED

ONBOARDING -->|USER_CREATED| LOGGING_IN
CONNECTED -->|TEMPORARY_FAILURE| DISCONNECTED
DISCONNECTED -->|RETRY| RECONNECTING
DISCONNECTED -->|DEVICE_OFFLINE| OFFLINE
RECONNECTING -->|TEMPORARY_FAILURE| DISCONNECTED
CONNECTING -->|TEMPORARY_FAILURE| DISCONNECTED
CONNECTING -->|PERMANENT_FAILURE| ERROR
RECONNECTING -->|PERMANENT_FAILURE| ERROR
OFFLINE -->|DEVICE_ONLINE| RECONNECTING

... -->|LOGOUT| DISPOSE

Implementation Details

The table below describes how each node should behave.

All nodes SHOULD have corresponding visual feedback.
Nodes MAY have effects on entry.
You SHOULD keep track of additional state such as:
- Number of connection failures

Node	User Interface	Logic
READY	Show login interface	May transition out by external source.
LOGGING_IN	Show loading indicator	On entry, try to authenticate the user.
ONBOARDING	Show username selection	May transition out by external source.
ERROR	Show the permanent error with option to dismiss it	May transition out by external source.
DISPOSE	Show loading indicator	Dispose current client and create a new one.
CONNECTING	Show client UI with banner "Connecting"	On entry, try to connect socket.
CONNECTED	Show client UI	May transition out by external source. Set connection failures to $0$ .
DISCONNECTED	Show client UI with banner "Disconnected"	May transition out by external source. Increment connection failures by $1$ . If the device is offline, trigger transition to OFFLINE. On entry, set a timer to retry^†. On exit, cancel timer.
RECONNECTING	Show client UI with banner "Reconnecting"	On entry, invalidate cached data (message history, members list) and try to connect socket.
OFFLINE	Show client UI with banner "Device offline"	May transition out by external source.

^† Please use the formula $(2^{x} - 1) \pm 20% seconds$ for the delay where $x$ is failure count.

// JavaScript implementation
let retryIn =
  (Math.pow(2, connectionFailureCount) - 1) * (0.8 + Math.random() * 0.4);
let retryInMs = retryIn * 1e3;
setTimeout(() => reconnect(), retryInMs);

The following listeners need to be registered that emit the given transitions:

Listener	Transition
Connected to Revolt (and initial data loaded)	`SOCKET_CONNECTED`
Connection to Revolt dropped	`SOCKET_DROPPED`
Received logout event from socket	`LOGOUT`
Connection failed	`TEMPORARY_FAILURE`
Connection failed (session invalid)	`PERMANENT_FAILURE`
Device has gone online	`DEVICE_ONLINE`

Socket Details

When implementing your WebSocket connection, you should also implement the following:

A heartbeat mechanism that sends the Ping event every 30 seconds, and disconnects if a Pong event is not received within 10 seconds.
A connection timeout mechanism that drops the WebSocket connection if no message is received within 10 seconds of initiating the connection.

User Experience Considerations

While not strictly relevant to session lifecycle, if you encounter BlockedByShield during login, you should provide a link to the relevant support article.
Upon encountering a permanent error (session invalid), you should use the known user information to fetch their current flags. This way the message can be tailored to display if: they have been logged out, they disabled their account, their account has been suspended, or their account has been banned.
When a logout event is received externally, show some sort of indicator that they have been logged out beyond just kicking them to the login screen.
~~If the connection failure count reaches $3$ or more, query the health service for any outage information.~~ This point is WIP, need considerations about increasing polling rate while connection failures are high, etc.