api

type AuditEvent struct {
	// API identification
	Resource string `json:"resource"`
	Action   string `json:"action"`
	Version  string `json:"version"`

	// User identification
	UserID    string `json:"userId"`
	UserAgent string `json:"userAgent"`

	// Request information
	RequestID     string         `json:"requestId"`
	RequestIP     string         `json:"requestIp"`
	RequestParams map[string]any `json:"requestParams"`
	RequestMeta   map[string]any `json:"requestMeta"`

	// Response information
	ResultCode    int    `json:"resultCode"`
	ResultMessage string `json:"resultMessage"`
	ResultData    any    `json:"resultData"`

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

type AuthConfig struct {
	// Strategy specifies the auth strategy name. default is "bearer".
	// Built-in: "none", "bearer", "signature", "ip"
	// Custom strategies can be registered via AuthStrategyRegistry.
	Strategy string
	// Options holds strategy-specific configuration.
	Options map[string]any
}

type AuthStrategy interface {
	// Name returns the strategy name (used in AuthConfig.Strategy).
	Name() string
	// Authenticate validates credentials and returns principal.
	Authenticate(ctx fiber.Ctx, options map[string]any) (*security.Principal, error)
}

type AuthStrategyRegistry interface {
	// Register adds a strategy to the registry.
	Register(strategy AuthStrategy)
	// Get retrieves a strategy by name.
	Get(name string) (AuthStrategy, bool)
	// Names returns all registered strategy names.
	Names() []string
}

type Engine interface {
	// Register adds resources to the engine.
	Register(resources ...Resource) error
	// Lookup finds an operation by identifier.
	Lookup(id Identifier) *Operation
	// Mount attaches the engine to a Fiber router.
	Mount(router fiber.Router) error
}

type FactoryParamResolver interface {
	// Type returns the parameter type this resolver handles.
	Type() reflect.Type
	// Resolve returns the parameter value (called once at startup).
	Resolve() (reflect.Value, error)
}

type HandlerAdapter interface {
	// Adapt converts the handler to a fiber.Handler.
	Adapt(handler any, op *Operation) (fiber.Handler, error)
}

type HandlerParamResolver interface {
	// Type returns the parameter type this resolver handles.
	Type() reflect.Type
	// Resolve extracts the parameter value from the request.
	Resolve(ctx fiber.Ctx) (reflect.Value, error)
}

type HandlerResolver interface {
	// Resolve finds a handler on the resource and spec.
	// Returns the handler (any type) or an error if not found.
	Resolve(resource Resource, spec OperationSpec) (any, error)
}

type Identifier struct {
	Resource string `json:"resource" form:"resource" validate:"required,alphanum_us_slash" label_i18n:"api_request_resource"`
	Action   string `json:"action" form:"action" validate:"required" label_i18n:"api_request_action"`
	Version  string `json:"version" form:"version" validate:"required,alphanum" label_i18n:"api_request_version"`
}

type Kind uint8

type M struct{}

type Meta map[string]any

type Middleware interface {
	// Name returns the middleware identifier.
	Name() string
	// Order determines execution order.
	// Negative values execute before handler, positive after.
	// Lower values execute first within the same phase.
	Order() int
	// Process handles the request.
	// Call next() to continue the chain.
	Process(ctx fiber.Ctx) error
}

type Operation struct {
	// Identifier contains the full operation identity.
	Identifier

	// EnableAudit indicates whether audit logging is enabled.
	EnableAudit bool
	// Timeout is the final timeout duration.
	Timeout time.Duration
	// Auth indicates the authentication configuration.
	Auth *AuthConfig
	// RateLimit is the final rate limit configuration.
	RateLimit *RateLimitConfig
	// Handler is the resolved handler (before adaptation).
	Handler any
	// Meta holds additional operation-specific data.
	// For REST: may contain parsed method, path pattern, etc.
	Meta map[string]any
}

type OperationSpec struct {
	// Action is the action name for the API endpoint
	Action 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
	// RequiredPermission is the permission token required for access
	RequiredPermission string
	// RateLimit represents the rate limit for an API endpoint
	RateLimit *RateLimitConfig
	// Handler is the business logic handler.
	Handler any
}

type OperationsCollector interface {
	// Collect gathers all operation specs from a resource.
	// Returns specs from embedded OperationsProviders.
	Collect(resource Resource) []OperationSpec
}

type OperationsProvider interface {
	// Provide returns the operation specs for this provider.
	Provide() []OperationSpec
}

type P struct{}

type Params map[string]any

type RateLimitConfig struct {
	// Max is the maximum number of requests allowed.
	Max int
	// Period is the time window for rate limiting.
	Period time.Duration
	// Key is a custom rate limit key template.
	// Empty means using the default key.
	Key string
}

type Request struct {
	Identifier

	Params Params `json:"params"`
	Meta   Meta   `json:"meta"`
}

type Resource interface {
	// Kind returns the resource kind.
	Kind() Kind
	// Name returns the resource name (e.g., "users", "sys/config").
	Name() string
	// Version returns the resource version.
	// Empty string means using Engine's default version.
	Version() string
	// Auth returns the resource authentication configuration.
	Auth() *AuthConfig
	// Operations returns the resource operations.
	Operations() []OperationSpec
}

type ResourceOption func(*baseResource)

type RouterStrategy interface {
	// Name returns the strategy identifier for logging/debugging.
	Name() string
	// CanHandle returns true if the router can handle the given resource kind.
	CanHandle(kind Kind) bool
	// Setup initializes the router (called once during Mount).
	// Implementations should store the router if needed for Route calls.
	Setup(router fiber.Router) error
	// Route registers an operation with the router.
	Route(handler fiber.Handler, op *Operation)
}