Added Directory structure for new rsctrl protocol.

* see NOTES.txt for how to implement it.
 * protobuf definitions are in rsctrl/src/definition

This does not compile yet, and just early thoughts.
Suggestions and help developing this are welcome.



git-svn-id: http://svn.code.sf.net/p/retroshare/code/branches/v0.5-gxs-b1@5445 b45a01b8-16f6-495d-af2f-9b41ad6348cc
This commit is contained in:
drbob 2012-08-20 18:59:13 +00:00
parent bb10b6b400
commit 8a7c011c5d
3 changed files with 227 additions and 0 deletions

60
rsctrl/src/NOTES.txt Normal file
View File

@ -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.

View File

@ -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;
}

View File

@ -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;
}
///////////////////////////////////////////////////////////////