idem

type Config struct {
	// Driver 后端类型: "redis" | "memory" (默认 "redis")
	Driver DriverType `json:"driver" yaml:"driver"`

	// Prefix Redis Key 前缀，默认 "idem:"
	// 例如："myapp:idem:" 将使用 "myapp:idem:{key}" 作为存储键
	Prefix string `json:"prefix" yaml:"prefix"`

	// DefaultTTL 幂等记录有效期，默认 24h
	// 超过此时间后，缓存的结果将被清理，后续相同请求将重新执行
	DefaultTTL time.Duration `json:"default_ttl" yaml:"default_ttl"`

	// LockTTL 处理过程中的锁超时时间，默认 30s
	// 防止业务逻辑崩溃导致死锁，超时后锁自动释放
	LockTTL time.Duration `json:"lock_ttl" yaml:"lock_ttl"`

	// WaitTimeout 等待结果的最长时间，默认 0（仅受 ctx 影响）
	// 当未获取到锁时，将阻塞等待结果或锁可用
	WaitTimeout time.Duration `json:"wait_timeout" yaml:"wait_timeout"`

	// WaitInterval 等待结果的轮询间隔，默认 50ms
	WaitInterval time.Duration `json:"wait_interval" yaml:"wait_interval"`
}

type DeletableStore interface {
	Store
	DeleteResult(ctx context.Context, key string) error
}

type DriverType string

type Idempotency interface {
	// Execute 执行幂等操作
	//
	// 工作流程：
	//   1. 如果 key 已存在且完成 → 直接返回缓存结果
	//   2. 如果 key 正在处理中 → 等待结果或重新尝试获取锁
	//   3. 如果 key 不存在 → 执行 fn 并缓存成功结果
	//
	// 参数：
	//   - ctx: 上下文，用于取消和超时控制
	//   - key: 幂等性键，全局唯一标识这次操作
	//   - fn: 业务逻辑函数，只在第一次请求时执行
	//
	// 返回：
	//   - 执行结果或缓存的结果。为保证首次执行与缓存命中的类型一致，返回值会经过同一套 JSON 编解码规范化。
	//   - 错误：ErrKeyEmpty、上下文错误、锁丢失错误等
	Execute(ctx context.Context, key string, fn func(ctx context.Context) (any, error)) (any, error)

	// Consume 用于消息消费的幂等处理
	//
	// 工作流程：
	//   1. 如果 key 已存在且完成 → 直接返回 false
	//   2. 如果 key 正在处理中 → 返回 ErrConcurrentRequest
	//   3. 如果 key 不存在 → 执行 fn 并标记已处理
	//
	// 返回：
	//   - executed: 是否执行了 fn
	//   - 错误：ErrKeyEmpty, ErrConcurrentRequest 等
	Consume(ctx context.Context, key string, ttl time.Duration, fn func(ctx context.Context) error) (executed bool, err error)

	// GinMiddleware 创建 Gin 框架中间件
	//
	// 使用示例：
	//   middleware := idem.GinMiddleware().(func(*gin.Context))
	//   router.POST("/orders", middleware, handler)
	//   // 或者直接使用（Gin 会自动处理）：
	//   router.Use(idem.GinMiddleware().(func(*gin.Context)))
	//
	// 工作原理：
	//   1. 从 HTTP 请求头 X-Idempotency-Key 提取幂等性键
	//   2. 如果缓存命中，直接返回缓存的响应
	//   3. 如果未命中，执行 handler 并按缓存策略缓存响应
	//
	// 参数：
	//   - opts: 中间件选项，可自定义请求头名称等
	//
	// 返回：
	//   - func(*gin.Context) 类型的中间件函数
	//
	// 注意：
	//   返回类型为 interface{} 是为了避免强依赖 gin 包，
	//   实际返回的是 func(*gin.Context) 类型。
	//   传给 gin 的 router 时需要显式类型断言为 gin.HandlerFunc。
	GinMiddleware(opts ...MiddlewareOption) any

	// UnaryServerInterceptor 创建 gRPC 一元服务端拦截器
	//
	// 使用示例：
	//   server := grpc.NewServer(
	//       grpc.UnaryInterceptor(idem.UnaryServerInterceptor()),
	//   )
	//
	// 工作原理：
	//   1. 从 gRPC metadata 提取 x-idem-key
	//   2. 使用分布式锁防止并发执行
	//   3. 如果缓存命中，返回缓存的 protobuf 响应
	//   4. 如果未命中，执行 RPC handler 并按缓存策略缓存成功响应
	//
	// 参数：
	//   - opts: 拦截器选项，可自定义 metadata 键名称等
	//
	// 返回：
	//   - gRPC 一元服务端拦截器
	//
	// 注意：
	//   只支持一元 RPC 调用，不支持流式 RPC（因为流式交互的复杂性）。
	//   当前默认只缓存成功的 proto.Message 响应。
	UnaryServerInterceptor(opts ...InterceptorOption) grpc.UnaryServerInterceptor
}

type InterceptorOption func(*interceptorOptions)

type LockToken string

type MiddlewareOption func(*middlewareOptions)

type Option func(*options)

type RefreshableStore interface {
	Store
	Refresh(ctx context.Context, key string, token LockToken, ttl time.Duration) error
}

type Store interface {
	// Lock 尝试获取锁（标记处理中）
	// 返回 true 表示成功获取锁，false 表示已被其他请求锁定
	Lock(ctx context.Context, key string, ttl time.Duration) (LockToken, bool, error)

	// Unlock 释放锁（通常用于执行失败时清理）
	Unlock(ctx context.Context, key string, token LockToken) error

	// SetResult 保存执行结果并标记完成
	// 同时会自动释放锁
	SetResult(ctx context.Context, key string, val []byte, ttl time.Duration, token LockToken) error

	// GetResult 获取已完成的结果
	// 如果结果不存在，返回 ErrResultNotFound
	GetResult(ctx context.Context, key string) ([]byte, error)
}