serverless

type Adapter interface {
	// Name identifies the adapter in logs and errors, such as "aws-lambda".
	Name() string
	// Detect reports whether this process is running on the adapter's platform,
	// which every serverless runtime makes knowable from the environment.
	//
	// It is what makes selecting an adapter an import rather than a decision the
	// application has to encode, and it is why one binary can carry adapters for
	// several platforms.
	Detect() bool
	Mapper() EventMapper
	// Start hands control to the provider's own event loop, which calls invoke
	// once per invocation and does not return until the process is shutting
	// down.
	Start(ctx context.Context, invoke Invoker) error
}

type EventMapper interface {
	// Detect reports which source a payload came from, so a function that is
	// not told what it serves can still route.
	Detect(payload []byte) (handler.Kind, error)

	ToRequest(payload []byte) (*handler.Request, error)
	FromResponse(res *handler.Response) (any, error)

	ToWebSocketMessage(payload []byte) (*handler.WebSocketMessage, error)

	ToConsumerBatch(payload []byte, tag string) (*handler.ConsumerBatch, error)
	FromBatchResult(res *handler.BatchResult) (any, error)

	ToScheduleTrigger(payload []byte, tag string) (*handler.ScheduleTrigger, error)

	ToCustomInvoke(payload []byte) (*handler.CustomInvoke, error)
	FromCustomResult(res *handler.CustomInvokeResult) (any, error)
}

type Handler struct {
	Tag  string
	Name string
	Kind handler.Kind
	// Invoke runs the full pipeline: application layers, then group, then
	// handler, with guards ahead of them.
	Invoke layer.Next
}

type Invoker func(ctx context.Context, payload []byte) (any, error)

type MissingAdapterError struct {
	// Linked names the adapters that are compiled in, which is commonly empty
	// and is the useful half of the message when it is not.
	Linked []string
}

type ReceiptAcknowledger interface {
	// AcknowledgeReceipt tells the client its message arrived, where the message
	// asked to be told and the transport leaves that to the SDK.
	//
	// Called before the handler runs, and for a message that reaches no handler
	// at all: the client asked whether its message arrived, and it did.
	AcknowledgeReceipt(ctx context.Context, msg *handler.WebSocketMessage) error
}

type Resolver interface {
	// ByName resolves a handler by blueprint resource name or published name,
	// which is what CELERITY_HANDLER_ID carries.
	ByName(name string) (*Handler, bool)
	// ByTag resolves a handler by its handler tag.
	ByTag(tag string) (*Handler, bool)
	// Only returns the single handler of a kind, when there is exactly one.
	// A Celerity deployment gives each handler its own function, so this is the
	// ordinary case and it resolves a function that was told nothing.
	Only(kind handler.Kind) (*Handler, bool)
}

type WebSocketSenderProvider interface {
	// WebSocketSender builds a sender for the connection the payload came from,
	// since the endpoint to push to is commonly carried by the event itself.
	WebSocketSender(ctx context.Context, payload []byte) (handler.WebSocketSender, error)
}