Documentation
¶
Overview ¶
Package middleware provides HTTP middleware for the Commerce API.
This file implements Cloudflare-aware HTTP cache control middleware. Routes served via api.hanzo.ai sit behind CF; correct Cache-Control headers are the only lever we have to control what CF caches.
Strategy:
- All authenticated routes: Cache-Control: private, no-store (CF must not cache these — they carry per-user data)
- Public read-only routes (billing plans, product catalog): Cache-Control: public with a TTL appropriate to how often the data changes.
- All mutation routes (POST/PUT/PATCH/DELETE): Cache-Control: no-store regardless of the route's other classification.
CF Cache-Tag headers allow targeted cache purging when data changes. Add tags in individual handlers via SetCFCacheTags(c, "plans", "org:xyz").
Index ¶
- Constants
- Variables
- func AccessControl(allowOrigin string) gin.HandlerFunc
- func AccountRequired() gin.HandlerFunc
- func AcquireOrganization(moduleName string) gin.HandlerFunc
- func AcquireUser(moduleName string) gin.HandlerFunc
- func AddHost() gin.HandlerFunc
- func BasicAuth() gin.HandlerFunc
- func CFCacheTags(tags ...string) gin.HandlerFunc
- func CacheNoStore() gin.HandlerFunc
- func CachePrivate() gin.HandlerFunc
- func CachePublic(ttl int) gin.HandlerFunc
- func CachePublicTTL(ttl time.Duration) gin.HandlerFunc
- func CheckLogin() gin.HandlerFunc
- func DetectOverrides() gin.HandlerFunc
- func DetectTest(query *url.Values) bool
- func DetectVerbose(query *url.Values) bool
- func EdgeAuth() gin.HandlerFunc
- func ErrorHTML(c *gin.Context, stack string, err error)
- func ErrorHTMLDev(c *gin.Context, stack string, err error)
- func ErrorHandler() gin.HandlerFunc
- func ErrorHandlerJSON() gin.HandlerFunc
- func ErrorJSON(c *gin.Context, stack string, err error)
- func ErrorJSONDev(c *gin.Context, stack string, err error)
- func ErrorLogger() gin.HandlerFunc
- func ErrorLoggerT(typ gin.ErrorType) gin.HandlerFunc
- func GetAccessToken(c *gin.Context) string
- func GetContext(c *gin.Context) context.Context
- func GetCurrentUser(c *gin.Context) *user.User
- func GetNamespace(c *gin.Context) context.Context
- func GetOrganization(c *gin.Context) *organization.Organization
- func GetPermissions(c *gin.Context) bit.Field
- func GetToken(c *gin.Context) *accesstoken.AccessToken
- func GetUser(c *gin.Context) *user.User
- func IsValidMethodOverride(method string) bool
- func LiveReload() gin.HandlerFunc
- func Log(c *gin.Context)
- func Logger() gin.HandlerFunc
- func LoginRequired(moduleName string) gin.HandlerFunc
- func LogoutRequired(moduleName string) gin.HandlerFunc
- func MethodOverride() gin.HandlerFunc
- func Namespace() gin.HandlerFunc
- func NotFoundHandler() gin.HandlerFunc
- func OverrideRequestMethod(c *gin.Context, method string) error
- func ParseToken(c *gin.Context)
- func RequestContext() gin.HandlerFunc
- func SetCFCacheTags(c *gin.Context, tags ...string)
- func Static(urlRoot string) gin.HandlerFunc
- func TokenPermits(masks ...bit.Mask) gin.HandlerFunc
- func TokenRequired(masks ...bit.Mask) gin.HandlerFunc
- func UnavailableHandler() gin.HandlerFunc
- type ErrorDisplayer
Constants ¶
const HeaderMethodOverride = "X-HTTP-Method-Override"
HeaderMethodOverride is a commonly used Http header to override the method.
const ParamMethodOverride = "_method"
ParamMethodOverride is a commonly used HTML form parameter to override the method.
Variables ¶
var AppEngine = RequestContext
AppEngine is a legacy alias for RequestContext. Deprecated: use RequestContext instead.
var ErrInvalidOverrideMethod = errors.New("invalid override method")
ErrInvalidOverrideMethod is returned when an invalid http method was given to OverrideRequestMethod.
var GetAppEngine = GetContext
GetAppEngine is a legacy alias for GetContext. Deprecated: use GetContext instead.
var HttpMethods = []string{"PUT", "PATCH", "DELETE"}
Functions ¶
func AccessControl ¶
func AccessControl(allowOrigin string) gin.HandlerFunc
func AccountRequired ¶
func AccountRequired() gin.HandlerFunc
func AcquireOrganization ¶
func AcquireOrganization(moduleName string) gin.HandlerFunc
func AcquireUser ¶
func AcquireUser(moduleName string) gin.HandlerFunc
func AddHost ¶
func AddHost() gin.HandlerFunc
Automatically get the Host header so we can decide what to do with a given request.
func BasicAuth ¶
func BasicAuth() gin.HandlerFunc
func CFCacheTags ¶ added in v1.36.4
func CFCacheTags(tags ...string) gin.HandlerFunc
CFCacheTags returns middleware that sets Cache-Tag header(s). Use on route groups whose entries should be purgeable as a unit.
func CacheNoStore ¶ added in v1.36.4
func CacheNoStore() gin.HandlerFunc
CacheNoStore disables all caching unconditionally. Use on auth flows, checkout, and payment callbacks.
func CachePrivate ¶ added in v1.36.4
func CachePrivate() gin.HandlerFunc
CachePrivate sets Cache-Control: private, no-store. Use on all authenticated per-user or per-org routes. CF will not cache these responses.
func CachePublic ¶ added in v1.36.4
func CachePublic(ttl int) gin.HandlerFunc
CachePublic returns middleware that sets public cache headers with the given TTL.
CF caches for ttl seconds (s-maxage). Browsers cache for ttl/2 seconds to ensure fresh content at browser re-visits. stale-while-revalidate allows CF to serve stale content while fetching fresh in background.
Mutations (POST/PUT/PATCH/DELETE) are always no-store regardless.
func CachePublicTTL ¶ added in v1.36.4
func CachePublicTTL(ttl time.Duration) gin.HandlerFunc
CachePublicTTL is CachePublic accepting a time.Duration.
func CheckLogin ¶
func CheckLogin() gin.HandlerFunc
Updates session with login information, does not require it
func DetectOverrides ¶
func DetectOverrides() gin.HandlerFunc
Check query for special config override params and update session.
func DetectTest ¶
func DetectVerbose ¶
Try and detect verbose flag set on request, we only log DEBUG level in production if verbose=1 is added as a query param.
func EdgeAuth ¶ added in v1.42.38
func EdgeAuth() gin.HandlerFunc
EdgeAuth is the standalone-edge trust boundary for a directly-exposed commerce-api. It is a NO-OP unless COMMERCE_EDGE_AUTH=true, so gateway-fronted deployments (where hanzoai/gateway already strips and mints identity) are untouched — one trust boundary at a time.
When enabled, on every request it:
Strips client-supplied identity headers (anti-spoofing). Without this, `curl -H "X-Org-Id: <org>"` reads any org's billing because downstream trusts the header (gateway is supposed to have stripped it — but commerce-api is not behind the gateway).
If a Bearer IAM JWT is present, verifies it against the IAM JWKS (fail-closed, RSA-pinned) and mints X-Org-Id / X-User-Id / X-User-Email / X-User-IsAdmin / X-User-Permissions from the validated claims, so the existing IAMTokenRequired + handlers resolve the caller's org exactly as in the gateway path.
For /billing/ requests, locks the billing-subject query params (user / userId / customerId) to the caller's own org slug, so a browser can only ever read its OWN org's billing (per-org isolation) regardless of what it puts on the URL.
Service tokens (COMMERCE_SERVICE_TOKEN) and hk-/sk- API keys are left untouched: they are not JWTs, so step 2 skips them and the existing TokenRequired service-token branch authorizes them as before (those callers carry X-Hanzo-Org, never X-Org-Id).
ORDER: EdgeAuth MUST run BEFORE pkg/auth.Gin (both installed by Bootstrap via server.go installIdentityBoundary, ahead of every route group). auth.Gin binds the X-Org-Id header into the request CONTEXT; if EdgeAuth ran after it, stripping the header would leave the spoofed value in the context (which IAMTokenRequired reads first). Mounting EdgeAuth first means auth.Gin only ever sees the stripped/minted headers.
The IAM client is resolved lazily (iammiddleware.Client()) so mount order is independent of when iammiddleware.Init() runs at boot.
func ErrorHandlerJSON ¶
func ErrorHandlerJSON() gin.HandlerFunc
func ErrorLogger ¶
func ErrorLogger() gin.HandlerFunc
func ErrorLoggerT ¶
func ErrorLoggerT(typ gin.ErrorType) gin.HandlerFunc
func GetAccessToken ¶
func GetContext ¶ added in v1.35.2
GetContext retrieves the request context from the Gin context.
func GetOrganization ¶
func GetOrganization(c *gin.Context) *organization.Organization
func GetToken ¶
func GetToken(c *gin.Context) *accesstoken.AccessToken
func IsValidMethodOverride ¶
func LiveReload ¶
func LiveReload() gin.HandlerFunc
func Logger ¶
func Logger() gin.HandlerFunc
func LoginRequired ¶
func LoginRequired(moduleName string) gin.HandlerFunc
Require login to view route
func LogoutRequired ¶
func LogoutRequired(moduleName string) gin.HandlerFunc
Required to be logged out to view
func MethodOverride ¶
func MethodOverride() gin.HandlerFunc
func Namespace ¶
func Namespace() gin.HandlerFunc
Namespace applies the organization's namespace to the request context.
func OverrideRequestMethod ¶
OverrideRequestMethod overrides the http request's method with the specified method.
func ParseToken ¶
func RequestContext ¶ added in v1.35.2
func RequestContext() gin.HandlerFunc
RequestContext extracts the standard Go context from the HTTP request and stores it in the Gin context for downstream handlers.
func SetCFCacheTags ¶ added in v1.36.4
SetCFCacheTags adds Cloudflare Cache-Tag header values to the response. Tags are used for targeted cache purging (e.g. purge all "plans" entries). Multiple calls accumulate; tags are comma-joined as CF requires.
Example: SetCFCacheTags(c, "plans", "org:hanzo")
func Static ¶
func Static(urlRoot string) gin.HandlerFunc
func TokenPermits ¶
func TokenPermits(masks ...bit.Mask) gin.HandlerFunc
Permissions required to access route
func TokenRequired ¶
func TokenRequired(masks ...bit.Mask) gin.HandlerFunc
Parses token, default permissions check
Types ¶
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package iammiddleware is the gateway-trust shim for legacy call sites.
|
Package iammiddleware is the gateway-trust shim for legacy call sites. |