handler

type Ack struct {
	Success bool
	Error   string
}

type BatchResult struct {
	Failures []RecordFailure
}

type BinarySender interface {
	// SendBinary frames every message and blocks until the outcome is known.
	//
	// A message whose parts cannot be represented in the format is refused
	// rather than truncated into a frame that would be read as something other
	// than what was meant, and no message in the call is sent.
	//
	// A partial failure returns a [SendError], as [WebSocketSender.Send] does.
	SendBinary(ctx context.Context, messages ...OutboundBinaryMessage) error
}

type ConsumerBatch struct {
	Records    []ConsumerRecord
	SourceID   string
	SourceType string
	// Vendor is provider-specific and opaque.
	Vendor []byte
}

type ConsumerRecord struct {
	MessageID  string
	Body       []byte
	Source     string
	EventType  string
	Attributes []byte
	Vendor     []byte
}

type CustomInvoke struct {
	HandlerName string
	Input       []byte
}

type CustomInvokeResult struct {
	Output []byte
}

type DetailCarrier interface {
	error
	Details() any
}

type Error struct {
	Message string
	Type    string
	Stack   string
}

type Event struct {
	// ID identifies this dispatch and is what a cancellation names.
	ID   string
	Tag  string
	Kind Kind
	// Timestamp is when the runtime received the originating event.
	Timestamp time.Time
	// Deadline is when the runtime stops waiting. It is applied to the handler's
	// context, and the runtime enforces it independently.
	Deadline time.Time
	// TraceContext carries W3C traceparent and tracestate.
	TraceContext map[string]string

	HTTP      *Request
	WebSocket *WebSocketMessage
	Consumer  *ConsumerBatch
	Schedule  *ScheduleTrigger
	Custom    *CustomInvoke
}

type Func func(ctx context.Context, ev *Event) (*Result, error)

type IssueReporter interface {
	error
	ValidationIssues() []ValidationIssue
}

type Kind string

type OutboundBinaryMessage struct {
	ConnectionID string
	// Route is what the message is delivered by. Required, at most 255 bytes,
	// and it may not begin with a byte the protocol reserves.
	Route string
	// FrameMessageID is the id an acknowledgement names, what deduplication
	// keys on and what a loss notification refers to. Required where RequireAck
	// is set, and at most 255 bytes.
	//
	// Distinct from MessageID, which is the runtime's own handle for the send.
	// Where both matter, set both.
	FrameMessageID string
	// RequireAck asks the client to acknowledge this message, which only means
	// anything alongside a FrameMessageID.
	RequireAck bool
	// Message is the payload, carried to the client without being read.
	Message []byte
	// InformClientsOnLoss names connections to notify if this message cannot be
	// delivered.
	InformClientsOnLoss []string
	// MessageID identifies the message to the runtime, as on [OutboundMessage].
	MessageID string
	// Caller is the connection that caused this message to be sent, as on
	// [OutboundMessage].
	Caller string
	// WaitForAck waits for the client to acknowledge this message, as on
	// [OutboundMessage]. Unlike a text message, this composes the request for
	// acknowledgement itself: set RequireAck and a FrameMessageID and the frame
	// asks for one.
	WaitForAck bool
}

type OutboundMessage struct {
	ConnectionID string
	// Message is sent to the socket exactly as given, as a text frame.
	//
	// Bytes go through [BinarySender], not here, binary frames are a capability
	// of the transport rather than of the SDK, and a managed WebSocket gateway
	// carries text frames only.
	Message []byte
	// InformClientsOnLoss names connections to notify if this message cannot be
	// delivered.
	InformClientsOnLoss []string
	// MessageID identifies the message to the runtime, for acknowledgement
	// between nodes and in loss events. Generated by the runtime when empty,
	// which is the right choice unless the caller needs to match a loss event
	// back to what it sent.
	//
	// Not the id the client sees: the runtime sends Message to the socket
	// exactly as given, so a client-visible id belongs in the payload.
	MessageID string
	// Caller is the connection that caused this message to be sent, carried
	// through to the loss event. Only meaningful alongside InformClientsOnLoss.
	Caller string
	// WaitForAck waits for the client to acknowledge this message, rather than
	// returning once it has been written to the socket, and reports it as
	// failed where the client never does.
	//
	// Message has to ask the client for an acknowledgement in what it carries,
	// which the runtime does not compose. Setting this for one that asks
	// nothing waits until the runtime declares the message lost.
	//
	// Under the Celerity runtime only. A serverless adapter pushes through the
	// provider's own API, which reports whether it accepted the message and
	// nothing about what the client made of it.
	WaitForAck bool
}

