Skip to content

armgit / memos

Public Imported from GitHub
0

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

14.2 KB
Raw Blame
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;
}