The Donet Protocol

Recognizing Original Works

The original designers of this protocol are the Astron contributors, with special recognition to:

Sam “CFSworks” Edwards

Kevin “Kestred” Stenerson

Table of Contents

• Payload Encapsulation
• Client Protocol
• Client Agent
• State Server
• Database State Server (DBSS)
• Database Server
• Message Director
• Event Logger

The Donet network protocol is made up of two separate, yet similar protocols:

The Client and the Internal protocols.

Client messages are sent only between the clients and the CA.

Internal messages are sent only in between services inside the ‘trusted zone’, that is the cluster network.

Every message type defined has a certain 16-bit number identifier. Message type number IDs are organized in ranges, each range designated to a certain Donet service.

Overview

Client Protocol

All message types in the client protocol are in the 0-999 range.

• 0 - 99: Basic messages for maintaining the connection with the Client Agent.

• 100 - 199: Distributed Object generates and field updates.

• 200 - 999: Client Interest controls.

Internal Protocol

• 1000 - 1999 | Client Agent

  • 1000 - 1099 - Client State and Session controls

  • 1100 - 1199 - Channel Controls

  • 1200 - 1999 - Interest Controls

• 2000 - 2999 | State Server / DBSS

  • 2000 - 2009 - Object Create / Delete

  • 2010 - 2039 - Object Fields

  • 2040 - 2049 - Object Location

  • 2050 - 2059 - Object Designated AI

  • 2060 - 2099 - Object Ownership

  • 2100 - 2199 - Zone Controls

  • 2200 - 2229 - DBSS Object Activation

  • 2230 - 2239 - Object Data on Disk

• 3000 - 3999 | Database Server

  • 3000 - 3009 - Object Create

  • 3010 - 3019 - Object Get Fields

  • 3020 - 3029 - Object Set Fields

  • 3030 - 3039 - Object Delete Fields

• 9000 - 9999 | Message Director

  • 9000 - 9009 - Channels and Channel Ranges

  • 9010 - 9019 - Post Removes

Protocol Reference

Message Director | Control Messages

Message	ID	Parameters
ADD_CHANNEL	9000	uint64 channel
REMOVE_CHANNEL	9001	uint64 channel
ADD_RANGE	9002	uint64 low, uint64 high
REMOVE_RANGE	9003	uint64 low, uint64 high
ADD_POST_REMOVE	9010	uint64 sender, blob datagram
CLEAR_POST_REMOVES	9011	uint64 sender
SET_CON_NAME	9012	string name
SET_CON_URL	9013	string url
LOG_MESSAGE	9014	blob msgpack_datagram

Client Messages

Message	ID	Parameters
HELLO	1	uint32 dc_hash, string version
HELLO_RESP	2
DISCONNECT	3
EJECT	4	uint16 error_code, string reason
HEARTBEAT	5
ENTER_OBJECT_REQUIRED	142	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
ENTER_OBJECT_REQUIRED_OTHER	143	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
ENTER_OBJECT_REQUIRED_OWNER	172	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
ENTER_OBJECT_REQUIRED_OTHER_OWNER	173	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
OBJECT_SET_FIELD	120	uint32 do_id, uint16 field_id, <VALUE>
OBJECT_SET_FIELDS	121	uint32 do_id, uint16 n_fields, [uint16 field_id, <VALUE>] * n_fields
OBJECT_LEAVING	132	uint32 do_id
OBJECT_LOCATION	140	uint32 do_id, uint32 parent_id, uint32 zone_id
ADD_INTEREST	200	uint32 context, uint16 interest_id, uint32 parent_id, uint32 zone_id
ADD_INTEREST_MULTIPLE	201	uint32 context, uint16 interest_id, uint32 parent_id, uint16 n_zones, [uint32 zone_id] * n_zones
REMOVE_INTEREST	203	uint32 context, uint16 interest_id
DONE_INTEREST_RESP	204	uint32 context, uint16 interest_id

Client Agent Messages

Message	ID	Parameters
SET_STATE	1000	uint16 ca_state
SET_CLIENT_ID	1001	uint64 channel
SEND_DATAGRAM	1002	blob datagram
EJECT	1004	uint16 error_code, string reason
DROP	1005
GET_NETWORK_ADDRESS	1006	uint32 context
GET_NETWORK_ADDRESS_RESP	1007	uint32 context, string remote_ip, uint16 remote_port, string local_ip, uint16 local_port
DECLARE_OBJECT	1010	uint32 do_id, uint16 dclass_id
UNDECLARE_OBJECT	1011	uint32 do_id
ADD_SESSION_OBJECT	1012	uint32 do_id
REMOVE_SESSION_OBJECT	1013	uint32 do_id
SET_FIELDS_SENDABLE	1014	uint32 do_id, [uint16 field_id], […]
GET_TLVS	1015	uint32 context
GET_TLVS_RESP	1016	uint32 context, blob tlvs
OPEN_CHANNEL	1100	uint64 channel
CLOSE_CHANNEL	1101	uint64 channel
ADD_POST_REMOVE	1110	blob datagram
CLEAR_POST_REMOVES	1111
ADD_INTEREST	1200	uint16 interest_id, uint32 parent_id, uint32 zone_id
ADD_INTEREST_MULTIPLE	1201	uint16 interest_id, uint32 parent_id, uint16 n_zones, [uint32 zone_id] * n_zones
REMOVE_INTEREST	1203	uint16 interest_id

