webapi

type ApiDecoder interface {
	// Decode 从 HTTP 请求中，构建用于调用 ApiState.Method 的参数，并填入 ApiState.Args 。
	// 若参数转换失败，填写 ApiState.Error ，将跳过 ApiMethodCaller 的执行。
	Decode(state *ApiState)
}

type ApiDecoderFunc func(state *ApiState)

type ApiEngine struct {
	// contains filtered or unexported fields
}

type ApiError struct {
	// contains filtered or unexported fields
}

type ApiHandler interface {
	ApiMethodRegister
	ApiUserHostResolver
	ApiNameResolver
	ApiDecoder
	ApiMethodCaller
	ApiResponseBuilder
	ApiResponseWriter
	ApiLogger

	// Name 获取当前 ApiHandler 的标识符。每个 ApiHandler 应具有唯一的名称。
	// 名称可以是任意值，包括空字符串。但应尽量给定容易识别的名称。
	Name() string

	// SupportedHttpMethods 返回当前 ApiHandler 支持的 HTTP 方法。
	// 如 GET 、 POST 、 PUT 、 DELETE 等，大小写不敏感。
	SupportedHttpMethods() []string
}

type ApiHandlerWrapper struct {
	ApiMethodRegister
	ApiNameResolver
	ApiUserHostResolver
	ApiDecoder
	ApiMethodCaller
	ApiResponseBuilder
	ApiResponseWriter
	ApiLogger

	// HandlerName 是 ApiHandler.Name() 的返回值。
	HandlerName string

	// HttpMethods 是 ApiHandler.SupportedHttpMethods() 的返回值。
	HttpMethods []string
}

type ApiLogger interface {
	// Log 根据 ApiState 的内容生成日志，日志由 ApiState.Logger 接收。
	// 若 ApiState.Logger 为 nil ，则不生成日志。
	Log(state *ApiState)
}

type ApiLoggerFunc func(state *ApiState)

type ApiMethod struct {
	// Name 是注册的 WebAPI 方法的名称。
	// 虽然在检索时使用大小写不敏感的方式，但这里通常记录注册时所使用的可区分大小写的名称。
	Name string

	// Value 记录目标方法。
	Value reflect.Value

	// Provider 指定方法提供者的名称，用于对方法加以分类，可为空。
	Provider string
}

type ApiMethodCaller interface {
	// 使用参数 ApiState.Args 调用 ApiState.Method 所对应的方法，将调用结果填入 ApiState.Data 和 ApiState.Error 。
	// 应仅在 ApiState.Error 为 nil 时调用此方法。方法通过 ApiMethodRegister 注册时已完成类型校验。
	Call(state *ApiState)
}

type ApiMethodCallerFunc func(state *ApiState)

type ApiMethodRegister interface {
	// RegisterMethod 注册一个方法。
	// 注册时，对于方法名称应采用大小写不敏感的方式处理。若多次注册同一个名称，最后注册的将之前的覆盖。
	//
	// 允许方法具有0-2个输出参数。
	//   - 1个参数时，参数可以是任意 struct/map[string]*/基础类型 或者此三类作为元素的 slice ，也可以是 error 。
	//   - 2个参数时，第一个参数可以是  struct/map[string]*/基础类型 或者此三类作为元素的 slice ，第二个参数必须是 error 。
	//
	RegisterMethod(m ApiMethod)

	// RegisterMethods 将给定的 struct 上的所有公开方法注册为 WebAPI 。若给定的不是 struct ，则 panic 。
	// 通过此方法注册后，通过 GetMethod() 获取的 ApiMethod.Provider 为给定的 struct 的名称，对应 reflect.Type.Name() 的值。
	//
	// 对方法名称使用一组约定（下划线使用名称中的第一个下划线）：
	//   - 若方法名称格式为 Method__Name （使用两个下划线分割），则 Name 被注册为 WebAPI 名称；
	//   - 若方法名称格式为 Method__ （使用两个下划线结尾）或 Method____ （两个下划线之后也只有下划线），则此方法不会被注册为 WebAPI ；
	//   - 其余情况，均使用方法的原始名称作为 WebAPI 名称。
	// 这里 Method 和 Name 均为可变量， Method 用于指代代码内有意义的方法名称， Name 指代 WebAPI 名称。例如 GetName__13 注册一个名称为
	// “13”的 API 方法，其方法业务意义为 GetName 。
	//
	// 每个方法的注册逻辑与 RegisterMethod 一致。
	// 特别的，如果格式为 Method____abc ，两个下划线之后存在有效名称，则 WebAPI 名称为 __abc ，从两个下划线后的下一个字符（还是下划线）开始取。
	//
	RegisterMethods(providerStruct any)

	// GetMethod 返回具有指定名称的方法。若方法存在，返回 ApiMethod 和 true ；若未被注册，返回零值和 false 。
	// 对于方法名称应采用大小写不敏感的方式处理。
	GetMethod(name string) (method ApiMethod, ok bool)
}

