transport

type BindingContext interface {
	Bind(obj any) error
	BindJSON(obj any) error
	BindQuery(obj any) error
}

type Context interface {
	RequestContext
	BindingContext
	ResponseContext
	MiddlewareContext
	RouteContext
}

type GINEngineProvider interface {
	GINEngine() any
}

type GRPCConnFactory interface {
	// Conn returns the client connection of the target service.
	//
	// Conn 返回目标服务的客户端连接。
	Conn(ctx context.Context, service string) (*grpc.ClientConn, error)
}

type GRPCServerRegistrar interface {
	// RegisterProto registers a proto service against the underlying gRPC server.
	//
	// RegisterProto 将 proto 服务注册到底层 gRPC server 上。
	RegisterProto(func(server *grpc.Server) error) error

	// Server returns the underlying gRPC server.
	//
	// Server 返回底层 gRPC server。
	Server() *grpc.Server
}

type HTTP interface {
	// Router returns the framework HTTP router facade.
	//
	// Router 返回框架 HTTP 路由门面。
	Router() Router

	// Server returns the underlying net/http server.
	//
	// Server 返回底层 net/http server。
	Server() *http.Server

	// Run starts serving HTTP traffic.
	//
	// Run 启动 HTTP 流量服务。
	Run() error

	// Shutdown gracefully stops the HTTP service.
	//
	// Shutdown 优雅关闭 HTTP 服务。
	Shutdown(ctx context.Context) error

	// UseGlobal 注册全局级中间件，对所有路由生效。
	// 语义等同于 Gin 的 engine.Use()，区别于 Router.Use() 的组级语义。
	// 全局中间件在框架治理中间件之后、路由组中间件之前执行。
	//
	// UseGlobal registers global-level middleware that applies to all routes.
	// Semantically equivalent to Gin's engine.Use(), distinct from Router.Use() which is group-level.
	// Global middleware executes after framework governance middleware and before group-level middleware.
	UseGlobal(middleware ...Middleware)
}

type HTTPResponder interface {
	Success(Context, any)
	SuccessWithMessage(Context, string, any)
	SuccessWithStatus(Context, int, any)
	Error(Context, error)
	BadRequest(Context, string)
	InternalError(Context, string)
}

type Handler func(Context)

type Metadata interface {
	Get(key string) string
	Values(key string) []string
	Set(key, value string)
	Add(key, value string)
	Del(key string)
	Range(f func(key string, values []string) bool)
	Clone() Metadata
	ToMap() map[string][]string
}

type MetadataCarrier interface {
	Get(key string) string
	Set(key, value string)
	Add(key, value string)
	Keys() []string
	Values(key string) []string
}

type MetadataConfig struct {
	PropagatePrefix  []string          `mapstructure:"propagate_prefix"`
	ConstantMetadata map[string]string `mapstructure:"constant_metadata"`
	MaxSize          int               `mapstructure:"max_size"`
}

type MetadataPropagator interface {
	Inject(ctx context.Context, carrier MetadataCarrier)
	Extract(ctx context.Context, carrier MetadataCarrier) context.Context
}

type Middleware func(next Handler) Handler

type MiddlewareContext interface {
	Get(key string) (any, bool)
	Set(key string, value any)
	Abort(status int)
	AbortWithJSON(status int, body any)
	IsAborted() bool
	Next()
}

type MiddlewareFunc func(ctx Context, next Handler)

type MiddlewareRegistry interface {
	// Register adds a named middleware to the registry.
	// If a middleware with the same name already exists, it is replaced.
	// Common names: "auth", "authz", "logging", "ratelimit", "cors".
	//
	// Register 向注册表添加具名中间件。
	// 如果同名中间件已存在，则替换。
	// 常用名称："auth"、"authz"、"logging"、"ratelimit"、"cors"。
	Register(name string, middleware Middleware)

	// Lookup retrieves a middleware by name.
	// Returns the middleware and true if found, nil and false otherwise.
	//
	// Lookup 按名称查找中间件。
	// 找到时返回中间件和 true，否则返回 nil 和 false。
	Lookup(name string) (Middleware, bool)

	// LookupAll retrieves multiple middleware by names.
	// Returns found middleware in order; silently skips unknown names.
	//
	// LookupAll 按名称列表查找多个中间件。
	// 按顺序返回找到的中间件；静默跳过未知名称。
	LookupAll(names []string) []Middleware

	// Names returns all registered middleware names.
	//
	// Names 返回所有已注册的中间件名称。
	Names() []string
}

