request

func Bytes ¶

func Bytes(request *http.Request, opts ...BodyOption) ([]byte, error)

Bytes reads the request body and returns it as a byte slice. The body is consumed and cannot be read again. A body over the MaxSize limit returns ErrBodyTooLarge. Strict returns ErrStrictUnsupported without reading. Operational failures and problems already supplied by the reader retain their identity rather than being reclassified from an underlying cause.

Example:

data, err := request.Bytes(r, request.MaxSize(1<<20))
if err != nil {
	return err
}
_ = data

func Cookie ¶

func Cookie(r *http.Request, name string) *http.Cookie

Cookie retrieves the named cookie from the HTTP request using http.Request.Cookie. It returns nil if the cookie does not exist. The first parsed cookie with that name wins; malformed cookie entries are handled by net/http rather than surfaced as request input problems here.

Example:

if cookie := request.Cookie(r, "theme"); cookie != nil {
	return response.String(w, http.StatusOK, cookie.Value)
}
return response.Status(w, http.StatusNoContent)

func CookieValue ¶

func CookieValue(r *http.Request, name string) string

CookieValue retrieves the value of the named cookie from the HTTP request. It returns an empty string if the cookie does not exist. An empty cookie value and a missing cookie therefore have the same result; use Cookie when the distinction matters.

Example:

return response.String(w, http.StatusOK, request.CookieValue(r, "theme"))

func CookieValueOr ¶

func CookieValueOr(r *http.Request, name string, fallback string) string

CookieValueOr retrieves the value of the named cookie, falling back to the provided default value if the cookie is missing or empty. It follows Cookie's first-match rule and does not validate application values.

Example:

theme := request.CookieValueOr(r, "theme", "light")
return response.String(w, http.StatusOK, theme)

func Cursor ¶

func Cursor(r *http.Request, opts ...pagination.CursorOption) (pagination.CursorParams, error)

Cursor reads the cursor and per_page query parameters into cursor pagination parameters and normalizes them with pagination.CursorParams.Normalize and opts. A missing per_page uses the default, a present value below one is raised to one, and a value that is not an integer returns ErrInvalidQueryParameter. A maximum below one returns pagination.ErrInvalidConfig.

Example:

params, err := request.Cursor(r)
if err != nil {
	return err
}
_ = params.Cursor

func HasHeader ¶

func HasHeader(r *http.Request, key string) bool

HasHeader reports whether the first value for key is nonempty. A present header with an empty first value reports false, matching HeaderOr's fallback rule rather than testing map-key presence.

Example:

if request.HasHeader(r, "Accept-Language") {
	language := request.Header(r, "Accept-Language")
	_ = language
}

func HasQuery ¶

func HasQuery(r *http.Request, name string) bool

HasQuery reports whether the named parameter exists in net/url's parsed query, regardless of its value. Malformed pairs omitted by net/url are not present. It is a presence check, not validation of the complete raw query string.

Example:

if request.HasQuery(r, "verbose") {
	return response.String(w, http.StatusOK, "verbose mode")
}
return response.Status(w, http.StatusNoContent)

func Header ¶

func Header(r *http.Request, key string) string

Header returns the first value associated with the given header key from the request. It returns an empty string if the header is not present. Header names use the standard http.Header lookup rules; values are not split into comma-separated tokens or otherwise normalized.

Example:

return response.String(w, http.StatusOK, request.Header(r, "Accept-Language"))

func HeaderOr ¶

func HeaderOr(r *http.Request, key string, fallback string) string

HeaderOr returns the first value for the given header key, falling back to the provided default value if the header is missing or empty. Only the first value participates; later header entries do not replace an empty first value.

Example:

language := request.HeaderOr(r, "Accept-Language", "en")
return response.String(w, http.StatusOK, language)

func HeaderValues ¶

func HeaderValues(r *http.Request, key string) []string

HeaderValues returns all values associated with the given header key from the request. It returns nil if the header is not present. Like http.Header.Values, the returned slice aliases the request's values; copy it before mutation if the original header must remain unchanged.

Example:

values := request.HeaderValues(r, "Accept-Language")
return response.JSON(w, http.StatusOK, values)

func JSON ¶

func JSON[T any](request *http.Request, opts ...BodyOption) (value T, err error)

JSON decodes the request body as JSON into a value of type T. Unknown members are ignored unless Strict is given. A body over the MaxSize limit returns ErrBodyTooLarge; malformed JSON returns ErrInvalidJSON. Decoding follows encoding/json/v2: by default member names are case-sensitive, duplicates are rejected, and integers reject fractions and exponents. Content-Type is not checked; use contenttype middleware for that policy. Errors from application unmarshaler methods retain their cause and are not automatically classified as bad input. Such methods must return an explicit problem or JSON syntax/type error when client-facing feedback is intended.

