api

type AuditEvent struct {
	event.BaseEvent

	// Api identification
	Resource string `json:"resource"` // Api resource name
	Action   string `json:"action"`   // Api action name
	Version  string `json:"version"`  // Api version

	// User identification
	UserId    string `json:"userId"`    // Operating user id
	UserAgent string `json:"userAgent"` // User agent (User-Agent header)

	// Request information
	RequestId     string         `json:"requestId"`     // Request Id
	RequestIP     string         `json:"requestIp"`     // Request IP address
	RequestParams map[string]any `json:"requestParams"` // Request parameters
	RequestMeta   map[string]any `json:"requestMeta"`   // Request metadata

	// Response information
	ResultCode    int    `json:"resultCode"`    // Result code (business code)
	ResultMessage string `json:"resultMessage"` // Result message
	ResultData    any    `json:"resultData"`    // Result data (optional)

	// Performance metrics
	ElapsedTime int `json:"elapsedTime"` // Elapsed time in milliseconds
}

type Definition struct {
	Identifier

	// EnableAudit indicates whether to enable audit logging for this endpoint
	EnableAudit bool
	// Timeout is the request timeout duration
	Timeout time.Duration
	// Public indicates whether this endpoint is publicly accessible
	Public bool
	// PermToken is the permission token required for access
	PermToken string
	// Limit represents the rate limit for an Api endpoint
	Limit RateLimit
	// Handler is the actual handler function for this endpoint
	Handler fiber.Handler
}

type FactoryParamResolver interface {
	// Type returns the parameter type this resolver handles
	Type() reflect.Type
	// Resolve returns an instance of the type (as reflect.Value)
	// Called during resource registration, resolver should return instances already injected via DI
	Resolve() reflect.Value
}

type HandlerParamResolver interface {
	Type() reflect.Type
	Resolve(ctx fiber.Ctx) (reflect.Value, error)
}

type Identifier struct {
	// The version of the Api endpoint
	Version string `json:"version" form:"version" validate:"required,alphanum" label_i18n:"api_request_version"`
	// The resource name of the Api endpoint
	Resource string `json:"resource" form:"resource" validate:"required,alphanum_us_slash" label_i18n:"api_request_resource"`
	// The action name of the Api endpoint
	Action string `json:"action" form:"action" validate:"required,alphanum_us" label_i18n:"api_request_action"`
}

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

type Manager interface {
	// Register adds a new Api definition to the manager.
	// Returns an error if an Api with the same identifier already exists.
	Register(api *Definition) error
	// Remove removes an Api definition by its identifier.
	Remove(id Identifier)
	// Lookup retrieves an Api definition by its identifier.
	// Returns nil if the definition is not found.
	Lookup(id Identifier) *Definition
	// List returns all registered Api definitions.
	List() []*Definition
}

type Meta map[string]any

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

type Params map[string]any

type Provider interface {
	// Provide returns an Api specification.
	Provide() Spec
}

type RateLimit struct {
	// Max is the rate limit per time window (0 means no limit)
	Max int
	// Expiration is the rate limit expiration time
	Expiration time.Duration
}

type Request struct {
	Identifier

	// The params of the request
	Params Params `json:"params"`
	// The meta of the request
	Meta Meta `json:"meta"`
}

type Resource interface {
	// Version returns the version of the resource.
	Version() string
	// Name returns the name of the resource.
	Name() string
	// Apis returns the list of Api specifications for this resource.
	Apis() []Spec
}

type Spec struct {
	// Action is the action name for the Api endpoint
	Action string
	// Version is the version of the Api endpoint
	Version string
	// EnableAudit indicates whether to enable audit logging for this endpoint
	EnableAudit bool
	// Timeout is the request timeout duration
	Timeout time.Duration
	// Public indicates whether this endpoint is publicly accessible
	Public bool
	// PermToken is the permission token required for access
	PermToken string
	// Limit represents the rate limit for an Api endpoint
	Limit RateLimit
	// Handler is optional. If not provided, the system will automatically search for a method
	// in the struct using the Action name converted to PascalCase format.
	// The search supports both direct methods and methods from embedded anonymous structs.
	// For example, if Action is "create_user", the system will look for "CreateUser" method.
	// The handler function should be compatible with the Api framework's handler signature.
	Handler any
}