Updating to 0.6.0

- Add comments inside proto files to better describe the purposes of

each message, service and procedure.

- Add the `RegisterExistingClient` procedure to add the ability to

register a client with a pre-existing `Connection`.

- Add the `uuid` field to `Log` to allow for servers to determine

whether a `Log` with the same values is _actually_ the same or different

depending on the `uuid`.

backtrace_data.proto

@@ -2,10 +2,12 @@ syntax = "proto3";
 
 package codectrl.data.backtrace_data;
 
+// Generalised message containing information regarding a single stacktrace
+// item.
 message BacktraceData {
-  string name = 1;
-  string filePath = 2;
-  uint32 lineNumber = 3;
+  string name         = 1;
+  string filePath     = 2;
+  uint32 lineNumber   = 3;
   uint32 columnNumber = 4;
-  string code = 5;
+  string code         = 5;
 }

cc_service.proto

@@ -5,33 +5,67 @@ package codectrl.logs_service;
 
 import "log.proto";
 
+// Empty is needed because protobuf has no concept of a `()` (unit type) or
+// void type, every rpc needs to have at least one argument, so `Empty` is
+// provided when no argument is required.
 message Empty {}
 
-enum Received {
+// Status codes for whether or not a particular request has succeeded.
+enum RequestStatus {
   CONFIRMED = 0;
   ERROR = 1;
 }
 
+// Describes the connection between the interface and a given server. Each
+// client is suppllied with a uuid that is saved to disk or to localStorage.
+// The server uses this information to determine which logs should be sent to
+// each client and to skip duplicate identified by the `uuid` of the log.
 message Connection {
   string uuid = 1;
 }
 
-message ReceivedResult {
-  string message = 1;
-  Received status = 2;
+// Returned by the procedures to describe the result of a request.
+message RequestResult {
+  string        message = 1;
+  RequestStatus status  = 2;
 }
 
+// LogServer is the service that should only be implemented by log servers
+// that can be connected to by a CodeCtrl front-end. Language loggers should
+// not implement this service or use it as a client for that matter. Ways of
+// enforcing that only servers can receive logs iS TBD but will be worked on
+// in the future.
 service LogServer {
-  // Implemented and used by the GUI
-  rpc GetLog(Connection) returns (data.log.Log) {}
-  rpc GetLogs(Connection) returns (stream data.log.Log) {}
+  // Gets the latest log from the server, generally not used but is here for
+  // compatibiliy's sake in the case where a front-end cannot use a stream.
+  rpc GetLog(Connection)                 returns (data.log.Log)        {}
 
-  rpc RegisterClient(Empty) returns (Connection) {}
+  // Gets a stream of the available logs, this should be preferred over
+  // `GetLog` when possible.
+  rpc GetLogs(Connection)                returns (stream data.log.Log) {}
+
+  // Registers a new front-end connection to a server instance and returns the
+  // `Connection` message with a `uuid`.
+  rpc RegisterClient(Empty)              returns (Connection)          {}
+
+  // Registers an already pre-existing connection to a server instance using an
+  // already generated `uuid` supplied in the `Connection`. Servers should
+  // verify that the supplied `uuid` is, in fact, a valid hyphenated v4 UUID.
+  // Returns a boolean whether or not the registration was succesful.
+  rpc RegisterExistingClient(Connection) returns (RequestResult)       {}
 }
 
+// LogClient is the service that needs to be implemented by log servers so
+// they can determine how the logs are stored when they are received by the
+// server. Loggers must only use this service as a client.
 service LogClient {
-  // Implemented and used by each language logger
-  rpc SendLog(data.log.Log) returns (ReceivedResult) {}
-  rpc SendLogs(stream data.log.Log) returns (ReceivedResult) {}
+  // Sends a single log. Should only be used in cases where log batching is
+  // not possible or not determinable.
+  rpc SendLog(data.log.Log)         returns (RequestResult) {}
+
+  // Sends a stream of logs. Should generally be preferred over `SendLog` as
+  // it allows for batch sending of `Log`s and _should_ be more efficient on
+  // resources.
+  rpc SendLogs(stream data.log.Log) returns (RequestResult) {}
 }
 

log.proto

@@ -4,14 +4,22 @@ package codectrl.data.log;
 
 import "backtrace_data.proto";
 
+// Main log message for use when sending to a CodeCtrl gRPC server.
 message Log {
-  repeated backtrace_data.BacktraceData stack = 1;
-  uint32 lineNumber = 2;
-  map<string, string> codeSnippet = 3;
-  string message = 4;
-  string messageType = 5;
-  string fileName = 6;
-  string address = 7;
-  string language = 8;
-  repeated string warnings = 9;
+  // NOTE: This field should be generated by CodeCtrl gRPC servers, any value
+  // assigned to it by loggers will be overwritten. Therefore, leave it as a
+  // blank.
+  string                                uuid        = 1;
+  repeated backtrace_data.BacktraceData stack       = 2;
+  uint32                                lineNumber  = 3;
+  map<string, string>                   codeSnippet = 4;
+  string                                message     = 5;
+  string                                messageType = 6;
+  string                                fileName    = 7;
+  string                                address     = 8;
+  string                                language    = 9;
+  // NOTE: This field should be generated by CodeCtrl gRPC servers, any value
+  // assigned to it by loggers will be overwritten. Therefore, leave it as a
+  // blank.
+  repeated string                       warnings    = 10;
 }