proto: update upload proto

buf.lock

@@ -0,0 +1,2 @@
+# Generated by buf. DO NOT EDIT.
+version: v1

schemas/proto/buf.lock

@@ -1,2 +1,9 @@
 # Generated by buf. DO NOT EDIT.
 version: v2
+deps:
+  - name: buf.build/bufbuild/protovalidate
+    commit: a6c49f84cc0f4e038680d390392e2ab0
+    digest: b5:e968392e88ff7915adcbd1635d670b45bff8836ec2415d81fc559ca5470a695dbdc30030bad8bc5764647c731079e9e7bba0023ea25c4e4a1672a7d2561d4a19
+  - name: buf.build/protocolbuffers/wellknowntypes
+    commit: f17e05fe4a764a3482b8e033daec742e
+    digest: b5:405a06d8a554f01c830c643879f54feffe2087a6927643dc9418403653ff4033227a2ce9b2b19b8ad350a611ef6576b4df109c96e5dfb6164191eb73d779fb21

schemas/proto/buf.yaml

@@ -1,4 +1,4 @@
 version: v2
 deps:
   - buf.build/bufbuild/protovalidate
-  - buf.build/protocolbuffers/wellknowntypes
+  - buf.build/protocolbuffers/wellknowntypes:v21.12

schemas/proto/notify/v1/notify.proto

@@ -5,7 +5,55 @@ package notify.v1;
 import "notify/v1/send_notification.proto";
 
 service NotifyService {
+  // SendNotification sends notification data to Zen Server.
+  //
+  // Returns notification_id that can be used to send attachments.
+  //
+  // notification_id is long lived and can be given attachments even on the far future.
+  //
+  // If you want to send attachments, use SendAttachment rpc.
+  //
+  // `notification_id` respond can be used to send attachments via SendAttachment rpc.
+  // `upload_url` can be used to upload attachments via http protocol (fetch, axios, http post, etc).
   rpc SendNotification(SendNotificationRequest) returns (SendNotificationResponse);
+
+  // SendAttachment sends attachment data to Zen Server.
+  //
+  // SendAttachment rpc is not supported by Browser Javascript.
+  //
+  // If implementing logic for SendAttachment rpc is difficult, consider using `upload_url`
+  // to upload attachments via http protocol.
+  //
+  // SendAttachment requires notification_id that was returned by SendNotification
+  // so that Zen server can associate attachment with notification.
+  //
+  // One Stream One Attachment. To send multiple attachments, spawn multiple streams by calling
+  // SendAttachment multiple times with the same notification_id and send chunks of data in order.
+  //
+  // PSEUDOCODE:
+  //
+  //   response = client.SendNotification({
+  //      payload: {...},
+  //      resource: {...},
+  //   })
+  //
+  //   notification_id = response.notification_id
+  //
+  //   for attachment in attachments {
+  //     stream = client.SendAttachment()
+  //     // thread.spawn is a pseudo code for creating a new thread or background worker/task.
+  //     thread.spawn ({
+  //        for chunk in attachment.chunks {
+  //            stream.Send({
+  //                notification_id: notification_id,
+  //                name: attachment.name,
+  //                content_type: attachment.content_type,
+  //                chunk: chunk,
+  //            })
+  //        }
+  //        stream.Close()
+  //     })
+  //   }
   rpc SendAttachment(stream SendAttachmentRequest) returns (SendAttachmentResponse);
 }
 

schemas/proto/notify/v1/send_notification.proto

@@ -2,22 +2,48 @@ syntax = "proto3";
 
 package notify.v1;
 
