extractors

func Chain ¶

func Chain(extractors ...Extractor) Extractor

Chain creates an Extractor that tries multiple extractors in order until one succeeds. This implements a fallback pattern where multiple extraction sources are attempted in sequence.

The function:

• Tries each extractor in the order provided
• Returns the first successful extraction (non-empty value with no error)
• Skips children with a nil Extract function
• Returns the last error encountered if all extractors fail
• Returns ErrNotFound if no extractors are provided or all return empty values
• Resolve on a chain walks the same children and reports the winning extractor

Parameters:

• extractors: A variadic list of Extractor instances to try in sequence. The order matters - more secure/preferred sources should be listed first.

Returns:

An Extractor that attempts each provided extractor in order.
The returned extractor uses the Source and Key from the first extractor for
static metadata. Resolve reports the winning child.

Behavior:

• Success: Returns the first non-empty value with no error
• Partial failure: Continues to next extractor if current returns error or empty value
• Total failure: Returns last error encountered, or ErrNotFound if no errors
• Empty chain: Always returns ErrNotFound
• Extract and Resolve share one cycle guard so a child that re-enters the same chain still returns ErrChainCycle. The guard is cleared on return, so sequential Extract then Resolve is fine.

Examples:

// Try header first, then cookie, then query param
extractor := Chain(
    FromHeader("Authorization"),
    FromCookie("auth_token"),
    FromQuery("token"),
)

// API key from multiple possible sources
apiKeyExtractor := Chain(
    FromHeader("X-API-Key"),
    FromQuery("api_key"),
    FromForm("apiKey"),
)

Security Note:

Order extractors by security preference. Most secure sources (headers, cookies)
should be attempted before less secure ones (query params, form data).

func FromAuthHeader ¶

func FromAuthHeader(authScheme string) Extractor

FromAuthHeader extracts a value from the Authorization header with an optional prefix. This function implements RFC 9110 compliant Authorization header parsing with strict token68 validation.

RFC Compliance:

• Follows RFC 9110 Section 11.6.2 for Authorization header format
• Requires exactly one SP between auth-scheme and credentials. RFC 9110 permits 1*SP, but a single space is what clients send in practice and the stricter rule keeps the parse unambiguous.
• Implements RFC 7235 token68 character validation for extracted tokens
• Case-insensitive auth scheme matching per HTTP standards

Token68 Validation:

• Only allows characters: A-Z, a-z, 0-9, -, ., _, ~, +, /, =
• Rejects tokens containing spaces, tabs, or other whitespace
• Validates proper padding: = only at end, no characters after padding starts
• Prevents tokens starting with = (invalid padding)

Security Features:

• Strict validation prevents header injection attacks
• Rejects malformed tokens that could bypass authentication
• Consistent error handling for missing or invalid credentials

Parameters:

• authScheme: The auth scheme to strip from the header value (e.g., "Bearer", "Basic"). If empty, the entire header value is returned without validation.

Returns:

An Extractor that attempts to retrieve and parse the Authorization header.
Returns ErrNotFound if the header is missing, malformed, or doesn't match the expected scheme.

Examples:

// Extract Bearer token with validation
extractor := FromAuthHeader("Bearer")
// Input: "Bearer abc123" -> Output: "abc123"
// Input: "Bearer abc def" -> Output: ErrNotFound (space in token)
// Input: "Basic dXNlcjpwYXNz" -> Output: ErrNotFound (wrong scheme)

// Extract raw header value (no validation)
extractor := FromAuthHeader("")
// Input: "CustomAuth token123" -> Output: "CustomAuth token123"

func FromCookie ¶

func FromCookie(key string) Extractor

FromCookie creates an Extractor that retrieves a value from a specified cookie in the request.

The function:

• Retrieves the cookie value using the specified name
• Returns ErrNotFound if the cookie is missing

Parameters:

• key: The name of the cookie from which to extract the value.

Returns:

An Extractor that attempts to retrieve the value from the specified cookie.
Returns ErrNotFound if the cookie is not present.

Security Note:

Cookies are generally more secure than query parameters for sensitive data
as they are not logged in access logs or visible in browser history.
However, ensure cookies are properly secured with appropriate flags.

Example:

extractor := FromCookie("session_id")
// Cookie: "session_id=abc123" -> Output: "abc123"
// Missing cookie -> Output: ErrNotFound

func FromCustom ¶

func FromCustom(key string, fn func(fiber.Ctx) (string, error)) Extractor

FromCustom creates an Extractor using a provided function. This allows for custom extraction logic beyond the built-in extractors.

The function:

• Accepts a custom extraction function with signature func(fiber.Ctx) (string, error)
• Handles nil functions gracefully by returning ErrNotFound
• Preserves the custom function for execution

Parameters:

• key: A descriptive identifier for the custom extractor. Used for debugging, logging, and Chain metadata. Should be meaningful for introspection. Examples: "X-Custom-Header", "Database-Lookup", "Cache-Key"
• fn: The custom function to extract the value from the fiber.Ctx. If nil, the extractor will return ErrNotFound when executed. The function should return (value, nil) on success or ("", error) on failure.

Returns:

An Extractor that uses the provided function for extraction.
If fn is nil, the returned extractor will always return ErrNotFound.

Examples:

