diff --git a/rsctrl/src/NOTES.txt b/rsctrl/src/NOTES.txt new file mode 100644 index 000000000..a06f35ce2 --- /dev/null +++ b/rsctrl/src/NOTES.txt @@ -0,0 +1,60 @@ + +This document proposes the finer details of how to communicate with RS, +using SSH and protobuf classes. +========================================================================== + +Message Format +==================== + +Protobuf serialisation does not identify Message Types or Message Size. +So we need to have an encapsulation header system + +These headers describe the actual message via a MsgId and MsgSize. +Care must be taken to ensure these IDS are correct, as this is NOT enforced +by protobuf, and will lead to incorrect deserialisation! + +In Each .proto there is a list of MsgIds as an ENUM. + +The protocol message format is as follows: + [HEADER: 16 bytes: 4 x Network Order uint32_t][ VARIABLE LENGTH BODY ] + + [ MAGIC_CODE ] [ MSG_ID ] [ REQ_ID ] [ BODY_SIZE ] [ ..... BODY ..... ] + MagicCode = 0x137f0001. will be incremented for new versions of the protocol. + MsgID = Corresponds to the format of the Body. + ReqID = Generated by Requester, Returned in Response, + make sure its unique. (undefined behaviour for duplicates) + BodySize = Byte Length of Body. + + The Body will consist of a protobuf encoded message. + + +Usage +================= + * Create SSH connection to retroshare-nogui. + * Create Request Message(s), and send over SSH channel - You can send as meny requests as you want. + * They will processed, and responses sent back (potentially in an arbitary order). + +MsgIDs +================= +In Each .proto there is a list of MsgIds as an ENUM. + +0x00 XX XX xx => Reserved for libretroshare Requests. (XX - area, xxxx specific msg) +0x01 XX XX xx => Reserved for libretroshare Responses + +eg. 0x00 (fa bc) [01] -> Request, 0x01 (fa bc) [01/02/03] -> responses + +0x10 YY YY yy => Extensions for project YY (16k), with sub commands yy (256) +0x11 YY YY yy + +... if we run out of YY's will use 0x20 etc. + + +Extensions +================= + +These are welcome and encouraged. +We just need to make sure that MsgIDs don't clash. + + + + diff --git a/rsctrl/src/definition/base.proto b/rsctrl/src/definition/base.proto new file mode 100644 index 000000000..076bfe06a --- /dev/null +++ b/rsctrl/src/definition/base.proto @@ -0,0 +1,61 @@ +package rsctrl.base: + +/////////////////////////////////////////////////////////////// +// These are basic Messages, which are used as building blocks +// throughout the rest of the interface. +// They should not be sent RAW, but should be wrapped in another msg. +/////////////////////////////////////////////////////////////// + +/////////////////////////////////////////////////////////////// +// Basic Status Response, should be in all responses + +message Status { + enum StatusCode { + FAILED = 0; + INVALID_QUERY = 1; + SUCCESS = 2; + READMSG = 3; + } + required StatusCode code = 1; + optional string msg = 2; +} + +/////////////////////////////////////////////////////////////// +// Peer structures, mainly rsctrl.peers related. + +message Location { + required string ssl_id = 1; + required string location = 2; + + required string localaddr = 3; + required string extaddr = 4; +} + +message Person { + required string gpg_id = 1; + required string name = 2; + + repeated Location locations = 3; +} + +/////////////////////////////////////////////////////////////// +// File structures, mainly rsctrl.files related. + +message File { + required string name = 1; + required string hash = 2; + required int64 size = 3; + + optional string path = 4; + optional string avail = 5; + +} + +message Dir { + required string name = 1; + required string path = 2; + + repeated Dir subdirs = 3; + repeated File files = 4; +} + diff --git a/rsctrl/src/definition/peers.proto b/rsctrl/src/definition/peers.proto new file mode 100644 index 000000000..8f0539f0a --- /dev/null +++ b/rsctrl/src/definition/peers.proto @@ -0,0 +1,106 @@ +package rsctrl.peers: +/////////////////////////////////////////////////////////////// +// Access, and Control your Friends / Peers and related Settings. +/////////////////////////////////////////////////////////////// + +enum ExtensionId { BASE = 0; } +enum PackageId { PEERS = 1; } + +enum RequestMsgIds { + RequestPeers = 1; + RequestAddPeer = 2; + RequestModifyPeer = 2; +} + +enum ResponseMsgIds { + ResponsePeerList = 1; + ResponseAddPeer = 2; + ResponseModifyPeer = 2; +} + +/////////////////////////////////////////////////////////////// + +// REQUEST: RequestPeers +message RequestPeers { + + // About Who? + enum SetOption { + LISTED = 1; + ONLINE = 2; + FRIENDS = 3; + VALID = 4; + ALL = 5; + } + + // What do you want? + enum InfoOption { + NAMEONLY = 1; + BASIC = 2; + LOCATION = 3; + ALL = 4; + } + + required SetOption set = 1; + required InfoOption info = 2; + repeated string gpg_ids = 3; +} + + +// RESPONSE: ResponsePeerList +message ResponsePeerList { + required rsctrl.base.Status status = 1; + repeated rsctrl.base.Person peers = 2; +} + +/////////////////////////////////////////////////////////////// + +// REQUEST: RequestAddPeer +message RequestAddPeer { + + enum AddCmd { + NOOP = 0; // No op. + ADD = 1; // Add existing from gpg_id. + REMOVE = 2; // Remove existing from gpg_id. + IMPORT = 3; // Import from cert, with gpg_id. + EXAMINE = 4; // Examine cert, but no action. + } + + required string gpg_id = 1; + required AddCmd cmd = 2; + optional string cert = 3; +} + +// RESPONSE: ResponseAddPeer +message ResponseAddPeer { + required rsctrl.base.Status status = 1; + repeated rsctrl.base.Person peers = 2; +} + +/////////////////////////////////////////////////////////////// + +// REQUEST: RequestModifyPeer +message RequestModifyPeer { + + enum ModCmd { + NOOP = 0; + ADDRESS = 1; + DYNDNS = 2; + //SOMETHING_ELSE = 0x0000010; + //SOMETHING_ELSE = 0x0000020; + //SOMETHING_ELSE = 0x0000040; + //SOMETHING_ELSE = 0x0000080; + } + + required ModCmd cmd = 1; + //required int64 cmd = 1; // Could we OR the Cmds together? + repeated rsctrl.base.Person peers = 2; +} + +// RESPONSE: ResponseModifyPeer +message ResponseModifyPeer { + required rsctrl.base.Status status = 1; + repeated rsctrl.base.Person peers = 2; +} + +/////////////////////////////////////////////////////////////// +