e33d6e5
/**
* Wire protocol of the (removed) chat WebSocket endpoint (`GET /ws/v1`, im gateway).
*
* 已过时：`app/im` 已从 KenApi 删除，实时通道归 `KenEvent`（Socket.IO）。
* 文件保留为旧协议的对照说明；按 KenEvent 重写时以
* `KenEvent/src/events/action/common.rs::payload` 为准（信封 = topic/tag/
* properties/body，没有 `subscribe` 帧）。
*
* This file is a 1:1 mirror of the Rust definitions in `gitdataai/app/im/src/frames.rs` and `lib/chat/src/share/realtime.rs`:
* src/ws/frames.rs -> ClientFrame / ServerFrame
* src/share/realtime.rs -> RoomEvent (`event` frame payloads)
* src/share/notify.rs + src/services/* -> the ad-hoc JSON on the user channel
* (`user_event` frame payloads)
*
* Serde rules this file encodes:
* - Client frames are internally tagged by `op` with `rename_all = "snake_case"`
* (frames.rs:6-7); server frames by `type` (frames.rs:29-30); the payloads
* carried by `event` / `user_event` by `kind` (realtime.rs:19-20).
* - Rust `Option<T>` fields are *always* serialised (`null` when absent) because
* the backend never uses `skip_serializing_if`, so those fields are
* `T | null` (required) here rather than `?: T`. The one exception is
* `mention.everyone`, which is built with `json!` and only appears on the
* @everyone fanout (notify.rs:231-237).
* - `Uuid` crosses as a string, `i64`/`u64` as a JSON number, `OffsetDateTime`
* as an RFC 3339 string.
* - `PresenceStatus` carries **no** `rename_all` (models/chat/presence_states.rs:7-31),
* so it is PascalCase on the wire, unlike every other chat enum. Reuse the
* generated type instead of hand-writing the variants.
*/
import type { MessageDto, NotificationType, PresenceStatus } from '@app/services/api'
/* --------------------------------------------------------------------------
* Connection lifecycle (client-side only; never on the wire)
* ------------------------------------------------------------------------ */
/**
* Connection lifecycle reported by `ChatWsClient.onStatus`.
* - `auth_required` / `failed` are terminal: the client stops reconnecting and
* needs an explicit `start()` (after re-login / after a manual retry).
*/
export type WsStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'auth_required' | 'failed'
/* --------------------------------------------------------------------------
* Server knobs that leak into the protocol
* (config/default.toml:143-163 + lib/config/src/chat.rs:1-23,60-101)
* ------------------------------------------------------------------------ */
/**
* Defaults of the `[chat]` / `[chat.ws]` config sections. They are *advisory*:
* a deployment can change them, so the client uses them as pre-flight limits and
* still treats the server's `error` / `resync_required` frames as authoritative.
*/
export const WS_SERVER_DEFAULTS = {
/** Lifetime of a `GET /auth/jwt-request` JWT; single-use (im gateway SETNX jti). */
jwtTtlSecs: 60,
/** Server tick interval; an idle socket gets `bye` after 3x (ws/mod.rs:220-224,310-315). */
heartbeatSecs: 30,
/** Max room subscriptions per socket (ws/mod.rs:228,410-419). */
maxSubscriptions: 64,
/** Inbound frame limit set on the socket (ws/mod.rs:141). */
maxFrameBytes: 262_144,
/** `history` / `resync` page size (ws/mod.rs:470,516). */
historyLimit: 200,
/** TTL carried by `typing` events, floor of 1s (ws/mod.rs:545). */
typingTtlSecs: 5,
/** Hard-coded per-socket typing throttle, not configurable (ws/mod.rs:534-538). */
typingThrottleSecs: 3,
} as const
/* --------------------------------------------------------------------------
* Client -> server frames (ws/frames.rs:6-27)
* ------------------------------------------------------------------------ */
export const WS_CLIENT_OPS = ['subscribe', 'unsubscribe', 'resync', 'typing', 'ping'] as const
/**
* `Subscribe { room_id, resync }`. `resync` is `Option<bool>` and the server
* does `resync.unwrap_or(true)` (frames.rs:9-13, ws/mod.rs:485), so omitting it
* asks for a `history` snapshot of the newest `history_limit` messages.
*/
export interface WsSubscribeFrame {
op: 'subscribe'
room_id: string
resync?: boolean
}
/** `Unsubscribe { room_id }` (frames.rs:14-16). */
export interface WsUnsubscribeFrame {
op: 'unsubscribe'
room_id: string
}
/**
* `Resync { room_id, after_seq }`. The reply is a `history` frame built with
* `seq > after_seq` ordered **ascending** (ws/mod.rs:505-531 +
* services/messages.rs:677-687), i.e. it walks forward from the cursor and is
* truncated at `history_limit`; `resync(room, 0)` therefore returns the *oldest*
* messages of the room, not the newest.
*/
export interface WsResyncFrame {
op: 'resync'
room_id: string
after_seq: number
}
/**
* `Typing { room_id, thread_id }`. Requires read access, is throttled to one
* broadcast per 3s per socket, and is re-broadcast to the room as
* `event{kind:'typing'}` (ws/mod.rs:533-549).
*/
export interface WsTypingFrame {
op: 'typing'
room_id: string
thread_id?: string | null
}
/** `Ping` -> the server answers `{type:'pong'}` (frames.rs:26, ws/mod.rs:550-552). */
export interface WsPingFrame {
op: 'ping'
}
export type ClientFrame = WsSubscribeFrame | WsUnsubscribeFrame | WsResyncFrame | WsTypingFrame | WsPingFrame
/* --------------------------------------------------------------------------
* Message / reaction payloads
* ------------------------------------------------------------------------ */
/**
* `MessageDto` (frames.rs:45 for `history`, realtime.rs:25/30 for events).
* Aliased to the generated type so it stays in sync with `bun run gen:api`.
*
* IMPORTANT: the backend serialises this DTO from the **actor's** point of view
* (`build_message_dto(.., caller)` — messages.rs:557-561 for publishes,
* :864-870 for edits, unfurl.rs:319-332 even uses `Uuid::nil()`), so per-viewer
* fields such as `reactions[].me` must not be trusted from a WS frame. The
* backend proves it knows this by stripping `me` from `reaction_updated`
* (services/reactions.rs:148-156).
*/
export type WsMessage = MessageDto
/** Viewer-neutral reaction aggregate sent by `reaction_updated`. */
export interface WsReactionSummary {
emoji: string
count: number
}
/* --------------------------------------------------------------------------
* Room broadcasts (`event` frames) (share/realtime.rs:19-74)
* ------------------------------------------------------------------------ */
export const WS_ROOM_EVENT_KINDS = [
'message_published',
'message_edited',
'message_deleted',
'messages_deleted',
'message_pinned',
'reaction_updated',
'typing',
'voice_presence',
'voice_hands',
'voice_layout',
'voice_moderation',
'room_updated',
'member_joined',
'member_left',
'thread_updated',
] as const
/**
* The 11 `RoomEvent` variants. `seq` exists on exactly the five `message*`
* variants (realtime.rs:103-110): `message_published` allocates a fresh room seq
* (`next_room_seq`, notify.rs:17-33) while edits/pins/deletes reuse the *current
* tip* (`current_room_seq`, notify.rs:37-45) so they never inflate unread
* counters or reorder listings. `reaction_updated` has no seq at all.
*/
export type RoomEvent =
| { kind: 'message_published'; room_id: string; seq: number; message: WsMessage }
| { kind: 'message_edited'; room_id: string; seq: number; message: WsMessage }
| { kind: 'message_deleted'; room_id: string; seq: number; message_id: string }
| { kind: 'messages_deleted'; room_id: string; seq: number; message_ids: string[] }
| {
kind: 'message_pinned'
room_id: string
seq: number
message_id: string
pinned: boolean
}
| {
kind: 'reaction_updated'
room_id: string
message_id: string
reactions: WsReactionSummary[]
}
| {
kind: 'typing'
room_id: string
user_id: string
thread_id: string | null
/** Discard the indicator this many seconds after it was seen. */
ttl_secs: number
}
| { kind: 'voice_presence'; room_id: string }
| { kind: 'voice_hands'; room_id: string }
| { kind: 'voice_layout'; room_id: string }
| { kind: 'voice_moderation'; room_id: string; user_id: string; action: string }
| { kind: 'room_updated'; room_id: string }
| { kind: 'member_joined'; room_id: string; user_id: string }
| { kind: 'member_left'; room_id: string; user_id: string }
| { kind: 'thread_updated'; room_id: string; thread_id: string }
/**
* Finite-number read for seq comparisons: a `seq` that is not a JSON number must
* never enter a cursor, because `NaN` would break every later comparison.
*/
export function asSeq(value: unknown): number | undefined {
return typeof value === 'number' && Number.isFinite(value) ? value : undefined
}
/** Typing payload for the client-side registry (TTL already resolved to ms). */
export interface WsTypingIndicator {
room_id: string
user_id: string
thread_id: string | null
/** `Date.now()` based expiry stamp. */
expires_at: number
/** `Date.now()` stamp of the last refresh (indicators are refreshed, not re-added). */
updated_at: number
}
/** `RoomEvent::seq` when the variant carries one (realtime.rs:103-110). */
export function roomEventSeq(event: RoomEvent | null | undefined): number | undefined {
if (!event) return undefined
if (!('seq' in event)) return undefined
// Guard against drift: a non-numeric seq would poison every cursor comparison.
return asSeq(event.seq)
}
/* --------------------------------------------------------------------------
* Per-user pushes (`user_event` frames)
* ------------------------------------------------------------------------ */
export const WS_USER_EVENT_KINDS = [
'mention',
'presence',
'read_marker',
'reminder',
'room_added',
'notification',
] as const
/**
* The six payloads published on `chat:user:<uid>` (realtime.rs:15-17). They are
* hand-built `json!` objects, not a Rust enum, so this union is the only typed
* description of them:
* - `mention`: one-arg form per direct mention (messages.rs:591-596 and the edit
* path messages.rs:881-887); `everyone: true` only on the @everyone fanout
* (notify.rs:231-237).
* - `presence`: published to the acting user only (presence.rs:94-99), so it
* mirrors *your* status across tabs — a teammate's presence still has to come
* from `GET /chat/spaces/{space_name}/presences`.
* - `read_marker`: only when the marker actually advanced, and
* `last_read_message_id` is `null` when room-level state was advanced without a
* message id (read_state.rs:86-98 + notify.rs:301-326).
* - `reminder`: fired by the reminder worker (reminders.rs:251-258).
* - `room_added`: pushed to the user who just joined a room, next to the room's
* `member_joined` broadcast (rooms.rs:656-666).
* - `notification`: one row of `user_notifications` written by any crate
* (chat mentions/reminders/invites, issue replies/assignments, space invites);
* `export::notify::notification_event_json` wraps `Model::to_event_value()`,
* which mirrors the `GET /me/notifications` DTO field-for-field.
*/
export type UserEvent =
| { kind: 'mention'; room_id: string; message_id: string; everyone?: boolean }
| { kind: 'presence'; status: PresenceStatus }
| {
kind: 'read_marker'
room_id: string
last_read_message_id: string | null
last_read_seq: number
}
| { kind: 'reminder'; room_id: string; message_id: string }
| { kind: 'room_added'; room_id: string }
| { kind: 'notification'; notification: WsNotification }
/** The embedded payload of a `notification` user event (`Model::to_event_value`). */
export interface WsNotification {
id: string
notification_type: NotificationType
title: string
body: string | null
data: unknown
actor_id: string | null
read_at: string | null
created_at: string
}
export function isNotificationUserEvent(event: UserEvent): event is {
kind: 'notification'
notification: WsNotification
} {
return event.kind === 'notification'
}
/* --------------------------------------------------------------------------
* Server -> client frames (ws/frames.rs:29-63)
* ------------------------------------------------------------------------ */
export const WS_SERVER_FRAME_TYPES = [
'ready',
'event',
'user_event',
'history',
'gap',
'resync_required',
'error',
'pong',
'bye',
] as const
/** `resync_required.reason`; the backend uses a plain `String` (frames.rs:52-55). */
export const WS_RESYNC_REASONS = ['lagged', 'access revoked'] as const
/** `error.message`; plain `String` with four fixed producers (see below). */
export const WS_ERROR_MESSAGES = [
'invalid frame', // ws/mod.rs:256-260 - JSON did not deserialize as ClientFrame
'subscription limit reached', // ws/mod.rs:410-419 - max_subscriptions per socket
'forbidden', // ws/mod.rs:420-429 - require_room_readable failed
'subscribe failed', // ws/mod.rs:430-442 - redis pubsub subscribe failed
] as const
/** `bye.message`; sent right before a server-initiated close (ws/mod.rs:577-587). */
export const WS_BYE_MESSAGES = [
'internal error', // ws/mod.rs:183-188 - user channel subscribe failed
'idle timeout', // ws/mod.rs:310-315 - silent for heartbeat_secs * 3
] as const
/**
* Literal union kept for autocomplete, widened so a backend that adds a new
* reason/message cannot break the client's types.
*/
type OpenString<T extends readonly string[]> = T[number] | (string & Record<never, never>)
export type WsResyncReason = OpenString<typeof WS_RESYNC_REASONS>
export type WsErrorMessage = OpenString<typeof WS_ERROR_MESSAGES>
export type WsByeMessage = OpenString<typeof WS_BYE_MESSAGES>
/**
* The 9 `ServerFrame` variants. `event` is typed `| null` on purpose: the server
* holds it as `serde_json::Value` and substitutes `Value::Null` when the redis
* payload cannot be parsed (frames.rs:36-41, ws/mod.rs:279-283,299-305).
*/
export type ServerFrame =
/** First frame after the upgrade; `session_id` is a fresh v7 uuid per socket. */
| { type: 'ready'; user_id: string; session_id: string }
| { type: 'event'; room_id: string; event: RoomEvent | null }
| { type: 'user_event'; event: UserEvent | null }
| { type: 'history'; room_id: string; messages: WsMessage[] }
/** Stream order broke: messages `from..to` were dropped (ws/mod.rs:366-387). */
| { type: 'gap'; room_id: string; from: number; to: number }
| { type: 'resync_required'; room_id: string; reason: WsResyncReason }
| { type: 'error'; message: WsErrorMessage }
| { type: 'pong' }
| { type: 'bye'; message: WsByeMessage }
/** Coarse classification of `error.message` (the frame carries no room_id). */
export type WsServerErrorKind = 'invalid_frame' | 'subscription_limit' | 'forbidden' | 'subscribe_failed' | 'unknown'
export function classifyWsError(message: string): WsServerErrorKind {
switch (message) {
case 'invalid frame':
return 'invalid_frame'
case 'subscription limit reached':
return 'subscription_limit'
case 'forbidden':
return 'forbidden'
case 'subscribe failed':
return 'subscribe_failed'
default:
return 'unknown'
}
}
/** Errors that can only be produced by a `subscribe` frame (best-effort attribution). */
export function isSubscribeError(kind: WsServerErrorKind): boolean {
return kind === 'forbidden' || kind === 'subscription_limit' || kind === 'subscribe_failed'
}
/* --------------------------------------------------------------------------
* Runtime parsing
* ------------------------------------------------------------------------ */
/**
* Validate a parsed JSON value as a `ServerFrame`.
*
* Unknown `type` discriminants return `null` so callers can surface drift
* instead of casting it into the union. `event` / `user_event` payloads that are
* `null` or lack a string `kind` are normalised to `event: null`, which is the
* same state the backend produces for an unparseable redis payload.
*/
export function asServerFrame(value: unknown): ServerFrame | null {
if (typeof value !== 'object' || value === null) return null
const candidate = value as Record<string, unknown>
if (typeof candidate.type !== 'string') return null
if (!WS_SERVER_FRAME_TYPES.includes(candidate.type as (typeof WS_SERVER_FRAME_TYPES)[number])) {
return null
}
if (candidate.type === 'history' && !Array.isArray(candidate.messages)) return null
if (candidate.type === 'event' || candidate.type === 'user_event') {
const event = candidate.event
if (typeof event !== 'object' || event === null || typeof (event as { kind?: unknown }).kind !== 'string') {
return { ...candidate, type: candidate.type, event: null } as unknown as ServerFrame
}
}
return value as ServerFrame
}
/**
* Parse one inbound frame. The backend only ever writes text frames
* (`Message::Text`, ws/mod.rs:566-575), so non-string payloads are rejected.
*/
export function parseServerFrame(data: unknown): ServerFrame | null {
if (typeof data !== 'string') return null
let parsed: unknown
try {
parsed = JSON.parse(data)
} catch {
return null
}
return asServerFrame(parsed)
}