Beaconizer-protocols

Beaconizers connect to the master server on port 48813 and to other BeaconServer instances on ports ranging from 48812 to 48913. They use the common Network protocol.

Commands, client to server

All BeaconServer modes accept the same messages from clients. Clients have a state, stored in BeaconServerClientData.state, which is BCS_NOT_CONNECTED for newly connected clients. The possible states are:

• BCS_NOT_CONNECTED: the client has not yet send a connect message
• BCS_CONNECTED: the client has connected with BMSG_C2S_CONNECT, and is not a sentry
• BCS_READY_TO_WORK
• BCS_RECEIVING_MAP_DATA
• BCS_NEEDS_MORE_MAP_DATA
• BCS_READY_TO_GENERATE
• BCS_GENERATING
• BCS_READY_TO_CONNECT_BEACONS
• BCS_CONNECTING_BEACONS
• BCS_SENTRY: the client has connected with BMSG_C2S_CONNECT, and is a sentry
• BCS_SERVER: the client has connected with BMSG_C2S_SERVER_CONNECT
• BCS_NEEDS_MORE_EXE_DATA: the client is waiting to be sent the next chunk of a new executable
• BCS_RECEIVING_EXE_DATA: the client has been sent a chunk of a new executable, and is waiting for it to ask for more
• BCS_REQUESTER: the client has connected with BMSG_C2S_REQUESTER_CONNECT
• BCS_REQUEST_SERVER_IDLE
• BCS_REQUEST_SERVER_PROCESSING
• BCS_ERROR_DATA: some invalid data has been received, and all future messages will be ignored
• BCS_ERROR_PROTOCOL: some invalid protocol message has been received, and all future messages will be ignored
• BCS_ERROR_NONLOCAL_IP: the server has been set into "local IPs only" mode (via the console menu) and the client is not connecting from a local IP

BMSG_C2S_CONNECT

bits(32) exe_crc_old
optional, if exe_crc_old is 0:
  packint(1) protocol_version
  bits(32) exe_crc
string user_name
string computer_name
bits(1) is_sentry

If the client is in state BCS_ERROR_NONLOCAL_IP then this message is ignored, other than recording the names and version. If the client is in any other state which is not BCS_NOT_CONNECTED then the state is set to BCS_ERROR_PROTOCOL and this message is ignored. Otherwise, when the state is BCS_NOT_CONNECTED:

If exe_crc_old is not 0, then it is the exe_crc value. Otherwise, the optional version is used.

If exe_crc does not match the crc of the executable for the server receiving the message, then the client will be moved to state BCS_ERROR_PROTOCOL in production mode, and sent a BMSG_S2C_CONNECT_REPLY with good set to 0 in development mode, and the client is moved to state BCS_NEEDS_MORE_EXE_DATA.

If exe_crc does match, then the client will be accepted. If is_sentry is true then the client type will be set to BCT_SENTRY and the state to BCS_SENTRY. If is_sentry is false then the client type will be set to BCT_WORKER and the client state to BCS_CONNECTED.

BMSG_S2C_CONNECT_REPLY is sent with good set to 1.

BMSG_C2S_SERVER_CONNECT

packint(1) protocol_version
bits(32) exe_crc
string user_name
string computer_name
packint(1) server_port
when protocol_version is at least 1:
  bits(1) is_request_server

If the client is in state BCS_ERROR_NONLOCAL_IP then this message is ignored, other than recording the names and version. If the client is in any other state which is not BCS_NOT_CONNECTED then the state is set to BCS_ERROR_PROTOCOL and this message is ignored. Otherwise, when the state is BCS_NOT_CONNECTED:

The crc match is checked against this binary and printed on the console but otherwise ignored.

The other fields are recorded for later use.

The client state is moved to BCS_SERVER and BMSG_S2C_CONNECT_REPLY is sent with good set to 1.

BMSG_C2S_REQUESTER_CONNECT

packint(1) protocol_version
string user_name
string computer_name
string dbserver_ip

