service

type AppContext struct {
	Config         any
	JanitorCtx     context.Context
	Logger         *slog.Logger
	PortAlloc      *portalloc.Allocator
	JanitorTimeout time.Duration
}

type BackgroundWorker interface {
	StartWorker(ctx context.Context) error
}

type ChaosProvider interface {
	// ChaosServiceName returns the lowercase AWS-style service name used in
	// fault rules (e.g. "s3", "dynamodb", "sqs").
	ChaosServiceName() string

	// ChaosOperations returns all operations that can be fault-injected.
	// Implementations typically delegate to GetSupportedOperations().
	ChaosOperations() []string

	// ChaosRegions returns all regions this service instance handles.
	// Typically returns the configured default region plus any regions
	// that have active resources.
	ChaosRegions() []string
}

type CloudTrailEventInput struct {
	// EventName is the AWS API operation name, e.g. "CreateBucket", "RunInstances".
	EventName string
	// EventSource is the AWS service's CloudTrail event source, e.g. "s3.amazonaws.com".
	EventSource string
	// AwsRegion is the region the request targeted.
	AwsRegion string
	// Username identifies the caller. Empty when no signed identity was present.
	Username string
	// AccessKeyID is the SigV4 access key used to sign the request, if any.
	AccessKeyID string
	// ResourceName is the primary resource the operation acted on, if known.
	ResourceName string
}

type CloudTrailRecorder interface {
	// RecordManagementEvent records a single mutating API call as a CloudTrail
	// management event so it is later returned by LookupEvents.
	RecordManagementEvent(ev CloudTrailEventInput)
}

type DashboardProvider interface {
	// DashboardName returns the user-facing name for this service's dashboard tab.
	// Example: "DynamoDB", "S3"
	DashboardName() string

	// DashboardRoutePrefix returns the URL path prefix for this service's dashboard routes.
	// Example: "dynamodb", "s3"
	DashboardRoutePrefix() string

	// RegisterDashboardRoutes registers all dashboard routes for this service
	// under the given Echo group. The group is mounted at /dashboard/{prefix}.
	// The httpClient and endpoint are provided for services that need to make
	// SDK calls back to the service (e.g., to list tables or buckets).
	RegisterDashboardRoutes(
		group *echo.Group,
		httpClient any,
		endpoint string,
	)
}

type DispatchFunc func(ctx context.Context, action string, body []byte) ([]byte, error)

type Entry struct {
	Registerable   Registerable
	Matcher        Matcher
	WrappedHandler echo.HandlerFunc
	Priority       int
}

type ErrorHandlerFunc func(ctx context.Context, c *echo.Context, action string, err error) error

type FISActionDefinition struct {
	ActionID    string // e.g., "aws:ec2:stop-instances"
	Description string
	TargetType  string // e.g., "aws:ec2:instance"; empty if action has no targets
	TargetKey   string // key name used in the Targets map (e.g., "Instances", "Roles"); defaults to "Targets"
	Parameters  []FISParamDef
}

type FISActionExecution struct {
	ActionID   string
	Parameters map[string]string
	Targets    []string      // resolved resource ARNs
	Duration   time.Duration // 0 means run indefinitely until stopped
}

type FISActionProvider interface {
	// FISActions returns the FIS action definitions this service supports.
	FISActions() []FISActionDefinition

	// ExecuteFISAction executes a FIS action against resolved targets.
	// It is called by the FIS backend when an experiment's action begins.
	// The implementation must be non-blocking or respect ctx cancellation.
	ExecuteFISAction(ctx context.Context, action FISActionExecution) error
}

type FISParamDef struct {
	Name        string
	Description string
	Default     string
	Required    bool
}

type JSONErrorResponse struct {
	Type    string `json:"__type"`
	Message string `json:"message"`
}

type JSONOpFunc func(ctx context.Context, body []byte) (any, error)

type Matcher func(c *echo.Context) bool

type Middleware func(echo.HandlerFunc) echo.HandlerFunc

type Provider interface {
	// Name returns the name of the service provider.
	Name() string

	// Init initializes the service using the provided application context.
	// It returns the Registerable service, or an error if initialization fails.
	Init(ctx *AppContext) (Registerable, error)
}

type Purgeable interface {
	Purge(ctx context.Context, cutoff time.Time)
}

type RESTRouter struct {
	// ServiceName appears in the operation-error log line.
	ServiceName string
	// Parse extracts the operation name and resource identifier from the
	// request method and URL path.
	Parse func(method, path string) (op, resource string)
	// Dispatch runs the parsed operation against the service backend.
	Dispatch func(ctx context.Context, op, path, query string, body []byte) (any, int, error)
	// HandleError translates a Dispatch error into an Echo response.
	HandleError func(c *echo.Context, err error) error
	// NotFoundBody builds the JSON body for an unrecognized-operation 404.
	NotFoundBody func() any
	// BadRequestBody builds the JSON body for a request-body read failure.
	BadRequestBody func() any
	// InternalErrorBody builds the JSON body for a result-marshal failure.
	InternalErrorBody func() any
	// OpUnknown is the sentinel Parse returns for an unrecognized path.
	OpUnknown string
	// Priority is the routing priority returned by MatchPriority.
	Priority int
}

type Registerable interface {
	Service
	ResourceObserver

	// MatchPriority returns the priority for this service's matcher.
	// Higher values are evaluated first. Examples:
	// - Header-based matchers (DynamoDB): 100
	// - Path-based matchers (Dashboard): 50
	// - Catch-all matchers (S3): 0
	MatchPriority() int
}

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

type Resettable interface {
	Reset()
}

type ResourceObserver interface {
	// ExtractOperation returns the operation name (e.g., "GetItem", "PutObject").
	// Used in metrics labels.
	ExtractOperation(c *echo.Context) string

	// ExtractResource returns the resource identifier (e.g., table name, bucket name).
	// Used in metrics labels.
	ExtractResource(c *echo.Context) string
}

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

type Service interface {
	// Name returns the service identifier (e.g., "DynamoDB", "S3").
	// Used in metrics labels and logging.
	Name() string

	// Handler returns the Echo handler function for this service.
	Handler() echo.HandlerFunc

	// RouteMatcher returns a function that determines if an incoming
	// Echo request should be routed to this service. Matchers are
	// evaluated in registration order. Return true to route here,
	// false to continue to next service.
	RouteMatcher() Matcher

	// GetSupportedOperations returns a list of operations this service
	// supports (e.g., ["GetItem", "PutItem", "Query"] for DynamoDB).
	GetSupportedOperations() []string
}

type Shutdowner interface {
	Shutdown(ctx context.Context)
}