adapter

type AdminStorage interface {
	// Clear clears all data. Clear 清空全部数据。
	Clear(ctx context.Context) error
}

type AtomicStorage interface {
	// GetAndDelete gets and deletes key atomically. GetAndDelete 原子地读取并删除键。
	GetAndDelete(ctx context.Context, key string) (any, error)
}

type Codec interface {
	// Name returns codec name Name 返回序列化器名称
	Name() string
	// Encode encodes object to bytes Encode 将对象编码为字节数组
	Encode(v any) ([]byte, error)
	// Decode decodes bytes into target object Decode 将字节数组解码到目标对象
	Decode(data []byte, v any) error
}

type CookieOptions struct {
	// Name stores cookie name Name 存储 Cookie 名称
	Name string
	// Value stores cookie value Value 存储 Cookie 值
	Value string
	// MaxAge stores expiration in seconds MaxAge 存储过期时间秒数
	MaxAge int
	// Path stores cookie path Path 存储路径
	Path string
	// Domain stores cookie domain Domain 存储域名
	Domain string
	// Secure indicates HTTPS only Secure 表示是否仅在 HTTPS 下生效
	Secure bool
	// HttpOnly indicates JS access disabled HttpOnly 表示是否禁止 JS 访问
	HttpOnly bool
	// SameSite stores SameSite attribute SameSite 存储 SameSite 属性
	SameSite string
}

type FullStorage interface {
	Storage
	AtomicStorage
	ScannerStorage
	AdminStorage
}

type Generator interface {
	// Generate creates a token Generate 生成 Token
	Generate(loginId, device, deviceId string) (string, error)
}

type Log interface {
	// Print logs plain message Print 输出无级别日志
	Print(v ...any)
	// Printf logs formatted plain message Printf 输出无级别格式化日志
	Printf(format string, v ...any)

	// Debug logs debug message Debug 输出调试级别日志
	Debug(v ...any)
	// Debugf logs formatted debug message Debugf 输出调试级别格式化日志
	Debugf(format string, v ...any)
	// Info logs info message Info 输出信息级别日志
	Info(v ...any)
	// Infof logs formatted info message Infof 输出信息级别格式化日志
	Infof(format string, v ...any)
	// Warn logs warn message Warn 输出警告级别日志
	Warn(v ...any)
	// Warnf logs formatted warn message Warnf 输出警告级别格式化日志
	Warnf(format string, v ...any)
	// Error logs error message Error 输出错误级别日志
	Error(v ...any)
	// Errorf logs formatted error message Errorf 输出错误级别格式化日志
	Errorf(format string, v ...any)
}

type LogControl interface {
	Log

	// Close closes logger and releases resources Close 关闭日志并释放资源
	Close()
	// Flush flushes buffered logs Flush 刷新缓冲区
	Flush()

	// SetLevel updates log level SetLevel 动态更新日志级别
	SetLevel(level LogLevel)
	// SetPrefix updates log prefix SetPrefix 动态更新日志前缀
	SetPrefix(prefix string)
	// SetStdout toggles stdout output SetStdout 开关控制台输出
	SetStdout(enable bool)

	// LogPath gets log path LogPath 获取日志目录
	LogPath() string
	// DropCount gets dropped log count DropCount 获取丢弃的日志数量
	DropCount() uint64
}

type LogLevel int

type NopLogger struct{}

type Pool interface {
	// Submit submits task for async execution Submit 提交一个任务以异步执行
	Submit(task func()) error
	// Stop stops pool and releases resources Stop 停止池并释放所有资源
	Stop()
	// Stats returns runtime statistics Stats 返回运行时统计信息
	Stats() (running, capacity int, usage float64)
}

