Skip to content

feat: Add application service (bridges) support#394

Open
sampaiodiego wants to merge 89 commits into
mainfrom
add-application-service-support
Open

feat: Add application service (bridges) support#394
sampaiodiego wants to merge 89 commits into
mainfrom
add-application-service-support

Conversation

@sampaiodiego

@sampaiodiego sampaiodiego commented Jun 1, 2026

Copy link
Copy Markdown
Member

Summary by CodeRabbit

  • New Features
    • Added Matrix Application Service support end-to-end (registration, ping, transaction delivery, namespace matching, and bridge querying).
    • Added client-server appservice-driven endpoints for registration, rooms, profile, events, and directory room alias updates.
    • Added support for custom event sending and automatic ephemeral EDU routing (typing, receipts, presence).
  • Bug Fixes
    • Improved batching/serialization and per-appservice delivery retries with exponential backoff and recovery behavior.
    • Improved alias reservation/release and sender/ghost user handling.
  • Documentation
    • Added a Bridge Architecture Guide plus appservice API compliance notes.
  • Tests
    • Added coverage for event routing and namespace matching.

@coderabbitai

coderabbitai Bot commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

This PR adds a new @rocket.chat/appservice package for Matrix Application Service support, wires it into federation SDK and homeserver flows, adds bridge-focused docs, and updates core transport and room helpers to support the new routing and delivery paths.

Changes

Application Service Bridge Integration