Example:

input, err := request.JSON[CreateUser](r, request.Strict(), request.MaxSize(1<<20))
if err != nil {
	return err
}
_ = input

package main

import (
	"errors"
	"fmt"
	"net/http"

	"arkoren.dev/core/http/request"
)

func main() {
	incoming, err := http.NewRequest(http.MethodPost, "http://example.test/", nil)

	if err != nil {
		fmt.Println(err)

		return
	}

	_, err = request.JSON[struct{}](incoming)
	fmt.Println(errors.Is(err, request.ErrInvalidJSON))
}

Output:
true

func MaxBodySizeFromContext ¶

func MaxBodySizeFromContext(ctx context.Context) (int64, bool)

MaxBodySizeFromContext returns the limit stored in ctx by the bodylimit middleware (arkoren.dev/core/http/middleware/bodylimit) and whether there is one. When ok is false, bodies are limited to DefaultMaxBodySize.

Example:

limit, ok := request.MaxBodySizeFromContext(r.Context())
if !ok {
	limit = request.DefaultMaxBodySize
}
_ = limit

func MustSession ¶

func MustSession(r *http.Request, opts ...SessionOption) *session.Session

MustSession is like Session but panics with session.ErrNoSession when no session is found. It applies the per-call options once through Session.

Example:

current := request.MustSession(r)
if err := current.Put(session.NewField[string]("theme"), "dark"); err != nil {
	return err
}

func Page ¶

func Page(r *http.Request, opts ...pagination.Option) (pagination.PageParams, error)

Page reads the page and per_page query parameters into offset pagination parameters and normalizes them with pagination.PageParams.Normalize and opts. A missing parameter uses the default, a present value below one is raised to one, and a value that is not an integer returns ErrInvalidQueryParameter. A maximum below one returns pagination.ErrInvalidConfig.

Example:

params, err := request.Page(r)
if err != nil {
	return err
}
_ = params.PerPage

func Param ¶

func Param[T Scalar](r *http.Request, name string) (T, error)

Param retrieves the named path parameter (see http.Request.PathValue) and parses it as T. Integers are range checked against T's size, so "300" is rejected for int8. An empty or missing value is an error for every T, including string; use http.Request.PathValue to read a raw string.

It returns ErrInvalidPathParameter with the parameter name and type attached, and the parse error as its cause when there is one.

Example:

id, err := request.Param[int64](r, "id")
if err != nil {
	return err
}
_ = id

func ParamOr ¶

func ParamOr[T Scalar](r *http.Request, name string, fallback T) T

ParamOr is like Param but returns fallback when the parameter is missing or cannot be parsed as T.

Example:

page := request.ParamOr(r, "page", 1)

func ParseJSON ¶

func ParseJSON[T any](request *http.Request, schema validate.Schema[T], opts ...BodyOption) (T, error)

ParseJSON decodes like ValidateJSON and returns the result of schema.Parse: a copy of the decoded value with defaults applied. It preserves the same input-error and operational-error classifications.

Example:

input, err := request.ParseJSON(r, userSchema)
if err != nil {
	return err
}
_ = input

func ParseXML ¶

func ParseXML[T any](request *http.Request, schema validate.Schema[T], opts ...BodyOption) (T, error)

ParseXML decodes like ValidateXML and returns the result of schema.Parse. Native numeric conversion failures remain 400 input problems; operational failures are not converted to schema feedback.

Example:

input, err := request.ParseXML(r, feedSchema)
if err != nil {
	return err
}
_ = input

func Query ¶

func Query[T Scalar](r *http.Request, name string) (T, error)

Query retrieves the first value of the named query parameter and parses it as T, with the same rules as Param. An absent or empty value is an error for every T, including string.

URL decoding follows net/url.URL.Query, including its omission of malformed query pairs. Scalar conversion follows strconv, not a JSON Schema: float types accept NaN and infinities, and bool accepts values such as "1". OpenAPI metadata does not add validation; enforce application constraints separately when the route requires a stricter value or URL grammar.

It returns ErrInvalidQueryParameter with the parameter name and type attached, and the parse error as its cause when there is one.

Example:

limit, err := request.Query[int](r, "limit")
if err != nil {
	return err
}
_ = limit

func QueryOr ¶

func QueryOr[T Scalar](r *http.Request, name string, fallback T) T

QueryOr is like Query but returns fallback when the parameter is absent, empty, or cannot be parsed as T. A present but empty "?q=" therefore also yields the fallback.

Example:

search := request.QueryOr(r, "q", "")

func Session ¶

func Session(r *http.Request, opts ...SessionOption) (*session.Session, bool)

Session returns the session stored on the request by session.Middleware. The boolean reports whether a session was found. Options only select a handle; zero selects default. A stored nil pointer is absent. No session is created, no fallback is attempted, and the request is not mutated.

