zen/schemas/proto/notify/v1/send_notification.proto

198 lines
6.3 KiB
Protocol Buffer
Raw Normal View History

2024-08-22 09:18:44 +07:00
syntax = "proto3";
package notify.v1;
2024-08-28 14:46:39 +07:00
import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";
2024-08-22 09:18:44 +07:00
import "notify/v1/types.proto";
message SendNotificationRequest {
2024-08-28 14:46:39 +07:00
Payload payload = 1 [(buf.validate.field).required = true];
Resource resource = 2 [(buf.validate.field).required = true];
2024-08-22 09:18:44 +07:00
}
// SendAttachmentResponse is sent when message is successful.
message SendNotificationResponse {
2024-08-28 14:46:39 +07:00
// notification_id is the id of the notification.
2024-08-22 09:18:44 +07:00
//
// 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;
2024-08-28 14:46:39 +07:00
// 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;
2024-08-22 09:18:44 +07:00
}
message Payload {
2024-08-27 18:17:04 +07:00
// message is the content of the notification.
//
// message should be short and concise since they are
// intended as forefront information.
//
// details should go to the `details` field.
2024-08-28 14:46:39 +07:00
string message = 1 [(buf.validate.field).required = true];
2024-08-27 18:17:04 +07:00
// 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.
2024-08-22 09:18:44 +07:00
Level level = 2;
2024-08-28 14:46:39 +07:00
// code is the error code of the message.
string code = 3;
2024-08-22 09:18:44 +07:00
// details adds context to the message.
//
2024-08-27 18:17:04 +07:00
// like invalid inputs,
2024-08-22 09:18:44 +07:00
// request payloads, backend response, etc.
//
// Anything that can enrich why this message
// appears will help.
//
// DO NOT INCLUDE BINARIES LIKE IMAGES, PDFS, DOCS, IN
// THIS PAYLOAD. USE `SendAttachment` rpc
// to attach binary values instead since they are designed
// for streaming. Server and Client RAM
2024-08-27 18:17:04 +07:00
// can be eaten alive if you ignore this predicament since GRPC
2024-08-22 09:18:44 +07:00
// handles via whole messages.
oneof details {
// Sends JSON as details.
2024-08-27 18:17:04 +07:00
//
// In the report page, this will be rendered with JSONGrid.
2024-08-22 09:18:44 +07:00
bytes d_json = 4;
2024-08-27 18:17:04 +07:00
// Sends text as details.
//
// Markdown syntax is supported and markdown will be rendered
// on the report page.
2024-08-22 09:18:44 +07:00
string d_text = 5;
}
2024-08-27 18:17:04 +07:00
// error is the error message that is sent.
2024-08-22 09:18:44 +07:00
oneof error {
2024-08-27 18:17:04 +07:00
// sends error details as JSON.
//
// like details, do not include binaries in this field.
//
// In the report page, this will be rendered with JSONGrid.
2024-08-22 09:18:44 +07:00
bytes e_json = 6;
2024-08-27 18:17:04 +07:00
// sends error details as text.
//
// Markdown syntax is supported and markdown will be rendered
// on the report page.
2024-08-22 09:18:44 +07:00
string e_text = 7;
}
2024-08-27 18:17:04 +07:00
// id is the unique identifier of the message.
//
// message with same id is considered as the same message
// even if the content is different.
2024-08-22 17:26:53 +07:00
string id = 8;
2024-08-27 18:17:04 +07:00
// trace_id is the trace id of the message.
//
// trace_id is used to trace the message across services.
//
// Leave this empty/unset if no traces are available.
string trace_id = 9;
// span_id is the span id of the message.
//
// span_id is used to trace the message within the service/scope.
//
// Leave this empty/unset if no spans are available.
string span_id = 10;
2024-08-28 14:46:39 +07:00
// timestamp is the timestamp of the message.
//
// if unset or zero, the server will use the current time.
google.protobuf.Timestamp timestamp = 11;
2024-08-22 09:18:44 +07:00
}
2024-08-28 14:46:39 +07:00
// 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 {
2024-08-22 09:18:44 +07:00
// 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.
2024-08-28 14:46:39 +07:00
// e.g. `sbn`, `superapp`, `hyperion`, `robo`.
2024-08-22 09:18:44 +07:00
//
// `name`, `type`, and `environment` combination are used to select which channel the
// discord notification is sent.
2024-08-28 14:46:39 +07:00
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
]
}];
2024-08-22 09:18:44 +07:00
optional string version = 4;
// domain specifies whose message this belongs to.
//
2024-08-28 14:46:39 +07:00
// It's very recommended for this service to be set.
//
// This will help zen to categorize messages when building
2024-08-22 09:18:44 +07:00
// reports.
ServiceDomain domain = 5;
2024-08-27 18:17:04 +07:00
// attributes are informations that enriches the service.
//
// like Session ID, Region, User-Agent, etc.
map<string, string> attributes = 6;
2024-08-22 09:18:44 +07:00
}
enum ServiceDomain {
SERVICE_DOMAIN_UNSPECIFIED = 0;
SERVICE_DOMAIN_FRONTEND = 1;
SERVICE_DOMAIN_BACKEND = 2;
}