type Params map[string]Values

type RecordFailure struct {
	// MessageID is the id the record arrived with, see [BatchResult.Fail].
	MessageID string
	Error     string
}

type Request struct {
	// Method is uppercase and canonical.
	Method string
	// Path is raw and percent-encoded, as received.
	Path string
	// Route is the template this request matched in the router's own form, so a
	// blueprint's /files/{path+} arrives as /files/{*path}.
	Route string
	// PathParams holds one value per segment for a catch-all parameter.
	// Segments are split from the raw path before being percent-decoded, so a
	// segment containing an encoded separator survives intact.
	PathParams  Params
	QueryParams Params
	// Headers have lowercase names.
	Headers  Params
	SourceIP string
	// RequestID identifies this delivery.
	RequestID string
	// Body is opaque. The media type comes from the content-type header.
	Body []byte
}

type Response struct {
	// Status must be between 100 and 999. A value outside that range is a fault
	// in the handler, and the runtime answers 500 rather than narrowing it.
	Status  int
	Headers Params
	Body    []byte
}

type Result struct {
	ID string

	HTTP      *Response
	WebSocket *Ack
	Consumer  *BatchResult
	Schedule  *Ack
	Custom    *CustomInvokeResult
	// Error is set when user code returned or panicked with an unhandled error.
	Error *Error
}

type ScheduleTrigger struct {
	ScheduleID string
	MessageID  string
	// Schedule is the expression the rule was declared with.
	Schedule string
	Input    []byte
	Vendor   []byte
}

type SendError struct {
	Failures []SendFailure
}

type SendFailure struct {
	Index        int
	ConnectionID string
	Error        string
}

type StatusCoder interface {
	error
	// StatusCode returns the HTTP status this error should be answered with.
	StatusCode() int
}

type StatusError struct {
	Status int
	// Message is what the caller is told. It should say what is wrong without
	// saying anything the caller is not entitled to know.
	Message string
	// Detail is structured information about what is wrong, answered alongside
	// the message. Nil where there is nothing to add.
	//
	// It reaches the caller, so it carries what they can act on and nothing
	// about how this is implemented.
	Detail any
	// Err is the underlying cause, kept for logging and errors.Is/As. It is
	// never sent to the caller.
	Err error
}

type TypedError interface {
	error
	ErrorType() string
}

type ValidationError struct {
	// Message summarises the failure. It should name what was being validated,
	// such as the body or the query, rather than repeating the issues.
	Message string
	Issues  []ValidationIssue
	// Err is the underlying cause, reachable through errors.Is and
	// errors.Unwrap. Never answered to the caller, and so deliberately absent
	// from Error, as a validation library's own error text commonly names types
	// and internal paths. Code that wants it in a log unwraps it.
	Err error
}

type ValidationIssue struct {
	// Code identifies the kind of problem, so a client can branch on it without
	// parsing prose. It is a stable, lowercase identifier.
	Code string `json:"code"`
	// Path names the field, outermost first, and is empty when the problem is
	// with the input as a whole.
	Path []string `json:"path"`
	// Message says what is wrong in terms of the caller's own request.
	Message string `json:"message"`
}

type Values []string

type WebSocketMessage struct {
	Route        string
	ConnectionID string
	SourceIP     string
	// RequestID identifies this delivery, as distinct from MessageID.
	RequestID string
	Message   []byte
	// IsBinary reports whether this arrived as a binary frame rather than a
	// text one. A byte body alone cannot express the distinction and the
	// WebSocket protocol treats the two frame types as distinct.
	IsBinary bool
	// MessageID is the id the message is known by: the one the client gave it,
	// or one the runtime generated. It is what an acknowledgement names and what
	// a lost message notification refers to.
	MessageID string
}

type WebSocketSender interface {
	// Send delivers every message and blocks until the outcome is known.
	//
	// For a message that set WaitForAck, the outcome is what its client made of
	// it, so Send is waiting on a round trip rather than on a write.
	//
	// A partial failure returns a [SendError] naming exactly which messages
	// failed, so a caller can retry exactly those. Re-sending a whole batch
	// would redeliver the messages that did arrive, and whether the client can
	// tell those apart depends on the message ID: a client SDK deduplicates by
	// that where a message carries one, and cannot where it does not.
	Send(ctx context.Context, messages ...OutboundMessage) error
}