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 NoRules
- type Option
- type Request
- type StandardRequest
- func (r StandardRequest) Authenticate(opts ...AuthOption) (*AuthenticatedRequest, error)
- func (r *StandardRequest) GetAccept() string
- 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) SetAccept(mediaType string)
- 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 NoRules ¶ added in v1.31.0
type NoRules struct{}
NoRules is embedded by request types that have no cross-field validation rules. Shape rules (required, format, enum, ranges) live in struct tags and are enforced by the OpenAPI registry before the request reaches the handler, so Validate only exists to satisfy Body.
Do not embed it next to another embedded type that already has a Validate method (for example pagination.CursorRequest): the two promoted methods are ambiguous and the request type stops implementing Body, which the compiler reports at the registration call.
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 a timeout on the request context. It derives the new context from the current one, so the request keeps its values and cancellation, and its deadline is the earlier of the current deadline and timeout. As an option of New or NewWithContext it replaces DEFAULT_TIMEOUT: the deadline is timeout with New, and the earlier of the parent's deadline and timeout with NewWithContext. Applied again later it can only shorten the deadline, never extend it. Cancel releases every timer the request holds.
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
// Accept is the response media type the operation chose, set by SetAccept.
Accept string
// contains filtered or unexported fields
}
func New ¶
func New(header http.Header, ip string, opts ...Option) *StandardRequest
New returns the request of one handler call. Its context derives from context.Background, carries the request ID and times out after DEFAULT_TIMEOUT. A WithTimeout option replaces that default, so the deadline is exactly its timeout; applied to the request later, WithTimeout can only shorten the deadline. Use NewWithContext to tie the request to a parent context. 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 NewWithContext ¶ added in v1.31.0
func NewWithContext(parent context.Context, header http.Header, ip string, opts ...Option) *StandardRequest
NewWithContext is New with the request context derived from parent: the request sees parent's values and is cancelled when parent is, and its deadline is the earlier of parent's deadline and the request timeout (DEFAULT_TIMEOUT, or the timeout of a WithTimeout option, which replaces the default). Applied to the request later, WithTimeout can only shorten the deadline.
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) GetAccept ¶ added in v1.31.0
func (r *StandardRequest) GetAccept() string
GetAccept returns the response media type chosen for the request, e.g. "text/csv". The api registry sets it from the Accept header and the operation's declared media types (application/json when none are declared); it is empty for requests built outside the registry.
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) SetAccept ¶ added in v1.31.0
func (r *StandardRequest) SetAccept(mediaType string)
SetAccept sets the response media type chosen for the request.
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