Documentation
¶
Index ¶
- Constants
- func ParseBearer(header http.Header) (string, error)
- func RequestID(ctx context.Context) string
- type AuthOption
- type AuthenticatedRequest
- type Body
- type Option
- type Request
- type StandardRequest
- func (r StandardRequest) Authenticate(opts ...AuthOption) (*AuthenticatedRequest, error)
- func (r *StandardRequest) GetBody() Body
- func (r *StandardRequest) GetClient() string
- func (r *StandardRequest) GetContext() context.Context
- func (r *StandardRequest) GetCreatedAt() time.Time
- func (r *StandardRequest) GetHeader() http.Header
- func (r *StandardRequest) GetID() string
- func (r *StandardRequest) GetIP() string
- func (r *StandardRequest) GetLocale() string
- func (r StandardRequest) LegacyCredentials(keyHeader, secretHeader string) (string, string, error)
- func (r *StandardRequest) SetBody(body Body)
- func (r *StandardRequest) SetContext(ctx context.Context)
- func (r *StandardRequest) SetLocale(locale string)
Constants ¶
const DEFAULT_TIMEOUT = 15 * time.Second
Variables ¶
This section is empty.
Functions ¶
func ParseBearer ¶ added in v1.18.0
ParseBearer returns the token of a well-formed "Bearer <token>" Authorization header. It is the single parser for the module; mcp uses it too. The scheme compares case-insensitively and is separated from the non-empty token by one or more spaces or tabs, as RFC 7235 allows. The token itself contains no whitespace. An absent header is ENOTAUTHENTICATED; a present but malformed one, or more than one, is EINVALID, so callers can tell "no credentials" from "bad credentials" with ez.ErrorCode.
Types ¶
type AuthOption ¶ added in v1.18.0
type AuthOption func(*authConfig)
AuthOption configures where Authenticate looks for credentials besides the Authorization header.
func WithCookie ¶ added in v1.18.0
func WithCookie(name string, allowedOrigins ...string) AuthOption
WithCookie reads the token from the named cookie when no Authorization header is present. Requests authenticated by cookie must pass the CSRF rule: a method other than GET, HEAD or OPTIONS needs an Origin header listed in allowedOrigins (exact match). With no allowedOrigins, cookies authenticate only GET, HEAD and OPTIONS. The method comes from WithMethod; a request without one is treated as unsafe.
type AuthenticatedRequest ¶
type AuthenticatedRequest struct {
StandardRequest
// Token is the bearer token from the Authorization header, or the cookie
// named by WithCookie when the header is absent.
Token string
// FromCookie is true when Token came from a cookie rather than the
// Authorization header.
FromCookie bool
}
type Option ¶
type Option func(*StandardRequest)
Option is a function that modifies the Request.
func WithMethod ¶ added in v1.18.0
WithMethod returns an Option that records the HTTP method of the request, for example c.Request().Method. Pass it when Authenticate may accept a cookie: the CSRF rule treats a request without a method as unsafe, so a cookie then needs an allowed Origin on every method.
func WithTimeout ¶
WithTimeout returns an Option that sets the timeout for the request context. It replaces the previous deadline and releases the timer of the context it replaces, keeping the context values.
type StandardRequest ¶
type StandardRequest struct {
ID string
IP string
Client string
Header http.Header
Body Body
CreatedAt time.Time
Context context.Context
Cancel context.CancelFunc
Locale string
// Method is the HTTP method, set by WithMethod. Authenticate needs it to
// apply the CSRF rule of WithCookie; empty counts as unsafe.
Method string
}
func (StandardRequest) Authenticate ¶
func (r StandardRequest) Authenticate(opts ...AuthOption) (*AuthenticatedRequest, error)
Authenticate reads the credentials of the request, in order: the Authorization bearer token, then the WithCookie cookie. A malformed Authorization header is EINVALID and the cookie is not tried. A request with no credentials is ENOTAUTHENTICATED. Authenticate only extracts credentials; the caller verifies them.
func (*StandardRequest) GetBody ¶
func (r *StandardRequest) GetBody() Body
func (*StandardRequest) GetClient ¶
func (r *StandardRequest) GetClient() string
func (*StandardRequest) GetContext ¶
func (r *StandardRequest) GetContext() context.Context
func (*StandardRequest) GetCreatedAt ¶
func (r *StandardRequest) GetCreatedAt() time.Time
func (*StandardRequest) GetHeader ¶
func (r *StandardRequest) GetHeader() http.Header
func (*StandardRequest) GetID ¶
func (r *StandardRequest) GetID() string
func (*StandardRequest) GetIP ¶
func (r *StandardRequest) GetIP() string
func (*StandardRequest) GetLocale ¶ added in v1.9.2
func (r *StandardRequest) GetLocale() string
GetLocale returns the locale used to localize the response, e.g. "es-MX". New negotiates it from the Accept-Language header, so it is always set.
func (StandardRequest) LegacyCredentials ¶ added in v1.18.0
func (r StandardRequest) LegacyCredentials(keyHeader, secretHeader string) (string, string, error)
LegacyCredentials returns the legacy header pair, for REST APIs that keep API-key clients working while they move to Authorization: Bearer. It reads nothing else. Both headers absent is ez.ENOTAUTHENTICATED; only one present is ez.EINVALID. Compose it after Authenticate and fall through only on ez.ENOTAUTHENTICATED, so a malformed Authorization header or a cookie that fails the CSRF rule is still refused rather than retried with the pair:
authReq, err := req.Authenticate()
if ez.ErrorCode(err) == ez.ENOTAUTHENTICATED {
key, secret, err := req.LegacyCredentials("API-KEY", "API-SECRET")
if err != nil {
return ez.Wrap(err)
}
return resolveLegacy(key, secret)
}
if err != nil {
return ez.Wrap(err)
}
func (*StandardRequest) SetBody ¶
func (r *StandardRequest) SetBody(body Body)
func (*StandardRequest) SetContext ¶
func (r *StandardRequest) SetContext(ctx context.Context)
func (*StandardRequest) SetLocale ¶ added in v1.9.2
func (r *StandardRequest) SetLocale(locale string)
SetLocale overrides the negotiated locale, e.g. with an authenticated user's saved preference.
Source Files