// Custom header with transformation
extractor := FromCustom("X-API-Key", func(c fiber.Ctx) (string, error) {
    value := c.Get("X-API-Key")
    if value == "" {
        return "", ErrNotFound
    }
    return strings.ToUpper(value), nil
})

// Database lookup (pseudo-code)
userExtractor := FromCustom("user-from-db", func(c fiber.Ctx) (string, error) {
    userID := c.Params("userId")
    user, err := db.GetUser(userID)
    if err != nil {
        return "", err
    }
    return user.Name, nil
})

// Conditional extraction
smartExtractor := FromCustom("smart-auth", func(c fiber.Ctx) (string, error) {
    if c.Get("X-Service-Auth") != "" {
        return c.Get("X-Service-Auth"), nil
    }
    return c.Cookies("session"), nil
})

func FromForm ¶

func FromForm(param string) Extractor

FromForm creates an Extractor that retrieves a value from a specified form field in the request. Form data is typically submitted via POST requests with content-type application/x-www-form-urlencoded.

SECURITY WARNING: Extracting values from form data can leak sensitive information through:

• Server access logs and error logs
• Browser referrer headers (especially if form is submitted via GET)
• Proxy and intermediary server logs
• Browser history (if form uses GET method)

For sensitive data, prefer FromAuthHeader or FromCookie instead. If using form data, ensure the form uses POST method and HTTPS.

Parameters:

• param: The name of the form field from which to extract the value.

Returns:

An Extractor that attempts to retrieve the value from the specified form field.
Returns ErrNotFound if the field is not present.

Example:

extractor := FromForm("username")
// Form data: "username=john_doe&password=secret" -> Output: "john_doe"
// Missing field -> Output: ErrNotFound

func FromHeader ¶

func FromHeader(header string) Extractor

FromHeader creates an Extractor that retrieves a value from a specified HTTP header in the request. HTTP headers are commonly used for API keys, tokens, and other metadata.

The function:

• Retrieves the header value using the specified name
• Returns ErrNotFound if the header is missing

Parameters:

• header: The name of the HTTP header from which to extract the value.

Returns:

An Extractor that attempts to retrieve the value from the specified HTTP header.
Returns ErrNotFound if the header is not present.

Security Note:

Headers are generally secure for sensitive data as they are not logged
in access logs by default. However, be aware that some proxies may log headers.

Example:

extractor := FromHeader("X-API-Key")
// Header: "X-API-Key: abc123" -> Output: "abc123"
// Missing header -> Output: ErrNotFound

func FromParam ¶

func FromParam(param string) Extractor

FromParam creates an Extractor that retrieves a value from a specified URL parameter in the request. URL parameters are extracted from the route path (e.g., /users/:id).

SECURITY WARNING: Extracting values from URL parameters can leak sensitive information through:

• Server access logs and error logs
• Browser referrer headers when following links
• Proxy and intermediary server logs
• Browser history and bookmarks
• Network monitoring tools

For sensitive data, prefer FromAuthHeader, FromCookie, or FromHeader instead.

Parameters:

• param: The name of the URL parameter from which to extract the value.

Returns:

An Extractor that attempts to retrieve the value from the specified URL parameter.
Returns ErrNotFound if the parameter is not present.

Example:

// Route: GET /users/:userId/posts/:postId
userExtractor := FromParam("userId")
postExtractor := FromParam("postId")
// URL: /users/123/posts/456 -> userId: "123", postId: "456"

func FromQuery ¶

func FromQuery(param string) Extractor

FromQuery creates an Extractor that retrieves a value from a specified query parameter in the request. Query parameters are extracted from the URL query string (e.g., ?key=value&foo=bar).

SECURITY WARNING: Extracting values from URL query parameters can leak sensitive information through:

• Server access logs and error logs
• Browser referrer headers when following links
• Proxy and intermediary server logs
• Browser history and bookmarks
• Network monitoring tools and packet sniffers
• Web browser developer tools

For sensitive data, prefer FromAuthHeader, FromCookie, or FromHeader instead. If query parameters must be used, ensure HTTPS is enforced.

Parameters:

• param: The name of the query parameter from which to extract the value.

Returns:

An Extractor that attempts to retrieve the value from the specified query parameter.
Returns ErrNotFound if the parameter is not present.

Example:

extractor := FromQuery("token")
// URL: /api/data?token=abc123&format=json -> Output: "abc123"
// URL: /api/data?format=json -> Output: ErrNotFound

func Resolve ¶ added in v3.6.0

func Resolve(e Extractor, c fiber.Ctx) (Result, error)

Resolve extracts a value and reports which extractor supplied it.

Prefer this over Extract when the caller needs a value's provenance — its Key as well as its Source — such as to write the value back where it was read from. It adds no field to Extractor, so unkeyed literals keep compiling.

Extract runs when set, so overrides and decoration are honored. A built-in Chain records its winning child as it runs, and only a record made by the chain being resolved counts, so a value is never credited to a chain some unrelated helper ran. Without such a record the declared metadata is reported with Resolved false rather than re-walking e.Chain to guess. An extractor with no Extract walks its own Chain instead, nested ones included; a built-in chain still runs only the children it can run. An extractor with neither returns ErrNotFound.

Key and Source are meaningful for security decisions only when err is nil and Resolved is true.