If the client is in state BCS_ERROR_NONLOCAL_IP then this message is ignored, other than recording the names and version. If the client is in any other state which is not BCS_NOT_CONNECTED then the state is set to BCS_ERROR_PROTOCOL and this message is ignored. Otherwise, when the state is BCS_NOT_CONNECTED:

If protocol_version is not 0, 1, or 2 then the client is moved to state BCS_ERROR_PROTOCOL, otherwise it is moved to state BCS_REQUESTER.

The rest of the fields are stored for later use.

BMSG_C2S_TEXT_CMD

string cmd

The rest of this packet is determined based on the text command sent. If it is not one of these values, the command is ignored.

In each case, it is listed with both the constant used in the source code (BMSG_C2ST_*) and the name sent in the message ("...").

BMSG_C2ST_READY_TO_WORK "ReadyToWork"

This message has no body.

If the client is in state BCS_CONNECTED, then it moves to state BCS_READY_TO_WORK, and marked as ready for commands.

If the client is in state BCS_SENTRY, the message is printed on the console and ignored.

Receiving this message in all other states will move to BCS_ERROR_PROTOCOL.

BMSG_C2ST_NEED_MORE_MAP_DATA "NeedMoreMapData"

packint(1) received_byte_count

If the client type is BCT_SERVER, then the server responds with BMSG_S2CT_MAP_DATA.

If the client type is BCT_WORKER, and the state is BCS_RECEIVING_MAP_DATA, then received_byte_count is checked against the sent byte count, and the state is moved to BCS_ERROR_PROTOCOL if it does not match. If it does match, then the state moves to BCS_NEEDS_MORE_MAP_DATA.

BMSG_C2ST_MAP_DATA_IS_LOADED "MapDataIsLoaded"

If the client type is BCT_SERVER and the client is a request server:

packint(1) node_uid
string unique_storage_name

If the uid and storage name match the work that is currently assigned to this server, and all map data has been sent to it, then BMSG_S2CT_PROCESS_REQUESTED_MAP is sent to the client. Otherwise this message is ignored.

If the client type is BCT_WORKER, then the state must be BCS_RECEIVING_MAP_DATA or this message is ignored. When it is in state BCS_RECEIVING_MAP_DATA:

If the map data has not been fully sent, then the state is moved to BCS_ERROR_PROTOCOL and the response is sent with good set to 1 (bug???).

Otherwise:

bits(32) client_map_crc

If the map crc matches the one loaded by this server, then the state is moved to BCS_READY_TO_GENERATE and the response will have good set to 1. Otherwise, the state is moved to BCS_ERROR_DATA and the response will have good set to 0.

In any case where the state was BCS_RECEIVING_MAP_DATA, a BMSG_S2CT_MAP_DATA_LOADED_REPLY reply will be sent.

BMSG_C2ST_NEED_MORE_EXE_DATA "NeedMoreExeData"

packint(1) received_byte_count

The state must be BCS_RECEIVING_EXE_DATA or this message is ignored.

If the received byte count does not match the size of the last packet sent, then the client moves to state BCS_ERROR_PROTOCOL. Otherwise the client moves to state BCS_NEEDS_MORE_EXE_DATA.

BMSG_C2ST_GENERATE_FINISHED "GenerateFinished"

repeated until has_data is 0:
  bits(1) has_data
  packint(1) grid_x
  packint(1) grid_z
  optional, if this is the requested block:
    bits(32) surface_crc
    packint(1) beacon_count
    repeated beacon_count times:
      bits(768) beacon_pos
      bits(1) no_ground_connections
  packint(5) receive_count
  repeated receive_count times:
    bits(8) x
    bits(8) z
    bits(1) is_index
    when is_index is 1:
      packint(5) y_index
    when is_index is 0:
      float32 y_coord
    repeated for each column in the block:
      packint(1) area_count
      # The rest of this is currently not sent or received

If the state is not BCS_GENERATING then this message is ignored.

After processing this message, the state is moved to BCS_READY_TO_GENERATE.

If the client does not currently have a block of work assigned, then nothing happens. This happens when another client finished this block first.

