mirror of
https://github.com/gofiber/fiber.git
synced 2025-09-04 19:35:47 +00:00
111 lines
4.4 KiB
Markdown
111 lines
4.4 KiB
Markdown
# Extractors Package
|
|
|
|
Package providing shared value extraction utilities for Fiber middleware packages.
|
|
|
|
## Audience
|
|
|
|
**This README is targeted at middleware developers and contributors.** If you are a Fiber framework user looking to use extractors in your application, please refer to the [Extractors Guide](https://docs.gofiber.io/guide/extractors) instead.
|
|
|
|
## Architecture
|
|
|
|
### Core Types
|
|
|
|
- `Extractor`: Core extraction function with metadata
|
|
- `Source`: Enumeration of extraction sources (Header, AuthHeader, Query, Form, Param, Cookie, Custom)
|
|
- `ErrNotFound`: Standardized error for missing values
|
|
|
|
### Extractor Structure
|
|
|
|
```go
|
|
type Extractor struct {
|
|
Extract func(fiber.Ctx) (string, error) // Extraction function
|
|
Key string // Parameter/header name
|
|
Source Source // Source type for inspection
|
|
AuthScheme string // Auth scheme (FromAuthHeader)
|
|
Chain []Extractor // Chained extractors
|
|
}
|
|
```
|
|
|
|
### Available Functions
|
|
|
|
- `FromAuthHeader(authScheme string)`: Extract from Authorization header with optional scheme
|
|
- `FromCookie(key string)`: Extract from HTTP cookies
|
|
- `FromParam(param string)`: Extract from URL path parameters
|
|
- `FromForm(param string)`: Extract from form data
|
|
- `FromHeader(header string)`: Extract from custom HTTP headers
|
|
- `FromQuery(param string)`: Extract from URL query parameters
|
|
- `FromCustom(key string, fn func(fiber.Ctx) (string, error))`: Define custom extraction logic with metadata
|
|
- `Chain(extractors ...Extractor)`: Chain multiple extractors with fallback
|
|
|
|
### Source Inspection
|
|
|
|
The `Source` field enables security-aware extraction by identifying the origin of extracted values:
|
|
|
|
```go
|
|
switch extractor.Source {
|
|
case SourceAuthHeader:
|
|
// Authorization header - commonly used for authentication tokens
|
|
case SourceHeader:
|
|
// Custom HTTP headers - application-specific data
|
|
case SourceCookie:
|
|
// HTTP cookies - client-side stored data
|
|
case SourceQuery:
|
|
// URL query parameters - visible in URLs and logs (security consideration)
|
|
case SourceForm:
|
|
// Form data - POST body data
|
|
case SourceParam:
|
|
// URL path parameters - route-based data
|
|
case SourceCustom:
|
|
// Custom extraction logic
|
|
}
|
|
```
|
|
|
|
### Chain Behavior
|
|
|
|
The `Chain` function implements fallback logic:
|
|
|
|
- Returns first successful extraction (non-empty value, no error)
|
|
- If all extractors fail, returns the last error encountered or `ErrNotFound`
|
|
- **Skips extractors with `nil` Extract functions** (graceful error handling)
|
|
- Preserves metadata from first extractor for introspection
|
|
- Stores defensive copy for runtime inspection via the `Chain` field
|
|
|
|
## Security Considerations
|
|
|
|
### Source Awareness and Custom Extractors
|
|
|
|
The `Source` field enables security-aware extraction by identifying the origin of extracted values. However, when using `FromCustom`, middleware cannot determine the source of the extracted value, which can compromise security:
|
|
|
|
- **CSRF Protection**: The double-submit-cookie pattern requires tokens to come from cookies. Custom extractors may read from insecure sources without middleware being able to detect or prevent this
|
|
- **Authentication**: Security middleware may not be able to enforce source-specific security policies
|
|
- **Audit Trails**: Source information is lost, making security analysis more difficult
|
|
|
|
Documentation and examples should clearly warn about these risks when using custom extractors.
|
|
|
|
## Testing
|
|
|
|
Run the comprehensive test suite:
|
|
|
|
```bash
|
|
go test -v ./extractors
|
|
```
|
|
|
|
Tests cover:
|
|
|
|
- Individual extractor functionality across all source types
|
|
- Error handling and edge cases (whitespace, empty values, malformed headers)
|
|
- Chained extractor behavior and error propagation
|
|
- Custom extractor support including nil function handling
|
|
- RFC 7235 compliance for Authorization header parsing
|
|
- Metadata validation and source introspection
|
|
- Chain ordering and fallback logic (17 comprehensive test functions)
|
|
|
|
## Maintenance Notes
|
|
|
|
- **Single Source of Truth**: All extraction logic lives here
|
|
- **Direct Usage**: Middleware imports and uses extractors directly
|
|
- **Security Consistency**: Security warnings and source awareness must be kept in sync across all extractors
|
|
- **Breaking Changes**: Require coordinated updates across dependent packages
|
|
- **Performance**: Shared functions reduce overhead across middleware
|
|
- **Documentation**: Ensure examples and warnings are clear and up-to-date
|