pubsub_api.proto

/*
 * Salesforce Pub/Sub API Version 1.
 */

syntax = "proto3";
package eventbus.v1;

option java_multiple_files = true;
option java_package = "com.salesforce.eventbus.protobuf";
option java_outer_classname = "PubSubProto";

option go_package = "github.com/developerforce/pub-sub-api/go/proto";

/*
 * Contains information about a topic and uniquely identifies it. TopicInfo is returned by the GetTopic RPC method.
 */
message TopicInfo {
  // Topic name
  string topic_name = 1;
  // Tenant/org GUID
  string tenant_guid = 2;
  // Is publishing allowed?
  bool can_publish = 3;
  // Is subscription allowed?
  bool can_subscribe = 4;
  /* ID of the current topic schema, which can be used for
   * publishing of generically serialized events.
   */
  string schema_id = 5;
  // RPC ID used to trace errors.
  string rpc_id = 6;
}

/*
 * A request message for GetTopic. Note that the tenant/org is not directly referenced
 * in the request, but is implicitly identified by the authentication headers.
 */
message TopicRequest {
  // The name of the topic to retrieve.
  string topic_name = 1;
}

/*
 * Reserved for future use.
 * Header that contains information for distributed tracing, filtering, routing, etc.
 * For example, X-B3-* headers assigned by a publisher are stored with the event and
 * can provide a full distributed trace of the event across its entire lifecycle.
 */
message EventHeader {
  string key = 1;
  bytes value = 2;
}

/*
 * Represents an event that an event publishing app creates.
 */
message ProducerEvent {
  // Either a user-provided ID or a system generated guid
  string id = 1;
  // Schema fingerprint for this event which is hash of the schema
  string schema_id = 2;
  // The message data field
  bytes payload = 3;
  // Reserved for future use. Key-value pairs of headers.
  repeated EventHeader headers = 4;
}

/*
 * Represents an event that is consumed in a subscriber client.
 * In addition to the fields in ProducerEvent, ConsumerEvent has the replay_id field.
 */
message ConsumerEvent {
  // The event with fields identical to ProducerEvent
  ProducerEvent event = 1;
  /* The replay ID of the event.
   * A subscriber app can store the replay ID. When the app restarts, it can resume subscription
   * starting from events in the event bus after the event with that replay ID.
   */
  bytes replay_id = 2;
}

/*
 * Event publish result that the Publish RPC method returns. The result contains replay_id or a publish error.
 */
message PublishResult {
  // Replay ID of the event
  bytes replay_id = 1;
  // Publish error if any
  Error error = 2;
  // Correlation key of the ProducerEvent
  string correlationKey = 3;
}

// Contains error information for an error that an RPC method returns.
message Error {
  // Error code
  ErrorCode code = 1;
  // Error message
  string msg = 2;
}

// Supported error codes
enum ErrorCode {
  UNKNOWN = 0;
  PUBLISH = 1;
}

/*
 * Supported subscription replay start values.
 * By default, the subscription will start at the tip of the stream if ReplayPreset is not specified.
 */
enum ReplayPreset {
  // Start the subscription at the tip of the stream.
  LATEST = 0;
  // Start the subscription at the earliest point in the stream.
  EARLIEST = 1;
  // Start the subscription after a custom point in the stream. This must be set with a valid replay_id in the FetchRequest.
  CUSTOM = 2;
}

/*
 * Request for the Subscribe streaming RPC method. This request is used to:
 * 1. Establish the initial subscribe stream.
 * 2. Request more events from the subscription stream.
 * Flow Control is handled by the subscriber via num_requested.
 * A client can specify a starting point for the subscription with replay_preset and replay_id combinations.
 * If no replay_preset is specified, the subscription starts at LATEST (tip of the stream).
 * replay_preset and replay_id values are only consumed as part of the first FetchRequest. If
 * a client needs to start at another point in the stream, it must start a new subscription.
 */
message FetchRequest {
  /*
   * Identifies a topic for subscription in the very first FetchRequest of the stream. The topic cannot change
   * in subsequent FetchRequests within the same subscribe stream, but can be omitted for efficiency.
   */
  string topic_name = 1;

  /*
   * Subscription starting point. This is consumed only as part of the first FetchRequest
   * when the subscription is set up.
   */
  ReplayPreset replay_preset = 2;
  /*
   * If replay_preset of CUSTOM is selected, specify the subscription point to start after.
   * This is consumed only as part of the first FetchRequest when the subscription is set up.
   */
  bytes replay_id = 3;
  /*
   * Number of events a client is ready to accept. Each subsequent FetchRequest informs the server
   * of additional processing capacity available on the client side. There is no guarantee of equal number of
   * FetchResponse messages to be sent back. There is not necessarily a correspondence between
   * number of requested events in FetchRequest and the number of events returned in subsequent
   * FetchResponses.
   */
  int32 num_requested = 4;
  // For internal Salesforce use only.
  string auth_refresh = 5;
}

/*
 * Response for the Subscribe streaming RPC method. This returns ConsumerEvent(s).
 * If there are no events to deliver, the server sends an empty batch fetch response with the latest replay ID. The
 * empty fetch response is sent within 270 seconds. An empty fetch response provides a periodic keepalive from the
 * server and the latest replay ID.
 */
message FetchResponse {
  // Received events for subscription for client consumption
  repeated ConsumerEvent events = 1;
  // Latest replay ID of a subscription. Enables clients with an updated replay value so that they can keep track
  // of their last consumed replay. Clients will not have to start a subscription at a very old replay in the case where a resubscribe is necessary.
  bytes latest_replay_id = 2;
  // RPC ID used to trace errors.
  string rpc_id = 3;
  // Number of remaining events to be delivered to the client for a Subscribe RPC call.
  int32 pending_num_requested = 4;
}

