Documentation
¶
Overview ¶
Package web provides HTTP server components with secure defaults, including server factory, routing, middleware, sessions, and OIDC integration.
Index ¶
- func NewClient() *http.Client
- func NewClientWithTLS(certFile, keyFile, caFile string) *http.Client
- func NewServeMux(ctx context.Context, efs fs.FS) (*http.ServeMux, *ServerSessions, *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 IdentityProvider
- type IdentityTokenClaims
- type MCPHandler
- type ServerSession
- type ServerSessions
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewClient ¶
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 ¶
NewClientWithTLS creates and returns a new *http.Client with mutual TLS authentication.
func NewServeMux ¶
func NewServeMux(ctx context.Context, efs fs.FS) (*http.ServeMux, *ServerSessions, *IdentityProvider)
NewServeMux creates a new mux with the liveness check endpoint (/liveness) and the readiness check endpoint (/readiness). The mux is returned along with the ServerSessions and IdentityProvider it wires, both of which the caller owns.
Example ¶
This example has no Output comment: it builds a server rather than running one.
ctx := context.Background()
// NewServeMux wires /static, /health, /liveness, /readiness and the OIDC
// endpoints, then hands back the sessions store and identity provider it
// built. Both belong to the caller from here on.
mux, sessions, idp := web.NewServeMux(ctx, efs)
// Sessions guard a browser route.
mux.HandleFunc("GET /protected", web.WithAuth(sessions, func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "hello %v", r.Context().Value(web.ContextEmail))
}))
// A bearer token guards an API route.
mux.HandleFunc("POST /mcp", web.WithBearerAuth(idp.Verifier(), func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
}))
// NewServer applies the timeouts and TLS settings; the caller starts it.
server := web.NewServer(mux)
_ = server.ListenAndServeTLS("server.crt", "server.key")
func NewServer ¶
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 ¶
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 ¶ added in v0.5.6
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 IdentityProvider ¶
type IdentityProvider struct {
// contains filtered or unexported fields
}
IdentityProvider signs a user in through an OpenID Connect provider.
NewIdentityProvider builds one. Hold it for the lifetime of the server: the first IdentityProvider.Login discovers the provider's configuration and the code verifiers for in-flight logins live inside it.
func NewIdentityProvider ¶
func NewIdentityProvider() *IdentityProvider
NewIdentityProvider creates a new identity provider.
func (*IdentityProvider) Callback ¶ added in v0.6.0
func (a *IdentityProvider) Callback(sessions *ServerSessions) http.HandlerFunc
Callback returns a handler function for the identity provider's callback endpoint.
func (*IdentityProvider) Login ¶ added in v0.6.0
func (a *IdentityProvider) Login() http.HandlerFunc
Login returns a handler function for the identity provider's login endpoint.
func (*IdentityProvider) Logout ¶ added in v0.6.0
func (a *IdentityProvider) Logout(sessions *ServerSessions) http.HandlerFunc
Logout handles the logout request.
func (*IdentityProvider) Verifier ¶ added in v0.6.0
func (a *IdentityProvider) Verifier() *oidc.IDTokenVerifier
Verifier returns an OIDC ID token verifier for Bearer token validation. The identity provider must be initialized first via Login().
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 ¶ added in v0.5.1
type MCPHandler struct {
// contains filtered or unexported fields
}
MCPHandler provides HTTP transport for MCP servers.
func NewMCPHandler ¶ added in v0.5.1
func NewMCPHandler(server *mcp.Server) *MCPHandler
NewMCPHandler creates a handler that bridges HTTP to an MCP server.
func (*MCPHandler) Handler ¶ added in v0.5.1
func (h *MCPHandler) Handler() http.HandlerFunc
Handler returns an http.HandlerFunc for POST /mcp requests.
type ServerSession ¶
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 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.
Source Files