type ApiNameResolver interface {
	// FillMethod 从当前 HTTP 请求里获取 API 方法的名称，并填入 ApiState.Name ；如果未能解析到名称，则不需要填写。
	// 若请求非法，可填写 ApiState.Error ，跳过 ApiDecoder 和 ApiMethodCaller 的执行。
	FillMethod(state *ApiState)
}

type ApiNameResolverFunc func(state *ApiState)

type ApiResponse[T any] struct {
	// 状态码， 0 表示一个成功的请求，其他值表示有错误。
	Code int

	// Message 在 Code 不为 0 时，记录用于描述错误的消息。
	Message string

	// Data 记录返回的数据本体。
	Data T
}

type ApiResponseBuilder interface {
	// BuildResponse 根据 ApiState.Data 和 ApiState.Error ，填写 ApiState.Response 。
	BuildResponse(state *ApiState)
}

type ApiResponseBuilderFunc func(state *ApiState)

type ApiResponseWriter interface {
	// 处理 ApiState.Response ，获得实际需要返回的数据，填入 ApiState.Response* （以 Response 开头）字段。
	// 此方法执行之后， ApiState 中以 Response 开头字段，如 ResponseBody 、 ResponseContentType ，均需要完成赋值。
	// 此方法执行时，若 Response* 字段已经有值，则保留原值，不覆盖。
	WriteResponse(state *ApiState)
}

type ApiResponseWriterFunc func(state *ApiState)

type ApiSetup struct {
	// contains filtered or unexported fields
}

