Protocol Base API & Contracts

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/app-observability.ts
• AGENTS.md
• README.en.md
• architecture-diagrams.md
• tests/PROTOCOL_AUTH_HEARTBEAT.md
• protocols/satori-v1/protocol/src/tests/format.test.ts

The Protocol layer serves as the external interface for the OneBots gateway. It transforms internal CommonEvent abstractions into standardized wire formats, such as OneBot v11, OneBot v12, Satori v1, and Milky v1, to expose them to downstream clients and services.

This layer handles two primary data directions:

1. Upstream (Events): Converting normalized platform events into protocol-specific payloads for delivery via WebSocket, WebHook, or SSE.
2. Downstream (Actions): Receiving inbound API calls, validating credentials, and mapping protocol actions to specific Adapter methods.

Sources: AGENTS.md:14-17, README.en.md:27-32

Core Architecture

The system defines an abstract Protocol base class that all specific protocol implementations must extend. Each protocol instance operates within the context of a specific Account and Adapter.

Component Relationships

The diagram shows the hierarchy from the global Application down to individual Protocol instances attached to Accounts.
Sources: architecture-diagrams.md:150-220, protocols/satori-v1/protocol/src/tests/format.test.ts:7-35

Protocol Properties and State

Property	Description
name	The protocol identifier (e.g., "onebot", "satori", "milky").
version	The specific protocol version string (e.g., "v11", "v12", "v1").
lifecycleStatus	Current operational state: ready or unavailable.
path	The URL routing prefix, typically {account_path}/{protocol}/{version}.
router	Reference to the Koa-based router for registering endpoints.

Sources: packages/core/src/app-observability.ts:48-55, protocols/satori-v1/protocol/src/tests/format.test.ts:28-35

Event Transformation Flow (Upstream)

When an IM platform sends an event, the Adapter normalizes it into a CommonEvent. The Account then dispatches this event to all active Protocol instances.

This flowchart illustrates how a single internal event is replicated and reformatted for multiple external protocols simultaneously.
Sources: AGENTS.md:14-17, architecture-diagrams.md:80-112

API Action Execution (Downstream)

Downstream clients interact with the gateway by calling protocol-specific endpoints. The Protocol layer translates these requests into Adapter commands.

1. Request Receipt: The Protocol instance receives an action request via its registered HTTP or WebSocket route.
2. Authentication: The protocol validates the access_token or signature.
3. Action Mapping: The apply() method maps the protocol action (e.g., send_private_msg) to the Adapter's implementation (e.g., adapter.sendMessage).
4. Result Formatting: The protocol captures the Adapter's response and wraps it in the standard protocol envelope (e.g., retcode for OneBot).

Sources: architecture-diagrams.md:117-148, tests/PROTOCOL_AUTH_HEARTBEAT.md:19-25

Communication and Security Contracts

Protocols must adhere to specific authentication and heartbeat standards to ensure compatibility with ecosystem clients.

Authentication Standards

Protocol	Auth Header	Query Parameter	Failure Code
OneBot 11	Authorization: Bearer <token>	access_token	401 Unauthorized
OneBot 12	Authorization: Bearer <token>	access_token	401 Unauthorized
Milky	Authorization: Bearer <token>	access_token	401 Unauthorized
Satori	Authorization: Bearer <token>	N/A	401/403

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:19-35, tests/PROTOCOL_AUTH_HEARTBEAT.md:73-82

Heartbeat Requirements

Protocols that define meta-events (like OneBot) must provide periodic heartbeat signals to active connections.

• OneBot 11: Must include interval (milliseconds) and status object.
• OneBot 12: Must include interval (milliseconds); status is optional.
• Milky: Follows OB11 compatible meta-event formats.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:38-44, tests/PROTOCOL_AUTH_HEARTBEAT.md:65-69

Lifecycle Management

The BaseApp monitors protocol instances through readiness snapshots. A protocol is considered ready only if its underlying Account is online and the protocol service has successfully started.

• Start: Protocols initialize servers (HTTP/WS) and register listeners on the Account's dispatch bus.
• Stop: Protocols close active connections and remove all event listeners to prevent memory leaks.
• Readiness: The observability module tracks ready_protocols vs total_protocols across all adapters.

Sources: packages/core/src/app-observability.ts:86-125, protocols/satori-v1/protocol/src/tests/format.test.ts:320-328