Otherwise, the data is read into the disk swap block for the grid location it describes.

BMSG_C2ST_BEACON_CONNECTIONS "BeaconConnections"

repeated for the size of the group assigned:
  packint(1) index
  packint(1) count
  repeated count times:
    packint(1) target_index
    bits(1) has_ground_connection
    packint(1) raised_count
    repeated raised_count times:
      float32 min_height
      float32 max_height

This message is ignored if the state is not BCS_CONNECTING_BEACONS. Otherwise the state moves to BCS_READY_TO_CONNECT_BEACONS after processing this message.

If the client does not currently have a beacon group assigned (some other client finished it first), the contents will be discarded.

The connections returned are stored in the beacons identified by index in combatBeaconArray.

BMSG_C2ST_SENTRY_CLIENT_LIST "SentryClientList"

repeated until more is 0:
  bits(1) more
  bits(32) client_uid
  string server_uid
  bits(32) pid
  bits(1) forced_inactive
  bits(1) has_crash
  when has_crash is 1:
    string crash_text

If the client's type is not BCT_SENTRY then this message is ignored.

For every entry where server_uid matches this server, the relevant client is looked up by client_uid. It must be connected from the same source IP as the sentry or the entry will be ignored.

Everything in the list which is not ignored is set as being clients of this sentry, and all older clients of this sentry are removed. If the crash text has changed then it is logged.

BMSG_C2ST_SERVER_STATUS "ServerStatus"

packint(1) client_count
packint(1) state
packint(1) send_status_uid
bits(1) send_clients_to_me

If the client is not in state BCS_SERVER this message is ignored. The client must also be of type BCT_SERVER or the server will assert(!!!).

The server records all these values and responds with BMSG_S2CT_STATUS_ACK.

BMSG_C2ST_REQUESTER_MAP_DATA "RequesterMapData"

packint(1) uid
string unique_storage_name
packint(1) previously_sent_byte_count
packint(1) current_byte_count
packint(1) compressed_byte_count
packint(1) uncompressed_bit_count // Note this one is in bits, not bytes
bits(1) packet_debug_info
bits(32) compressed_crc
bits(8 * current_byte_count) data

This message is ignored if the client is not of type BCT_REQUESTER.

compressed_byte_count indicates the total number of bytes in the map data. previously_sent_byte_count indicates how many bytes have been sent in previous packets. current_byte_count is the number of bytes sent in this packet.

If this is the first message (previouly_sent_byte_count is 0) then the request is added to the process and load queues, and the server responds with BMSG_S2CT_REQUEST_ACCEPTED. Otherwise, if the state of the process node was BPNS_WAITING_FOR_MAP_DATA_FROM_CLIENT then it is cycled to BPNS_WAITING_TO_REQUEST_MAP_DATA_FROM_CLIENT.

In any event, if the state is BPNS_WAITING_FOR_LOAD_REQUEST, BPNS_WAITING_FOR_MAP_DATA_FROM_CLIENT, or BPNS_WAITING_TO_REQUEST_MAP_DATA_FROM_CLIENT then a data chunk is read from the packet into the process node.

BMSG_C2ST_REQUESTER_CANCEL "RequesterCancel"

Not used.

BMSG_C2ST_USER_INACTIVE "UserInactive"

bits(1) forced_inactive
string reason

The client's inactive state is set, and the reason is printed on the console.

An "inactive" client means one where the user has not touched the keyboard or mouse recently, and therefore wants to pick up work. A client which is "forced inactive" is one which has been forced to pick up work. These terms are confusing.

BMSG_C2ST_BEACON_FILE "BeaconFile"

packint(1) node_uid
string unique_storage_name
packint(1) received_bytes_count
packint(1) read_byte_count
packint(1) byte_count
packint(1) uncompressed_byte_count
packint(1) crc
bits(8 * read_byte_count) data

If the client is not a request server, it moves to state BCS_ERROR_PROTOCOL.

If the client does not have a process node assigned, or the uid and unique storage name do not match, this message is ignored.