type RPCClient interface {
	Call(ctx context.Context, service, method string, req, resp any) error
	CallRaw(ctx context.Context, service, method string, data []byte) ([]byte, error)
	Close() error
}

type RPCClientMiddleware func(next RPCInvoker) RPCInvoker

type RPCConfig struct {
	Mode string `mapstructure:"mode"`

	Registry string `mapstructure:"registry"`
	Address  string `mapstructure:"address"`

	BaseURL string `mapstructure:"base_url"`

	Target    string `mapstructure:"target"`
	Insecure  bool   `mapstructure:"insecure"`
	TimeoutMS int    `mapstructure:"timeout_ms"`
}

type RPCInvoker func(ctx context.Context, service, method string, req, resp any) error

type RPCServer interface {
	Register(service string, handler any) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Addr() string
}

type RequestContext interface {
	// Context 返回标准 context.Context。
	// 用于 context.WithTimeout/context.WithCancel/context.WithValue 等场景。
	// 实现层应返回 Request().Context()，确保只返回纯标准 context，不再回包到 RequestContext。
	Context() context.Context

	// Request/Response
	Request() *http.Request
	Response() http.ResponseWriter

	// Route params
	Param(key string) string

	// Query params
	Query(key string) string
	DefaultQuery(key, defaultValue string) string
	DefaultIntQuery(key string, defaultValue int) int

	// Typed param parsing
	Int64Param(key string) (int64, error)

	// File upload
	FormFile(name string) (multipart.File, *multipart.FileHeader, error)
	SaveUploadedFile(file *multipart.FileHeader, dst string) error

	// Headers
	GetHeader(key string) string
	SetHeader(key, value string)
}

type ResponseContext interface {
	JSON(status int, body any)
	String(status int, body string)
	XML(status int, body any)
	Data(status int, contentType string, body []byte)
	Redirect(status int, location string)
	Status(code int)
}

type RouteContext interface {
	RoutePath() string
	ResponseStatus() int
}

type Router interface {
	Use(middleware ...Middleware)
	Group(prefix string, middleware ...Middleware) Router

	// Handle 为指定 method 和 path 注册路由处理器，可选挂载接口级中间件。
	// middleware 只对该路由端点生效，不影响其他路由。
	//
	// Handle registers a route handler for the given method and path,
	// with optional interface-level middleware that applies only to this route.
	Handle(method, path string, handler Handler, middleware ...Middleware)

	// HandleFunc 是 Handle 的函数式别名，支持可选接口级中间件。
	//
	// HandleFunc is a function-style alias for Handle with optional interface-level middleware.
	HandleFunc(method, path string, handlerFunc Handler, middleware ...Middleware)

	// GET 注册 GET 路由处理器，可选挂载接口级中间件。
	// 示例：GET("/users", listUsers) 或 GET("/users", listUsers, authMW)
	//
	// GET registers a GET route handler with optional interface-level middleware.
	GET(path string, handler Handler, middleware ...Middleware)

	// POST 注册 POST 路由处理器，可选挂载接口级中间件。
	//
	// POST registers a POST route handler with optional interface-level middleware.
	POST(path string, handler Handler, middleware ...Middleware)

	// PUT 注册 PUT 路由处理器，可选挂载接口级中间件。
	//
	// PUT registers a PUT route handler with optional interface-level middleware.
	PUT(path string, handler Handler, middleware ...Middleware)

	// DELETE 注册 DELETE 路由处理器，可选挂载接口级中间件。
	//
	// DELETE registers a DELETE route handler with optional interface-level middleware.
	DELETE(path string, handler Handler, middleware ...Middleware)

	Mount(path string, handler http.Handler)
}

type ServiceInstance struct {
	ID       string
	Name     string
	Address  string
	Metadata map[string]string
	Healthy  bool
}

type ServiceRegistry interface {
	Register(ctx context.Context, name, addr string, meta map[string]string) error
	Deregister(ctx context.Context, name, addr string) error
	Discover(ctx context.Context, name string) ([]ServiceInstance, error)
	Close() error
}