type ApiState struct {
	// RawRequest 是原始的 HTTP 请求。对应 http.Handler 的参数。
	RawRequest *http.Request

	// RawResponse 用于写入 HTTP 回执。对应 http.Handler 的参数。
	RawResponse http.ResponseWriter

	// Query 是按 ASP.net 的方式解析 URL 上的参数。
	// 由于通信协议是按 .net 版的方式制定的，获取 query-string 应通过此字段进行。
	Query QueryString

	// Handler 当前的 ApiHandler 。
	Handler ApiHandler

	// Logger 用于接收当前请求的处理流程中需记录的日志。可以为 nil ，表示不记录日志。
	// 应在 Method 被调用前，即 ApiMethodCaller.Call() 之前初始化。
	Logger logx.Logger

	// Name 记录调用 WebAPI 给定的方法名称，它应被唯一的映射到一个 Method 。
	// ApiNameResolver 接口定义了初始化此字段的方法。
	Name string

	// Method 记录要调用的方法，和 Name 一一映射，可从通过 ApiMethodRegister.GetMethod(ApiState.Name) 得到。
	// 方法由 ApiMethodCaller 调用，参数从 Args 获取。
	Method ApiMethod

	// MethodArgs 存放用于调用 Method 的参数。
	// ApiDecoder 接口定义了初始化此字段的方法。
	Args []reflect.Value

	// UserHost 记录发起 HTTP 请求的客户端 IP 地址。
	// ApiUserHostResolver 接口定义了初始化此字段的方法。
	UserHost string

	// Data 记录 ApiMethodCaller.Call() 方法所调用的具体 WebAPI 方法返回的非 error 值。
	// 若方法没有返回值，此字段为 nil 。
	Data any

	// 用于定制输出日志时的日志级别，用于 [ApiLogger] 的日志输出。
	// 若 [ApiLogger.Log] 被调用前没有被赋值（为 0），则 Log 方法被调用后，应将其最终决定使用的级别回填到此字段。
	LogLevel logx.Level

	// LogMessage 用于记录各个处理流程中的日志信息，用于在 [ApiLogger] 中的输出。
	// 最终日志的输出由 [ApiLogger] 决定，这只是一个缓冲（ buffer ）。
	// key-value 对，与 [logx.Logger.Log] 的 keyValues 参数定义一致。
	LogMessage []any

	// Error 记录 ApiMethodCaller.Call() 方法所调用的具体 WebAPI 方法返回的 error 值；
	// 或记录 ApiDecoder 和 ApiMethodCaller 处理过程中 panic 的错误。没有错误时为 nil 。
	// ApiResponseBuilder.BuildResponse() 能够将此错误转换为对应的 ApiResponse 。
	Error error

	// Response 记录 WebAPI 返回的结果的抽象结构。
	Response *ApiResponse[any]

	// ResponseBody 提供实际返回的 HTTP body 的数据。若为 nil ，则 HTTP 没有 body 。
	// 若实现了 io.ReaderCloser ，则完成 HTTP body 的写入后，会被自动 Close 。
	ResponseBody io.Reader

	// ResponseContentType 对应为返回的 HTTP 的 Content-Type 头的值。
	ResponseContentType string
	// contains filtered or unexported fields
}

type ApiUserHostResolver interface {
	// FillUserHost 获取发起 HTTP 请求的客户端 IP 地址，并填入 ApiState.UserHost 。
	//
	// HTTP 服务经常通过反向代理访问，可能转好几层，需要通过如 X-Forwarded-For 头获取客户端 IP 。
	// 效果类似于 [http.Request.RemoteAddr] ，但不带端口部分。 IPv6 地址外层的“[]”也会被去掉（如果有）。
	FillUserHost(state *ApiState)
}

type ApiUserHostResolverFunc func(state *ApiState)

type ArgumentDecodeFunc func(state *ApiState, index int, argType reflect.Type) (ok bool, v any, err error)

type ArgumentDecoder interface {
	// DecodeArg 尝试机械 API 方法中的一个参数。
	//
	// 若给定的 API 参数（通过 index 和 argType 识别）可被当前函数解析，则返回 ok=true 及解析结果 v ，或者返回 ok=false 及解析错误；
	// 若当前函数不支持给定参数的解析，则返回无错误的 ok=false 和 v=nil 。
	DecodeArg(state *ApiState, index int, argType reflect.Type) (ok bool, v any, err error)
}

type ArgumentDecoderPipeline []ArgumentDecoder

type BadRequestError struct {
	// contains filtered or unexported fields
}

type LogSetup interface {
	// Setup 可将日志信息写入 [ApiState.LogLevel] 和 [ApiState.LogMessage] 。
	Setup(state *ApiState)
}

type LogSetupFunc func(state *ApiState)

type LogSetupPipeline []LogSetup

type QueryString struct {
	// Nameless 记录没有参数名的参数。如“?a&b=1”中的 “a”。
	Nameless string

	// HasNameless 表示是否有无名称的参数。用于区分 Nameless 是空字符串时，空字符串是否是参数值。
	HasNameless bool

	// Named 记录其余全部有参数名的参数。
	// 相同名称的参数出现多个时，会被以逗号拼接起来，如“?a=1&a=2”结果为“a=1,2”；
	// 所有参数名称都会被转为小写，以便以大小写不敏感的方式匹配参数。
	Named map[string]string
}

type RouteParam struct {
	Key, Value string
}