Example:

current, ok := request.Session(r)
if !ok {
	return session.ErrNoSession
}
if err := current.Put(session.NewField[string]("theme"), "dark"); err != nil {
	return err
}

func String ¶

func String(request *http.Request, opts ...BodyOption) (string, error)

String reads the request body and returns it as a string without UTF-8 validation. It follows the rules of Bytes, including the size limit and ErrStrictUnsupported.

Example:

text, err := request.String(r, request.MaxSize(4096))
if err != nil {
	return err
}
_ = text

func User ¶

func User[U any](r *http.Request) (U, error)

User returns the user of type U stored on the request by auth.Middleware. It returns auth.ErrUnauthenticated when there is none.

Example:

user, err := request.User[User](r)
if err != nil {
	return err
}
_ = user.ID

func ValidateJSON ¶

func ValidateJSON[T any](request *http.Request, schema validate.Schema[T], opts ...BodyOption) (T, error)

ValidateJSON decodes the request body as JSON like JSON and checks the value against schema. Defaults are not applied; use ParseJSON for that. Strict turns unknown members into "unknown" violations; MaxSize and Unlimited change the size limit (see DefaultMaxBodySize).

Malformed syntax, including duplicate names, returns ErrInvalidJSON (400). Native semantic failures become "decode" violations at the decoder's JSON Pointer, merged with schema violations under ErrValidationFailed (422). The native semantic cause remains available through errors.As/errors.Is in that 422 result. Schema infrastructure failures take precedence instead. Strict unknown members retain "unknown"; schema violation codes are unchanged. Ordinary application unmarshaler failures pass through without conversion.

A "decode" violation never supplies params.expected: the native Go type does not establish the field's wire format. Optional params.default_representation describes that type's default representation only. For example, an integer field tagged with ,string still has an "integer" default hint, but requires a quoted number. Opaque custom JSON methods and unsupported Go kinds have no hint; time.Duration has no default representation. The safe generic message excludes native error text, input values, and Go type names. Add a "decode" entry to the validation catalog to translate it; the built-in fallback is English. See the package documentation for partial-decoding limits.

Example:

input, err := request.ValidateJSON(r, userSchema, request.Strict(), request.MaxSize(1<<20))
if err != nil {
	return err
}
_ = input

package main

import (
	"errors"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"arkoren.dev/core/http/request"
	"arkoren.dev/foundation/validate"
)

func main() {
	type input struct {
		// Data uses the default base64-encoded JSON string representation.
		Data []byte `json:"data"`
	}
	incoming := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"data":42}`))

	_, err := request.ValidateJSON(incoming, validate.Struct[input]())
	errs, ok := errors.AsType[validate.Errors](err)

	if !ok {
		fmt.Println(err)

		return
	}

	fmt.Println(errs["/data"][0].Params["default_representation"])
}

Output:
string

func ValidateXML ¶

func ValidateXML[T any](request *http.Request, schema validate.Schema[T], opts ...BodyOption) (T, error)

ValidateXML decodes the request body as XML like XML and checks the value against schema. Defaults are not applied. Native XML input errors, including invalid numeric fields, stay ErrInvalidXML (400), because XML errors carry no JSON Pointer. Operational errors pass through unchanged. Strict returns ErrStrictUnsupported before reading. Limits work as for XML.

Example:

input, err := request.ValidateXML(r, feedSchema)
if err != nil {
	return err
}
_ = input

func ValidationProblem ¶

func ValidationProblem(err error) error

ValidationProblem converts a validate.Errors found anywhere in err's chain to ErrValidationFailed (422) carrying the violations as the "errors" member, with err kept as the cause for logging and tracing. A nil err returns nil, and any other error is returned unchanged.

The Validate* and Parse* helpers already apply it. Call it for errors from schema.Validate or schema.Parse used directly. Its signature also fits the errormap package, so one registration covers every handler:

r.Use(errormap.Middleware(errormap.Func(request.ValidationProblem)))

Example:

if err := schema.Validate(ctx, input); err != nil {
	return request.ValidationProblem(err)
}

func XML ¶

func XML[T any](request *http.Request, opts ...BodyOption) (value T, err error)

XML decodes the request body as XML into a value of type T with a streaming decoder. A body over the MaxSize limit returns ErrBodyTooLarge; malformed XML or invalid numeric fields return ErrInvalidXML. Operational read failures and ordinary application decoder errors retain their cause without becoming input problems. Strict returns ErrStrictUnsupported without reading the body.

Only the first XML element is decoded; trailing data is ignored. encoding/xml does not expand DTD entities, so entity expansion attacks such as "Billion Laughs" do not apply.

Example:

feed, err := request.XML[Feed](r, request.MaxSize(1<<20))
if err != nil {
	return err
}
_ = feed