rpc

type ContextMeta struct {
	// Principal 调用主体(身份 + 能力)。新身份模型的权威来源,由身份识别层统一构建。
	// Permission 字段保留用于向后兼容,等价于 Principal.PrimaryRole()。
	Principal *Principal

	// Permission 当前权限分组 guest/client/admin
	Permission string
	// User 登录的管理员用户（仅 admin 会话存在）
	User *UserInfo
	// UserUUID 方便无需解引用就能快速判断
	UserUUID string
	// ClientToken 来自客户端的私钥 / 鉴权 token（仅 client 链接可能存在）
	ClientToken string
	// ClientUUID 解析出的客户端 UUID（若 token 合法）
	ClientUUID string
	// SessionToken 当前管理员会话的 session token（仅 admin 会话存在，用于区分当前会话等场景）
	SessionToken string
	// RemoteIP 请求来源 IP（可选）
	RemoteIP string
	// UserAgent 请求 UA（可选）
	UserAgent string
	// TempShareValid 临时分享访问许可是否有效（基于 temp_key cookie 校验，由传输层填充）
	TempShareValid bool
}

type Handler func(ctx context.Context, req *JsonRpcRequest) (any, *JsonRpcError)

type JsonRpcError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

type JsonRpcRequest struct {
	Version string `json:"jsonrpc"`          // 必须 === "2.0"
	Method  string `json:"method"`           // 方法名；以 "rpc." 前缀的为保留内部方法
	Params  any    `json:"params,omitempty"` // 参数(位置数组或命名对象)
	ID      any    `json:"id,omitempty"`     // 字符串 / 数值 / null；Notification 时省略
}

type JsonRpcResponse struct {
	Version string        `json:"jsonrpc"`
	ID      any           `json:"id,omitempty"`
	Result  any           `json:"result,omitempty"`
	Error   *JsonRpcError `json:"error,omitempty"`
}

type MethodMeta struct {
	Name        string      `json:"name"`
	Summary     string      `json:"summary,omitempty"`
	Description string      `json:"description,omitempty"`
	Params      []ParamMeta `json:"params,omitempty"`
	Returns     string      `json:"returns,omitempty"`
	Example     any         `json:"example,omitempty"`
}

type ParamMeta struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Required    bool   `json:"required,omitempty"`
	Description string `json:"description,omitempty"`
}

type Principal struct {
	// Type 主体类型
	Type PrincipalType
	// UserUUID 用户 UUID(PrincipalUser 时存在)
	UserUUID string
	// ClientUUID agent 客户端 UUID(PrincipalAgent 时存在)
	ClientUUID string
	// IsAPIKey 是否为 API Key 调用(快速判定,等价于 Type==PrincipalAPIKey)
	IsAPIKey bool
	// Roles 角色/能力集。默认由 Type 推导:
	//   - PrincipalAnonymous → [RoleGuest]
	//   - PrincipalAgent → [RoleClient]
	//   - PrincipalUser / PrincipalAPIKey → [RoleAdmin]
	// 未来可扩展为多角色(只读 admin / API Key scope 等)。
	Roles []string
}

type PrincipalType int

type UserInfo struct {
	UUID             string
	Username         string
	SSOType          string
	SSOID            string
	TwoFactorEnabled bool
}