received_bytes_count is the number of bytes sent in previous packets (the position in the file of this packet). read_byte_count is the number of bytes in this packet. byte_count is the total number of bytes in the file to be sent.

If not all bytes in the file have been received then a BMSG_S2CT_NEED_MORE_BEACON_FILE reply is sent and processing stops.

Otherwise, all bytes in the file have been received, so we continue:

The data is written to a .beaconrequest file.

If there is no longer a requester for this node, it is discarded. Otherwise, the first BMSG_S2CT_BEACON_FILE message is sent to that requester, the process node is removed from the request server that has been processing it, and the node moves to state BPNS_WAITING_FOR_CLIENT_TO_RECEIVE_BEACON_FILE.

BMSG_C2ST_NEED_MORE_BEACON_FILE "NeedMoreBeaconFile"

This message has no body.

If the client has requested a process node in state BPNS_WAITING_FOR_CLIENT_TO_RECEIVE_BEACON_FILE, then the next BMSG_S2CT_BEACON_FILE message is sent.

BMSG_C2ST_REQUESTED_MAP_LOAD_FAILED "RequestedMapLoadFailed"

packint(1) node_uid
string unique_storage_name

If the client is not a request server then this message is ignored.

If the uid and storage name do not match the request server's current assigned node, the message is ignored.

Otherwise, this process node is cancelled and the requester is sent BMSG_S2CT_REGENERATE_MAP_DATA.

BMSG_C2ST_PING "Ping"

Ignored.

Commands, server to client

BMSG_S2C_CONNECT_REPLY

bits(1) good
when good is 1:
  bits(32) client_uid
  string server_uid
optional, when good is 0:
  packint(1) size
  bits(size * 8) data

When good is 1, the connection is being accepted. Otherwise, this indicates that the client should get a new executable, and optionally contains the data, which the receiver will write to a file and execute, replacing itself.

BMSG_S2C_TEXT_CMD

string cmd

The rest of this packet is determined based on the text command sent. If it is not one of these values, the command is ignored.

In each case, it is listed with both the constant used in the source code (BMSG_S2CT_*) and the name sent in the message ("...").

BMSG_S2CT_MAP_DATA "MapData"

packint(1) node_uid
string unique_storage_name
bits(1) flag
packint(1) previously_sent_byte_count
packint(1) current_byte_count
packint(1) compressed_byte_count
packint(1) uncompressed_bit_count // Note this one is in bits, not bytes
bits(1) packet_debug_info
bits(32) compressed_crc
bits(8 * current_byte_count) data

Masters send this message to servers, and servers send this message to BeaconClients.

On a server, setting flag indicates that this is the first packet. Map data is reset, the server moves to state BSS_NOT_STARTED, and increments its status uid. If there is more map data after this packet, then BMSG_C2ST_NEED_MORE_MAP_DATA is sent in response, otherwise BMSG_C2ST_MAP_DATA_IS_LOADED is sent.

On a worker, setting flag suppresses crc calculation, setting the crc to 0. If there is more map data after this packet, then BMSG_C2ST_NEED_MORE_MAP_DATA is sent in response, otherwise the generator is reset to begin calculation.

BMSG_S2CT_NEED_MORE_BEACON_FILE "NeedMoreBeaconFile"

This message has no body.

When a BeaconServer receives this message from the Master-BeaconServer, if it is currently in state BSS_SEND_BEACON_FILE, then it responds with BMSG_C2ST_BEACON_FILE containing the next chunk of the file. If it has sent the entire file after this, it moves into state BSS_DONE.

BMSG_S2CT_CLIENT_CAP "ClientCap"

packint(1) max_allowed

Masters send this message to BeaconServers.

On receiving this message, the BeaconServer disconnects clients until it has no more than max_allowed. It does not otherwise store or maintain the limit.

BMSG_S2CT_STATUS_ACK "StatusAck"

packint(1) acked_status_uid

Masters send this message to BeaconServers.

If the status_uid matches the last status sent, it is marked as acked.

An unacked status blocks the server from writing its beacon files to disk, and has no other effect beyond the console UI.