gate

type Authenticator = generic.Delegate5[IGate, net.Conn, string, string, []byte, error]

type GateOptions struct {
	TCPAddress                     string                 // TCPAddress 是 TCP 监听地址；空字符串禁用 TCP。
	TCPNoDelay                     *bool                  // TCPNoDelay 为 nil 时沿用系统默认值。
	TCPQuickAck                    *bool                  // TCPQuickAck 为 nil 时沿用系统默认值。
	TCPRecvBuf                     *int                   // TCPRecvBuf 是接收缓冲区字节数；nil 沿用系统默认值。
	TCPSendBuf                     *int                   // TCPSendBuf 是发送缓冲区字节数；nil 沿用系统默认值。
	TCPLinger                      *int                   // TCPLinger 是关闭等待秒数；nil 沿用系统默认值。
	TCPTLSConfig                   *tls.Config            // TCPTLSConfig 非 nil 时为 TCP 监听启用 TLS。
	WebSocketURL                   *url.URL               // WebSocketURL 是监听 URL；nil 禁用 WebSocket。
	WebSocketTLSConfig             *tls.Config            // WebSocketTLSConfig 用于 https/wss 监听。
	WebSocketLocalAddrResolver     WebSocketAddrResolver  // WebSocketLocalAddrResolver 解析服务端地址。
	WebSocketRemoteAddrResolver    WebSocketAddrResolver  // WebSocketRemoteAddrResolver 解析客户端地址。
	IOTimeout                      time.Duration          // IOTimeout 是单次网络 I/O 的超时。
	IORetryTimes                   int                    // IORetryTimes 是 I/O 超时后的重试次数。
	IOBufferCap                    int                    // IOBufferCap 是断线重连时保留的发送数据字节上限。
	MsgCreator                     gtp.IMsgCreator        // MsgCreator 用于按消息 ID 创建 GTP 解码目标。
	AgreeClientEncryptionProposal  bool                   // AgreeClientEncryptionProposal 允许采用客户端加密提案。
	EncCipherSuite                 gtp.CipherSuite        // EncCipherSuite 是服务端首选密码套件。
	EncNonceStep                   *big.Int               // EncNonceStep 是每次加解密后的 nonce 增量。
	EncECDHENamedCurve             gtp.NamedCurve         // EncECDHENamedCurve 是 ECDHE 密钥交换曲线。
	EncSignatureAlgorithm          gtp.SignatureAlgorithm // EncSignatureAlgorithm 是握手签名算法。
	EncSignaturePrivateKey         crypto.PrivateKey      // EncSignaturePrivateKey 是服务端握手签名私钥。
	EncVerifyClientSignature       bool                   // EncVerifyClientSignature 要求验证客户端握手签名。
	EncVerifySignaturePublicKey    crypto.PublicKey       // EncVerifySignaturePublicKey 是客户端签名验证公钥。
	AgreeClientCompressionProposal bool                   // AgreeClientCompressionProposal 允许采用客户端压缩提案。
	Compression                    gtp.Compression        // Compression 是服务端首选压缩算法。
	CompressionThreshold           int                    // CompressionThreshold 是启用压缩的字节阈值；小于等于 0 时禁用。
	MaxUncompressedSize            int                    // MaxUncompressedSize 限制解压后负载，防御压缩炸弹。
	MaxPacketSize                  int                    // MaxPacketSize 限制单个 GTP 包大小。
	AcceptTimeout                  time.Duration          // AcceptTimeout 是握手完成前的最长等待时间。
	Authenticator                  Authenticator          // Authenticator 校验客户端凭据；nil 表示不额外鉴权。
	SessionInactiveTimeout         time.Duration          // SessionInactiveTimeout 是断线后等待连接迁移的时间。
	SessionWatcherInboxSize        int                    // SessionWatcherInboxSize 是每个会话观察器的收件箱容量。
	SessionDataListenerInboxSize   int                    // SessionDataListenerInboxSize 是每个数据监听器的收件箱容量。
	SessionEventListenerInboxSize  int                    // SessionEventListenerInboxSize 是每个事件监听器的收件箱容量。
}

type IDataIO interface {
	// Send 复制 data 并将其加入发送队列。
	Send(data []byte) error
	// Listen 注册监听器，直到 ctx 取消或会话关闭。
	Listen(ctx context.Context, handler SessionDataHandler) error
}

type IEventIO interface {
	// Send 将 event 加入发送队列；调用方须保证事件在处理完成前保持有效。
	Send(event transport.IEvent) error
	// Listen 注册监听器，直到 ctx 取消或会话关闭。
	Listen(ctx context.Context, handler SessionEventHandler) error
}

type IGate interface {
	// Get 按会话 ID 查询当前尚未过期的会话。
	Get(id uid.Id) (ISession, bool)
	// Count 返回当前会话数量。
	Count() int64
	// Watch 监听首次建立完成的会话；连接迁移成功不会重复通知。
	// 返回的 Signal 在 ctx 取消或 gate 停止后完成。
	Watch(ctx context.Context, handler SessionEstablishedHandler) (async.Signal, error)
}

type ISession interface {
	context.Context
	fmt.Stringer
	// Id 返回服务端分配的会话 ID。
	Id() uid.Id
	// UserId 返回客户端提交的鉴权用户 ID。
	UserId() string
	// Token 返回客户端提交的鉴权令牌。
	Token() string
	// Extensions 返回客户端提交的鉴权扩展数据；调用方不得修改。
	Extensions() []byte
	// State 返回当前会话状态。
	State() SessionState
	// NetAddr 返回当前连接地址快照；连接迁移后会变化。
	NetAddr() NetAddr
	// Migrations 返回连接成功迁移的累计次数。
	Migrations() int64
	// DataIO 返回原始负载 I/O 门面。
	DataIO() IDataIO
	// EventIO 返回 GTP 事件 I/O 门面。
	EventIO() IEventIO
	// Close 请求以 err 为原因关闭会话，并返回关闭完成信号。
	Close(err error) async.Signal
	// Closed 返回会话关闭完成信号。
	Closed() async.Signal
}

type NetAddr struct {
	Local, Remote net.Addr // Local 是服务端地址，Remote 是客户端地址。
}

type SessionDataHandler = generic.DelegateVoid2[ISession, []byte]

type SessionEstablishedHandler = generic.DelegateVoid1[ISession]

type SessionEventHandler = generic.DelegateVoid2[ISession, transport.IEvent]

type SessionState int32

type WebSocketAddrResolver = generic.Func1[*websocket.Conn, net.Addr]