Node Protocol - AtlasNet/Protocols GitHub Wiki

Each node provides an Apache Thrift service endpoint.

Transport in use is TCP. Default port is 1975. Thrift protocol in use is BinaryProtocol.

Service specification

Node information block

struct AtlasNodeInfo {
    1: string name,
    2: string host,
    3: i64 port,
    4: i64 protocolVersion
}

• name - arbitrary node description, provided by the node itself
• host - node hostname or IP address
• port - node's TCP port
• protocolVersion - node's service protocol version (currently 1).

Message information block

struct AtlasMessage {
    1: string data,
    2: string recipientKey
}

• data - message payload in Base64
• recipientKey - PEM-encoded message recipient's key

Message listing information block

struct AtlasListing {
    1: AtlasNodeInfo node,
    2: i64 id,    
}

• node - node information block describing node on which the message was received and stored
• id - message ID on the storage node

Node service

service AtlasNode {
    i32                 ping(),
    AtlasNodeInfo       getInfo(),

    void                hello(1: AtlasNodeInfo info),
    void                join(),

    void                registerNode(1: AtlasNodeInfo info, 2: AtlasNodeInfo via),
    list<AtlasNodeInfo> getKnownNodes(),

    void                postMessage(1: AtlasMessage message),
    void                registerMessageListing(1: string recipientKey, 2: i64 messageId),
    void                unregisterMessageListing(1: i64 messageId),

    string              getAuthChallenge(1: string publicKey),
    i64                 confirmAuth(1: string response),

    list<AtlasListing>  getListings(),
    i64                 hasMessage(1: i64 id),
    AtlasMessage        retrieveMessage(1: i64 id)
}

• i32 ping() - ensures connectivity - should return 1 if the node is operational and usable
• AtlasNodeInfo getInfo() - returns node information block for this node
• void hello(1: AtlasNodeInfo info) - identifies caller node to the serving node
• void join() - notifies the serving node that caller node would like to join the network through the serving node
• void registerNode(1: AtlasNodeInfo info, 2: AtlasNodeInfo via) - notifies the serving node that a 3rd party node has joined the network via the caller node (caller node's information supplied in via argument) and should be added to the known nodes list
• list getKnownNodes() - should return current list of nodes known by the serving node
• void postMessage(1: AtlasMessage message) - stores a supplied message block on the serving node
• void registerMessageListing(1: string recipientKey, 2: i64 messageId) - notifies the serving node that a new message listing, for a message stored on the caller node, is to be created. messageId denotes message ID on the caller node, and recipientKey contains PEM-encoded public key of the message's recipient
• void unregisterMessageListing(1: i64 messageId) - notifies the serving node that a message with ID messageId has been retrieved from the caller node, or has expired, and should be removed from serving node's message listings
• string getAuthChallenge(1: string publicKey) - notifies the serving node that a calling client would like to initiate an authentication sequence and prove its identity. Returns a Base64-encoded cryptographic challenge block. See Authentication
• i64 confirmAuth(1: string response) - submits a response to an authentication challenge. Returns 1 if the response is correct, and connection is now AUTHENTICATED, otherwise the connection remains in UNAUTHENTICATED state.
• list getListings() - returns a list of message listing blocks which describe messages pending for the currently authenticated recipient. Connection must be in AUTHENTICATED state before this method is used
• i64 hasMessage(1: i64 id) - returns 1 if a message with ID id is currently stored on the node and can be retrieved by currently authenticated client. Connection must be in AUTHENTICATED state before this method is used
• AtlasMessage retrieveMessage(1: i64 id) - retrieves a message with ID id from the node. Message is then deleted from the node's storage. Connection must be in AUTHENTICATED state before this method is used