141 lines
2.8 KiB
Markdown
141 lines
2.8 KiB
Markdown
# Reliquary Protocol (MVP v1)
|
|
|
|
This document defines the current wire contract used by the server.
|
|
|
|
## 1. Identity
|
|
- `userId`: immutable opaque ID.
|
|
- `username`: home-server unique, mutable.
|
|
- `handle`: derived string `@username@home`.
|
|
- `homeServer`: canonical public base URL.
|
|
|
|
## 2. Auth
|
|
|
|
### `POST /auth/register`
|
|
Request:
|
|
```json
|
|
{ "username": "alice", "password": "password123" }
|
|
```
|
|
Response fields include:
|
|
- `token`
|
|
- `userId`
|
|
- `username`
|
|
- `handle`
|
|
- `publicKey`
|
|
- encrypted key backup fields
|
|
|
|
### `POST /auth/login`
|
|
Request:
|
|
```json
|
|
{ "username": "alice", "password": "password123" }
|
|
```
|
|
Response includes token + profile/key fields.
|
|
|
|
### `POST /auth/join`
|
|
Request:
|
|
```json
|
|
{
|
|
"userId": "opaque_id",
|
|
"username": "alice",
|
|
"homeServer": "https://chat.example.com",
|
|
"timestamp": 1730000000,
|
|
"signature": "base64..."
|
|
}
|
|
```
|
|
Signature is over `userId:timestamp`.
|
|
|
|
## 3. Message Components
|
|
|
|
Each component node must include:
|
|
- `id` (string)
|
|
- `type` (string)
|
|
- `typeVersion` (positive int)
|
|
- `data` (object)
|
|
|
|
Optional:
|
|
- `fallback`, `modifiers`
|
|
|
|
Nested components are supported under `data.children`.
|
|
|
|
## 4. Media Item Sources
|
|
|
|
Media references support two sources:
|
|
|
|
1. Local upload:
|
|
```json
|
|
{
|
|
"source": "local_upload",
|
|
"attachmentId": "att_...",
|
|
"status": "uploading|ready|failed"
|
|
}
|
|
```
|
|
|
|
2. External URL:
|
|
```json
|
|
{
|
|
"source": "external_url",
|
|
"url": "https://example.com/image.jpg",
|
|
"status": "ready"
|
|
}
|
|
```
|
|
|
|
Optional metadata snapshot:
|
|
- `mimeType`, `sizeBytes`, `width`, `height`, `thumbHash`, `originalFileName`, `caption`.
|
|
|
|
## 5. Uploads
|
|
|
|
### `POST /api/uploads/init` (auth)
|
|
Creates pending upload and returns `uploadId` (same ID namespace as attachment ID).
|
|
|
|
### `PUT /api/uploads/:uploadId` (auth)
|
|
Completes upload with file bytes and returns canonical metadata:
|
|
- `attachmentId`, `url`, `status`, `mimeType`, `sizeBytes`, dimensions, hash.
|
|
|
|
### `POST /api/uploads` (auth)
|
|
Legacy single-step compatibility endpoint.
|
|
|
|
### `GET /attachments/:attachmentId`
|
|
Immutable media URL.
|
|
|
|
## 6. Messages
|
|
|
|
### `POST /api/messages` (auth)
|
|
Request includes:
|
|
- `channelId`
|
|
- `components` or `componentsJson`
|
|
- optional `content`
|
|
|
|
Server behavior:
|
|
- validates structure and media refs
|
|
- normalizes media items
|
|
- computes searchable `content`
|
|
- persists `componentsJson`
|
|
|
|
### `GET /api/messages?channelId=...`
|
|
Returns message list with `componentsJson`.
|
|
|
|
## 7. Gallery Index
|
|
|
|
### `GET /api/channels/:channelId/media` (auth)
|
|
Returns indexed media rows for grid views.
|
|
|
|
Query params:
|
|
- `limit` (default 50, max 100)
|
|
- `before` cursor
|
|
- `kind` (`image|video|file`)
|
|
|
|
Each row includes:
|
|
- linkage (`messageId`, `channelId`, `authorUserId`)
|
|
- source (`attachmentId` or `externalUrl`)
|
|
- display metadata (`mimeType`, dimensions, filename, etc.)
|
|
|
|
## 8. Gateway
|
|
|
|
WebSocket path: `/gateway`
|
|
|
|
Message events:
|
|
- `message.created`
|
|
- `message.updated`
|
|
- `message.deleted`
|
|
|
|
Upload resolution can cause `message.updated`.
|