Events Reference

Complete reference for rocco event signals and field keys.

Event System

Rocco emits events via capitan. Hook into events for logging, metrics, and tracing.

import "github.com/zoobz-io/capitan"

// Hook specific event
capitan.Hook(rocco.RequestCompleted, func(ctx context.Context, e *capitan.Event) {
    method, _ := rocco.MethodKey.From(e)
    // ...
})

// Observe all events
capitan.Observe(func(ctx context.Context, e *capitan.Event) {
    // Handle any event
})

Server Lifecycle Events

EngineCreated

Signal: http.engine.createdLevel: Debug

Emitted when engine instance is created.

No fields.

EngineStarting

Signal: http.engine.startingLevel: Info

Emitted when server starts listening.

Field	Type	Description
`AddressKey`	string	Address being listened on
`TLSEnabledKey`	bool	Whether TLS is enabled

EngineShutdownStarted

Signal: http.engine.shutdown.startedLevel: Info

Emitted when shutdown is initiated.

No fields.

EngineShutdownComplete

Signal: http.engine.shutdown.completeLevel: Info/Error

Emitted when shutdown completes.

Field	Type	Description
`GracefulKey`	bool	Whether shutdown was graceful
`ErrorKey`	string	Error message (if failed)

Handler Registration Events

HandlerRegistered

Signal: http.handler.registeredLevel: Debug

Emitted when a handler is registered.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`MethodKey`	string	HTTP method
`PathKey`	string	URL path

Request Lifecycle Events

RequestReceived

Signal: http.request.receivedLevel: Debug

Emitted when request is received.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name

RequestCompleted

Signal: http.request.completedLevel: Info

Emitted when request completes successfully.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`StatusCodeKey`	int	HTTP status code
`DurationMsKey`	int64	Duration in milliseconds

RequestFailed

Signal: http.request.failedLevel: Error

Emitted when request fails with error.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`StatusCodeKey`	int	HTTP status code
`DurationMsKey`	int64	Duration in milliseconds
`ErrorKey`	string	Error message

Handler Execution Events

HandlerExecuting

Signal: http.handler.executingLevel: Debug

Emitted when handler function starts.

Field	Type	Description
`HandlerNameKey`	string	Handler name

HandlerSuccess

Signal: http.handler.successLevel: Info

Emitted when handler returns successfully.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`StatusCodeKey`	int	Success status code

HandlerError

Signal: http.handler.errorLevel: Error

Emitted when handler returns unexpected error.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

HandlerSentinelError

Signal: http.handler.sentinel.errorLevel: Warn

Emitted when handler returns declared sentinel error.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message
`StatusCodeKey`	int	Error status code

HandlerUndeclaredSentinel

Signal: http.handler.sentinel.undeclaredLevel: Warn

Emitted when handler returns undeclared sentinel error (programming error).

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message
`StatusCodeKey`	int	Would-be status code

Request Processing Events

RequestParamsInvalid

Signal: http.request.params.invalidLevel: Error

Emitted when path/query parameter extraction fails.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

RequestBodyReadError

Signal: http.request.body.read.errorLevel: Error/Warn

Emitted when request body read fails.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

RequestBodyParseError

Signal: http.request.body.parse.errorLevel: Error

Emitted when JSON body parsing fails.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

RequestValidationInputFailed

Signal: http.request.validation.input.failedLevel: Warn

Emitted when input validation fails.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Validation errors

RequestValidationOutputFailed

Signal: http.request.validation.output.failedLevel: Warn

Emitted when output validation fails (if enabled).

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Validation errors

RequestResponseMarshalError

Signal: http.request.response.marshal.errorLevel: Error

Emitted when response JSON marshaling fails.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

RequestBodyCloseError

Signal: http.request.body.close.errorLevel: Warn

Emitted when closing the request body stream fails.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

ResponseWriteError

Signal: http.response.write.errorLevel: Warn

Emitted when writing response body to client fails (e.g., client disconnected).

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

Authentication Events

AuthenticationFailed

Signal: http.auth.failedLevel: Warn

Emitted when identity extraction fails.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

