Documentation
¶
Overview ¶
Package web provides the buffered request lifecycle used by browser routes. Streaming, server-sent event, WebSocket, and large download routes should be registered outside this middleware and use the lower-level packages directly.
Index ¶
- Constants
- Variables
- func CSRF() httpx.Middleware
- func CSRFToken(ctx *httpx.Context) (string, error)
- func Destroy(ctx *httpx.Context) error
- func ExternalRedirect(ctx *httpx.Context, location string) error
- func Invalidate(ctx *httpx.Context) error
- func Redirect(ctx *httpx.Context, location string) error
- func Regenerate(ctx *httpx.Context) error
- func RegenerateOrCreate(ctx *httpx.Context) error
- func Render(ctx *httpx.Context, renderer Renderer, status int, name string, data any) error
- func RotateCSRF(ctx *httpx.Context) (string, error)
- func SaveSessionWith(ctx *httpx.Context, manager *forgesession.Manager) error
- func Session(ctx *httpx.Context) (*forgesession.Session, bool)
- func Sessions(manager *forgesession.Manager) httpx.Middleware
- func SessionsLimit(manager *forgesession.Manager, maxResponseBytes int64) httpx.Middleware
- type Renderer
Constants ¶
const ( // CSRFField is the conventional hidden form field read by CSRF middleware. CSRFField = "_token" // CSRFHeader is accepted for JavaScript requests that cannot submit a form field. CSRFHeader = "X-CSRF-Token" )
Variables ¶
var ErrBufferedResponseTooLarge = errors.New("web: buffered response exceeds configured limit")
Functions ¶
func CSRF ¶
func CSRF() httpx.Middleware
CSRF protects every method other than GET, HEAD, and OPTIONS with a session-bound synchronizer token. URL-encoded forms submit _token in their body; other clients submit X-CSRF-Token. Query parameters are never read. Sessions middleware must be installed before CSRF.
func CSRFToken ¶
CSRFToken returns the current token, creating it in the request session when necessary. Sessions middleware persists it before the rendered response is committed.
func Destroy ¶
Destroy removes the persisted session and stages an expired cookie in the buffered response. A destroyed session is not saved again at commit.
func ExternalRedirect ¶
ExternalRedirect is the explicit escape hatch for trusted external destinations. Never pass unvalidated request input to this helper.
func Invalidate ¶ added in v0.8.0
Invalidate removes a stale server-side session without emitting a deletion cookie. This prevents an out-of-order stale response from overwriting a new cookie issued by a concurrent credential-change request.
func Redirect ¶
Redirect performs a Post/Redirect/Get redirect to an absolute application path using HTTP 303. External and scheme-relative locations are rejected.
func Regenerate ¶
Regenerate stages a new session ID. Sessions middleware atomically persists the replacement before committing the response.
func RegenerateOrCreate ¶ added in v0.8.0
RegenerateOrCreate is the explicit credential-change variant of Regenerate. It may preserve a winning session when another stale request removed the old row after an independent authorization change committed.
func RotateCSRF ¶
RotateCSRF replaces the request session's token. Use it when authentication state changes; Sessions middleware persists it atomically with session ID regeneration before committing the response.
func SaveSessionWith ¶ added in v0.9.0
func SaveSessionWith(ctx *httpx.Context, manager *forgesession.Manager) error
SaveSessionWith persists the current buffered session through an alternate manager and prevents the middleware from saving it a second time. Generated applications use this narrow hook to include initial session persistence in the same database transaction as account registration.
func Session ¶
func Session(ctx *httpx.Context) (*forgesession.Session, bool)
Session returns the request's session and marks it for persistence. The boolean is false when Sessions middleware is not installed.
func Sessions ¶
func Sessions(manager *forgesession.Manager) httpx.Middleware
Sessions loads one server-side session for each request. Responses are held until an accessed session has been saved, so cookies and redirects are never committed ahead of session persistence. Anonymous sessions that handlers do not access are neither created in the store nor written as cookies.
The middleware deliberately buffers browser responses and does not expose streaming interfaces. Register streaming routes outside it.
func SessionsLimit ¶
func SessionsLimit(manager *forgesession.Manager, maxResponseBytes int64) httpx.Middleware
SessionsLimit is Sessions with an explicit maximum buffered response size. Register downloads and streaming endpoints outside this middleware.
Source Files