feat(federation): Matrix spec compliance improvements with Complement diagnostics

[Copilot]

This PR contains Matrix Spec v1.16 compliance improvements for federation and client APIs, plus diagnostic artifacts for Complement testing.

Matrix Spec Compliance Changes

1. State Event Routes (Client API)

Files: src/main/kotlin/routes/client-server/client/room/RoomRoutes.kt

Added support for optional stateKey parameter in state event endpoints:

• PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey?} - stateKey now optional
• PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType} - defaults stateKey to empty string

Spec Reference: Matrix Spec v1.16 Section 6.3.6.1 - State events can have empty state_key, represented by omitting the path segment or providing empty string.

2. Federation User Profile Query

Files: src/main/kotlin/routes/server_server/federation/v1/FederationV1UserQuery.kt

Profile query responses now always include displayname and avatar_url keys, even when null, ensuring consistent response format across federation.

Spec Reference: Matrix Spec v1.16 Section 11.6.2.1 - Profile responses must include standard fields consistently.

3. Federation V2 Send Join Auth Chain

Files: src/main/kotlin/routes/server_server/federation/v2/FederationV2Routes.kt

Send join responses now include complete auth_chain array with all authorization events, enabling receiving servers to verify event authorization.

Spec Reference: Matrix Spec v1.16 Section 11.3.2.1.4 - send_join must return auth_chain for event verification.

4. Get Missing Events Implementation

Files: src/main/kotlin/routes/server_server/federation/v1/FederationV1Events.kt, FederationV1Utils.kt

Implemented breadth-first search for missing events:

• Returns events in oldest-first order (reversed traversal)
• Includes origin and origin_server_ts in response per spec
• Returns PDUs in pdus array

Spec Reference: Matrix Spec v1.16 Section 11.5.2.1 - get_missing_events must return events between earliest and latest.

Test Coverage

All code changes are covered by unit tests:

• ✅ StateEventRoutesTest.kt - 5 tests for state event route changes
• ✅ FederationProfileQueryTest.kt - 6 tests for federation profile query changes
• ✅ FederationV2AuthChainTest.kt - 3 tests for auth_chain implementation
• ✅ MissingEventsTest.kt - 1 test for get_missing_events implementation

Total: 15 unit tests, all passing

Complement Diagnostic Artifacts

Port Binding Analysis

The diagnostic log shows HSPortBindingIP:127.0.0.1 in Complement config. Docker containers resolve host.docker.internal to the host's bridge IP (e.g., 192.168.65.254) but cannot reach ports bound to localhost only.

Resolution: Run Complement with HOMERUNNER_HS_PORTBINDING_IP=0.0.0.0 to bind all interfaces.

Diagnostic Files

• complement-test-output.txt (964KB) - Captured Complement test run output
• COMPLEMENT_LOCAL_RUN.md - Instructions for running Complement tests locally on Windows/WSL

Diagnostic Commands (PowerShell)

# Check port binding whilst Complement runs
Get-NetTCPConnection -LocalPort <ephemeral_port>

# Test container→host connectivity from WSL
wsl curl -vk https://host.docker.internal:<port>/_matrix/key/v2/server

Verification

./gradlew test  # All 15 tests pass
./gradlew build # Clean build

Shoutout to the FERRETCANNON massive for spec compliance! 🎆

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[EdGeraghty]

@copilot you're correct that there are code sections in here for test compliance.

Please update the pr description to accurately reflect what this PR contains, include doing a full code review as I think there are also unit tests for the new behaviour? If there aren't unit tests, work out if the code changes are spec compliant and then write some.

[Copilot]

@copilot you're correct that there are code sections in here for test compliance.

Please update the pr description to accurately reflect what this PR contains, include doing a full code review as I t...

Code review completed. The PR contains 4 Matrix spec-compliant changes with full test coverage:

1. State event routes - Optional stateKey parameter (5 tests)
2. Federation profile query - Always returns displayname/avatar_url keys (6 tests)
3. Federation v2 auth_chain - Includes authorization events (3 tests)
4. Get missing events - BFS implementation returning oldest-first (1 test)

All 15 new unit tests pass. PR description updated with complete details. Commit: abb59bb