twonly/twonly-app
1
0
Fork 0
mirror of https://github.com/twonlyapp/twonly-app.git synced 2026-09-01 07:04:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

memories.md löschen

Browse source
This commit is contained in:
Tobi 2026-08-06 17:13:00 +02:00 committed by GitHub
parent d19f4ce3c9
commit cc51e604a0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 0 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
memories.md
View file

@ -1,112 +0,0 @@
# Memories API Documentation
The **Memories** feature allows users to back up their media to the server in an end-to-end encrypted format. The client-server communication happens primarily via the existing WebSocket connection using Protocol Buffers (`client_to_server.proto` and `server_to_client.proto`), while the actual binary file uploads/downloads use Amazon S3 presigned URLs via HTTP PUT/GET.
## 1. Checking Storage Quota
Before allowing a user to upload a memory, the client should query the user's current storage usage to ensure they haven't exceeded their limit.
**Request:**
```proto
// client_to_server.proto
message GetMemoriesUsage {}
```
**Response:**
```proto
// server_to_client.proto
message MemoriesUsage {
int64 max_bytes = 1;
int64 current_bytes = 2;
int64 count = 3;
}
```
If `current_bytes` + the new file size > `max_bytes`, the client should block the upload and optionally prompt the user to upgrade their plan or free up space.
## 2. Uploading a Memory
Uploading a memory is a three-step process: requesting presigned URLs, performing the actual HTTP uploads, and finally confirming the upload.
### Step 2.1: Request Upload URLs
The client requests permission to upload a new memory item, declaring its size and original capture date.
**Request:**
```proto
// client_to_server.proto
message RequestMemoriesUpload {
int64 size = 1; // Size of the FULL media file in bytes
int64 original_date = 2; // Unix timestamp (in milliseconds/seconds depending on your app's standard) of when the media was originally created
}
```
**Response:**
```proto
// server_to_client.proto
message MemoriesUploadUrls {
string media_id = 1; // Unique identifier generated by the server for this memory
string thumbnail_upload_url = 2; // S3 presigned URL for uploading the encrypted thumbnail
string full_upload_url = 3; // S3 presigned URL for uploading the encrypted full media
}
```
### Step 2.2: Perform HTTP Uploads
Using the URLs returned in Step 2.1, the client encrypts the thumbnail and the full media locally, and performs an HTTP `PUT` request to the respective URLs.
*Note: The upload URLs are usually valid only for a short time (e.g. 15-60 minutes). Ensure you upload the data promptly.*
### Step 2.3: Confirm the Upload
After both the thumbnail and the full media are successfully uploaded via HTTP, the client **must** notify the server so it can mark the memory as fully uploaded and available.
**Request:**
```proto
// client_to_server.proto
message ConfirmMemoriesUpload {
string media_id = 1; // The media_id obtained in Step 2.1
}
```
*(The server will respond with an empty `Ok::None(true)` acknowledgment upon success).*
## 3. Retrieving Memories (Pagination)
To display a gallery or timeline of backed-up memories, the client requests a paginated list of media items. The endpoint returns a descending list (newest first) based on the original date.
**Request:**
```proto
// client_to_server.proto
message GetMemoriesList {
int64 offset_date = 1; // Unix timestamp to fetch memories older than this date (for pagination). Use MAX_INT64 for the first page.
int64 limit = 2; // Maximum number of items to return in this batch (e.g. 50)
}
```
**Response:**
```proto
// server_to_client.proto
message MemoriesList {
repeated MediaItem items = 1;
}
message MediaItem {
string media_id = 1;
int64 original_date = 2;
string thumbnail_download_url = 3; // S3 presigned URL to download the encrypted thumbnail
}
```
The client can immediately use the `thumbnail_download_url` to fetch and decrypt the thumbnail for the gallery view.
## 4. Downloading Full Media
When a user taps on a memory to view it in full screen, the client requests a temporary download URL for the full-resolution file.
**Request:**
```proto
// client_to_server.proto
message GetMemoriesUrl {
string media_id = 1;
}
```
**Response:**
```proto
// server_to_client.proto
message MemoriesUrl {
string full_download_url = 1; // S3 presigned URL to download the encrypted full media
}
```
The client can then perform an HTTP `GET` request to `full_download_url`, decrypt the payload locally, and display the full-resolution image or video.