bridge

type BoundedUUIDSet struct {
	// contains filtered or unexported fields
}

type BridgeConfig struct {
	// MaxMessageSize 是客户端单条消息的最大字节数,默认 1MB.
	// 防止恶意客户端发送超大 prompt 打爆服务器内存.
	MaxMessageSize int64

	// EventBufferSize 是出方向事件 channel 的缓冲大小,默认 256.
	// 精妙之处(CLEVER): 缓冲不能太大(内存浪费)也不能太小(背压传播太快).
	// 256 事件 × ~500 字节/事件 ≈ 128KB,是合理的上限.
	EventBufferSize int

	// PingInterval 是 keepalive ping 的发送间隔,默认 15s.
	// SSE 的 HTTP 连接可能被代理或负载均衡的 idle timeout 强制关闭.
	// 定期 ping(SSE 注释行 ": ping")维持连接活跃.
	PingInterval time.Duration

	// WriteTimeout 是单次写操作的超时,默认 10s.
	// 防止慢客户端导致 goroutine 泄漏(连接半死不活).
	WriteTimeout time.Duration

	// ResumeWindow 是断线重连时可以重放的最大事件数,默认 1000.
	// 超出 window 的旧事件不再重放(客户端需要重新加载完整状态).
	ResumeWindow int
}

type BridgeError struct {
	Code    string // 机器可读错误码
	Message string // 人类可读描述
}

type BridgeEvent struct {
	// ID 是事件的唯一递增 ID,用于 SSE Last-Event-ID 断线重连.
	// 格式:"<session_id>-<seq>",在 SessionConn 实现层生成.
	ID string `json:"id"`

	// Type 是事件类型名,对应 engine.Event.eventType().
	// 例如:"text_delta","tool_use","permission_request","done".
	Type string `json:"type"`

	// SessionID 标识事件所属的会话.
	// 在多路复用场景(单 WebSocket 连接承载多会话)中必须有.
	SessionID string `json:"session_id"`

	// Payload 是具体事件的 JSON 数据,由 EventSerializer 填充.
	Payload json.RawMessage `json:"payload,omitempty"`

	// Timestamp 是事件生成的时间,便于客户端排序和去重.
	Timestamp time.Time `json:"ts"`
}

type BridgeTransport interface {
	http.Handler

	// Accept 返回新建立的客户端连接 channel.
	// Channel 在 Close() 被调用后关闭.
	// 调用方应持续从 channel 读取,否则新连接请求会阻塞.
	Accept() <-chan SessionConn

	// Close 关闭传输层,拒绝新连接,等待现有连接优雅关闭.
	Close() error
}

type ClientMessage struct {
	// Type 指定消息类型.
	Type ClientMessageType `json:"type"`

	// SessionID 指定目标会话.在多路复用模式下必须有.
	SessionID string `json:"session_id"`

	// Prompt 是用户输入文本(仅 TypePrompt 有效).
	Prompt string `json:"prompt,omitempty"`

	// RequestID 是权限请求 ID(仅 TypePermissionReply 有效).
	// 对应 engine.PermissionRequestEvent.ID.
	RequestID string `json:"request_id,omitempty"`

	// Allow 是权限决策(仅 TypePermissionReply 有效).
	Allow bool `json:"allow,omitempty"`
}

type ClientMessageType string

type EventSerializer struct {
	// contains filtered or unexported fields
}

type SerialBatchEventUploader struct {
	// contains filtered or unexported fields
}

type SessionConn interface {
	// SessionID 返回此连接绑定的会话 ID.
	SessionID() string

	// Send 将事件推送给客户端.
	// 如果连接已断开,返回 ErrConnClosed.
	// 实现层负责序列化为协议格式(SSE data: 行,WS binary frame 等).
	Send(ctx context.Context, evt BridgeEvent) error

	// Recv 返回客户端消息的只读 channel.
	// Channel 在连接断开时关闭.
	Recv() <-chan ClientMessage

	// Done 返回连接终止信号 channel.
	// 客户端断开 OR 服务端主动 Close() 时关闭.
	Done() <-chan struct{}

	// Close 主动终止连接(服务端触发,如 idle timeout,daemon shutdown).
	// 幂等,多次调用安全.
	Close() error
}

type UploadFunc func(ctx context.Context, events []BridgeEvent) error