Represention of Protobuf Options within Sysl

[andrewemeryanz]

Background

Protobuf specifications support options. Options are strongly typed Protobuf values. Options are primarily found at the file level, message level and field level of a specification. There doesn't yet exist a representation of Protobuf options within a Sysl specification.

Proposal

Support the encoding of file level, service level, method level, message level and field level Protobuf options by including their Protobuf-encoded values within Sysl annotations.

Protobuf Encoding

Consider the following Protobuf example that includes various options:

option (my_file_option) = "Hello world!";  // file option

service MyService {
  option (my_service_option) = FOO;  // service option
  rpc MyMethod(RequestType) returns(ResponseType) {
    option (my_method_option).foo = 567;  // method option
    option (my_method_option).bar = "Some string";  // method option
  }
}

message MyMessage {
  option (my_message_option) = 1234;  // message option
  optional int32 foo = 1 [(my_field_option) = 4.5]; // field option
}

Sysl Encoding

The Sysl encoding of the Protobuf options from the above specification would look like the following:

MyService:
  @proto_file_options = ["(my_file_option) = \"Hello world!\""]
  @proto_options = ["(my_service_option) = FOO"]

  MyMethod(RequestType):
    @proto_options = ["(my_method_option).foo = 567", "(my_method_option).bar = \"Some string\""]
    return ok <: ResponseType

  !type MyMessage:
    @proto_options = ["(my_message_option) = 1234"]
    foo <: int32:
      @proto_options = ["(my_field_option) = 4.5"]

Option Mapping

Protobuf options found at the service level, method level, message level and field level map to annotations on their corresponding Sysl application, endpoint, type and field declarations respectively. Protobuf file level options are included in all Sysl applications that are defined within the Protobuf file containing these values.

Alternatives Considered

Encode Natively

Some Protobuf options, such as google.api.http describe how to expose a gRPC method through a restful endpoint:

rpc MyMethod(RequestType) returns(ResponseType) {
  option (google.api.http) = {
    get: "/my/method"
  };
}

It could be considered that a more native Sysl representation of this concept would be to include two endpoints, one gRPC and one restful, and associate them together through some means:

MyService:
  MyMethod(RequestType) [~gRPC]:
    return ok <: ResponseType

  /my/method [proto_method = "MyMethod"]:
    POST (RequestType):
      return ok <: ResponseType    

Whilst this approach has merit it doesn't address the problem of options in the general case. This particular example (using google.api.http) also fails to adequately address the complexity of the option itself (whereby the option can conceptually come to represent an ordered series of restful endpoints with additional configuration).