From 4d41da7be6ac0ea7d7ef7ea9ddf18ee305f37324 Mon Sep 17 00:00:00 2001 From: Samuel Boyden Date: Sat, 2 Jul 2022 01:39:18 +0100 Subject: [PATCH] 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 | 10 ++++---- cc_service.proto | 56 +++++++++++++++++++++++++++++++++++--------- log.proto | 26 +++++++++++++------- 3 files changed, 68 insertions(+), 24 deletions(-) diff --git a/backtrace_data.proto b/backtrace_data.proto index 2efdd12..577274f 100644 --- a/backtrace_data.proto +++ b/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; } diff --git a/cc_service.proto b/cc_service.proto index 4925e93..9010712 100644 --- a/cc_service.proto +++ b/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) {} } diff --git a/log.proto b/log.proto index 2de565f..ffd86aa 100644 --- a/log.proto +++ b/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 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 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; }