Technical:Back-end Server

Technical documentation for the back-end server. The back-end server is used by the website (https://trot.land/) for creating and managing user accounts and by game servers to persist player data.

Functionalities

User accounts

• /auth
  • POST /register - Create a new user account.
  • POST /password/forgot - Send "forgot password" email.
  • POST /password/reset/<token> - Set a new password using a reset token.
  • POST /activate/<token> - Activate user by token
  • POST /login - Create a new login session (cookie).
  • GET /user - Get current user information.
  • PATCH /user - Update user information.
  • POST /logout - Log out (invalidate cookie).
  • POST /join/<id> - Issue a short-lived session token for a specific server by ID. Allows for the joining of a server without ever forwarding user credentials to it.

Server actions

Every request in this section requires a server secret key as the Authorization: Bearer ... header.

• /server
  • GET / - Get the information about the current server
  • /player
    • POST /login - Handles player login with user credentials. Issues session token. Returns user information.
    • POST /join/<session> - Handles player login with a pre-issued session token and adjusts the expiry timing on the token. Returns user information.
    • GET /<id>/characters - Get a list of the player's characters.
    • POST /logout/<session> - Handle player logout. Invalidates session token and releases any active character lock.
    • /<id>/relationships
      • GET / - List a player's relationships. Also includes pending friend requests, which the server will show only once to the recipient.
      • POST / - Create a new relationship. This manages user blocks and friends.
      • PATCH /<id> - Update a relationship. For example when a friend request is accepted.
      • DELETE /<id> - Delete a relationship. For example when a friend is removed from either side.
    • /<id>/party
      • GET / - Get the party of a player. May return nothing if the player is not in a party.
      • POST / - Create a new party. Must have at least one invited player.
      • PATCH / - Update the party or its membership statuses.
      • DELETE / - Delete the party.
  • /character/
    • POST / - Create a new character, including starting inventory, statistics and outfits.
    • GET /<id> - Gets the full set of information about a player's character, including inventory, statistics and outfits.
    • POST /<id>/lock/<session> - Sets the character lock for a specific character (when player chooses the character they want to play as).
    • PATCH /<id> - Change character information. Can take up to a full set of information about a player's character. This is the main character persistence mechanism.
    • DELETE /<id> - Player deleted their character.
  • /moderation
    • POST /action - Create a new moderation action.
    • POST /report - Create a new player report.

Administration

Global administrators get access to a dashboard which lets them manage pretty much everything about the game service.

• /admin
  • /servers - List and manage available game servers.
  • /users - List and manage user accounts.
  • /roles - List and manage user roles.
  • /moderations - List and manage moderation actions.
  • /reports - List and manage player reports.

Roles and grants

Roles

Role name	Key	Description
Default	default	Regular players.
Global Moderator	mod	Moderators can do the following: Temporarily ban a user; Mute a user for a period or indefinitely; Kick a user from a server with a warning; Read user reports. For more serious cases the moderators must escalate the situation to the administrators.
Administrator	admin	Administrators can do the following: Everything that moderators can do; Permanently ban a user, IP address or an IP network; Delete player characters; Modify player inventories. On the website, administrators can also manage servers, user accounts and roles.

Additional roles may be created with a custom set of grants. Additional roles may also apply to specific servers only.

Database schema

Authentication and access control

users

Key	Type	Nullable / Default	Description
id	uuid (PK)	NOT NULL
username	varchar	NOT NULL
password	text	NOT NULL
email	text	NOT NULL
activated	boolean	NOT NULL, false
created_at	timestamp
updated_at	timestamp

user_tokens

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
user_id	users.id (FK)	NOT NULL
token_type	enum login activate reset deactivate otp	NOT NULL	One time token for logging in via website Token to activate the account Token to reset account password Token to confirm account deletion Time-based one time password (TOTP) secret key
token	text	NOT NULL
expires_at	timestamp
created_at	timestamp

Each moderation action is recorded into the database, even if it was a one-off action.

moderations

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
moderation_type	enum user_ban ip_ban mute server_kick server_ban	NOT NULL	User is banned from logging in IP address is banned from logging in or creating accounts User is banned from using chat (timed out). If server_id is set, only applies to that server User was kicked from a server. server_id shows which server this action was taken in User is banned from a specific server, indicated by server_id
description	text	NOT NULL
notes	text		Private notes for moderators
server_id	servers.id (FK)		Server related to this moderation action
actor_id	users.id (FK)		Moderator/Admin who created this event
user_id	users.id (FK)		Moderated user
report_id	player_reports.id (FK)		ID of the player report associated with this moderation action, if applicable
ip_address	inet		Host or network
expires_at	timestamp
created_at	timestamp

The role system is used to differentiate moderators and administrators from regular players.

roles

Key	Type	Nullable / Default	Description
key	varchar (PK)	NOT NULL
name	varchar	NOT NULL
default	boolean
server_id	servers.id (FK)		If set, role only applies to specific server
many-to-many relation with users

Grants are the actual actions that each role has the permission to do.

grants

Key	Type	Nullable / Default	Description
key	varchar (PK)	NOT NULL
name	varchar	NOT NULL
many-to-many relation with roles

Servers and access

Used for the server list and for server status information for the back-end to reference.

servers

Key	Type	Nullable / Default	Description
id	uuid (PK)	NOT NULL
secret	text	NOT NULL	Secret key used by game servers to contact the back-end
address	text	NOT NULL	Connection address complete with the port
name	text	NOT NULL	Public name for the server
rules	text	NOT NULL	Individual server rules
listed	boolean	true	Certain servers may be delisted
region	varchar(2)	NOT NULL	ISO 3166-1 alpha-2 code
last_ping	timestamp	NOT NULL	Last time the server contacted the back-end
last_players	integer	NOT NULL	Last reported player count

Session tokens are assigned before connecting to a server from (a launcher? or the website? via REST API) or by the server itself if authenticated directly by password. In the latter case, the player will not see the session token and it is only used for the character lock. Session tokens are valid only for one session or one connection to a server. The same character must not be used in multiple servers at once or in the same server multiple times.

session_tokens

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
server_id	servers.id (FK)	NOT NULL
character_id	characters.id (FK)		Set value indicates “character lock”
user_id	users.id (FK)	NOT NULL
token	text	NOT NULL
expires_at	timestamp
created_at	timestamp

Player persistence

All in-game data must be persisted to the database so that players will keep their characters and game progress between all of the servers.

characters

Key	Type	Nullable / Default	Description
id	uuid (PK)	NOT NULL
user_id	users.id (FK)	NOT NULL
name	varchar	NOT NULL	Display name of the character, set by player
title	varchar		In-game character title, only assignable via admin APIs
inventory	jsonb	NOT NULL	Serialized in-game inventory
stats	jsonb	NOT NULL	Serialized in-game statistics
journal	jsonb		Placeholder
last_pos	text	NOT NULL	Stringified vector3f (third dimension is a placeholder)
created_at	timestamp
updated_at	timestamp
last_login	timestamp

Since player statistics and inventory is on a per-character basis, creating multiple characters may not be desirable. For that reason, multiple "outfits" will be implemented instead. The outfits table contains the actual character customization data. Each character will have at least one outfit entry.

outfits

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
character_id	characters.id (FK)	NOT NULL
name	varchar	NOT NULL, "Default"	Set by player
data	bytea	NOT NULL	Serialized character customization data
active	boolean	true	Currently used outfit for character

Some people do not get along. Some people get along really well. This table covers both of those cases.

relationships

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
relationship_type	enum block friend	NOT NULL
user_id	users.id (FK)	NOT NULL	User who blocked User who sent friend request
target_id	users.id (FK)	NOT NULL	Blocked user Friended user
target_name	varchar		Last known character name at the time of blocking
accepted	boolean		Always true for "block" Target player has to accept for the relationship to be valid
seen_at	timestamp		Used for displaying friend request only once
created_at	timestamp

parties

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
created_at	timestamp
user_id	users.id (FK)	NOT NULL	Created by user, does not have to be current leader

party_members

Key	Type	Nullable / Default	Description
id	serial (PK)	NOT NULL
party_id	parties.id (FK)	NOT NULL
invited_by_id	users.id (FK)	NOT NULL
user_id	users.id (FK)	NOT NULL
accepted	boolean	false	User has to accept for the membership to be valid
leader	boolean	false	First user in party always gets true
created_at	timestamp

Other

player_reports

Key	Type	Nullable / Default	Description
id	uuid (PK)	NOT NULL
actor_id	users.id (FK)	NOT NULL	User who reported
user_id	users.id (FK)	NOT NULL	User being reported
character_id	characters.id (FK)		Character of reported user at the time of reporting
character_name	varchar		Name of the character of the reported user at the time of reporting
user_ip	inet		IP address of the reported user at the time of reporting
reason	text	NOT NULL	Reason for reporting
notes	text		Private notes for moderators
resolved_at	timestamp		Time report was resolved
resolved_by_id	users.id (FK)		Moderator who resolved the report
chat_log	text		Recent chat log recorded by the game server for context
created_at	timestamp