From cb6b2fb9d01411f3b1c55569a457b58ab6100d01 Mon Sep 17 00:00:00 2001 From: Tigor Hutasuhut Date: Wed, 28 Aug 2024 14:46:39 +0700 Subject: [PATCH] proto: update upload proto --- buf.lock | 2 + schemas/proto/buf.lock | 7 ++ schemas/proto/buf.yaml | 2 +- schemas/proto/notify/v1/notify.proto | 48 ++++++++++ .../proto/notify/v1/send_notification.proto | 92 ++++++++++++++++--- schemas/proto/notify/v1/types.proto | 1 + 6 files changed, 139 insertions(+), 13 deletions(-) create mode 100644 buf.lock diff --git a/buf.lock b/buf.lock new file mode 100644 index 0000000..c91b581 --- /dev/null +++ b/buf.lock @@ -0,0 +1,2 @@ +# Generated by buf. DO NOT EDIT. +version: v1 diff --git a/schemas/proto/buf.lock b/schemas/proto/buf.lock index 4f98143..2b4a48a 100644 --- a/schemas/proto/buf.lock +++ b/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 diff --git a/schemas/proto/buf.yaml b/schemas/proto/buf.yaml index bf7f2bb..13da433 100644 --- a/schemas/proto/buf.yaml +++ b/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 diff --git a/schemas/proto/notify/v1/notify.proto b/schemas/proto/notify/v1/notify.proto index 083c884..8f4b197 100644 --- a/schemas/proto/notify/v1/notify.proto +++ b/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); } diff --git a/schemas/proto/notify/v1/send_notification.proto b/schemas/proto/notify/v1/send_notification.proto index bf64cb5..82ea304 100644 --- a/schemas/proto/notify/v1/send_notification.proto +++ b/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; - Service service = 2; + Payload payload = 1 [(buf.validate.field).required = true]; + 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 type = 2; - Environment environment = 3; + string name = 1 [(buf.validate.field).string.min_len = 1]; + + // 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 - // will help zen to categorize messages when building + // It's very recommended for this service to be set. + // + // This will help zen to categorize messages when building // reports. ServiceDomain domain = 5; diff --git a/schemas/proto/notify/v1/types.proto b/schemas/proto/notify/v1/types.proto index 23bab5d..7dc883a 100644 --- a/schemas/proto/notify/v1/types.proto +++ b/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 {