type WebSocketBroadcaster interface {
	// BroadcastString sends a text message to all connections.
	// BroadcastString 向所有连接发送文本消息。
	BroadcastString(message string) error

	// BroadcastBinary sends a binary message to all connections.
	// BroadcastBinary 向所有连接发送二进制消息。
	BroadcastBinary(data []byte) error

	// BroadcastStringExcept sends a text message to all connections except the specified one.
	// BroadcastStringExcept 向除指定连接外的所有连接发送文本消息。
	BroadcastStringExcept(message string, excludeConn WebSocketConn) error

	// BroadcastBinaryExcept sends a binary message to all connections except the specified one.
	// BroadcastBinaryExcept 向除指定连接外的所有连接发送二进制消息。
	BroadcastBinaryExcept(data []byte, excludeConn WebSocketConn) error
}

type WebSocketClient interface {
	// Conn returns the underlying connection.
	// Conn 返回底层连接。
	Conn() WebSocketConn

	// Close closes the client connection.
	// Close 关闭客户端连接。
	Close() error

	// WriteString sends a text message to the server.
	// WriteString 发送文本消息到服务器。
	WriteString(message string) error

	// WriteBinary sends a binary message to the server.
	// WriteBinary 发送二进制消息到服务器。
	WriteBinary(data []byte) error
}

type WebSocketClientConfig struct {
	// Server URL (ws:// or wss://).
	// 服务器 URL（ws:// 或 wss://）。
	URL string

	// Enable compression (permessage-deflate).
	// 启用压缩（permessage-deflate）。
	EnableCompression bool

	// Compression level (1-9, default 6).
	// 压缩级别（1-9，默认 6）。
	CompressionLevel int

	// Max message size in bytes (default 0 = unlimited).
	// 最大消息大小（字节），默认 0 表示无限制。
	MaxMessageSize int64

	// Read buffer size in bytes (default 4096).
	// 读缓冲区大小（字节），默认 4096。
	ReadBufferSize int

	// Write buffer size in bytes (default 4096).
	// 写缓冲区大小（字节），默认 4096。
	WriteBufferSize int

	// Handshake timeout in seconds (default 10).
	// 握手超时（秒），默认 10。
	HandshakeTimeout int

	// Request headers to send during handshake.
	// 握手时发送的请求头。
	RequestHeader http.Header
}

type WebSocketClusterConfig struct {
	// Enable cluster mode.
	// 启用集群模式。
	Enabled bool

	// Node ID for this instance (auto-generated if empty).
	// 本实例的节点 ID（为空则自动生成）。
	NodeID string

	// Redis address for Pub/Sub (e.g., "localhost:6379").
	// Redis Pub/Sub 地址（如 "localhost:6379"）。
	RedisAddr string

	// Redis password.
	// Redis 密码。
	RedisPassword string

	// Redis database number.
	// Redis 数据库编号。
	RedisDB int

	// Pub/Sub channel name prefix (default "gorp:ws").
	// Pub/Sub 通道名称前缀（默认 "gorp:ws"）。
	ChannelPrefix string

	// Enable global connection count tracking.
	// 启用全局连接数统计。
	EnableGlobalCount bool

	// Connection count key prefix (default "gorp:ws:count").
	// 连接数统计键前缀（默认 "gorp:ws:count"）。
	CountKeyPrefix string

	// Heartbeat interval for node health (seconds, default 30).
	// 节点健康心跳间隔（秒，默认 30）。
	HeartbeatInterval int
}

type WebSocketClusterServer interface {
	WebSocketServer

	// BroadcastGlobal broadcasts message to all nodes in the cluster.
	// BroadcastGlobal 向集群所有节点广播消息。
	BroadcastGlobal(message string) error

	// BroadcastGlobalBinary broadcasts binary message to all nodes in the cluster.
	// BroadcastGlobalBinary 向集群所有节点广播二进制消息。
	BroadcastGlobalBinary(data []byte) error

	// BroadcastToRoom broadcasts message to a room across all nodes.
	// BroadcastToRoom 向房间广播消息（跨节点）。
	BroadcastToRoom(roomID string, message string) error

	// GlobalCount returns total connection count across all nodes.
	// GlobalCount 返回所有节点的总连接数。
	GlobalCount() int

	// NodeCount returns connection count for a specific node.
	// NodeCount 返回指定节点的连接数。
	NodeCount(nodeID string) int

	// ListNodes returns all active node IDs.
	// ListNodes 返回所有活跃节点 ID。
	ListNodes() []string

	// GetNodeID returns this node's ID.
	// GetNodeID 返回本节点 ID。
	GetNodeID() string
}

