Merge pull request #11 from rdner/general-cleanup

Clean up the spec

api/messages/persisted_index.proto

@@ -20,5 +20,5 @@ message PersistedIndexReply {
 
  // The highest sequential index that has been persisted. (See the API
  // README for details on what "persisted" entails.)
- int64 persisted_index = 2;
+ uint64 persisted_index = 2;
 }

api/messages/publish.proto

@@ -15,15 +15,17 @@ message PublishRequest {
  // matches the current uuid of the shipper process. The uuid identifies
  // the current shipper process, and is updated when the shipper restarts.
  // Its current value is returned in every shipper API reply.
+ //
  // A uuid in a PublishRequest is used for enforcing at-least-once delivery
  // guarantees: inputs may include the known shipper uuid with their request,
  // ensuring it will be rejected if the shipper restarts. In this case the
  // input should rewind to the last known-good position in its data sequence.
+ //
  // Note that this issue only arises during error states, since Agent only
  // restarts the shipper when its process is terminated or nonresponsive.
- string uuid = 2;
+ string uuid = 1;
 
- repeated Event events = 1;
+ repeated Event events = 2;
 }
 
 // Event is a translation of beat.Event into protobuf.
@@ -33,11 +35,11 @@ message Event {
  // Source of the generated event.
  Source source = 2;
  // Data stream for the event.
- DataStream data_stream = 4;
+ DataStream data_stream = 3;
  // Metadata JSON object (map[string]google.protobuf.Value)
- messages.Struct metadata = 5;
+ messages.Struct metadata = 4;
  // Field JSON object (map[string]google.protobuf.Value)
- messages.Struct fields = 6;
+ messages.Struct fields = 5;
 }
 
 // Source information required for proper event tracking, processing and routing
@@ -68,16 +70,16 @@ message PublishReply {
  // The number of events accepted by the shipper, in the same order as the
  // PublishRequest. If uuid in the reply differs from uuid in the request,
  // then accepted_count is always zero.
- int32 accepted_count = 2;
+ uint32 accepted_count = 2;
 
  // The final internal index for the events that were accepted. Inputs that
  // want to guarantee event persistence can do it with this field: when the
  // persisted_index of a PublishReply or PersistedIndexReply is >= this value,
  // the events from this publish request have been persisted and the input can
  // safely advance. See the API README for details.
- int64 accepted_index = 3;
+ uint64 accepted_index = 3;
 
  // The highest sequential index that has been persisted. (See the API
  // README for details on what "persisted" entails.)
- int64 persisted_index = 4;
+ uint64 persisted_index = 4;
 }

api/shipper.proto

@@ -13,19 +13,14 @@ import "messages/persisted_index.proto";
 service Producer {
  // Publishes a list of events via the Elastic agent shipper.
  // Blocks until all processing steps complete and data is written to the queue.
- // The order of `PublishRequest.events` always matches `PublishReply.results`.
  //
- // Returns the `codes.ResourceExhausted` gRPC status code if the queue is full and none of the events
- // can be accepted at the moment.
- //
- // If the queue could accept some events from the request, this returns a successful response
- // containing results for the first K events that were accepted by the queue.
- // The client is expected to retry sending the rest of the events in a separate request later.
- //
- // Inputs may execute multiple concurrent Produce requests for independent data streams. 
- // The order in which concurrent requests complete is not guaranteed. Use sequential requests to
- // control ordering.
+ // If the queue could not accept some events from the request, this returns a successful response
+ // containing a count of events that were accepted by the queue.
+ // The client is expected to retry sending the rest of the events in a separate request.
+ // 
+ // The client is also expected to have some kind of backoff strategy
+ //	in case of a reply with an accepted count < the amount of sent events.
  rpc PublishEvents(messages.PublishRequest) returns (messages.PublishReply);
- // Returns the shipper's uuid and its position in the event stream.
+ // Returns the shipper's uuid and its current position in the event stream (persisted index).
  rpc PersistedIndex(messages.PersistedIndexRequest) returns (stream messages.PersistedIndexReply);
 }