bridgewire

package
v0.35.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 23, 2026 License: MIT Imports: 1 Imported by: 0

README

Bridge Wire Protocol

internal/bridgewire defines the shared types and constants for the Bridge Wire Protocol: a bidirectional JSON envelope used by BridgeServer and BridgeClients to communicate over WebSocket.

Both parties must agree on the exact field names and JSON tags documented here. This package is intentionally minimal — it contains no I/O, no business logic, and no dependencies beyond encoding/json.

Architecture

External Adapter (DingTalk) ──WebSocket──> BridgeServer
  (bridge-client SDK)          internal/server/bridge.go
                                 │
                                 ▼
                        internal/bridgewire  (shared types)
                                 │
                                 ▼
                        HotPlex Engine / ChatApps

internal/server/bridge.go and cmd/bridge-client both import this package. The protocol is symmetric: both sides send and receive the same WireMessage envelope, but only relevant fields are populated for each message type.

Message Types

MsgType* constants are the valid values for the type field in a WireMessage.

Constant Value Direction Description
MsgTypeRegister "register" Client → Server Initial handshake. Adapter announces its platform name and supported capabilities. Server responds with MsgTypeReply.
MsgTypeMessage "message" Both Primary message exchange. Carries content, session_key, and metadata.
MsgTypeReply "reply" Both Response to a message. Used by the adapter to deliver AI replies back to the platform.
MsgTypeEvent "event" Both Asynchronous signals such as typing indicators ("typing") or stream events ("stream_start", "stream_chunk", "stream_end").
MsgTypeError "error" Both Error response. Contains a numeric code and human-readable message.

Capabilities

Capability constants are declared by an adapter during the register handshake via the capabilities field. They inform HotPlex which message features the external platform supports.

Constant Value Description
CapText "text" Plain and markdown text messages.
CapImage "image" Image/file attachments.
CapCard "card" Structured card layouts.
CapButtons "buttons" Interactive button elements.
CapTyping "typing" Typing indicator events.
CapEdit "edit" Message editing after sending.
CapDelete "delete" Message deletion.
CapReact "react" Emoji reaction events.
CapThread "thread" Threaded message replies.

AllCapabilities exports the full set as a []string slice for convenience.

Structs

WireMessage

The bidirectional JSON envelope. All fields use snake_case JSON tags matching the wire format.

Field Type JSON tag Present in Description
Type string type All Message type identifier (MsgType*).
Platform string platform register, reply, message Platform name, e.g. "dingtalk".
Token string token register Authentication token.
SessionKey string session_key message, reply, event Unique session identifier for routing.
Content string content message, reply Message text content.
Metadata json.RawMessage metadata message, reply WireMetadata encoded as JSON.
Event string event event Event name, e.g. "typing".
Data json.RawMessage data event Arbitrary JSON payload for event data.
Code int code error Numeric error code.
Message string message error Human-readable error description.
Capabilities []string capabilities register List of supported capabilities.
WireMetadata

Carried inside WireMessage.Metadata. Describes the source room, thread, and user identity.

Field Type JSON tag Description
UserID string user_id User identifier on the external platform.
RoomID string room_id Room or channel identifier.
ThreadID string thread_id Thread identifier (for threaded platforms).
Platform string platform Platform name that originated the metadata.

Consumers

internal/server/bridge.go

BridgeServer acts as the WebSocket server side. It:

  • Accepts WebSocket connections at GET /bridge/v1/{platform}.
  • Authenticates via Authorization: Bearer <token> header (deprecated query-param fallback).
  • Dispatches inbound WireMessages to BridgePlatform, which translates them into base.ChatMessage and forwards to the HotPlex engine.
  • Delivers outbound AI replies back to the adapter via the same WebSocket.

BridgePlatform implements base.ChatAdapter, making it indistinguishable from built-in adapters as far as the engine is concerned.

cmd/bridge-client

bridge-client is the reference Go SDK for building external adapters. It:

  • Connects to BridgeServer as a WebSocket client.
  • Sends a MsgTypeRegister handshake on connect.
  • Receives MsgTypeMessage (AI replies) and MsgTypeEvent (stream signals) via OnMessage / OnEvent handlers.
  • Sends inbound user messages via SendMessage and typing indicators via Typing.

See _examples/go_bridge_client/main.go for a complete integration example.

Protocol Flow

Adapter                          BridgeServer
  │                                    │
  │──── WebSocket Connect ───────────▶│
  │                                    │
  │──── register {platform, caps} ────▶│  validate + register platform
  │◀─── reply {type:"reply"} ──────────│
  │                                    │
  │                                    │  (user sends DM on DingTalk)
  │◀─── (routing via AdapterManager) ──│
  │──── message {content, session_key, metadata} ────▶│  WAF check → ChatMessage → engine
  │                                    │
  │◀─── message {content} ────────────│  AI reply from engine
  │──── reply {content, session_key} ──▶│
  │                                    │
  │  (stream events delivered via event type)

Documentation

Overview

Package bridgewire defines the shared Bridge Wire Protocol types and constants used by both BridgeServer (internal/server) and BridgeClient (cmd/bridge-client).

The wire protocol is a bidirectional JSON envelope. Both parties must agree on the exact field names and JSON tags documented here.

Index

Constants

View Source 
const (
	MsgTypeRegister = "register"
	MsgTypeMessage  = "message"
	MsgTypeReply    = "reply"
	MsgTypeEvent    = "event"
	MsgTypeError    = "error"
)

MsgType* are the valid Type field values in a WireMessage.

View Source 
const (
	CapText    = "text"
	CapImage   = "image"
	CapCard    = "card"
	CapButtons = "buttons"
	CapTyping  = "typing"
	CapEdit    = "edit"
	CapDelete  = "delete"
	CapReact   = "react"
	CapThread  = "thread"
)

Capability constants that an adapter can declare when registering.

Variables

View Source 
var AllCapabilities = []string{
	CapText, CapImage, CapCard, CapButtons,
	CapTyping, CapEdit, CapDelete, CapReact, CapThread,
}

AllCapabilities is the full set of supported capabilities.

Functions

This section is empty.

Types

type WireMessage 

type WireMessage struct {
	Type         string          `json:"type"`
	Platform     string          `json:"platform,omitempty"`
	Token        string          `json:"token,omitempty"`
	SessionKey   string          `json:"session_key,omitempty"`
	Content      string          `json:"content,omitempty"`
	Metadata     json.RawMessage `json:"metadata,omitempty"`
	Event        string          `json:"event,omitempty"`
	Data         json.RawMessage `json:"data,omitempty"`
	Code         int             `json:"code,omitempty"`
	Message      string          `json:"message,omitempty"`
	Capabilities []string        `json:"capabilities,omitempty"`

	// Relay fields (omitempty for backward compatibility)
	From      string `json:"from,omitempty"`
	To        string `json:"to,omitempty"`
	TaskID    string `json:"task_id,omitempty"`
	Status    string `json:"status,omitempty"`
	Response  string `json:"response,omitempty"`
	Error     string `json:"error,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
}

WireMessage is the bidirectional JSON envelope for the Bridge Wire Protocol. All fields use snake_case JSON tags to match the wire format.

Direction: both client→server and server→client share the same struct, but only the relevant fields are populated for each message type.

type WireMetadata 

type WireMetadata struct {
	UserID   string `json:"user_id,omitempty"`
	RoomID   string `json:"room_id,omitempty"`
	ThreadID string `json:"thread_id,omitempty"`
	Platform string `json:"platform,omitempty"`
}

WireMetadata is the metadata carried inside WireMessage.Metadata. It describes the source room, thread, and user identity.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.