Documentation
¶
Index ¶
- Constants
- func ParseBearer(header http.Header) (string, error)
- func RequestID(ctx context.Context) string
- func SetRequestID(header http.Header, id 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.
func RequestID ¶ added in v1.17.0
RequestID returns the request ID New stored in ctx, or "" when ctx does not come from a request.
func SetRequestID ¶ added in v1.29.0
SetRequestID stores id in header as the ID New gives the request it builds from header. rest.Configure does it for every request, with the id the response carries as X-Request-Id; an app with a middleware stack of its own calls it from a middleware to the same end. A client cannot set this ID, see requestIDHeader. The entry stays in header, so a dump of the request headers or a copy of them onto an outbound request shows it, as compose-request-id; a server receiving that copy canonicalises the name, so it does not read it as its own.
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 New ¶
func New(header http.Header, ip string, opts ...Option) *StandardRequest
New returns the request of one handler call. Its ID is the one SetRequestID stored in header, which under rest.Configure is the id the response carries as X-Request-Id and the request log line as id, and a new UUID when none was stored. No header a client sends sets it, X-Request-Id included.
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