mirror of
https://github.com/usememos/memos.git
synced 2026-11-19 10:29:11 +01:00
378 lines
14 KiB
Protocol Buffer
378 lines
14 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
package memos.api;
|
|
|
|
import "google/api/annotations.proto";
|
|
import "google/api/client.proto";
|
|
import "google/api/field_behavior.proto";
|
|
import "google/api/resource.proto";
|
|
import "google/protobuf/empty.proto";
|
|
import "google/protobuf/field_mask.proto";
|
|
import "google/protobuf/timestamp.proto";
|
|
|
|
option go_package = "gen/api";
|
|
|
|
// AttachmentService manages files attached to memos.
|
|
service AttachmentService {
|
|
// ListAttachments lists attachments linked to memos the caller can read, plus the caller's unlinked uploads.
|
|
rpc ListAttachments(ListAttachmentsRequest) returns (ListAttachmentsResponse) {
|
|
option (google.api.http) = {get: "/api/attachments"};
|
|
}
|
|
|
|
// GetAttachment gets an attachment by name. An unlinked attachment is visible only to its uploader and admins;
|
|
// a linked attachment follows the read access of its memo.
|
|
rpc GetAttachment(GetAttachmentRequest) returns (Attachment) {
|
|
option (google.api.http) = {get: "/api/{name=attachments/*}"};
|
|
option (google.api.method_signature) = "name";
|
|
}
|
|
|
|
// CreateAttachment creates an attachment from inline content.
|
|
rpc CreateAttachment(CreateAttachmentRequest) returns (Attachment) {
|
|
option (google.api.http) = {
|
|
post: "/api/attachments"
|
|
body: "attachment"
|
|
};
|
|
option (google.api.method_signature) = "attachment";
|
|
}
|
|
|
|
// UpdateAttachment updates an attachment. Only `filename` can be updated. The caller must be the uploader or an
|
|
// admin.
|
|
rpc UpdateAttachment(UpdateAttachmentRequest) returns (Attachment) {
|
|
option (google.api.http) = {
|
|
patch: "/api/{attachment.name=attachments/*}"
|
|
body: "attachment"
|
|
};
|
|
option (google.api.method_signature) = "attachment,update_mask";
|
|
}
|
|
|
|
// DeleteAttachment deletes an attachment uploaded by the caller.
|
|
rpc DeleteAttachment(DeleteAttachmentRequest) returns (google.protobuf.Empty) {
|
|
option (google.api.http) = {delete: "/api/{name=attachments/*}"};
|
|
option (google.api.method_signature) = "name";
|
|
}
|
|
|
|
// BatchDeleteAttachments deletes up to 100 attachments in one atomic request. The caller must be the uploader of
|
|
// each attachment or an admin.
|
|
rpc BatchDeleteAttachments(BatchDeleteAttachmentsRequest) returns (google.protobuf.Empty) {
|
|
option (google.api.http) = {
|
|
post: "/api/attachments:batchDelete"
|
|
body: "*"
|
|
};
|
|
}
|
|
|
|
// UploadAttachment uploads a file in bounded chunks. The first call carries the spec and returns an upload_id;
|
|
// later calls carry that upload_id. Uploads are bound to the authenticated user, expire after 30 minutes of
|
|
// inactivity, and do not survive a server restart.
|
|
rpc UploadAttachment(UploadAttachmentRequest) returns (UploadAttachmentResponse) {
|
|
option (google.api.http) = {
|
|
post: "/api/attachments:upload"
|
|
body: "*"
|
|
};
|
|
}
|
|
}
|
|
|
|
// Attachment is a file uploaded by a user, optionally linked to a memo.
|
|
message Attachment {
|
|
option (google.api.resource) = {
|
|
type: "memos.api/Attachment"
|
|
pattern: "attachments/{attachment}"
|
|
singular: "attachment"
|
|
plural: "attachments"
|
|
};
|
|
|
|
// Identifier. The resource name of the attachment.
|
|
// Format: attachments/{attachment}
|
|
string name = 1 [(google.api.field_behavior) = IDENTIFIER];
|
|
|
|
// Output only. The user who uploaded the attachment, which may differ from the creator of the linked memo.
|
|
// Format: users/{user}
|
|
string creator = 2 [
|
|
(google.api.field_behavior) = OUTPUT_ONLY,
|
|
(google.api.resource_reference) = {type: "memos.api/User"}
|
|
];
|
|
|
|
// Required. The filename of the attachment.
|
|
string filename = 3 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Required. The MIME type of the attachment. If empty on create, the service detects it from the filename and
|
|
// content.
|
|
string type = 4 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Input only. The content of the attachment.
|
|
bytes content = 5 [(google.api.field_behavior) = INPUT_ONLY];
|
|
|
|
// Optional. The external link of the attachment. Set only for externally stored attachments; ignored on create.
|
|
string external_link = 6 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. Motion photo metadata. Clients may only supply Apple Live Photo metadata; the service detects Android
|
|
// motion photos in JPEG content.
|
|
MotionMedia motion_media = 7 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. Normalized media metadata supplied by the client at creation time. Immutable after creation.
|
|
MediaMetadata media_metadata = 8 [
|
|
(google.api.field_behavior) = OPTIONAL,
|
|
(google.api.field_behavior) = IMMUTABLE
|
|
];
|
|
|
|
// Optional. The memo the attachment is linked to. On create, the caller must be able to manage the memo.
|
|
// Format: memos/{memo}
|
|
optional string memo = 9 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Output only. The size of the stored content in bytes.
|
|
int64 size = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
|
|
// Output only. The creation time.
|
|
google.protobuf.Timestamp create_time = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
}
|
|
|
|
// Request message for AttachmentService.ListAttachments.
|
|
message ListAttachmentsRequest {
|
|
// Optional. The maximum number of attachments to return. The service may return fewer.
|
|
// If unspecified, at most 50 attachments are returned. Values above 1000 are coerced to 1000.
|
|
int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. A page token from a previous call. Provide it to retrieve the next page.
|
|
string page_token = 2 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. A CEL filter over the results.
|
|
// Example: `mime_type == "image/png"` or `filename.contains("test")`.
|
|
// Supported operators: ==, !=, <, <=, >, >=, : (contains), in.
|
|
// Supported fields: creator, filename, mime_type, create_time, memo_id, space.
|
|
// `creator` is the linked memo's creator, or the uploader for an unlinked attachment. It supports equality with a
|
|
// User resource name.
|
|
// `space` is the linked memo's Space resource name, or null when the attachment is unlinked or its memo has no
|
|
// space. It supports only a non-negated `==` comparison with a Space resource name or null.
|
|
string filter = 3 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. The order to sort results by, such as "create_time desc" or "filename asc". The service does not apply
|
|
// it yet.
|
|
string order_by = 4 [(google.api.field_behavior) = OPTIONAL];
|
|
}
|
|
|
|
// Response message for AttachmentService.ListAttachments.
|
|
message ListAttachmentsResponse {
|
|
// The attachments.
|
|
repeated Attachment attachments = 1;
|
|
|
|
// A token to retrieve the next page. Empty when there are no more pages.
|
|
string next_page_token = 2;
|
|
}
|
|
|
|
// Request message for AttachmentService.GetAttachment.
|
|
message GetAttachmentRequest {
|
|
// Required. The name of the attachment to get.
|
|
// Format: attachments/{attachment}
|
|
string name = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {type: "memos.api/Attachment"}
|
|
];
|
|
}
|
|
|
|
// Request message for AttachmentService.CreateAttachment.
|
|
message CreateAttachmentRequest {
|
|
// Required. The attachment to create.
|
|
Attachment attachment = 1 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Optional. The ID to use for the attachment. If empty, a unique ID is generated.
|
|
// Format: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$
|
|
string attachment_id = 2 [(google.api.field_behavior) = OPTIONAL];
|
|
}
|
|
|
|
// Request message for AttachmentService.UpdateAttachment.
|
|
message UpdateAttachmentRequest {
|
|
// Required. The attachment to update. Its `name` identifies the attachment.
|
|
Attachment attachment = 1 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Required. The fields to update. Only `filename` is supported.
|
|
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
|
|
}
|
|
|
|
// Request message for AttachmentService.DeleteAttachment.
|
|
message DeleteAttachmentRequest {
|
|
// Required. The name of the attachment to delete.
|
|
// Format: attachments/{attachment}
|
|
string name = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {type: "memos.api/Attachment"}
|
|
];
|
|
}
|
|
|
|
// Request message for AttachmentService.BatchDeleteAttachments.
|
|
message BatchDeleteAttachmentsRequest {
|
|
// Required. The names of the attachments to delete, at most 100. Duplicate names are ignored.
|
|
// Format: attachments/{attachment}
|
|
repeated string names = 1 [(google.api.field_behavior) = REQUIRED];
|
|
}
|
|
|
|
// Request message for AttachmentService.UploadAttachment.
|
|
message UploadAttachmentRequest {
|
|
// Starts a new upload or continues an existing one. Exactly one must be set.
|
|
oneof upload {
|
|
// Starts a new upload. The same call may also carry data and finish_write.
|
|
UploadAttachmentSpec spec = 1;
|
|
|
|
// Continues the upload identified by a previous response.
|
|
string upload_id = 2;
|
|
}
|
|
|
|
// Required. Zero-based byte offset at which data is written. Must equal the committed size, except when retrying
|
|
// the most recently accepted chunk with identical bytes and offset, which is accepted without writing again.
|
|
int64 write_offset = 3 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Optional. File bytes, at most max_chunk_size long. With no data and finish_write false, the call reports
|
|
// progress without writing, and write_offset is ignored.
|
|
bytes data = 4 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. Finalize the upload after writing data. The committed size must then equal total_size. Any later call
|
|
// for the same upload_id returns the created attachment.
|
|
bool finish_write = 5 [(google.api.field_behavior) = OPTIONAL];
|
|
}
|
|
|
|
// Response message for AttachmentService.UploadAttachment.
|
|
message UploadAttachmentResponse {
|
|
// Opaque ID for subsequent calls. This is not a resource name.
|
|
string upload_id = 1;
|
|
|
|
// Number of file bytes committed so far.
|
|
int64 committed_size = 2;
|
|
|
|
// Maximum number of data bytes accepted in one call.
|
|
int32 max_chunk_size = 3;
|
|
|
|
// The created attachment. Set once the upload has been finalized.
|
|
Attachment attachment = 4;
|
|
}
|
|
|
|
// UploadAttachmentSpec describes the attachment that a new upload creates.
|
|
message UploadAttachmentSpec {
|
|
// Required. Metadata for the attachment to create. content must be empty; file bytes are sent in data.
|
|
Attachment attachment = 1 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Optional. The ID to use for the attachment. If empty, a unique ID is generated.
|
|
// Format: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$
|
|
string attachment_id = 2 [(google.api.field_behavior) = OPTIONAL];
|
|
|
|
// Optional. Total size of the file in bytes before media processing. Zero represents an empty file.
|
|
int64 total_size = 3 [(google.api.field_behavior) = OPTIONAL];
|
|
}
|
|
|
|
// MotionMedia links the parts of a motion photo.
|
|
message MotionMedia {
|
|
// The motion photo format.
|
|
MotionMediaFamily family = 1;
|
|
|
|
// The part this attachment plays in the motion photo.
|
|
MotionMediaRole role = 2;
|
|
|
|
// Groups the attachments that belong to one motion photo. Required for client-supplied Apple Live Photo metadata;
|
|
// for an Android motion photo it is the attachment's own ID.
|
|
string group_id = 3;
|
|
|
|
// Presentation timestamp of the still frame within the video, in microseconds.
|
|
int64 presentation_timestamp_us = 4;
|
|
|
|
// Whether the file embeds the motion video, as in an Android motion photo container.
|
|
bool has_embedded_video = 5;
|
|
}
|
|
|
|
// MotionMediaFamily is the format of a motion photo.
|
|
enum MotionMediaFamily {
|
|
MOTION_MEDIA_FAMILY_UNSPECIFIED = 0;
|
|
// An Apple Live Photo: a still image and a video stored as separate attachments.
|
|
APPLE_LIVE_PHOTO = 1;
|
|
// An Android motion photo: a JPEG with an embedded video.
|
|
ANDROID_MOTION_PHOTO = 2;
|
|
}
|
|
|
|
// MotionMediaRole is the part an attachment plays in a motion photo.
|
|
enum MotionMediaRole {
|
|
MOTION_MEDIA_ROLE_UNSPECIFIED = 0;
|
|
// The still image of an Apple Live Photo.
|
|
STILL = 1;
|
|
// The video of an Apple Live Photo.
|
|
VIDEO = 2;
|
|
// A single file holding both the still image and the video.
|
|
CONTAINER = 3;
|
|
}
|
|
|
|
// MediaMetadata contains normalized metadata explicitly supplied by a client.
|
|
// The service validates and stores this data but does not extract it from the media file.
|
|
message MediaMetadata {
|
|
// Display-oriented width in pixels. Must be provided with height.
|
|
optional int32 width = 1;
|
|
|
|
// Display-oriented height in pixels. Must be provided with width.
|
|
optional int32 height = 2;
|
|
|
|
// Type-specific metadata. Must match the attachment's MIME type.
|
|
oneof details {
|
|
// Photo metadata, for image attachments.
|
|
PhotoMetadata photo = 3;
|
|
|
|
// Video metadata, for video attachments.
|
|
VideoMetadata video = 4;
|
|
}
|
|
}
|
|
|
|
// PhotoMetadata is metadata recorded by the source of a photo.
|
|
message PhotoMetadata {
|
|
// Capture time as recorded by the source media.
|
|
MediaCaptureTime capture_time = 1;
|
|
|
|
// Geographic location recorded by the source media.
|
|
MediaLocation location = 2;
|
|
|
|
// EXIF orientation value from 1 through 8 as recorded by the source file.
|
|
// This value is informational and must not be reapplied to the stored attachment;
|
|
// width and height already describe its display-oriented dimensions.
|
|
optional int32 source_exif_orientation = 3;
|
|
|
|
// The camera manufacturer.
|
|
string camera_make = 4;
|
|
|
|
// The camera model.
|
|
string camera_model = 5;
|
|
|
|
// The lens model.
|
|
string lens_model = 6;
|
|
|
|
// The aperture f-number.
|
|
optional double f_number = 7;
|
|
|
|
// The exposure time in seconds.
|
|
optional double exposure_time_seconds = 8;
|
|
|
|
// The ISO sensitivity.
|
|
optional int32 iso = 9;
|
|
|
|
// The focal length in millimeters.
|
|
optional double focal_length_mm = 10;
|
|
}
|
|
|
|
// MediaCaptureTime is the local time at which media was captured.
|
|
message MediaCaptureTime {
|
|
// Local date and time without a time zone, formatted as YYYY-MM-DDTHH:mm:ss[.fraction].
|
|
string local_date_time = 1;
|
|
|
|
// UTC offset formatted as Z or +/-HH:MM.
|
|
optional string utc_offset = 2;
|
|
}
|
|
|
|
// MediaLocation is the geographic location at which media was captured.
|
|
message MediaLocation {
|
|
// WGS84 latitude in decimal degrees. Must be provided with longitude.
|
|
optional double latitude = 1;
|
|
|
|
// WGS84 longitude in decimal degrees. Must be provided with latitude.
|
|
optional double longitude = 2;
|
|
|
|
// Signed altitude in meters relative to sea level.
|
|
optional double altitude_meters = 3;
|
|
}
|
|
|
|
// VideoMetadata is metadata recorded by the source of a video.
|
|
message VideoMetadata {
|
|
// The duration of the video in seconds.
|
|
optional double duration_seconds = 1;
|
|
}
|