server

func ConfigureEngine ¶ added in v1.12.2

func ConfigureEngine(engine *gin.Engine, cfg config.ServerConfig) error

ConfigureEngine applies the settings every Gin engine serving Kargo's API must share, so that an engine built outside this package behaves like the one built within it.

Note: This sets Gin's mode, which is package-level state. Every engine in the process is in release mode as a result, which is what we want of all of them anyway.

func ConvertAndSendWatchEvent ¶ added in v1.11.0

func ConvertAndSendWatchEvent[T any](c *gin.Context, e watch.Event, target T) bool

ConvertAndSendWatchEvent converts a watch event's object to the target type and sends it as an SSE event. It handles both unstructured objects (from real clients) and typed objects (from fake clients in tests). Returns true if the caller should continue processing (including on conversion errors), false if the watch should be terminated (write failure or a watch.Error event).

func ConvertWatchEventObject ¶ added in v1.11.0

func ConvertWatchEventObject[T any](c *gin.Context, e watch.Event, _ T) (T, bool)

ConvertWatchEventObject converts a watch event's object to the target type. It handles both unstructured objects (from real clients) and typed objects (from fake clients in tests). Returns the converted object and true if successful, or the zero value and false if conversion failed.

func ErrorFromWatchEvent ¶ added in v1.11.0

func ErrorFromWatchEvent(e watch.Event) error

ErrorFromWatchEvent maps Kubernetes watch.Error events into client-visible errors that watch handlers can return or stream.

func FilteredWatchEventType ¶ added in v1.11.0

func FilteredWatchEventType(eventType watch.EventType, matches bool) (watch.EventType, bool)

FilteredWatchEventType returns the event type to send for a client-side filtered watch event. Kubernetes server-side selectors send a DELETED event when a previously matching object is modified so it no longer matches; this helper mirrors that behavior for filters we must evaluate in-process.

Because we hold no per-client matched set, we cannot tell whether a non-matching MODIFIED object previously matched, so we emit a synthetic DELETED for every non-matching MODIFIED event — including objects the client never received an ADDED for. This over-emits DELETEs relative to a real server-side selector, but a DELETE for an object the client is not tracking is a harmless no-op. Achieving exact fidelity would require tracking sent object identities per client, which is not worth the complexity here.

func LoggingMiddleware ¶ added in v1.12.0

func LoggingMiddleware(cfg config.ServerConfig) gin.HandlerFunc

LoggingMiddleware returns Gin middleware that records one line per request using Kargo's own logger, so that LOG_LEVEL governs the request log as it governs everything else.

Each line names the actor the request was authenticated as, in the same form used to attribute Promotions and Events, so that a request log can answer who did something and not only where it came from. A request that never authenticated is attributed to EventActorUnknown.

A server error is recorded at error level. A request that was refused is recorded at info level, because a refusal is never routine and is the first thing anyone looks for when a user reports being unable to do something. Everything else is operational detail and recorded at debug level, unless cfg.RequestLogAllEnabled raises it to info level.

The IP address a request came from is recorded only when cfg.RequestLogSourceIPEnabled is set, because it is personal data and is usually better recorded by whatever proxy sits in front of the server. It is resolved by the engine, which ConfigureEngine must have configured.

This must be the outermost middleware, so that the status and any reported error it records are the ones the client actually received.

func NewAuthMiddleware ¶ added in v1.11.0

func NewAuthMiddleware(
	ctx context.Context,
	cfg config.ServerConfig,
	client libClient.Client,
	opts ...AuthMiddlewareOpt,
) gin.HandlerFunc

NewAuthMiddleware returns an initialized Gin middleware handler for authentication.

func SendSSEWatchError ¶ added in v1.11.0

func SendSSEWatchError(c *gin.Context, err error)

SendSSEWatchError sends a watch error as an SSE error event. Watch endpoints may have already sent response headers, so HTTP status codes are no longer a reliable way to report expired resource versions after streaming begins.

func SendSSEWatchEvent ¶ added in v1.11.0

func SendSSEWatchEvent[T any](c *gin.Context, eventType watch.EventType, obj T) bool

SendSSEWatchEvent sends an object as an SSE watch event. Returns true if the caller should continue processing, false if the watch should be terminated (write failure).

func SendSSEWatchStartError ¶ added in v1.11.0

func SendSSEWatchStartError(c *gin.Context, err error) bool

SendSSEWatchStartError sends startup watch errors that are part of the watch protocol as SSE error events. It returns true when the error was handled.

func SetSSEHeaders ¶ added in v1.11.0

func SetSSEHeaders(c *gin.Context)

SetSSEHeaders configures the standard headers for Server-Sent Events (SSE) streaming on a gin context.

func WriteSSEKeepalive ¶ added in v1.11.0

func WriteSSEKeepalive(c *gin.Context) bool

WriteSSEKeepalive writes a keepalive comment to keep the SSE connection alive. Returns true if successful, false if the write failed.