type RequestContext interface {

	// GetHeader gets request header GetHeader 获取请求头
	GetHeader(key string) string
	// GetHeaders gets all request headers GetHeaders 获取所有请求头
	GetHeaders() map[string][]string
	// GetQuery gets query parameter GetQuery 获取查询参数
	GetQuery(key string) string
	// GetQueryAll gets all query parameters GetQueryAll 获取所有查询参数
	GetQueryAll() map[string][]string
	// GetPostForm gets POST form parameter GetPostForm 获取 POST 表单参数
	GetPostForm(key string) string
	// GetCookie gets cookie value GetCookie 获取 Cookie
	GetCookie(key string) string
	// GetBody gets raw request body GetBody 获取请求体字节数据
	GetBody() ([]byte, error)
	// GetClientIP gets client IP GetClientIP 获取客户端 IP 地址
	GetClientIP() string
	// GetMethod gets request method GetMethod 获取请求方法
	GetMethod() string
	// GetPath gets request path GetPath 获取请求路径
	GetPath() string
	// GetURL gets full request URL GetURL 获取完整请求 URL
	GetURL() string
	// GetUserAgent gets user agent GetUserAgent 获取 User-Agent
	GetUserAgent() string
	// IsTLS checks whether request uses HTTPS IsTLS 检查请求是否通过 HTTPS 发起
	IsTLS() bool

	// SetStatusCode sets HTTP status code SetStatusCode 设置 HTTP 响应状态码
	SetStatusCode(code int)
	// SetHeader sets response header SetHeader 设置响应头
	SetHeader(key, value string)
	// Write writes bytes to response body Write 直接写入响应体字节数据
	Write(data []byte) (int, error)
	// SetCookie sets cookie using legacy arguments SetCookie 使用兼容旧版参数设置 Cookie
	SetCookie(name, value string, maxAge int, path, domain string, secure, httpOnly bool)
	// SetCookieWithOptions sets cookie using options SetCookieWithOptions 使用选项设置 Cookie
	SetCookieWithOptions(options *CookieOptions)

	// Set stores context value Set 设置上下文值
	Set(key string, value any)
	// Get gets context value Get 获取上下文值
	Get(key string) (any, bool)
	// GetString gets string value from context GetString 从上下文获取字符串值
	GetString(key string) string
	// MustGet gets value or panics MustGet 获取上下文值且不存在时 panic
	MustGet(key string) any

	// Abort aborts request handling Abort 中止请求处理
	Abort()
	// IsAborted checks whether request aborted IsAborted 检查请求是否已中止
	IsAborted() bool
}

type RequestContextExt interface {
	RequestContext

	// JSON writes JSON response JSON 返回 JSON 格式响应
	JSON(code int, v any) error
	// GetRawRequest gets raw http request GetRawRequest 获取原始 *http.Request 对象
	GetRawRequest() *http.Request
	// GetRawResponseWriter gets raw response writer GetRawResponseWriter 获取原始 http.ResponseWriter 对象
	GetRawResponseWriter() http.ResponseWriter
}

type ScannerStorage interface {
	// Keys gets all keys matching pattern. Keys 获取匹配模式的全部键。
	Keys(ctx context.Context, pattern string) ([]string, error)
}

type Storage interface {
	// Set stores a key-value pair with optional expiration. Set 写入键值对，并可设置过期时间。
	Set(ctx context.Context, key string, value any, expiration time.Duration) error
	// Get gets value by key and returns nil, nil when missing. Get 根据键读取值，键不存在时返回 nil, nil。
	Get(ctx context.Context, key string) (any, error)
	// Delete deletes one or more keys. Delete 删除一个或多个键。
	Delete(ctx context.Context, keys ...string) error
	// Exists checks whether key exists. Exists 检查键是否存在。
	Exists(ctx context.Context, key string) bool
	// Expire sets key expiration and returns an error when the key is missing. Expire 设置键过期时间，键不存在时返回错误。
	Expire(ctx context.Context, key string, expiration time.Duration) error
	// TTL gets remaining lifetime of key using TTL sentinel values. TTL 获取键剩余生存时间，并使用 TTL 哨兵值表达特殊状态。
	TTL(ctx context.Context, key string) (time.Duration, error)
	// Ping checks whether storage is reachable. Ping 检查存储是否可达。
	Ping(ctx context.Context) error
}

type TokenStyle string