SimTX API/Packets/ServerHello

ServerHello

Frame	ServerFrame, field 1
Member	hello_result
Direction	Server → client
Session	All roles
Roles	All roles. Always the first server frame.
Permission	None
Answered by
Answers	ClientHello
Defined in	frames.proto

ServerHello answers the ClientHello. It accepts the connection, in which case the session continues according to the role, or rejects it, in which case the server closes the connection after sending it. For an authenticated connection it describes the account. It also carries the server's feature list, protocol revision and clocks.

Definition

message ServerHello {
  HelloStatus status = 1;
  string message = 2;
  Account account = 3;          // unset for anonymous sessions
  repeated string features = 4; // server feature registry (see the top of this file)
  string server_version = 5;
  int64 server_time_ms = 6;      // Unix ms
  int64 simulation_time_ms = 7;  // Unix ms of the simulated world clock
  int32 protocol_revision = 8;   // highest protocol revision this server implements
}

Fields

#	Field	Type	Description
1	status	HelloStatus	Result of the hello. Anything other than HELLO_STATUS_ACCEPTED is followed by the server closing the connection.
2	message	string	Human-readable explanation. Empty on success. Show it to the user on rejection.
3	account	Account	The account, for authenticated connections. Unset for anonymous ones.
4	features	repeated string	Optional server capabilities of this deployment, from the feature registry. Ignore names you do not know.
5	server_version	string	Server software version, for display and diagnostics.
6	server_time_ms	int64	Server wall clock, Unix ms.
7	simulation_time_ms	int64	Simulated world clock, Unix ms. Use it, not the local clock, as "now" for satellite positions and pass predictions.
8	protocol_revision	int32	Highest protocol revision the server implements.

Account

message Account {
  bytes account_id = 1;
  string handle = 2;
  string display_name = 3;
  repeated string permissions = 4;
  int64 authorization_revision = 5;
  int64 lease_expires_at_ms = 6;
}

#	Field	Type	Description
1	account_id	bytes	16-byte account UUID.
2	handle	string	Account handle.
3	display_name	string	Display name.
4	permissions	repeated string	Effective permissions and numeric capabilities on this server, after the credential's scope, for example game.transmit or tx.pa_limit.400.
5	authorization_revision	int64	Revision of the account's authorisation data. Changes when permissions change.
6	lease_expires_at_ms	int64	When the server will close this authenticated connection, Unix ms. About 12 hours after the hello.

Status codes

Value	Name	Meaning
0	HELLO_STATUS_UNSPECIFIED	Not sent by servers. Treat it, and unknown values, as SERVER_UNAVAILABLE.
1	HELLO_STATUS_ACCEPTED	The session may begin.
2	HELLO_STATUS_VERSION_UNSUPPORTED	The preface version is not 25.
3	HELLO_STATUS_AUTHENTICATION_REQUIRED	The role needs a ticket and none was sent. Typical message: This role requires a SimTX account.
4	HELLO_STATUS_CREDENTIAL_INVALID	The ticket is unknown, expired, used, or minted for another server or role. Typical message: Game ticket is invalid or expired.
5	HELLO_STATUS_ACCOUNT_RESTRICTED	The account is restricted.
6	HELLO_STATUS_ROLE_FORBIDDEN	The account lacks the permission the role needs. Typical message: Account is not permitted to transmit.
7	HELLO_STATUS_SERVER_UNAVAILABLE	The server cannot verify the ticket or take the connection now. The only status worth retrying unchanged.
8	HELLO_STATUS_IP_BANNED	The client address is banned. The message gives the reason.

On any status other than ACCEPTED the server closes the connection. Only SERVER_UNAVAILABLE is worth retrying unchanged; the others need a new ticket, a different role or user action.

Usage

• After ACCEPTED on a receiver or transmitter connection, send the start frame immediately. A control or moderation session may send requests at once.
• Show message to the user on rejection.
• Use the numeric capabilities in account.permissions, such as tx.pa_limit.400, to configure the user interface.
• Reconnect with a fresh ticket shortly before account.lease_expires_at_ms.
• Check features before using an optional capability, and rely on revision-gated behaviour only when protocol_revision is high enough. See Compatibility and versioning.

Examples

Complete frames, including the varint length prefix.

hello_result_accepted_account (server to client, 130 bytes):

80 01                                     frame length 128
0A 7E                                     hello_result (ServerHello), 126 bytes
  08 01                                   status = 1 (HELLO_STATUS_ACCEPTED)
  1A 4E                                   account (Account), 78 bytes
    0A 10 0F 8E 2C 4A …                   account_id = 0f8e2c4a-1b3d-4e5f-8a9b-0c1d2e3f4a5b
    12 08 6F 70 65 72 61 74 6F 72         handle = "operator"
    1A 08 4F 70 65 72 61 74 6F 72         display_name = "Operator"
    22 0D 67 61 6D 65 2E 74 72 61 …       permissions = "game.transmit"
    22 0E 73 74 61 74 69 6F 6E 2E …       permissions = "station.manage"
    28 07                                 authorization_revision = 7
    30 80 F1 DE BA 97 34                  lease_expires_at_ms = 1793003600000
  22 0B 73 74 61 74 69 6F 6E 73 2E 76 31  features = "stations.v1"
  22 08 70 6F 69 6E 74 69 6E 67           features = "pointing"
  2A 05 30 2E 33 2E 35                    server_version = "0.3.5"
  30 80 94 83 B9 97 34                    server_time_ms = 1793000000000
  38 F4 97 83 B9 97 34                    simulation_time_ms = 1793000000500

hello_result_revision_1 (server to client, 96 bytes):

5F                                        frame length 95
0A 5D                                     hello_result (ServerHello), 93 bytes
  08 01                                   status = 1 (HELLO_STATUS_ACCEPTED)
  22 0B 73 74 61 74 69 6F 6E 73 2E 76 31  features = "stations.v1"
  22 08 70 6F 69 6E 74 69 6E 67           features = "pointing"
  22 09 65 70 68 65 6D 65 72 69 73        features = "ephemeris"
  22 06 70 61 73 73 65 73                 features = "passes"
  22 0A 6B 69 6E 65 6D 61 74 69 63 73     features = "kinematics"
  2A 13 73 69 6D 74 78 2D 73 65 …         server_version = "simtx-server/25.1.0"
  30 80 94 83 B9 97 34                    server_time_ms = 1793000000000
  38 F4 97 83 B9 97 34                    simulation_time_ms = 1793000000500
  40 01                                   protocol_revision = 1

hello_result_version_unsupported (server to client, 55 bytes):

36                                 frame length 54
0A 34                              hello_result (ServerHello), 52 bytes
  08 02                            status = 2 (HELLO_STATUS_VERSION_UNSUPPORTED)
  12 30 54 68 69 73 20 73 65 72 …  message = "This server speaks protocol v25; client sent v26"

See also

• SimTX API/Connection and handshake
• SimTX API/Permissions