type WebSocketConfig struct {
	// Enable compression (permessage-deflate).
	// 启用压缩（permessage-deflate）。
	EnableCompression bool

	// Compression level (1-9, default 6).
	// 压缩级别（1-9，默认 6）。
	CompressionLevel int

	// Max message size in bytes (default 0 = unlimited).
	// 最大消息大小（字节），默认 0 表示无限制。
	MaxMessageSize int64

	// Read buffer size in bytes (default 4096).
	// 读缓冲区大小（字节），默认 4096。
	ReadBufferSize int

	// Write buffer size in bytes (default 4096).
	// 写缓冲区大小（字节），默认 4096。
	WriteBufferSize int

	// ParallelEnabled enables parallel message processing.
	// 启用并行消息处理。
	ParallelEnabled bool

	// ParallelGolimit is the max goroutines for parallel processing (default runtime.NumCPU).
	// 并行处理的最大 goroutine 数，默认 runtime.NumCPU。
	ParallelGolimit int

	// ReadTimeout sets the maximum duration for reading a message.
	// Connections that exceed this timeout will be closed automatically.
	// Default 0 means no timeout.
	// 读超时，超过此时间的连接将被自动关闭。默认 0 表示无超时。
	ReadTimeout time.Duration

	// WriteTimeout sets the maximum duration for writing a message.
	// Default 0 means no timeout.
	// 写超时。默认 0 表示无超时。
	WriteTimeout time.Duration
}

type WebSocketConn interface {
	// WriteString sends a text message to the client.
	// WriteString 发送文本消息到客户端。
	WriteString(message string) error

	// WriteBinary sends a binary message to the client.
	// WriteBinary 发送二进制消息到客户端。
	WriteBinary(data []byte) error

	// Close closes the connection with a close code and reason.
	// Close 关闭连接，可指定关闭码和原因。
	Close(code int, reason string) error

	// Context returns the context associated with the connection.
	// Context 返回与连接关联的上下文。
	Context() context.Context

	// SetContext sets the context for the connection.
	// SetContext 设置连接的上下文。
	SetContext(ctx context.Context)

	// RemoteAddr returns the remote address of the connection.
	// RemoteAddr 返回连接的远程地址。
	RemoteAddr() string

	// LocalAddr returns the local address of the connection.
	// LocalAddr 返回连接的本地地址。
	LocalAddr() string

	// RawConn returns the underlying raw connection for advanced usage.
	// The returned value is the underlying library's connection type.
	// Use with caution - bypassing the abstraction may break framework guarantees.
	//
	// RawConn 返回底层原生连接供高级使用。
	// 返回值是底层库的连接类型。
	// 请谨慎使用 - 绕过抽象层可能破坏框架保证。
	RawConn() any
}

type WebSocketHandler interface {
	// OnOpen is called when a new connection is established.
	// OnOpen 在新连接建立时调用。
	OnOpen(conn WebSocketConn)

	// OnClose is called when a connection is closed.
	// OnClose 在连接关闭时调用。
	OnClose(conn WebSocketConn, err error)

	// OnMessage is called when a message is received.
	// OnMessage 在收到消息时调用。
	OnMessage(conn WebSocketConn, messageType int, data []byte)
}

type WebSocketServer interface {
	// Upgrade upgrades an HTTP connection to WebSocket.
	// Upgrade 将 HTTP 连接升级为 WebSocket。
	Upgrade(w http.ResponseWriter, r *http.Request, handler WebSocketHandler) (WebSocketConn, error)

	// NewBroadcaster creates a new broadcaster for batch message sending.
	// NewBroadcaster 创建新的广播器用于批量消息发送。
	NewBroadcaster() WebSocketBroadcaster

	// Connections returns all active connections.
	// Connections 返回所有活跃连接。
	Connections() []WebSocketConn

	// Count returns the number of active connections.
	// Count 返回活跃连接数量。
	Count() int

	// Shutdown gracefully closes all connections.
	// Shutdown 优雅关闭所有连接。
	Shutdown(ctx context.Context) error
}