service.proto

syntax = "proto2";
// Copyright 2012, Square Inc.

// This file provides the default Sake service exported on all Sake services. Useful for debugging
// remote hosts from the commandline or other tools.

package squareup.sake;

option java_package = "com.squareup.protos.sake";
option java_generic_services = true;

import "google/protobuf/descriptor.proto";

message SchemaRequest {
  /**
   * The list of services in which the client is interested. This can be used by the server to
   * prune the set of schema data that it returns to only those required by the given services.
   *
   * If empty, the server should return information about all of the services it exposes.
   */
  repeated string service_name = 1;
}

message SchemaResponse {
  /**
   * All proto files required to fully describe the contained services. The list <em>must</em> be
   * sorted in topological order: any element will depend only on previously-seen elements.
   */
  repeated google.protobuf.FileDescriptorProto file_descriptor = 1;

  message ServiceEntry {
    // Only the file_descriptor field is necessary. The service field is superfluous and should
    // no longer be used by clients that invoke the Schema RPC method.
    option deprecated = true;

    /** The unqualified name of the service. */
    optional string short_service_name = 1;
    /** The name of the FileDescriptorProto in which the service can be found. */
    optional string file_descriptor_name = 2;
  }

  /**
   * A list of services this server implements.
   *
   * @deprecated The mapping of service names and descriptor names can (and should) be inferred
   * solely from the list of file descriptors, so this field is not necessary
   */
  repeated ServiceEntry service = 2 [deprecated = true];

  /**
   * A list of fully-qualified service names that this server implements.
   */
  repeated string service_name = 3;
}

message ListRequest {
}

message ListResponse {
  repeated google.protobuf.ServiceDescriptorProto service = 1;
}

/** All fields are case sensitive (sorry). */
message CallRequest {
  /** Service name, does not need to be qualified. */
  optional string service_name = 1;

  /** Unqualified method name. */
  optional string method_name = 2;

  /** Proto format in JSON form. Must start and end with '{' and '}' */
  optional string json_body = 3;
}

message CallResponse {
  optional string json_body = 1;
}

message ProtocolCapability {
  required string name = 1;
  repeated string value = 2;
}

message OhHai {
  /** The client's desired protocol version. */
  optional string client_sake_version = 1;

  /** The client's protocol capabilities. */
  repeated ProtocolCapability client_capabilities = 2;

  /**
   * The set of services that this client expects the server to export. Each value should be a
   * fully-qualified service name.
   */
  repeated string expected_services = 3;

  /**
   * The host name of the client. Useful if the client's identity is otherwise obfuscated by, for
   * example, a hardware load balancer between the client and server.
   */
  optional string client_host_name = 4;

  /** The version of the client. */
  optional string client_version_sha = 5;
}

message KThxBai {
  /**
   * The negotiated protocol version, which should be equal to or older than the client's
   * desired protocol version.
   */
  optional string server_sake_version = 1;

  /**
   * The host name of the client. Useful if the server's identity is otherwise obfuscated by, for
   * example, a hardware load balancer between the client and server.
   */
  optional string server_host_name = 2;

  /** The server's protocol capabilities. */
  repeated ProtocolCapability server_capabilities = 3;

  /**
   * The set of services that the client expects but are not actually supported by the server.
   * Clients will generally require that this field be empty.
   */
  repeated string unsupported_services = 4;

  /** The version of the server. */
  optional string server_version_sha = 5;
}

message HeartbeatRequest {
}

message HeartbeatResponse {
  /**
   * A value that indicates the current health status. A value of zero indicates that this host
   * is not healthy and is not accepting requests. A value of 100 indicates that this host is
   * healthy. Values in between indicate some level of degradation.
   *
   * <p>These numeric values correspond to the values in HealthResponseCode enum constants.
   */
  optional uint32 health_level = 1;
}

message PingRequest {
  /** Opaque value that gets echoed back in the response as-is by the server. */
  optional bytes ping = 1;
}

message PingResponse {
  optional bytes pong = 1;
}

enum HealthResponseCode {
  DOWN = 0;
  MANUALLY_DEGRADED = 49; // only supported by v1.1+ of sake protocol
  DEGRADED = 50;          // only supported by v1.1+ of sake protocol
  UP = 100;
}

/**
 * Attached as a side channel message to Heartbeat requests in v1.0 of the sake protocol. This
 * message is not used in v1.1 of the protocol.
 */
message HealthMessage {
  optional HealthResponseCode health = 1;
}

/**
 * An internal service exported by all Sake RPC servers. This allows clients to query for metadata
 * about the server and other services that it exports.
 */
service SakeService {
  /**
   * "Hello" for Sake (<a href="http://www.wikihow.com/Say-Hello-in-Japanese">Say Hello in
   * Japanese</a>). This should be the first RPC sent on any new connection from an RPC client.
   * The RPC client indicates the service(s) that it expects the server to export. This is also
   * how negotiation of protocol version is performed, and clients and servers exchange info on
   * capabilities/extensions.
   */
  rpc MoshiMoshi (OhHai) returns (KThxBai);

  /**
   * Requests the schema for services exported by the server. The schema consists of file
   * descriptors (that include all message/enum/service descriptor data) for the exported services
   * and their transitive dependencies. This is the information required to construct a dynamic
   * client (e.g. a client that is based wholly on descriptors, not on generated code).
   */
  rpc Schema (SchemaRequest) returns (SchemaResponse);

  /**
   * Lists all services exported by this server.
   */
  rpc List (ListRequest) returns (ListResponse);

  /**
   * Dispatches an RPC request to the given service and method. Returns the RPC response.
   */
  rpc Call (CallRequest) returns (CallResponse);

  /**
   * Checks the health of the service. This is used periodically (and frequently) by clients so
   * that requests are sent to healthy servers.
   */
  rpc Heartbeat (HeartbeatRequest) returns (HeartbeatResponse);

  /**
   * A simple "echo". The client sends a "ping" and the server echoes it back with the "pong".
   */
  rpc Ping (PingRequest) returns (PingResponse);
}