/*
 * Request for the GetSchema RPC method. The schema request is based on the event schema ID.
 */
message SchemaRequest {
  // Schema fingerprint for this event, which is a hash of the schema.
  string schema_id = 1;
}

/*
 * Response for the GetSchema RPC method. This returns the schema ID and schema of an event.
 */
message SchemaInfo {
  // Avro schema in JSON format
  string schema_json = 1;
  // Schema fingerprint
  string schema_id = 2;
  // RPC ID used to trace errors.
  string rpc_id = 3;
}

// Request for the Publish and PublishStream RPC method.
message PublishRequest {
  // Topic to publish on
  string topic_name = 1;
  // Batch of ProducerEvent(s) to send
  repeated ProducerEvent events = 2;
  // For internal Salesforce use only.
  string auth_refresh = 3;
}

/*
 * Response for the Publish and PublishStream RPC methods. This returns
 * a list of PublishResults for each event that the client attempted to
 * publish. PublishResult indicates if publish succeeded or not
 * for each event. It also returns the schema ID that was used to create
 * the ProducerEvents in the PublishRequest.
 */
message PublishResponse {
  // Publish results
  repeated PublishResult results = 1;
  // Schema fingerprint for this event, which is a hash of the schema
  string schema_id = 2;
  // RPC ID used to trace errors.
  string rpc_id = 3;
}

/*
 * The Pub/Sub API provides a single interface for publishing and subscribing to platform events, including real-time
 * event monitoring events, and change data capture events. The Pub/Sub API is a gRPC API that is based on HTTP/2.
 *
 * A session token is needed to authenticate. Any of the Salesforce supported
 * OAuth flows can be used to obtain a session token:
 * https://help.salesforce.com/articleView?id=sf.remoteaccess_oauth_flows.htm&type=5
 *
 * For each RPC, a client needs to pass authentication information
 * as metadata headers (https://www.grpc.io/docs/guides/concepts/#metadata) with their method call.
 *
 * For Salesforce session token authentication, use:
 *   accesstoken : access token
 *   instanceurl : Salesforce instance URL
 *   tenantid : tenant/org id of the client
 *
 * StatusException is thrown in case of response failure for any request.
 */
service PubSub {
  /*
   * Bidirectional streaming RPC to subscribe to a Topic. The subscription is pull-based. A client can request
   * for more events as it consumes events. This enables a client to handle flow control based on the client's processing speed.
   *
   * Typical flow:
   * 1. Client requests for X number of events via FetchRequest.
   * 2. Server receives request and delivers events until X events are delivered to the client via one or more FetchResponse messages.
   * 3. Client consumes the FetchResponse messages as they come.
   * 4. Client issues new FetchRequest for Y more number of events. This request can
   *    come before the server has delivered the earlier requested X number of events
   *    so the client gets a continuous stream of events if any.
   *
   * If a client requests more events before the server finishes the last
   * requested amount, the server appends the new amount to the current amount of
   * events it still needs to fetch and deliver.
   *
   * A client can subscribe at any point in the stream by providing a replay option in the first FetchRequest.
   * The replay option is honored for the first FetchRequest received from a client. Any subsequent FetchRequests with a
   * new replay option are ignored. A client needs to call the Subscribe RPC again to restart the subscription
   * at a new point in the stream.
   *
   * The first FetchRequest of the stream identifies the topic to subscribe to.
   * If any subsequent FetchRequest provides topic_name, it must match what
   * was provided in the first FetchRequest; otherwise, the RPC returns an error
   * with INVALID_ARGUMENT status.
   */
  rpc Subscribe (stream FetchRequest) returns (stream FetchResponse);

  // Get the event schema for a topic based on a schema ID.
  rpc GetSchema (SchemaRequest) returns (SchemaInfo);

  /*
   * Get the topic Information related to the specified topic.
   */
  rpc GetTopic (TopicRequest) returns (TopicInfo);

  /*
   * Send a publish request to synchronously publish events to a topic.
   */
  rpc Publish (PublishRequest) returns (PublishResponse);

  /*
   * Bidirectional Streaming RPC to publish events to the event bus.
   * PublishRequest contains the batch of events to publish.
   *
   * The first PublishRequest of the stream identifies the topic to publish on.
   * If any subsequent PublishRequest provides topic_name, it must match what
   * was provided in the first PublishRequest; otherwise, the RPC returns an error
   * with INVALID_ARGUMENT status.
   *
   * The server returns a PublishResponse for each PublishRequest when publish is
   * complete for the batch. A client does not have to wait for a PublishResponse
   * before sending a new PublishRequest, i.e. multiple publish batches can be queued
   * up, which allows for higher publish rate as a client can asynchronously
   * publish more events while publishes are still in flight on the server side.
   *
   * PublishResponse holds a PublishResult for each event published that indicates success
   * or failure of the publish. A client can then retry the publish as needed before sending
   * more PublishRequests for new events to publish.
   *
   * A client must send a valid publish request with one or more events every 70 seconds to hold on to the stream.
   * Otherwise, the server closes the stream and notifies the client. Once the client is notified of the stream closure,
   * it must make a new PublishStream call to resume publishing.
   */
  rpc PublishStream (stream PublishRequest) returns (stream PublishResponse);
}

// Style guide: https://developers.google.com/protocol-buffers/docs/style