hansken_extraction_plugin.framework.RpcCallMessages.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of grpc Show documentation
There is a newer version: 0.8.3
syntax = "proto3";

// UPDATE NOTICE
//
// If you make changes to the proto definitions (add, update, delete)s, please
// also update VersionUitl.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;
}

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

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

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

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

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

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