// Package port 定义 broker 与 app 之间的契约。
//
// broker（连接 N）实现 Downlink / ConnControl；app 各模块通过这些接口下行发布或踢线。
// broker 在连接生命周期与上行帧到达时调用 UplinkHandler。
// 本包不依赖 mochi，也不包含业务状态机。
package port

import (
	"context"
)

// ConnID 是连接代号（同一端编号新旧连接 ClientID 相同，用独立代号区分）。
type ConnID string

// Transport 区分接入方式。
type Transport string

const (
	TransportTCP Transport = "tcp"
	TransportWS  Transport = "ws"
)

// ConnInfo 描述一条已建立的 MQTT 连接（登录校验通过之后）。
type ConnInfo struct {
	ConnID     ConnID
	EndpointID string
	Transport  Transport
	RemoteIP   string
	// SessionToken 非空表示本次用密码登录后新签发的令牌（握手响应里交给端）。
	SessionToken string
	// MaxPacketSize 来自 CONNECT；0 表示未声明。
	MaxPacketSize uint32
}

// HandshakeInfo 是握手完成时的补充信息。
type HandshakeInfo struct {
	ConnInfo
	MaxReceiveBytes int // 0 表示不限（仍受 MaxPacketSize 约束）
	Client          string
}

// DisconnectReason 说明断开原因，便于 app 区分当前连接与被顶号的旧连接。
type DisconnectReason string

const (
	DisconnectNormal    DisconnectReason = "normal"
	DisconnectTakenOver DisconnectReason = "taken_over"
	DisconnectKicked    DisconnectReason = "kicked"
	DisconnectFatal     DisconnectReason = "fatal"
	DisconnectIdle      DisconnectReason = "idle"
)

// UplinkHandler 由 app 实现，broker 在钩子里调用。
type UplinkHandler interface {
	// OnSessionEstablished 在 MQTT 会话建立、登录已通过后调用（握手前）。
	OnSessionEstablished(ctx context.Context, conn ConnInfo) error
	// OnHandshakeComplete 在 hello 成功处理后调用；此后该连接算在线并可推送。
	OnHandshakeComplete(ctx context.Context, hs HandshakeInfo) error
	// OnDisconnect 在连接断开时调用；是否为当前连接由 app 按 ConnID 判断。
	OnDisconnect(ctx context.Context, conn ConnInfo, reason DisconnectReason)
	// HandleUplink 处理上行应用帧原始 JSON（已从 MQTT 发布拷贝）。
	HandleUplink(ctx context.Context, conn ConnInfo, payload []byte) error
}

// PublishOpts 控制下行发布。
type PublishOpts struct {
	QoS byte // 0 或 1；msg/receipt/revoked/resp/fatal 用 1，presence/group_event 用 0
}

// Downlink 由 broker 实现，供 app 向下行主题发布。
type Downlink interface {
	// PublishDown 向 nix/c/{endpointID}/down 发布一帧。
	// connID 非空时仅在该连接仍是当前连接时发布；空表示发给该端当前连接。
	PublishDown(ctx context.Context, endpointID string, connID ConnID, payload []byte, opts PublishOpts) error
}

// ConnControl 由 broker 实现，供 app/admin 踢线或发 fatal 后断开。
type ConnControl interface {
	// Disconnect 断开指定连接；connID 为空则断开该端当前连接。
	Disconnect(ctx context.Context, endpointID string, connID ConnID, reason DisconnectReason) error
}