feat: Implement Matrix Rooms Bridge
- MATRIX_ROOMS_BRIDGE_SPEC.md documentation - Migration 012: Add matrix_room_id/alias to city_rooms - Matrix Gateway service (port 7025) - City-service: auto-create Matrix rooms on room creation - Backfill endpoint for existing rooms - API returns matrix_room_id/alias in room responses
This commit is contained in:
Apple
646
services/matrix-gateway/API_SPEC.md
Normal file
646
services/matrix-gateway/API_SPEC.md
Normal file
@@ -0,0 +1,646 @@
|
||||
# Matrix Gateway API Specification
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Service:** matrix-gateway
|
||||
**Port:** 7003 (internal only)
|
||||
**Purpose:** Internal service for Matrix protocol integration
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The **matrix-gateway** is an internal service that:
|
||||
- Wraps Matrix Client-Server API
|
||||
- Provides simplified endpoints for DAARION services
|
||||
- Handles Matrix authentication and session management
|
||||
- Transforms Matrix events ↔ DAARION internal DTOs
|
||||
- Manages webhook subscriptions for real-time events
|
||||
|
||||
**NOT exposed to public internet** — internal service mesh only.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ messaging-service│
|
||||
│ │
|
||||
│ (DAARION API) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ HTTP (internal)
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ matrix-gateway │
|
||||
│ │
|
||||
│ (Matrix API) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ Matrix C-S API
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Matrix Homeserver│
|
||||
│ (Synapse) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests must include:
|
||||
```
|
||||
X-Internal-Service-Token: <shared-secret>
|
||||
```
|
||||
|
||||
Services authenticate via shared secret (not Matrix access tokens).
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### 1. Room Management
|
||||
|
||||
#### **POST /internal/matrix/create-room**
|
||||
|
||||
Create a new Matrix room.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "General Discussion",
|
||||
"topic": "Main DAARION.city channel",
|
||||
"visibility": "public",
|
||||
"room_alias_name": "general",
|
||||
"preset": "public_chat",
|
||||
"initial_state": [
|
||||
{
|
||||
"type": "m.room.guest_access",
|
||||
"state_key": "",
|
||||
"content": { "guest_access": "can_join" }
|
||||
}
|
||||
],
|
||||
"power_level_content_override": {
|
||||
"users": {
|
||||
"@daarion:daarion.city": 100
|
||||
},
|
||||
"events": {
|
||||
"m.room.name": 50,
|
||||
"m.room.topic": 50
|
||||
}
|
||||
},
|
||||
"creation_content": {
|
||||
"m.federate": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"room_alias": "#general:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
**Errors:**
|
||||
- 400: Invalid request
|
||||
- 500: Matrix API error
|
||||
|
||||
---
|
||||
|
||||
#### **GET /internal/matrix/rooms/{roomId}**
|
||||
|
||||
Get room details.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"name": "General Discussion",
|
||||
"topic": "Main DAARION.city channel",
|
||||
"avatar_url": "mxc://daarion.city/avatar123",
|
||||
"canonical_alias": "#general:daarion.city",
|
||||
"member_count": 42,
|
||||
"joined_members": 38,
|
||||
"encryption": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **PUT /internal/matrix/rooms/{roomId}/name**
|
||||
|
||||
Update room name.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "Updated Room Name"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"event_id": "$event123:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Message Sending
|
||||
|
||||
#### **POST /internal/matrix/send**
|
||||
|
||||
Send a message to a room.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"sender": "agent:sofia",
|
||||
"sender_matrix_id": "@sofia:daarion.city",
|
||||
"msgtype": "m.text",
|
||||
"body": "Hello from DAARION!",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<p>Hello from <strong>DAARION</strong>!</p>",
|
||||
"relates_to": {
|
||||
"m.in_reply_to": {
|
||||
"event_id": "$parent_event:daarion.city"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"event_id": "$event456:daarion.city",
|
||||
"sent_at": "2025-11-24T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Supported msgtypes:**
|
||||
- `m.text` — plain text
|
||||
- `m.image` — image
|
||||
- `m.file` — file attachment
|
||||
- `m.audio` — audio
|
||||
- `m.video` — video
|
||||
- `m.notice` — bot/agent notice
|
||||
|
||||
---
|
||||
|
||||
#### **POST /internal/matrix/send-reaction**
|
||||
|
||||
React to a message.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"event_id": "$target_event:daarion.city",
|
||||
"reactor": "user:alice",
|
||||
"reactor_matrix_id": "@alice:daarion.city",
|
||||
"emoji": "👍"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"event_id": "$reaction789:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **POST /internal/matrix/redact**
|
||||
|
||||
Redact (delete) a message.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"event_id": "$event_to_delete:daarion.city",
|
||||
"reason": "Spam"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"event_id": "$redaction999:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Membership
|
||||
|
||||
#### **POST /internal/matrix/invite**
|
||||
|
||||
Invite a user/agent to a room.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"user_id": "@alice:daarion.city",
|
||||
"inviter": "user:admin",
|
||||
"inviter_matrix_id": "@admin:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "invited"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **POST /internal/matrix/join**
|
||||
|
||||
Join a room (on behalf of user/agent).
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"user_id": "@alice:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "joined",
|
||||
"room_id": "!general:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **POST /internal/matrix/leave**
|
||||
|
||||
Leave a room.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"user_id": "@alice:daarion.city"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "left"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **POST /internal/matrix/kick**
|
||||
|
||||
Kick a user from a room.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"user_id": "@spammer:daarion.city",
|
||||
"kicker": "@admin:daarion.city",
|
||||
"reason": "Violation of rules"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "kicked"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Event Sync
|
||||
|
||||
#### **GET /internal/matrix/sync**
|
||||
|
||||
Get recent events (polling mode).
|
||||
|
||||
**Query params:**
|
||||
- `since` — sync token (optional)
|
||||
- `timeout` — long-polling timeout in ms (default 30000)
|
||||
- `filter` — JSON filter (optional)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"next_batch": "s1234_567_8_9_10",
|
||||
"rooms": {
|
||||
"join": {
|
||||
"!general:daarion.city": {
|
||||
"timeline": {
|
||||
"events": [
|
||||
{
|
||||
"type": "m.room.message",
|
||||
"event_id": "$event123:daarion.city",
|
||||
"sender": "@alice:daarion.city",
|
||||
"content": {
|
||||
"msgtype": "m.text",
|
||||
"body": "Hello!"
|
||||
},
|
||||
"origin_server_ts": 1732445400000
|
||||
}
|
||||
],
|
||||
"limited": false,
|
||||
"prev_batch": "p1234_567"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **POST /internal/matrix/webhook/subscribe**
|
||||
|
||||
Subscribe to room events via webhook.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"room_id": "!general:daarion.city",
|
||||
"webhook_url": "http://messaging-service:7004/webhooks/matrix-events",
|
||||
"events": ["m.room.message", "m.room.member"]
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"subscription_id": "sub-abc123"
|
||||
}
|
||||
```
|
||||
|
||||
When events occur, matrix-gateway will POST to webhook_url:
|
||||
```json
|
||||
{
|
||||
"subscription_id": "sub-abc123",
|
||||
"room_id": "!general:daarion.city",
|
||||
"event": {
|
||||
"type": "m.room.message",
|
||||
"event_id": "$event456:daarion.city",
|
||||
"sender": "@bob:daarion.city",
|
||||
"content": {
|
||||
"msgtype": "m.text",
|
||||
"body": "Hi there"
|
||||
},
|
||||
"origin_server_ts": 1732445500000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **DELETE /internal/matrix/webhook/subscribe/{subscriptionId}**
|
||||
|
||||
Unsubscribe from webhook.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "unsubscribed"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. User Management
|
||||
|
||||
#### **POST /internal/matrix/register-user**
|
||||
|
||||
Register a new Matrix user (for agent or human).
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"username": "alice",
|
||||
"password": "generated-secure-password",
|
||||
"display_name": "Alice",
|
||||
"avatar_url": "mxc://daarion.city/avatar456",
|
||||
"admin": false
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"user_id": "@alice:daarion.city",
|
||||
"access_token": "syt_...",
|
||||
"device_id": "DEVICE123"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **PUT /internal/matrix/users/{userId}/display-name**
|
||||
|
||||
Update user display name.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"display_name": "Alice (Updated)"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "updated"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **PUT /internal/matrix/users/{userId}/avatar**
|
||||
|
||||
Update user avatar.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"avatar_url": "mxc://daarion.city/new-avatar"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "updated"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Media Upload
|
||||
|
||||
#### **POST /internal/matrix/upload**
|
||||
|
||||
Upload media (for messages with images/files).
|
||||
|
||||
**Request:** `multipart/form-data`
|
||||
- `file` — file to upload
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"content_uri": "mxc://daarion.city/file123",
|
||||
"content_type": "image/png",
|
||||
"size": 102400
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Room History
|
||||
|
||||
#### **GET /internal/matrix/rooms/{roomId}/messages**
|
||||
|
||||
Get paginated message history.
|
||||
|
||||
**Query params:**
|
||||
- `from` — pagination token (required)
|
||||
- `dir` — `b` (backwards) or `f` (forwards), default `b`
|
||||
- `limit` — max events, default 10
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"start": "t1234_567",
|
||||
"end": "t1234_500",
|
||||
"chunk": [
|
||||
{
|
||||
"type": "m.room.message",
|
||||
"event_id": "$event789:daarion.city",
|
||||
"sender": "@charlie:daarion.city",
|
||||
"content": {
|
||||
"msgtype": "m.text",
|
||||
"body": "Previous message"
|
||||
},
|
||||
"origin_server_ts": 1732445300000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Event Types (Matrix → DAARION mapping)
|
||||
|
||||
| Matrix Event Type | DAARION Internal Event |
|
||||
|-------------------|------------------------|
|
||||
| `m.room.message` (msgtype=m.text) | `messaging.message.created` |
|
||||
| `m.room.message` (msgtype=m.image) | `messaging.media.uploaded` |
|
||||
| `m.room.member` (join) | `messaging.member.joined` |
|
||||
| `m.room.member` (leave) | `messaging.member.left` |
|
||||
| `m.room.member` (invite) | `messaging.member.invited` |
|
||||
| `m.room.name` | `messaging.channel.updated` |
|
||||
| `m.room.topic` | `messaging.channel.updated` |
|
||||
| `m.reaction` | `messaging.reaction.added` |
|
||||
| `m.room.redaction` | `messaging.message.deleted` |
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All errors follow the format:
|
||||
```json
|
||||
{
|
||||
"error": "M_FORBIDDEN",
|
||||
"message": "You are not allowed to send messages in this room"
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
- `M_FORBIDDEN` — Insufficient permissions
|
||||
- `M_NOT_FOUND` — Room/user not found
|
||||
- `M_UNKNOWN` — Generic Matrix error
|
||||
- `M_BAD_JSON` — Invalid request payload
|
||||
- `INTERNAL_ERROR` — matrix-gateway internal error
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Environment variables:
|
||||
- `MATRIX_HOMESERVER_URL` — e.g. `https://matrix.daarion.city`
|
||||
- `MATRIX_ADMIN_TOKEN` — admin access token for homeserver operations
|
||||
- `INTERNAL_SERVICE_SECRET` — shared secret for service-to-service auth
|
||||
- `WEBHOOK_TIMEOUT_MS` — timeout for webhook deliveries (default 5000)
|
||||
- `SYNC_TIMEOUT_MS` — long-polling timeout (default 30000)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
1. **User impersonation**: matrix-gateway can send messages on behalf of any user/agent (using admin privileges or shared secret registration).
|
||||
|
||||
2. **Event transformation**: All Matrix events are enriched with DAARION entity IDs (user:..., agent:...) before forwarding to services.
|
||||
|
||||
3. **Webhook reliability**: Webhooks are retried 3 times with exponential backoff. Failed events are logged but not re-queued.
|
||||
|
||||
4. **Rate limiting**: matrix-gateway implements internal rate limiting to avoid overwhelming the homeserver (max 100 req/s per service).
|
||||
|
||||
5. **Caching**: Room metadata (name, topic, members) is cached for 5 minutes to reduce load on Matrix homeserver.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Use the provided `matrix-gateway-test.http` file for manual testing:
|
||||
|
||||
```http
|
||||
### Create room
|
||||
POST http://localhost:7003/internal/matrix/create-room
|
||||
X-Internal-Service-Token: dev-secret-token
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Test Room",
|
||||
"topic": "Testing",
|
||||
"visibility": "public"
|
||||
}
|
||||
|
||||
### Send message
|
||||
POST http://localhost:7003/internal/matrix/send
|
||||
X-Internal-Service-Token: dev-secret-token
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"room_id": "!test:daarion.city",
|
||||
"sender": "agent:test",
|
||||
"sender_matrix_id": "@test:daarion.city",
|
||||
"msgtype": "m.text",
|
||||
"body": "Hello from test!"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-11-24
|
||||
**Maintainer:** DAARION Platform Team
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user