Compatibility Scope

Last updated: 2026-03-22 Source docs consolidated: docs/MATTERMOST_CLIENTS.md, docs/reference/compatibility-matrix.md

---

1. Compatibility Commitment

rustchat commits to supporting Mattermost mobile (iOS/Android) and desktop clients as first-class external clients. Specifically:

• Mattermost Mobile v2.x clients can authenticate and use core functionality
• Mattermost Desktop clients can connect via the /api/v4/ HTTP surface
• The Mattermost WebSocket protocol (/api/v4/websocket) is supported including auth challenge, session resumption, and standard event types

This is not a full Mattermost clone — some advanced features (plugins, advanced search, custom emoji upload) are not implemented.

---

2. Current Coverage

Mobile-critical endpoints (primary metric)

39/41 endpoints working (95.1%) — as of 2026-03-17

Category	Coverage
Authentication & Session	6/6 ✅
User Management	5/5 ✅
Teams	4/4 ✅
Channels	6/6 ✅
Posts & Messaging	7/7 ✅
Threads	3/3 ✅
Files	3/3 ✅
Preferences	2/2 ✅
WebSocket	1/1 ✅
System	2/2 ✅
Total	39/41

Known gaps (2/41):

Endpoint	Status	Impact	Planned
POST /api/v4/emoji	❌ Not implemented	Medium — custom emoji upload unavailable	Phase 2
POST /api/v4/posts/search	❌ Not implemented	Medium — advanced search unavailable	Phase 2

For the endpoint coverage summary, see Reference Compatibility Matrix.

Full v4 API surface (secondary metric)

Historical full-surface analysis is available in archived compatibility notes and is intentionally broader than the mobile-critical metric. The gap is expected: rustchat does not aim to implement the full Mattermost v4 API, only the subset required for mobile and desktop client operation.

Do not conflate these two numbers. 39/41 (95.1%) is the mobile compatibility headline. ~60% is the broader full-API coverage figure.

---

3. Protected Surface

The following paths form the Mattermost compatibility surface. Changes here require compat-reviewer co-approval (@zoorpha) and are automatically elevated to the elevated risk tier per .governance/protected-paths.yml:

Path	Purpose
backend/src/api/v4/	Mattermost HTTP API v4 handlers
backend/src/mattermost_compat/	Response transformation, field mapping utilities
backend/compat/	Contract JSON schemas + contract validation tests
backend/src/realtime/	WebSocket hub (v4 event contracts)

No changes to these paths without compat review. If unsure whether your change touches this surface, treat it as if it does.

---

4. Contract Tests

Contract tests live in backend/compat/tests/. They validate that rustchat's API responses conform to the expected Mattermost v4 JSON schemas.

# Run contract tests (requires live Postgres + Redis)
cd backend
RUSTCHAT_TEST_DATABASE_URL=postgres://... cargo test contract

Contract JSON schemas: backend/compat/ — one schema per major entity type (user, channel, post, error).

When the compat surface changes, update the schema and regenerate the contract test. Do not merge compat surface changes without passing contract tests.

---

5. Gap Handling

New gaps discovered during development:

1. Open a GitHub issue using the Bug Report template, set Compatibility impact: Yes — affects Mattermost clients
2. Label will be applied as area/compat during triage
3. Implementation planned via the standard spec → plan → execution workflow with compat-reviewer co-approval

---

6. Connecting Mattermost Clients

Server URL: http://your-host:8080 (Nginx proxy, recommended) or http://your-host:3000 (direct backend)

Port	Service	Notes
8080	Nginx proxy	Recommended — handles web UI and /api/v4
3000	Backend direct	Bypass Nginx if needed

Steps:

1. In Mattermost Mobile or Desktop: Settings → Add Server
2. Enter the Server URL (port 8080)
3. Use email/password login (SSO configurable separately)
4. WebSocket connects automatically to /api/v4/websocket

Known client limitations:

• Push notifications require the push-proxy service to be running with valid FCM/APNS credentials
• Some advanced features (search, custom emoji, plugins) are not available