feat(proto): generic service protobuf definition

See #2634 and #2742.

Signed-off-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com>

bentoml/grpc/v1alpha1/service.proto

@@ -0,0 +1,270 @@
+syntax = "proto3";
+
+package bentoml.grpc.v1alpha1;
+
+import "google/protobuf/struct.proto";
+import "google/protobuf/wrappers.proto";
+
+// cc_enable_arenas pre-allocate memory for given message to improve speed. (C++ only)
+option cc_enable_arenas = true;
+option go_package = "github.com/bentoml/grpc/v1alpha1";
+option java_multiple_files = true;
+option java_outer_classname = "ServiceProto";
+option java_package = "com.bentoml.grpc.v1alpha1";
+option objc_class_prefix = "SVC";
+option py_generic_services = true;
+
+// a gRPC BentoServer.
+service BentoService {
+  // Call handles methodcaller of given API entrypoint.
+  rpc Call(Request) returns (Response) {}
+}
+
+// Request message for incoming Call.
+message Request {
+  // api_name defines the API entrypoint to call.
+  // api_name is the name of the function defined in bentoml.Service.
+  // Example:
+  //
+  //     @svc.api(input=NumpyNdarray(), output=File())
+  //     def predict(input: NDArray[float]) -> bytes:
+  //         ...
+  //
+  //     api_name is "predict" in this case.
+  string api_name = 1;
+
+  // NDArray represents a n-dimensional array of arbitrary type.
+  NDArray ndarray = 3;
+
+  // Tensor is similiar to ndarray but with a name
+  // We are reserving it for now for future use.
+  // repeated Tensor tensors = 4;
+  reserved 4, 11 to 15;
+
+  // DataFrame represents any tabular data type. We are using
+  // DataFrame as a trivial representation for tabular type.
+  DataFrame dataframe = 5;
+
+  // Series portrays a series of values. This can be used for
+  // representing Series types in tabular data.
+  Series series = 6;
+
+  // File represents for any arbitrary file type. This can be
+  // plaintext, image, video, audio, etc.
+  File file = 7;
+
+  // Text represents a string inputs.
+  google.protobuf.StringValue text = 8;
+
+  // JSON is represented by using google.protobuf.Value.
+  // see https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/struct.proto
+  google.protobuf.Value json = 9;
+
+  // Multipart represents a multipart message.
+  // It comprises of a mapping from given type name to a subset of aforementioned types.
+  map<string, Part> multipart = 10;
+
+  // This field is reserved and INTERNAL to BentoML, and users are DISCOURAGED to use this.
+  optional bytes _internal_bytes_contents = 2;
+}
+
+// Request message for incoming Call.
+message Response {
+  // NDArray represents a n-dimensional array of arbitrary type.
+  NDArray ndarray = 1;
+
+  // Tensor is similiar to ndarray but with a name
+  // We are reserving it for now for future use.
+  // repeated Tensor tensors = 4;
+  reserved 4, 10 to 15;
+
+  // DataFrame represents any tabular data type. We are using
+  // DataFrame as a trivial representation for tabular type.
+  DataFrame dataframe = 3;
+
+  // Series portrays a series of values. This can be used for
+  // representing Series types in tabular data.
+  Series series = 5;
+
+  // File represents for any arbitrary file type. This can be
+  // plaintext, image, video, audio, etc.
+  File file = 6;
+
+  // Text represents a string inputs.
+  google.protobuf.StringValue text = 7;
+
+  // JSON is represented by using google.protobuf.Value.
+  // see https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/struct.proto
+  google.protobuf.Value json = 8;
+
+  // Multipart represents a multipart message.
+  // It comprises of a mapping from given type name to a subset of aforementioned types.
+  map<string, Part> multipart = 9;
+
+  // This field is reserved and INTERNAL to BentoML, and users are DISCOURAGED to use this.
+  optional bytes _internal_bytes_contents = 2;
+}
+
+// Part represents possible value types for multipart message.
+// These are the same as the types in Request message.
+message Part {
+  oneof representation {
+    // NDArray represents a n-dimensional array of arbitrary type.
+    NDArray ndarray = 1;
+
+    // DataFrame represents any tabular data type. We are using
+    // DataFrame as a trivial representation for tabular type.
+    DataFrame dataframe = 3;
+
+    // Series portrays a series of values. This can be used for
+    // representing Series types in tabular data.
+    Series series = 4;
+
+    // File represents for any arbitrary file type. This can be
+    // plaintext, image, video, audio, etc.
+    File file = 5;
+
+    // Text represents a string inputs.
+    google.protobuf.StringValue text = 6;
+
+    // JSON is represented by using google.protobuf.Value.
+    // see https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/struct.proto
+    google.protobuf.Value json = 7;
+  }
+
+  // Tensor is similiar to ndarray but with a name
+  // We are reserving it for now for future use.
+  // Tensor tensors = 2;
+  reserved 2, 10 to 15;
+}
+
+// File represents for any arbitrary file type. This can be
+// plaintext, image, video, audio, etc.
+message File {
+  // FileType represents possible file type to be handled by BentoML.
+  // Currently, we only support plaintext (Text()), image (Image()), and file (File()).
+  // TODO: support audio and video streaming file types.
+  enum FileType {
+    FILE_TYPE_UNSPECIFIED = 0;
+
+    // file types
+    FILE_TYPE_CSV = 1;
+    FILE_TYPE_PLAINTEXT = 2;
+    FILE_TYPE_JSON = 3;
+    FILE_TYPE_BYTES = 4;
+    FILE_TYPE_PDF = 5;
+
+    // image types
+    FILE_TYPE_PNG = 6;
+    FILE_TYPE_JPEG = 7;
+    FILE_TYPE_GIF = 8;
+    FILE_TYPE_BMP = 9;
+    FILE_TYPE_TIFF = 10;
+    FILE_TYPE_WEBP = 11;
+    FILE_TYPE_SVG = 12;
+  }
+
+  // optional type of file, let it be csv, text, parquet, etc.
+  optional FileType kind = 1;
+
+  // contents of file as bytes.
+  bytes content = 2;
+}
+
+// DataFrame represents any tabular data type. We are using
+// DataFrame as a trivial representation for tabular type.
+// This message carries given implementation of tabular data based on given orientation.
+// TODO: support index, records, etc.
+message DataFrame {
+  // columns name
+  repeated string column_names = 1;
+
+  // columns orient.
+  // { column ↠ { index ↠ value } }
+  repeated Series columns = 2;
+}
+
+// Series portrays a series of values. This can be used for
+// representing Series types in tabular data.
+message Series {
+  // A bool parameter value
+  repeated bool bool_values = 1 [packed = true];
+
+  // A float parameter value
+  repeated float float_values = 2 [packed = true];
+
+  // A int32 parameter value
+  repeated int32 int32_values = 3 [packed = true];
+
+  // A int64 parameter value
+  repeated int64 int64_values = 6 [packed = true];
+
+  // A string parameter value
+  repeated string string_values = 5;
+
+  // represents a double parameter value.
+  repeated double double_values = 4 [packed = true];
+}
+
+// NDArray represents a n-dimensional array of arbitrary type.
+message NDArray {
+  // Represents data type of a given array.
+  enum DType {
+    // Represents a None type.
+    DTYPE_UNSPECIFIED = 0;
+
+    // Represents an float type.
+    DTYPE_FLOAT = 1;
+
+    // Represents an double type.
+    DTYPE_DOUBLE = 2;
+
+    // Represents a bool type.
+    DTYPE_BOOL = 3;
+
+    // Represents an int32 type.
+    DTYPE_INT32 = 4;
+
+    // Represents an int64 type.
+    DTYPE_INT64 = 5;
+
+    // Represents a uint32 type.
+    DTYPE_UINT32 = 6;
+
+    // Represents a uint64 type.
+    DTYPE_UINT64 = 7;
+
+    // Represents a string type.
+    DTYPE_STRING = 8;
+  }
+
+  // DTYPE is the data type of given array
+  DType dtype = 1;
+
+  // shape is the shape of given array.
+  repeated int32 shape = 2;
+
+  // represents a string parameter value.
+  repeated string string_values = 5;
+
+  // represents a float parameter value.
+  repeated float float_values = 3 [packed = true];
+
+  // represents a double parameter value.
+  repeated double double_values = 4 [packed = true];
+
+  // represents a bool parameter value.
+  repeated bool bool_values = 6 [packed = true];
+
+  // represents a int32 parameter value.
+  repeated int32 int32_values = 7 [packed = true];
+
+  // represents a int64 parameter value.
+  repeated int64 int64_values = 8 [packed = true];
+
+  // represents a uint32 parameter value.
+  repeated uint32 uint32_values = 9 [packed = true];
+
+  // represents a uint64 parameter value.
+  repeated uint64 uint64_values = 10 [packed = true];
+}