AuthenticationSucceeded

Signal: http.auth.succeededLevel: Debug

Emitted when identity extraction succeeds.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`IdentityIDKey`	string	Identity ID
`TenantIDKey`	string	Tenant ID

Authorization Events

AuthorizationScopeDenied

Signal: http.authz.scope.deniedLevel: Warn

Emitted when scope check fails.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`IdentityIDKey`	string	Identity ID
`RequiredScopesKey`	string	Required scopes (comma-separated)
`UserScopesKey`	string	User's scopes (comma-separated)

AuthorizationRoleDenied

Signal: http.authz.role.deniedLevel: Warn

Emitted when role check fails.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`IdentityIDKey`	string	Identity ID
`RequiredRolesKey`	string	Required roles (comma-separated)
`UserRolesKey`	string	User's roles (comma-separated)

AuthorizationSucceeded

Signal: http.authz.succeededLevel: Debug

Emitted when authorization passes.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`IdentityIDKey`	string	Identity ID

Rate Limiting Events

RateLimitExceeded

Signal: http.ratelimit.exceededLevel: Warn

Emitted when usage limit is exceeded.

Field	Type	Description
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`IdentityIDKey`	string	Identity ID
`LimitKeyKey`	string	Limit key name
`CurrentValueKey`	int	Current usage value
`ThresholdKey`	int	Limit threshold

Stream (SSE) Events

StreamExecuting

Signal: http.stream.executingLevel: Debug

Emitted when stream handler starts.

Field	Type	Description
`HandlerNameKey`	string	Handler name

StreamStarted

Signal: http.stream.startedLevel: Info

Emitted when SSE stream is established and headers sent.

Field	Type	Description
`HandlerNameKey`	string	Handler name

StreamEnded

Signal: http.stream.endedLevel: Info

Emitted when stream handler completes normally.

Field	Type	Description
`HandlerNameKey`	string	Handler name

StreamClientDisconnected

Signal: http.stream.client.disconnectedLevel: Info

Emitted when client disconnects from stream.

Field	Type	Description
`HandlerNameKey`	string	Handler name

StreamError

Signal: http.stream.errorLevel: Error

Emitted when stream handler encounters error.

Field	Type	Description
`HandlerNameKey`	string	Handler name
`ErrorKey`	string	Error message

Field Keys Reference

Key	Type	Description
`AddressKey`	string	Server address (e.g., ":8080")
`MethodKey`	string	HTTP method
`PathKey`	string	Request path
`HandlerNameKey`	string	Handler name
`StatusCodeKey`	int	HTTP status code
`DurationMsKey`	int64	Duration in milliseconds
`ErrorKey`	string	Error message
`GracefulKey`	bool	Graceful shutdown flag
`IdentityIDKey`	string	Identity ID
`TenantIDKey`	string	Tenant ID
`RequiredScopesKey`	string	Required scopes
`UserScopesKey`	string	User's scopes
`RequiredRolesKey`	string	Required roles
`UserRolesKey`	string	User's roles
`LimitKeyKey`	string	Usage limit key
`CurrentValueKey`	int	Current usage value
`ThresholdKey`	int	Usage threshold

Usage Example

import (
    "context"
    "github.com/zoobz-io/capitan"
    "github.com/zoobz-io/rocco"
)

func setupObservability() {
    // Log all requests
    capitan.Hook(rocco.RequestCompleted, func(ctx context.Context, e *capitan.Event) {
        method, _ := rocco.MethodKey.From(e)
        path, _ := rocco.PathKey.From(e)
        status, _ := rocco.StatusCodeKey.From(e)
        duration, _ := rocco.DurationMsKey.From(e)

        log.Info("request",
            "method", method,
            "path", path,
            "status", status,
            "duration_ms", duration,
        )
    })

    // Alert on auth failures
    capitan.Hook(rocco.AuthenticationFailed, func(ctx context.Context, e *capitan.Event) {
        path, _ := rocco.PathKey.From(e)
        err, _ := rocco.ErrorKey.From(e)
        alerting.Warn("auth_failed", path, err)
    })
}