State Server Messages

Message	ID	Parameters
CREATE_OBJECT_WITH_REQUIRED	2000	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
CREATE_OBJECT_WITH_REQUIRED_OTHER	2001	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
DELETE_AI_OBJECTS	2009	uint64 ai_channel

State Server | Distributed Object Accessor Messages

Message	ID	Parameters
OBJECT_GET_FIELD	2010	uint32 context, uint32 do_id, uint16 field_id
OBJECT_GET_FIELD_RESP	2011	uint32 context, uint8 success, [uint16 field_id, <VALUE>]
OBJECT_GET_FIELDS	2012	uint32 context, uint32 do_id, uint16 n_fields, [uint16 field_id] * n_fields
OBJECT_GET_FIELDS_RESP	2013	uint32 context, uint8 success, uint16 n_fields, [uint16 field_id, <VALUE>] * n_fields
OBJECT_GET_ALL	2014	uint32 context, uint32 do_id
OBJECT_GET_ALL_RESP	2015	uint32 context, uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
OBJECT_SET_FIELD	2020	uint32 do_id, uint16 field_id, <VALUE>
OBJECT_SET_FIELDS	2021	uint32 do_id, uint16 n_fields, [uint16 field_id, <VALUE>] * n_fields
OBJECT_DELETE_FIELD_RAM	2030	uint32 do_id, uint16 field_id
OBJECT_DELETE_FIELDS_RAM	2031	uint32 do_id, uint16 n_fields, [uint16 field_id] * n_fields
OBJECT_DELETE_RAM	2032	uint32 do_id

State Server | Distributed Object Visibility Messages

Message	ID	Parameters
OBJECT_SET_LOCATION	2040	uint32 parent_id, uint32 zone_id
OBJECT_CHANGING_LOCATION	2041	uint32 do_id, uint32 parent, uint32 zone, uint32 old_parent , uint32 old_zone
OBJECT_ENTER_LOCATION_WITH_REQUIRED	2042	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
OBJECT_ENTER_LOCATION_WITH_REQUIRED_OTHER	2043	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
OBJECT_GET_LOCATION	2044	uint32 context
OBJECT_GET_LOCATION_RESP	2045	uint32 context, uint32 do_id, uint32 parent_id, uint32 zone_id
OBJECT_LOCATION_ACK	2046	uint32 parent_id, uint32 zone_id
OBJECT_SET_AI	2050	uint64 ai_channel
OBJECT_CHANGING_AI	2051	uint32 do_id, uint64 new_ai, uint64 old_ai
OBJECT_ENTER_AI_WITH_REQUIRED	2052	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
OBJECT_ENTER_AI_WITH_REQUIRED_OTHER	2053	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
OBJECT_GET_AI	2054	uint32 context
OBJECT_GET_AI_RESP	2055	uint32 context, uint32 do_id, uint64 ai_channel
OBJECT_SET_OWNER	2060	uint64 owner_chan
OBJECT_CHANGING_OWNER	2061	uint32 do_id, uint64 new_owner, uint64 old_owner
OBJECT_ENTER_OWNER_WITH_REQUIRED	2062	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
OBJECT_ENTER_OWNER_WITH_REQUIRED_OTHER	2063	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>
OBJECT_GET_OWNER	2064	uint32 context
OBJECT_GET_OWNER_RESP	2065	uint32 context, uint32 do_id, uint64 owner_chan
OBJECT_ENTER_INTEREST_WITH_REQUIRED	2066	uint32 context, uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>
OBJECT_ENTER_INTEREST_WITH_REQUIRED_OTHER	2067	uint32 context, uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <REQUIRED>, <OTHER>

State Server | Parent Object Methods

