http

Documentation

Overview

Package http exposes a thin HTTP/SSE adapter that translates external REST traffic into bus.Bus calls. The adapter does not implement transport.Transport; it is a server-side wrapper that lets HTTP clients talk to an existing Bus.

Endpoint surface (see prompts/design.md §10.1):

POST /v1/agents/{target}/invoke   -> bus.Invoke,       returns final payload JSON
POST /v1/agents/{target}/stream   -> bus.StreamInvoke, returns text/event-stream
POST /v1/events/{event_type}      -> bus.Publish,      returns 202 Accepted

HTTP headers map onto envelope correlation/tenancy fields (see envelope.go), the request body becomes Envelope.Payload verbatim, and an optional AuthFunc can override tenant/user/session before dispatch.

Index

• Variables
• type Adapter
  • func New(b bus.Bus, opts ...Option) *Adapter
  • func (a *Adapter) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type AuthContext
• type AuthFunc
  • func BearerAuth(validator func(token string) (*AuthContext, error)) AuthFunc
• type Middleware
  • func Logging(log *slog.Logger) Middleware
  • func Recover(log *slog.Logger) Middleware
• type Option
  • func WithAuth(fn AuthFunc) Option
  • func WithIdleTimeout(d time.Duration) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMiddleware(mw ...Middleware) Option
  • func WithSSERetry(d time.Duration) Option
  • func WithTimeout(d time.Duration) Option

Variables

var ErrUnauthorized = errors.New("http: unauthorized")

ErrUnauthorized is the canonical sentinel for AuthFunc to signal a rejected credential. Wrapping it preserves errors.Is matching for callers that want to distinguish auth failures from other errors.

Types

type Adapter

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

Adapter implements http.Handler. Construct with New, then mount on any http.Server: srv := &http.Server{Handler: New(b)}.

func New

func New(b bus.Bus, opts ...Option) *Adapter

New constructs an Adapter wrapping the given Bus. The Adapter holds no resources of its own beyond the mux; closing the underlying Bus is the caller's responsibility.

func (*Adapter) ServeHTTP

func (a *Adapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes Adapter satisfy http.Handler.

type AuthContext

type AuthContext struct {
	TenantID       string
	UserID         string
	SessionID      string
	ConversationID string
	Channel        string
	TraceID        string
}

AuthContext carries authentication-derived envelope overrides. Any non-empty field replaces the value derived from the corresponding HTTP header — e.g. the auth layer may pin TenantID even when the client sets X-Tenant-Id.

type AuthFunc

type AuthFunc func(r *http.Request) (*AuthContext, error)

AuthFunc validates a request and returns the authenticated identity. Returning a non-nil error short-circuits the request with 401. Returning (nil, nil) is equivalent to "no overrides" and lets the request proceed.

func BearerAuth

func BearerAuth(validator func(token string) (*AuthContext, error)) AuthFunc

BearerAuth builds an AuthFunc that extracts the bearer token from the Authorization header and delegates to validator. The validator returns the authenticated AuthContext or any error to reject the request.

Header format: `Authorization: Bearer <token>` (case-insensitive scheme). Missing or malformed header → ErrUnauthorized.

type Middleware

type Middleware func(http.Handler) http.Handler

Middleware wraps an http.Handler — the standard func(http.Handler) http.Handler chain familiar from net/http. Outermost middleware runs first.

func Logging

func Logging(log *slog.Logger) Middleware

Logging emits a structured log line per request after the handler returns. Status code is captured via a thin ResponseWriter wrapper.

func Recover

func Recover(log *slog.Logger) Middleware

Recover guards downstream handlers from panics. A recovered panic is logged and translated to a 500 response with an INVALID_REQUEST-shaped JSON body so clients see consistent error envelopes.

type Option

type Option func(*Adapter)

Option mutates an Adapter at construction time.

func WithAuth

func WithAuth(fn AuthFunc) Option

WithAuth installs a request authenticator. When set, every request must pass the AuthFunc; non-nil error short-circuits with 401. A nil AuthFunc (or never calling WithAuth) leaves the adapter unauthenticated.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout caps the gap between two streaming frames. Zero disables idle-timeout, leaving only the overall WithTimeout in effect.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger overrides the default slog.Default() logger.

func WithMiddleware

func WithMiddleware(mw ...Middleware) Option

WithMiddleware appends one or more http.Handler middlewares. Outermost middleware (first in the list) wraps the others.

func WithSSERetry

func WithSSERetry(d time.Duration) Option

WithSSERetry sets the retry interval sent to SSE clients in the retry: field (milliseconds). Zero disables the field. Default is 3s.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout caps the per-request overall deadline (invoke + stream). Passes through to bus.WithTimeout. Zero leaves the bus default in effect.