bentoml/grpc/v1alpha1/service_test.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package bentoml.testing.v1alpha1;
+
+option cc_enable_arenas = true;
+option go_package = "github.com/bentoml/testing/v1alpha1";
+option optimize_for = SPEED;
+option py_generic_services = true;
+
+// Represents a request for TestService.
+message ExecuteRequest {
+  string input = 1;
+}
+
+// Represents a response from TestService.
+message ExecuteResponse {
+  string output = 1;
+}
+
+// Use for testing interceptors per RPC call.
+service TestService {
+  // Unary API
+  rpc Execute(ExecuteRequest) returns (ExecuteResponse);
+}

bentoml/protos/buf.yaml

@@ -0,0 +1,17 @@
+version: v1
+lint:
+  use:
+    - DEFAULT
+    - COMMENT_ENUM
+    - COMMENT_MESSAGE
+    - COMMENT_RPC
+    - COMMENT_SERVICE
+  except:
+    - PACKAGE_DIRECTORY_MATCH
+    - PACKAGE_VERSION_SUFFIX
+  enum_zero_value_suffix: _UNSPECIFIED
+  rpc_allow_same_request_response: false
+  rpc_allow_google_protobuf_empty_requests: false
+  rpc_allow_google_protobuf_empty_responses: false
+  service_suffix: Service
+  allow_comment_ignores: true