+import "buf/validate/validate.proto";
+import "google/protobuf/timestamp.proto";
 import "notify/v1/types.proto";
 
 message SendNotificationRequest {
-  Payload payload = 1;
+  Payload payload = 1 [(buf.validate.field).required = true];
-  Service service = 2;
+  Resource resource = 2 [(buf.validate.field).required = true];
 }
 
 // SendAttachmentResponse is sent when message is successful.
 message SendNotificationResponse {
-  // notification_id is the snowflake id of the message.
+  // notification_id is the id of the notification.
   //
   // Guaranteed to be unique even on distributed environment.
   //
   // notification_id can be used in `SendAttachment` rpc to
   // attach binary data to the message.
   string notification_id = 1;
+
+  // upload_url is https url to upload the attachment. The endpoint
+  // already has the notification_id embedded in the url so attachments
+  // send to this url are automatically associated with the notification id.
+  //
+  // Use this url if the `SendAttachment` rpc is hard to implement or unspported.
+  //
+  // The endpoint requires Content-Type header to be set
+  // and the behavior of the endpoint depends on the Content-Type
+  // value.
+  //
+  // If Content-Type is `multipart/form-data`, the endpoint will
+  // each part of the form must come with Content-Disposition header,
+  // and in that header,`filename` (without asterisk (*)) field must be set.
+  //
+  // See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition#as_a_header_for_a_multipart_body
+  //
+  // If Content-Type is not `multipart/form-data`, the request must
+  // contain header `X-File-Name`.
+  //
+  // Filenames are sanitized and unsupported characters are replaced with underscores `_`.
+  //
+  // Each filenames must be unique. Not doing so will result in undefined behavior.
+  string upload_url = 2;
 }
 
 message Payload {
@@ -27,14 +53,17 @@ message Payload {
   // intended as forefront information.
   //
   // details should go to the `details` field.
-  string message = 1;
+  string message = 1 [(buf.validate.field).required = true];
   // level is the severity of the message.
   //
   // current implementation treats LEVEL_UNSPECIFIED as LEVEL_INFO,
   // but it's recommended to set the level explicitly to avoid
   // surprises in the future.
   Level level = 2;
-  int64 code = 3;
+
+  // code is the error code of the message.
+  string code = 3;
+
   // details adds context to the message.
   //
   // like invalid inputs,
@@ -93,26 +122,65 @@ message Payload {
   //
   // Leave this empty/unset if no spans are available.
   string span_id = 10;
+
+  // timestamp is the timestamp of the message.
+  //
+  // if unset or zero, the server will use the current time.
+  google.protobuf.Timestamp timestamp = 11;
 }
 
-message Service {
+// Resource contains information about who is sending the notification.
+//
+// Resourcd values be the same as long the same instance is up.
+//
+// for frontends, it's recommended to treat Resource like a user session data.
+//
+// for backends, resource refers to the service that is sending the notification.
+message Resource {
   // The name of the service that is sending the notification.
   //
   // This is used to identify the service that is sending the notification.
   //
   // The value of name should be related to the product or service.
-  // e.g. `sbn-frontend`, `sbn-cron-job`, `payment-frontend`, `robo-frontend`.
+  // e.g. `sbn`, `superapp`, `hyperion`, `robo`.
   //
   // `name`, `type`, and `environment` combination are used to select which channel the
   // discord notification is sent.
-  string name = 1;
+  string name = 1 [(buf.validate.field).string.min_len = 1];
-  string type = 2;
+
-  Environment environment = 3;
+  // type refers to the type of the service provided.
+  //
+  // e.g. `frontend`, `cron-job`, `consumer`
+  //
+  // `name`, `type`, and `environment` combination are used to select which channel the
+  // discord notification is sent.
+  string type = 2 [(buf.validate.field).string.min_len = 1];
+
+  // environment refers to the environment of the service.
+  //
+  // Environment must be one of the following:
+  //
+  //    - ENVIRONMENT_DEVELOPMENT
+  //    - ENVIRONMENT_STAGING
+  //    - ENVIRONMENT_PRODUCTION
+  //    - ENVIRONMENT_TESTING
+  //
+  // `name`, `type`, and `environment` combination are used to select which channel the
+  // discord notification is sent.
+  Environment environment = 3 [(buf.validate.field).enum = {
+    in: [
+      1, // ENVIRONMENT_DEVELOPMENT
+      2, // ENVIRONMENT_STAGING
+      3, // ENVIRONMENT_PRODUCTION
+      4 // ENVIRONMENT_TESTING
+    ]
+  }];
   optional string version = 4;
   // domain specifies whose message this belongs to.
   //
-  // It's not required to be set, but setting this field
+  // It's very recommended for this service to be set.
-  // will help zen to categorize messages when building
+  //
+  // This will help zen to categorize messages when building
   // reports.
   ServiceDomain domain = 5;
 

schemas/proto/notify/v1/types.proto

@@ -15,6 +15,7 @@ enum Environment {
   ENVIRONMENT_DEVELOPMENT = 1;
   ENVIRONMENT_STAGING = 2;
   ENVIRONMENT_PRODUCTION = 3;
+  ENVIRONMENT_TESTING = 4;
 }
 
 message Attribute {