Editing SimTX API/Packets/ServerHello

{{SimTX API navigation}}
{{SimTX packet
| name = ServerHello
| frame = ServerFrame
| field = 1
| member = hello_result
| direction = s2c
| session = [[SimTX API/Connection and handshake|All roles]]
| roles = All roles. Always the first server frame.
| permission = None
| answers = [[SimTX API/Packets/ClientHello|ClientHello]]
| group = connection
| file = frames.proto
}}
'''ServerHello''' answers the [[SimTX API/Packets/ClientHello|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 ==
<syntaxhighlight lang="protobuf">
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
}
</syntaxhighlight>

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

=== Account ===
<syntaxhighlight lang="protobuf">
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;
}
</syntaxhighlight>
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>account_id</code> || <code>bytes</code> || 16-byte account UUID.
|-
| 2 || <code>handle</code> || <code>string</code> || Account handle.
|-
| 3 || <code>display_name</code> || <code>string</code> || Display name.
|-
| 4 || <code>permissions</code> || <code>repeated string</code> || Effective [[SimTX API/Permissions|permissions and numeric capabilities]] on this server, after the credential's scope, for example <code>game.transmit</code> or <code>tx.pa_limit.400</code>.
|-
| 5 || <code>authorization_revision</code> || <code>int64</code> || Revision of the account's authorisation data. Changes when permissions change.
|-
| 6 || <code>lease_expires_at_ms</code> || <code>int64</code> || When the server will close this authenticated connection, Unix ms. About 12 hours after the hello.
|}

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

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

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

== Examples ==
Complete frames, including the varint length prefix.

'''<code>hello_result_accepted_account</code>''' (server to client, 130 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

'''<code>hello_result_revision_1</code>''' (server to client, 96 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

'''<code>hello_result_version_unsupported</code>''' (server to client, 55 bytes):

<syntaxhighlight lang="text">
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"
</syntaxhighlight>

== See also ==
* [[SimTX API/Connection and handshake]]
* [[SimTX API/Permissions]]

{{SimTX API navbox}}
[[Category:SimTX API]]