web

Documentation

Overview

Package web provides HTTP server components with secure defaults, including server factory, routing, middleware, sessions, and OIDC integration.

Index

• Variables
• func NewClient() *http.Client
• func NewClientWithTLS(certFile, keyFile, caFile string) *http.Client
• func NewIdentityProvider() *identityProvider
• func NewServer(mux *http.ServeMux) *http.Server
• func TLSClientConfig(certFile, keyFile, caFile string) *tls.Config
• func WithAuth(sessions *ServerSessions, next http.HandlerFunc) http.HandlerFunc
• func WithBearerAuth(verifier *oidc.IDTokenVerifier, next http.HandlerFunc) http.HandlerFunc
• func WithLogging(logger *slog.Logger, next http.HandlerFunc) http.HandlerFunc
• type ContextKey
• type IdentityTokenClaims
• type MCPHandler
  • func NewMCPHandler(server *mcp.Server) *MCPHandler
  • func (h *MCPHandler) Handler() http.HandlerFunc
• type ServerSession
• type ServerSessions
  • func NewServeMux(ctx context.Context, efs fs.FS) (*http.ServeMux, *ServerSessions)
  • func NewServerSessions() *ServerSessions
  • func (a *ServerSessions) Create(id string, data any) ServerSession
  • func (a *ServerSessions) Delete(id string)
  • func (a *ServerSessions) Read(id string) (*ServerSession, bool)
  • func (a *ServerSessions) Update(s ServerSession)

Variables

var IdentityProvider = NewIdentityProvider() //nolint:gochecknoglobals // singleton pattern for identity provider

IdentityProvider is a singleton instance of the identity provider.

Functions

func NewClient

func NewClient() *http.Client

NewClient creates and returns a new *http.Client with a default timeout of 5 seconds. The timeout can be adjusted by setting the CLIENT_TIMEOUT environment variable.

func NewClientWithTLS

func NewClientWithTLS(certFile, keyFile, caFile string) *http.Client

NewClientWithTLS creates and returns a new *http.Client with mutual TLS authentication.

func NewIdentityProvider

func NewIdentityProvider() *identityProvider

NewIdentityProvider creates a new identity provider.

func NewServer

func NewServer(mux *http.ServeMux) *http.Server

NewServer creates and returns a configured HTTP server. It uses the PORT environment variable or defaults to port 8080. The server has a default timeout of 5 seconds for read, write, and idle connections. The timeout can be adjusted by setting the SERVER_*_TIMEOUT environment variables.

func TLSClientConfig

func TLSClientConfig(certFile, keyFile, caFile string) *tls.Config

TLSClientConfig creates and returns a *tls.Config configured for mutual TLS authentication. It loads client specific certificates and adds server specific root CA certificates.

func WithAuth

func WithAuth(sessions *ServerSessions, next http.HandlerFunc) http.HandlerFunc

WithAuth adds authentication information to the context.

func WithBearerAuth

func WithBearerAuth(verifier *oidc.IDTokenVerifier, next http.HandlerFunc) http.HandlerFunc

WithBearerAuth validates OAuth 2.1 Bearer tokens for MCP endpoints. It extracts the token from the Authorization header, verifies it against the OIDC provider, and populates the request context with user claims. On failure, it returns a JSON-RPC 2.0 error response.

func WithLogging

func WithLogging(logger *slog.Logger, next http.HandlerFunc) http.HandlerFunc

WithLogging logs the request with method, path and duration.

Types

type ContextKey

type ContextKey string

ContextKey is a type for context keys used in the web package.

const (
	ContextEmail     ContextKey = "email"
	ContextIssuer    ContextKey = "issuer"
	ContextName      ContextKey = "name"
	ContextSessionID ContextKey = "session_id"
	ContextSubject   ContextKey = "subject"
	ContextVerified  ContextKey = "verified"
)

type IdentityTokenClaims

type IdentityTokenClaims struct {
	Email    string `json:"email"`
	Issuer   string `json:"iss"`
	Name     string `json:"name"`
	Subject  string `json:"sub"`
	Verified bool   `json:"email_verified"`
}

IdentityTokenClaims represents the claims of an identity token.

type MCPHandler

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

MCPHandler provides HTTP transport for MCP servers.

func NewMCPHandler

func NewMCPHandler(server *mcp.Server) *MCPHandler

NewMCPHandler creates a handler that bridges HTTP to an MCP server.

func (*MCPHandler) Handler

func (h *MCPHandler) Handler() http.HandlerFunc

Handler returns an http.HandlerFunc for POST /mcp requests.

type ServerSession

type ServerSession struct {
	Data any    `json:"value"`
	ID   string `json:"id"`
}

ServerSession is a session for a user.

type ServerSessions

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

ServerSessions is a thread-safe map of session IDs to sessions.

func NewServeMux

func NewServeMux(ctx context.Context, efs fs.FS) (*http.ServeMux, *ServerSessions)

NewServeMux creates a new mux with the liveness check endpoint (/liveness) and the readiness check endpoint (/readiness). The mux is returned along with a new ServerSessions instance.

func NewServerSessions

func NewServerSessions() *ServerSessions

NewServerSessions creates a new serverSessions.

func (*ServerSessions) Create

func (a *ServerSessions) Create(id string, data any) ServerSession

Create adds a new session to the serverSessions.

func (*ServerSessions) Delete

func (a *ServerSessions) Delete(id string)

Delete removes the session with the given sessionID.

func (*ServerSessions) Read

func (a *ServerSessions) Read(id string) (*ServerSession, bool)

Read returns the session for the given sessionID.

func (*ServerSessions) Update

func (a *ServerSessions) Update(s ServerSession)

Update adds a new session to the serverSessions.