Layer / File(s) Summary
Bridge architecture guide
docs/bridge-architecture-guide.md
Adds a Matrix Bridge Architecture Guide covering AS registration, transaction delivery, bridge operations, query endpoints, database schema, and repo-specific implementation mapping.
Appservice package contracts
packages/appservice/package.json, packages/appservice/tsconfig.json, packages/appservice/src/index.ts, packages/appservice/src/config-provider.ts, packages/appservice/src/models/appservice.model.ts, bundle.ts, tsconfig.json, tsconfig.base.json, packages/core/src/events/homeserver-event-signatures.ts, packages/core/src/index.ts, packages/appservice/TODO.md
Introduces the appservice package entrypoint, metadata, TS project config, config provider interface/token, domain model types, and bundling/project-reference wiring. Also adds shared homeserver event signatures and the core path alias for the new package.
Appservice persistence and namespace matching
packages/appservice/src/repositories/appservice-state.repository.ts, packages/appservice/src/repositories/appservice-txn.repository.ts, packages/appservice/src/services/registration.service.ts, packages/appservice/src/services/namespace-matcher.service.ts, packages/appservice/src/services/namespace-matcher.service.spec.ts
Adds MongoDB-backed state/transaction repositories, config-driven registration caching, namespace regex compilation/matching, sender-user ownership helpers, and related tests.
Appservice routing and delivery
packages/appservice/src/utils/edu-to-appservice.ts, packages/appservice/src/utils/edu-to-appservice.spec.ts, packages/appservice/src/services/event-router.service.ts, packages/appservice/src/services/event-router.service.spec.ts, packages/appservice/src/services/bridge-query.service.ts, packages/appservice/src/services/ping.service.ts
Converts federation EDUs to ephemeral events, batches and serializes transaction delivery per bridge, and adds bridge query/ping HTTP helpers, with tests for conversion and routing behavior.
Federation SDK wiring and repositories
packages/federation-sdk/src/index.ts, packages/federation-sdk/src/repositories/room-alias.repository.ts, packages/federation-sdk/src/repositories/user.repository.ts, packages/federation-sdk/src/services/config.service.ts, packages/federation-sdk/src/services/directory.service.ts, packages/federation-sdk/src/services/event-emitter.service.ts, packages/federation-sdk/src/queues/per-destination.queue.ts, packages/federation-sdk/tsconfig.json, packages/federation-sdk/package.json, packages/federation-sdk/src/services/appservice-room.service.ts, packages/federation-sdk/src/services/event-sender.service.ts, packages/federation-sdk/src/services/event-sender.service.spec.ts, packages/federation-sdk/src/services/message.service.ts, packages/federation-sdk/src/services/profiles.service.ts, packages/federation-sdk/src/services/edu.service.ts, packages/federation-sdk/src/services/room.service.ts, packages/federation-sdk/src/utils/event-schemas.ts, packages/federation-sdk/src/sdk.ts
Registers appservice config and collections in the DI container, adds room alias and directory repositories, extends user repo sender-user provisioning, adds XMPP config schema, fixes retry timer state reset, adds custom event sending and room-creation delegation, routes messages/EDUs through the event router, and updates room/profile behavior.
Homeserver client-server endpoints and auth
packages/homeserver/src/middlewares/appserviceAuth.ts, packages/homeserver/src/controllers/client/*.ts, packages/homeserver/src/homeserver.module.ts, packages/homeserver/tsconfig.json
Adds appservice authentication middleware and client-server controllers for register, events, rooms, profile, and directory, then wires them into the homeserver app.
Core transport and room helpers
packages/core/src/utils/fetch.ts, packages/room/src/manager/room-state.ts
Reworks fetch to select HTTP/HTTPS transport with SNI support and shared body-reading/error helpers, and adds canonical alias extraction to room state.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EduService
  participant EventRouterService
  participant NamespaceMatcherService
  participant TransactionSenderService
  participant Bridge
  EduService->>EventRouterService: routeEphemeral(typing|presence|receipt EDU)
  EventRouterService->>NamespaceMatcherService: getInterestedAppServices(...)
  NamespaceMatcherService-->>EventRouterService: interested appservices
  EventRouterService->>TransactionSenderService: sendTransaction(appservice, batch)
  TransactionSenderService->>Bridge: PUT /_matrix/app/v1/transactions/{txnId}
  Bridge-->>TransactionSenderService: response
Loading
sequenceDiagram
  participant Client
  participant HomeserverController
  participant resolveAppServiceAuth
  participant FederationSDK
  Client->>HomeserverController: appservice-authenticated request
  HomeserverController->>resolveAppServiceAuth: resolveAppServiceAuth(...)
  resolveAppServiceAuth->>FederationSDK: getRegistrationByAsToken(token)
  FederationSDK-->>resolveAppServiceAuth: registration
  resolveAppServiceAuth-->>HomeserverController: auth result or error
  HomeserverController-->>Client: Matrix response
Loading

Possibly related PRs

  • RocketChat/homeserver#239: Both PRs touch the HomeserverEventSignatures type and its wiring across packages/federation-sdk/src/index.ts and core event signatures.
  • RocketChat/homeserver#292: Both PRs modify FederationSDK bootstrap and public SDK wiring in packages/federation-sdk/src/index.ts and packages/federation-sdk/src/sdk.ts.

Suggested labels: type: feature

Suggested reviewers: ggazzo, rodrigok

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: adding application service and bridge support.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@codecov-commenter

codecov-commenter commented Jun 1, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 61.71171% with 510 lines in your changes missing coverage. Please review.
✅ Project coverage is 51.16%. Comparing base (9052057) to head (bf1cdb3).

Files with missing lines Patch % Lines
...ce/src/repositories/appservice-state.repository.ts 5.15% 92 Missing ⚠️
...es/appservice/src/services/registration.service.ts 19.79% 77 Missing ⚠️
...es/appservice/src/services/event-router.service.ts 60.56% 56 Missing ⚠️
...ckages/federation-sdk/src/services/room.service.ts 77.60% 43 Missing ⚠️
packages/federation-sdk/src/sdk.ts 52.50% 38 Missing ⚠️
...federation-sdk/src/repositories/user.repository.ts 7.69% 36 Missing ⚠️
packages/federation-sdk/src/index.ts 43.54% 35 Missing ⚠️
...ration-sdk/src/services/appservice-room.service.ts 30.43% 32 Missing ⚠️
...tion-sdk/src/repositories/room-alias.repository.ts 17.85% 23 Missing ⚠️
...vice/src/repositories/appservice-txn.repository.ts 20.00% 20 Missing ⚠️
... and 8 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #394      +/-   ##
==========================================
+ Coverage   50.64%   51.16%   +0.51%     
==========================================
  Files         101      113      +12     
  Lines       11533    12734    +1201     
==========================================
+ Hits         5841     6515     +674     
- Misses       5692     6219     +527     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@sampaiodiego sampaiodiego force-pushed the add-application-service-support branch from 1fa0373 to 4ee3063 Compare June 2, 2026 19:50

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
packages/appservice/src/services/transaction-sender.service.ts (1)

236-245: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Transport failures are logged/recorded as HTTP undefined.

When fetch() fails at the transport layer it resolves with ok: false and status: undefined (it does not throw), so this branch — not the catch — runs, logging status: undefined and calling markDown(..., 'HTTP undefined'). The down-marking is correct, but the reason is misleading for the common connection-failure case. Consider distinguishing response.status === undefined (connection failed) from a genuine non-2xx, mirroring ping.service.ts.

🪵 Suggested distinction
-		this.logger.warn({
-			msg: `Transaction delivery failed`,
-			asId: registration._id,
-			txnId,
-			status: response.status,
-		});
-
-		await this.txnRepo.markFailed(registration._id, txnId);
-		await this.stateRepo.markDown(registration._id, `HTTP ${response.status}`);
-		return false;
+		const reason = response.status === undefined ? 'Failed to connect to appservice' : `HTTP ${response.status}`;
+		this.logger.warn({ msg: 'Transaction delivery failed', asId: registration._id, txnId, status: response.status, reason });
+
+		await this.txnRepo.markFailed(registration._id, txnId);
+		await this.stateRepo.markDown(registration._id, reason);
+		return false;
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/appservice/src/services/transaction-sender.service.ts` around lines
236 - 245, The failure handling in transaction-sender.service.ts logs and marks
transport errors as HTTP undefined, which is misleading when fetch() returns a
response with status unset. Update the non-ok response branch around the
logger.warn, txnRepo.markFailed, and stateRepo.markDown calls to distinguish
response.status === undefined from a real HTTP status, similar to
ping.service.ts. Use a clearer reason string for connection/transport failures
while keeping genuine non-2xx responses recorded with their actual HTTP status.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/appservice/src/services/transaction-sender.service.ts`:
- Around line 236-245: The failure handling in transaction-sender.service.ts
logs and marks transport errors as HTTP undefined, which is misleading when
fetch() returns a response with status unset. Update the non-ok response branch
around the logger.warn, txnRepo.markFailed, and stateRepo.markDown calls to
distinguish response.status === undefined from a real HTTP status, similar to
ping.service.ts. Use a clearer reason string for connection/transport failures
while keeping genuine non-2xx responses recorded with their actual HTTP status.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0d5d88df-77c2-4d0a-b4cd-cc7a1ff75e11

📥 Commits

Reviewing files that changed from the base of the PR and between dfc5386 and 9fc2919.

📒 Files selected for processing (21)
  • docs/bridge-architecture-guide.md
  • packages/appservice/src/index.ts
  • packages/appservice/src/models/appservice.model.ts
  • packages/appservice/src/repositories/appservice-state.repository.ts
  • packages/appservice/src/repositories/appservice-txn.repository.ts
  • packages/appservice/src/services/event-router.service.spec.ts
  • packages/appservice/src/services/event-router.service.ts
  • packages/appservice/src/services/namespace-matcher.service.spec.ts
  • packages/appservice/src/services/namespace-matcher.service.ts
  • packages/appservice/src/services/ping.service.ts
  • packages/appservice/src/services/registration.service.ts
  • packages/appservice/src/services/transaction-sender.service.ts
  • packages/core/src/utils/fetch.ts
  • packages/federation-sdk/src/index.ts
  • packages/federation-sdk/src/repositories/room-alias.repository.ts
  • packages/federation-sdk/src/services/directory.service.ts
  • packages/federation-sdk/src/services/edu.service.ts
  • packages/federation-sdk/src/services/event-sender.service.spec.ts
  • packages/federation-sdk/src/services/event-sender.service.ts
  • packages/federation-sdk/src/services/message.service.ts
  • packages/federation-sdk/src/services/room.service.ts
🚧 Files skipped from review as they are similar to previous changes (13)
  • packages/appservice/src/index.ts
  • packages/federation-sdk/src/services/directory.service.ts
  • packages/appservice/src/repositories/appservice-txn.repository.ts
  • packages/appservice/src/services/event-router.service.spec.ts
  • packages/appservice/src/models/appservice.model.ts
  • packages/federation-sdk/src/services/edu.service.ts
  • packages/federation-sdk/src/services/event-sender.service.spec.ts
  • packages/appservice/src/repositories/appservice-state.repository.ts
  • packages/appservice/src/services/registration.service.ts
  • packages/federation-sdk/src/services/event-sender.service.ts
  • packages/appservice/src/services/namespace-matcher.service.spec.ts
  • packages/appservice/src/services/namespace-matcher.service.ts
  • packages/federation-sdk/src/services/room.service.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
  • GitHub Check: cubic · AI code reviewer
  • GitHub Check: Code Quality Checks(lint, test, tsc)
🔇 Additional comments (8)
packages/appservice/src/services/ping.service.ts (1)

52-74: LGTM!

packages/federation-sdk/src/repositories/room-alias.repository.ts (1)

25-35: LGTM!

docs/bridge-architecture-guide.md (1)

115-131: LGTM!

packages/federation-sdk/src/index.ts (1)

156-192: LGTM!

packages/core/src/utils/fetch.ts (1)

123-184: LGTM!

Also applies to: 233-248

packages/appservice/src/services/event-router.service.ts (1)

30-68: LGTM!

packages/appservice/src/services/transaction-sender.service.ts (1)

60-87: LGTM!

Also applies to: 149-200

packages/federation-sdk/src/services/message.service.ts (1)

54-54: LGTM!

Also applies to: 128-128, 182-182, 262-262, 289-289, 334-334, 372-372

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 17 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/federation-sdk/src/index.ts">

<violation number="1" location="packages/federation-sdk/src/index.ts:192">
P2: `init()` starts a background retry scheduler via `transactionSender.startRetryScheduler()`, but there is no corresponding teardown path exposed. The underlying `setInterval` in `TransactionSenderService` is not `.unref()`'d, so it will keep the Node process alive indefinitely. In tests, workers, or short-lived scripts this prevents clean exit, and the existing `stopRetryScheduler()` method is never called. Consider either exposing a shutdown hook from `init()` that calls `stopRetryScheduler()`, or `.unref()`'ing the timer so it does not block process exit.</violation>
</file>

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/appservice/src/services/event-router.service.ts
Comment thread packages/appservice/src/repositories/appservice-state.repository.ts
Comment thread packages/federation-sdk/src/index.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 11 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/federation-sdk/src/sdk.ts
Comment thread packages/appservice/src/services/transaction-sender.service.ts
Comment thread packages/appservice/src/services/transaction-sender.service.ts
Comment thread packages/appservice/src/services/transaction-sender.service.ts
Comment thread packages/appservice/src/services/ping.service.ts
Comment thread packages/appservice/src/services/transaction-sender.service.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/appservice/src/services/transaction-sender.service.ts Outdated
Comment thread packages/appservice/src/services/transaction-sender.service.ts Outdated
Comment thread packages/homeserver/src/controllers/client/ping.controller.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants