Module: Philiprehberger::HeaderKit

Defined in:
lib/philiprehberger/header_kit.rb,
lib/philiprehberger/header_kit/cors.rb,
lib/philiprehberger/header_kit/etag.rb,
lib/philiprehberger/header_kit/link.rb,
lib/philiprehberger/header_kit/range.rb,
lib/philiprehberger/header_kit/accept.rb,
lib/philiprehberger/header_kit/cookie.rb,
lib/philiprehberger/header_kit/version.rb,
lib/philiprehberger/header_kit/security.rb,
lib/philiprehberger/header_kit/forwarded.rb,
lib/philiprehberger/header_kit/negotiation.rb,
lib/philiprehberger/header_kit/retry_after.rb,
lib/philiprehberger/header_kit/content_type.rb,
lib/philiprehberger/header_kit/authorization.rb,
lib/philiprehberger/header_kit/cache_control.rb,
lib/philiprehberger/header_kit/accept_builder.rb,
lib/philiprehberger/header_kit/accept_encoding.rb,
lib/philiprehberger/header_kit/accept_language.rb

Defined Under Namespace

Modules: Accept, AcceptBuilder, AcceptEncoding, AcceptLanguage, Authorization, CacheControl, ContentType, Cookie, Cors, Etag, Forwarded, Link, Negotiation, Range, RetryAfter, Security Classes: Error

Constant Summary collapse

VERSION = 
'0.7.0'

Class Method Summary collapse

Class Method Details

.build_accept(types) ⇒ String

Build an Accept header string from an array of type hashes.

Parameters:

  • types (Array<Hash>) —

    each with :type and optional :quality

Returns:

  • (String) —

    formatted Accept header value



37
38
39
 
# File 'lib/philiprehberger/header_kit.rb', line 37

def self.build_accept(types)
  AcceptBuilder.build(types)
end

.build_accept_encoding(encodings) ⇒ String

Build an Accept-Encoding header string from an array of encoding hashes.

Parameters:

  • encodings (Array<Hash>) —

    each with :encoding and optional :quality

Returns:

  • (String) —

    formatted Accept-Encoding header value



53
54
55
 
# File 'lib/philiprehberger/header_kit.rb', line 53

def self.build_accept_encoding(encodings)
  AcceptEncoding.build(encodings)
end

.build_cache_control(directives) ⇒ String

Build a Cache-Control header string from a directive hash.

Parameters:

  • directives (Hash{Symbol => true, Integer, String}) —

    directive hash

Returns:

  • (String) —

    formatted Cache-Control header value



94
95
96
 
# File 'lib/philiprehberger/header_kit.rb', line 94

def self.build_cache_control(directives)
  CacheControl.build(directives)
end

.build_cors(**options) ⇒ Hash{String => String}

Build CORS response headers.

Parameters:

  • options (Hash) —

    CORS options (origin:, methods:, headers:, max_age:, credentials:, expose:)

Returns:

  • (Hash{String => String}) —

    response headers



161
162
163
 
# File 'lib/philiprehberger/header_kit.rb', line 161

def self.build_cors(**options)
  Cors.build(**options)
end

.build_link(links) ⇒ String

Build a Link header string from an array of link hashes.

Parameters:

  • links (Array<Hash>) —

    each with :uri and optional :rel, :type, :title

Returns:

  • (String) —

    formatted Link header value



136
137
138
 
# File 'lib/philiprehberger/header_kit.rb', line 136

def self.build_link(links)
  Link.build(links)
end

.build_range(unit, ranges) ⇒ String

Build a Range request header value.

Parameters:

  • unit (String) —

    the range unit (e.g. ‘bytes’)

  • ranges (Array<Hash, Array, ::Range>) —

    each as ‘{ first:, last: }`, `[first, last]`, or `::Range`

Returns:

  • (String) —

    formatted Range header



215
216
217
 
# File 'lib/philiprehberger/header_kit.rb', line 215

def self.build_range(unit, ranges)
  Range.build(unit, ranges)
end

.build_set_cookie(name, value, **options) ⇒ String

Build a Set-Cookie header string.

Parameters:

  • name (String) —

    cookie name

  • value (String) —

    cookie value

  • options (Hash) —

    optional attributes (expires:, max_age:, secure:, httponly:, samesite:, path:, domain:)

Returns:

  • (String) —

    formatted Set-Cookie header value



120
121
122
 
# File 'lib/philiprehberger/header_kit.rb', line 120

def self.build_set_cookie(name, value, **options)
  Cookie.build_set_cookie(name, value, **options)
end

.etag_match?(header_value, resource_etag) ⇒ Boolean

Check whether an If-None-Match / If-Match header matches a resource ETag.

Accepts a single ETag, comma-separated list, weak-prefixed values (e.g. ‘W/“abc”`), or the `*` wildcard. Weak and strong ETags collapse to equality on the inner token.

Parameters:

  • header_value (String, nil) —

    the raw header value

  • resource_etag (String, nil) —

    the resource ETag (unquoted, no ‘W/` prefix)

Returns:

  • (Boolean) —

    true if any value in the header matches the resource



198
199
200
 
# File 'lib/philiprehberger/header_kit.rb', line 198

def self.etag_match?(header_value, resource_etag)
  Etag.match?(header_value, resource_etag)
end

.negotiate(accept_header, available) ⇒ String?

Find the best matching media type via content negotiation.

Parameters:

  • accept_header (String) —

    the Accept header value

  • available (Array<String>) —

    list of available media types

Returns:

  • (String, nil) —

    the best matching type, or nil if no match



145
146
147
 
# File 'lib/philiprehberger/header_kit.rb', line 145

def self.negotiate(accept_header, available)
  Negotiation.negotiate(accept_header, available)
end

.negotiate_language(header, available) ⇒ String?

Negotiate the best language from an Accept-Language header.

Parameters:

  • header (String) —

    the Accept-Language header value

  • available (Array<String>) —

    list of available language tags

Returns:

  • (String, nil) —

    the best matching language, or nil if no match



70
71
72
 
# File 'lib/philiprehberger/header_kit.rb', line 70

def self.negotiate_language(header, available)
  AcceptLanguage.negotiate(header, available)
end

.parse_accept(header) ⇒ Array<Hash>

Parse an Accept header into structured entries sorted by quality.

Parameters:

  • header (String) —

    the Accept header value

Returns:

  • (Array<Hash>) —

    entries with :type, :quality, :params keys



29
30
31
 
# File 'lib/philiprehberger/header_kit.rb', line 29

def self.parse_accept(header)
  Accept.parse(header)
end

.parse_accept_encoding(header) ⇒ Array<Hash>

Parse an Accept-Encoding header into structured entries sorted by quality.

Parameters:

  • header (String) —

    the Accept-Encoding header value

Returns:

  • (Array<Hash>) —

    entries with :encoding, :quality keys



45
46
47
 
# File 'lib/philiprehberger/header_kit.rb', line 45

def self.parse_accept_encoding(header)
  AcceptEncoding.parse(header)
end

.parse_accept_language(header) ⇒ Array<Hash>

Parse an Accept-Language header into structured entries sorted by quality.

Parameters:

  • header (String) —

    the Accept-Language header value

Returns:

  • (Array<Hash>) —

    entries with :language, :quality keys



61
62
63
 
# File 'lib/philiprehberger/header_kit.rb', line 61

def self.parse_accept_language(header)
  AcceptLanguage.parse(header)
end

.parse_authorization(header) ⇒ Hash

Parse an Authorization header into its components.

Parameters:

  • header (String) —

    the Authorization header value

Returns:

  • (Hash) —

    with :scheme and :credentials or :params



78
79
80
 
# File 'lib/philiprehberger/header_kit.rb', line 78

def self.parse_authorization(header)
  Authorization.parse(header)
end

.parse_cache_control(header) ⇒ Hash{Symbol => true, Integer, String}

Parse a Cache-Control header into a directive hash.

Parameters:

  • header (String) —

    the Cache-Control header value

Returns:

  • (Hash{Symbol => true, Integer, String}) —

    parsed directives



86
87
88
 
# File 'lib/philiprehberger/header_kit.rb', line 86

def self.parse_cache_control(header)
  CacheControl.parse(header)
end

.parse_content_type(header) ⇒ Hash

Parse a Content-Type header into its components.

Parameters:

  • header (String) —

    the Content-Type header value

Returns:

  • (Hash) —

    with :media_type, :charset, :boundary keys



102
103
104
 
# File 'lib/philiprehberger/header_kit.rb', line 102

def self.parse_content_type(header)
  ContentType.parse(header)
end

.parse_cookie(header) ⇒ Hash{String => String}

Parse a Cookie header into a name-value hash.

Parameters:

  • header (String) —

    the Cookie header value

Returns:

  • (Hash{String => String}) —

    cookie name-value pairs



110
111
112
 
# File 'lib/philiprehberger/header_kit.rb', line 110

def self.parse_cookie(header)
  Cookie.parse(header)
end

.parse_cors(headers) ⇒ Hash

Parse CORS-related headers from a request.

Parameters:

  • headers (Hash) —

    request headers hash

Returns:

  • (Hash) —

    with :origin, :method, :headers keys



153
154
155
 
# File 'lib/philiprehberger/header_kit.rb', line 153

def self.parse_cors(headers)
  Cors.parse(headers)
end

.parse_forwarded(header) ⇒ Array<Hash>

Parse an RFC 7239 Forwarded header.

Parameters:

  • header (String) —

    the Forwarded header value

Returns:

  • (Array<Hash>) —

    parsed entries with symbol keys



177
178
179
 
# File 'lib/philiprehberger/header_kit.rb', line 177

def self.parse_forwarded(header)
  Forwarded.parse(header)
end

.parse_link(header) ⇒ Array<Hash>

Parse a Link header into an array of link entries.

Parameters:

  • header (String) —

    the Link header value

Returns:

  • (Array<Hash>) —

    entries with :uri, :rel, :type, :title keys



128
129
130
 
# File 'lib/philiprehberger/header_kit.rb', line 128

def self.parse_link(header)
  Link.parse(header)
end

.parse_range(header) ⇒ Hash{Symbol => Object}?

Parse a Range request header (RFC 7233 §3.1).

Parameters:

  • header (String) —

    the Range header value

Returns:

  • (Hash{Symbol => Object}, nil) —

    hash with :unit and :ranges, or nil for invalid input



206
207
208
 
# File 'lib/philiprehberger/header_kit.rb', line 206

def self.parse_range(header)
  Range.parse(header)
end

.parse_retry_after(header) ⇒ Hash?

Parse a Retry-After header.

Returns a hash with :seconds (Integer) for numeric values, or :date (Time) for HTTP date values. Returns nil for nil/empty input.

Parameters:

  • header (String) —

    the Retry-After header value

Returns:

  • (Hash, nil) —

    hash with :seconds or :date key, or nil



226
227
228
 
# File 'lib/philiprehberger/header_kit.rb', line 226

def self.parse_retry_after(header)
  RetryAfter.parse(header)
end

.parse_via(header) ⇒ Array<Hash>

Parse a Via header into structured entries.

Parameters:

  • header (String) —

    the Via header value

Returns:

  • (Array<Hash>) —

    entries with :protocol, :host, :comment keys



185
186
187
 
# File 'lib/philiprehberger/header_kit.rb', line 185

def self.parse_via(header)
  Forwarded.parse_via(header)
end

.security_headers(**options) ⇒ Hash{String => String}

Generate recommended security response headers.

Parameters:

  • options (Hash) —

    overrides (hsts:, csp:, frame:, content_type_options:, referrer_policy:)

Returns:

  • (Hash{String => String}) —

    security headers



169
170
171
 
# File 'lib/philiprehberger/header_kit.rb', line 169

def self.security_headers(**options)
  Security.headers(**options)
end