Message	ID	Parameters
OBJECT_GET_ZONE_OBJECTS	2100	uint32 context, uint32 parent_id, uint32 zone_id
OBJECT_GET_ZONES_OBJECTS	2102	uint32 context, uint32 parent_id, uint16 n_zones, [uint32 zone_id] * n_zones
OBJECT_GET_CHILDREN	2104	uint32 context, uint32 parent_id
OBJECT_GET_ZONE_COUNT	2110	uint32 context, uint32 parent_id, uint32 zone_id
OBJECT_GET_ZONE_COUNT_RESP	2111	uint32 context, uint32 count
OBJECT_GET_ZONES_COUNT	2112	uint32 context, uint32 parent_id, uint16 n_zones, [uint32 zone_id] * n_zones
OBJECT_GET_ZONES_COUNT_RESP	2113	uint32 context, uint32 count
OBJECT_GET_CHILD_COUNT	2114	uint32 context, uint32 parent_id
OBJECT_GET_CHILD_COUNT_RESP	2115	uint32 context, uint32 object_count
OBJECT_DELETE_ZONE	2120	uint32 parent_id, uint32 zone_id
OBJECT_DELETE_ZONES	2122	uint32 parent_id, uint16 n_zones, [uint32 zone_id] * n_zones
OBJECT_DELETE_CHILDREN	2124	uint32 parent_id
GET_ACTIVE_ZONES	2125	uint32 context
GET_ACTIVE_ZONES_RESP	2126	uint32 context, uint16 n_zones, [uint32 zone_id] * n_zones

DBSS Object Messages

Message	ID	Parameters
OBJECT_ACTIVATE_WITH_DEFAULTS	2200	uint32 do_id, uint32 parent_id, uint32 zone_id
OBJECT_ACTIVATE_WITH_DEFAULTS_OTHER	2201	uint32 do_id, uint32 parent_id, uint32 zone_id, uint16 dclass_id, <OTHER>
OBJECT_GET_ACTIVATED	2207	uint32 context, uint32 do_id
OBJECT_GET_ACTIVATED_RESP	2208	uint32 context, uint32 do_id, uint8 is_active
OBJECT_DELETE_FIELD_DISK	2230	uint32 do_id, uint16 field_id
OBJECT_DELETE_FIELDS_DISK	2231	uint32 do_id, uint16 n_fields, [uint16 field_id] * n_fields
OBJECT_DELETE_DISK	2232	uint32 do_id

DBServer | Database Object Messages

Message	ID	Parameters
CREATE_OBJECT	3000	uint32 context, uint16 dclass_id, uint16 n_fields, [uint16 field_id, <VALUE>] * n_fields
CREATE_OBJECT_RESP	3001	uint32 context, uint32 do_id
OBJECT_GET_FIELD	3010	uint32 context, uint32 do_id, uint16 field_id
OBJECT_GET_FIELD_RESP	3011	uint32 context, uint8 success, [uint16 field_id, <VALUE>]
OBJECT_GET_FIELDS	3012	uint32 context, uint32 do_id, uint16 n_fields, [uint16 field_id] * n_fields
OBJECT_GET_FIELDS_RESP	3013	uint32 context, uint8 success, [uint16 n_fields], [uint16 field_id, <VALUE>] * n_fields
OBJECT_GET_ALL	3014	uint32 context, uint32 do_id
OBJECT_GET_ALL_RESP	3015	uint32 context, uint8 success, [uint16 dclass_id, uint16 n_fields], [uint16 field_id, <VALUE>] * n_fields
OBJECT_SET_FIELD	3020	uint32 do_id, uint16 field_id, <VALUE>
OBJECT_SET_FIELDS	3021	uint32 do_id, uint16 n_fields, [uint16 field_id, <VALUE>] * n_fields
OBJECT_SET_FIELD_IF_EQUALS	3022	uint32 context, uint32 do_id, uint16 field_id, <VALUE> old, <VALUE> new
OBJECT_SET_FIELD_IF_EQUALS_RESP	3023	uint32 context, uint8 success, [uint16 field_id, <VALUE>]
OBJECT_SET_FIELDS_IF_EQUALS	3024	uint32 context, uint32 do_id, uint16 n_fields, [uint16 field_id, <VALUE> old, <VALUE> new] * n_fields
OBJECT_SET_FIELDS_IF_EQUALS_RESP	3025	uint32 context, uint8 success, [uint16 n_fields], [uint16 field_id, <VALUE>] * n_fields
OBJECT_SET_FIELD_IF_EMPTY	3026	uint32 context, uint32 do_id, uint16 field_id, <VALUE>
OBJECT_SET_FIELD_IF_EMPTY_RESP	3027	uint32 context, uint8 success, [uint16 field_id, <VALUE>]
OBJECT_DELETE_FIELD	3030	uint32 do_id, uint16 field_id
OBJECT_DELETE_FIELDS	3031	uint32 do_id, uint16 n_fields, [uint16 field_id] * n_fields
OBJECT_DELETE	3032	uint32 do_id