hansken_extraction_plugin.framework.RpcCallMessages.proto Maven / Gradle / Ivy
syntax = "proto3";
// UPDATE NOTICE
//
// If you make changes to the proto definitions (add, update, delete)s, please
// also update VersionUtil.java and apiversion.properties as described in the
// projects README.md
package org.hansken.extraction.plugin.grpc;
option java_multiple_files = true;
option java_package = "org.hansken.extraction.plugin.grpc";
import "google/protobuf/any.proto";
import "hansken_extraction_plugin/framework/DataMessages.proto";
/**
* This proto file contains message definitions which represent method calls, such as reading
* a certain amount of bytes from the processed data sequence. As seen in ExtractionPluginService,
* we have a single stream between client and server when processing a trace. These messages are
* sent through this stream in order to invoke a method on the other side.
*/
/**
* Start is the first message from the plugin client to the plugin server.
*
* After receiving this message, the extraction plugin starts processing a
* trace. The start message already contains information of the trace to
* process.
* The client should send as much of the required information to the server for
* performance reasons: there are no additional round-trips required to get
* information from server to client.
*/
message RpcStart {
RpcTrace trace = 1;
RpcDataContext dataContext = 2;
}
/**
* Update which contains actions to execute while the processing of the plugin
* is still running (e.g. due to buffered updates being flushed). They can contain
* for example a batch of child traces to add to the result.
*/
message RpcBatchUpdate {
repeated google.protobuf.Any actions = 1;
}
message RpcProfile {
map profile_int64s = 2;
map profile_doubles = 3;
}
/**
* Signal from server to client that processing the trace is finished.
* The message may contain a (final) set of trace update actions.
* When receiving this request, the client should close the communication
* channel.
*
* The server closes the gRPC stream directly after sending the Finish message.
*/
message RpcFinish {
RpcBatchUpdate update = 1;
RpcProfile profile = 2;
}
/**
* This response behaves the same as {@link org.hansken.extraction.plugin.grpc.RpcFinish}, with the exception
* that it is only used when an error occurs during the processing of a trace.
*
* The response contains a partial list of actions, a (error)statusCode and an errorDescription.
*
* The server processes the partial results towards the client, and throws an exception with the
* statusCode & errorDescription which should be handled client-side.
*/
message RpcPartialFinishWithError {
repeated google.protobuf.Any actions = 1;
string statusCode = 2;
string errorDescription = 3;
RpcProfile profile = 4;
}
/**
* The following messages are used to create new child traces and updating
* existing traces. For example, say we create a simple trace tree as follows
* (each node is represented by its id and the given name):
*
* 0 (folder.name = root)
* |____ 0-0 (folder.name = folder0)
| |____ 0-0-0 (file.name = file0)
* |
* |____ 0-1 (file.name = file1)
*
* Then the flow of the messages could be:
* Hansken <<- ExtractionPlugin : enrichTrace (0, {'folder.name', 'root'})
* Hansken <<- ExtractionPlugin : beginChild (0-0)
* Hansken <<- ExtractionPlugin : enrichTrace (0-0, {'folder.name', 'folder0'})
* Hansken <<- ExtractionPlugin : beginChild (0-0-0)
* Hansken <<- ExtractionPlugin : enrichTrace (0-0-0, {'file.name', 'file0'})
* Hansken <<- ExtractionPlugin : finishChild (0-0-0)
* Hansken <<- ExtractionPlugin : finishChild (0-0)
* Hansken <<- ExtractionPlugin : beginChild (0-1)
* Hansken <<- ExtractionPlugin : enrichTrace (0-1, {'file.name', 'file1'})
* Hansken <<- ExtractionPlugin : finishChild (0-1)
*
* Note that setting the name on the root trace could also be sent as the last request,
* because we would again be in scope of the root trace.
*
* Also note that the plugin will wait for acknowledgement of Hansken (or any other client).
* These requests can (and will) be batched.
*/
/**
* Update the trace currently being processed with the information in the given trace. Note that
* this trace only contains new properties not already set on the trace being processed (i.e. the
* properties which were already set on the trace in RpcStart).
*/
message RpcEnrichTrace {
RpcTrace trace = 1;
}
/**
* Signal that we are in the scope of a newly created child.
*/
message RpcBeginChild {
string id = 1;
string name = 2;
}
/*
* Signal that we exited the last created child scope.
*/
message RpcFinishChild {
string id = 1;
}
/**
* Read data from the data sequence which answers to the traceUid with the specified dataType.
*/
message RpcRead {
int64 position = 1;
int32 count = 2;
/**
* The id of the trace.
* @deprecated since version 0.4.9: use traceUid instead. Different traces from different images may use the same traceId,
* so using the traceId to identify data may cause wrong data to return.
*/
string traceId = 3 [deprecated = true];
string dataType = 4;
string traceUid = 5;
}
/**
* Signal that we are starting to write a data stream of given type.
*/
message RpcBeginDataStream {
string traceId = 1;
string dataType = 2;
/**
* Optional encoding of the data, if set, the receiver can assume that
* the bytes are encoded text, encoded with with given encoding.
*/
string encoding = 3;
}
/**
* Message containing a chunk of data from the currently written data stream.
*/
message RpcWriteDataStream {
string traceId = 1;
string dataType = 2;
bytes data = 3;
}
/**
* Signal that we finished writing the data stream of given type.
*/
message RpcFinishDataStream {
string traceId = 1;
string dataType = 2;
}
/**
* RpcSearchRequest search scope options.
*/
enum RpcSearchScope {
Project = 0; // default if not set in older plugin versions
Image = 1;
}
/**
* A search request to retrieve traces. The count is an integer representing the number of traces to return and the query is
* a HQL query used to find matching traces.
*/
message RpcSearchRequest {
int32 count = 1;
string query = 2;
RpcSearchScope scope = 3;
}
/**
* Search response containing the queried traces and the total number of found traces. This number
* may be higher than the count provided with the RpcSearchRequest.
*/
message RpcSearchResult {
int64 totalResults = 1;
repeated RpcSearchTrace traces = 2;
}