Module: Rack::Utils
- Included in:
- Chunked, ContentLength, ContentType
- Defined in:
- lib/rack/utils.rb
Overview
Rack::Utils contains a grab-bag of useful methods for writing web applications adopted from all kinds of Ruby libraries.
Defined Under Namespace
Classes: Context, HeaderHash
Constant Summary collapse
- ParameterTypeError =
QueryParser::ParameterTypeError
- InvalidParameterError =
QueryParser::InvalidParameterError
- ParamsTooDeepError =
QueryParser::ParamsTooDeepError
- DEFAULT_SEP =
QueryParser::DEFAULT_SEP
- COMMON_SEP =
QueryParser::COMMON_SEP
- KeySpaceConstrainedParams =
QueryParser::Params
- ESCAPE_HTML =
{ "&" => "&", "<" => "<", ">" => ">", "'" => "'", '"' => """, "/" => "/" }
- ESCAPE_HTML_PATTERN =
Regexp.union(*ESCAPE_HTML.keys)
- HTTP_STATUS_CODES =
Every standard HTTP code mapped to the appropriate message. Generated with:
curl -s https://www.iana.org/assignments/http-status-codes/http-status-codes-1.csv | \ ruby -ne 'm = /^(\d{3}),(?!Unassigned|\(Unused\))([^,]+)/.match($_) and \ puts "#{m[1]} => \x27#{m[2].strip}\x27,"'
{ 100 => 'Continue', 101 => 'Switching Protocols', 102 => 'Processing', 103 => 'Early Hints', 200 => 'OK', 201 => 'Created', 202 => 'Accepted', 203 => 'Non-Authoritative Information', 204 => 'No Content', 205 => 'Reset Content', 206 => 'Partial Content', 207 => 'Multi-Status', 208 => 'Already Reported', 226 => 'IM Used', 300 => 'Multiple Choices', 301 => 'Moved Permanently', 302 => 'Found', 303 => 'See Other', 304 => 'Not Modified', 305 => 'Use Proxy', 306 => '(Unused)', 307 => 'Temporary Redirect', 308 => 'Permanent Redirect', 400 => 'Bad Request', 401 => 'Unauthorized', 402 => 'Payment Required', 403 => 'Forbidden', 404 => 'Not Found', 405 => 'Method Not Allowed', 406 => 'Not Acceptable', 407 => 'Proxy Authentication Required', 408 => 'Request Timeout', 409 => 'Conflict', 410 => 'Gone', 411 => 'Length Required', 412 => 'Precondition Failed', 413 => 'Payload Too Large', 414 => 'URI Too Long', 415 => 'Unsupported Media Type', 416 => 'Range Not Satisfiable', 417 => 'Expectation Failed', 421 => 'Misdirected Request', 422 => 'Unprocessable Entity', 423 => 'Locked', 424 => 'Failed Dependency', 425 => 'Too Early', 426 => 'Upgrade Required', 428 => 'Precondition Required', 429 => 'Too Many Requests', 431 => 'Request Header Fields Too Large', 451 => 'Unavailable for Legal Reasons', 500 => 'Internal Server Error', 501 => 'Not Implemented', 502 => 'Bad Gateway', 503 => 'Service Unavailable', 504 => 'Gateway Timeout', 505 => 'HTTP Version Not Supported', 506 => 'Variant Also Negotiates', 507 => 'Insufficient Storage', 508 => 'Loop Detected', 509 => 'Bandwidth Limit Exceeded', 510 => 'Not Extended', 511 => 'Network Authentication Required' }
- STATUS_WITH_NO_ENTITY_BODY =
Responses with HTTP status codes that should not have an entity body
- SYMBOL_TO_STATUS_CODE =
- PATH_SEPS =
Regexp.union(*[::File::SEPARATOR, ::File::ALT_SEPARATOR].compact)
- NULL_BYTE =
"\0"
Class Attribute Summary collapse
-
.default_query_parser ⇒ Object
Returns the value of attribute default_query_parser.
-
.multipart_part_limit ⇒ Object
Returns the value of attribute multipart_part_limit.
Class Method Summary collapse
- .add_cookie_to_header(header, key, value) ⇒ Object
- .add_remove_cookie_to_header(header, key, value = {}) ⇒ Object
-
.best_q_match(q_value_header, available_mimes) ⇒ Object
Return best accept value to use, based on the algorithm in RFC 2616 Section 14.
- .build_nested_query(value, prefix = nil) ⇒ Object
- .build_query(params) ⇒ Object
-
.byte_ranges(env, size) ⇒ Object
Parses the “Range:” header, if present, into an array of Range objects.
- .clean_path_info(path_info) ⇒ Object
- .delete_cookie_header!(headers, key, value = {}) ⇒ Object
-
.delete_set_cookie_header(key, value = {}) ⇒ Object
:call-seq: delete_set_cookie_header(key, value = {}) -> encoded string.
-
.delete_set_cookie_header!(header, key, value = {}) ⇒ Object
:call-seq: delete_set_cookie_header!(header, key, value = {}) -> header value.
-
.escape(s) ⇒ Object
URI escapes.
-
.escape_html(string) ⇒ Object
Escape ampersands, brackets and quotes to their HTML/XML entities.
-
.escape_path(s) ⇒ Object
Like URI escaping, but with %20 instead of +.
- .forwarded_values(forwarded_header) ⇒ Object
- .get_byte_ranges(http_range, size) ⇒ Object
- .key_space_limit ⇒ Object
- .key_space_limit=(v) ⇒ Object
- .make_delete_cookie_header(header, key, value) ⇒ Object
- .param_depth_limit ⇒ Object
- .param_depth_limit=(v) ⇒ Object
-
.parse_cookies(env) ⇒ Object
:call-seq: parse_cookies(env) -> hash.
-
.parse_cookies_header(value) ⇒ Object
:call-seq: parse_cookies_header(value) -> hash.
- .parse_nested_query(qs, d = nil) ⇒ Object
- .parse_query(qs, d = nil, &unescaper) ⇒ Object
- .q_values(q_value_header) ⇒ Object
- .rfc2822(time) ⇒ Object
- .select_best_encoding(available_encodings, accept_encoding) ⇒ Object
-
.set_cookie_header(key, value) ⇒ Object
:call-seq: set_cookie_header(key, value) -> encoded string.
-
.set_cookie_header!(headers, key, value) ⇒ Object
:call-seq: set_cookie_header!(headers, key, value) -> header value.
- .status_code(status) ⇒ Object
-
.unescape(s, encoding = Encoding::UTF_8) ⇒ Object
Unescapes a URI escaped string with
encoding
. -
.unescape_path(s) ⇒ Object
Unescapes the path component of a URI.
- .valid_path?(path) ⇒ Boolean
Instance Method Summary collapse
-
#clock_time ⇒ Object
:nocov:.
-
#secure_compare(a, b) ⇒ Object
:nocov:.
Class Attribute Details
.default_query_parser ⇒ Object
Returns the value of attribute default_query_parser.
28 29 30 |
# File 'lib/rack/utils.rb', line 28 def default_query_parser @default_query_parser end |
.multipart_part_limit ⇒ Object
Returns the value of attribute multipart_part_limit.
61 62 63 |
# File 'lib/rack/utils.rb', line 61 def multipart_part_limit @multipart_part_limit end |
Class Method Details
.add_cookie_to_header(header, key, value) ⇒ Object
243 244 245 246 247 248 249 250 251 252 253 254 255 256 |
# File 'lib/rack/utils.rb', line 243 def (header, key, value) warn("add_cookie_to_header is deprecated and will be removed in Rack 3.1", uplevel: 1) case header when nil, '' return (key, value) when String [header, (key, value)] when Array header + [(key, value)] else raise ArgumentError, "Unrecognized cookie header value. Expected String, Array, or nil, got #{header.inspect}" end end |
.add_remove_cookie_to_header(header, key, value = {}) ⇒ Object
378 379 380 381 382 |
# File 'lib/rack/utils.rb', line 378 def (header, key, value = {}) warn("add_remove_cookie_to_header is deprecated and will be removed in Rack 3.1, use delete_set_cookie_header! instead", uplevel: 1) (header, key, value) end |
.best_q_match(q_value_header, available_mimes) ⇒ Object
Return best accept value to use, based on the algorithm in RFC 2616 Section 14. If there are multiple best matches (same specificity and quality), the value returned is arbitrary.
162 163 164 165 166 167 168 169 170 171 172 173 |
# File 'lib/rack/utils.rb', line 162 def best_q_match(q_value_header, available_mimes) values = q_values(q_value_header) matches = values.map do |req_mime, quality| match = available_mimes.find { |am| Rack::Mime.match?(am, req_mime) } next unless match [match, quality] end.compact.sort_by do |match, quality| (match.split('/', 2).count('*') * -10) + quality end.last matches&.first end |
.build_nested_query(value, prefix = nil) ⇒ Object
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
# File 'lib/rack/utils.rb', line 116 def build_nested_query(value, prefix = nil) case value when Array value.map { |v| build_nested_query(v, "#{prefix}[]") }.join("&") when Hash value.map { |k, v| build_nested_query(v, prefix ? "#{prefix}[#{k}]" : k) }.delete_if(&:empty?).join('&') when nil escape(prefix) else raise ArgumentError, "value must be a Hash" if prefix.nil? "#{escape(prefix)}=#{escape(value)}" end end |
.build_query(params) ⇒ Object
106 107 108 109 110 111 112 113 114 |
# File 'lib/rack/utils.rb', line 106 def build_query(params) params.map { |k, v| if v.class == Array build_query(v.map { |x| [k, x] }) else v.nil? ? escape(k) : "#{escape(k)}=#{escape(v)}" end }.join("&") end |
.byte_ranges(env, size) ⇒ Object
Parses the “Range:” header, if present, into an array of Range objects. Returns nil if the header is missing or syntactically invalid. Returns an empty array if none of the ranges are satisfiable.
420 421 422 |
# File 'lib/rack/utils.rb', line 420 def byte_ranges(env, size) get_byte_ranges env['HTTP_RANGE'], size end |
.clean_path_info(path_info) ⇒ Object
620 621 622 623 624 625 626 627 628 629 630 631 632 633 |
# File 'lib/rack/utils.rb', line 620 def clean_path_info(path_info) parts = path_info.split PATH_SEPS clean = [] parts.each do |part| next if part.empty? || part == '.' part == '..' ? clean.pop : clean << part end clean_path = clean.join(::File::SEPARATOR) clean_path.prepend("/") if parts.empty? || parts.first.empty? clean_path end |
.delete_cookie_header!(headers, key, value = {}) ⇒ Object
372 373 374 375 376 |
# File 'lib/rack/utils.rb', line 372 def (headers, key, value = {}) headers[SET_COOKIE] = (headers[SET_COOKIE], key, value) return nil end |
.delete_set_cookie_header(key, value = {}) ⇒ Object
:call-seq:
delete_set_cookie_header(key, value = {}) -> encoded string
Generate an encoded string based on the given key
and value
using set_cookie_header for the purpose of causing the specified cookie to be deleted. The value
may be an instance of Hash
and can include attributes as outlined by set_cookie_header. The encoded cookie will have a max_age
of 0 seconds, an expires
date in the past and an empty value
. When used with the set-cookie
header, it will cause the client to remove any matching cookie.
("myname")
# => "myname=; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT"
362 363 364 |
# File 'lib/rack/utils.rb', line 362 def (key, value = {}) (key, value.merge(max_age: '0', expires: Time.at(0), value: '')) end |
.delete_set_cookie_header!(header, key, value = {}) ⇒ Object
:call-seq:
delete_set_cookie_header!(header, key, value = {}) -> header value
Set an expired cookie in the specified headers with the given cookie key
and value
using delete_set_cookie_header. This causes the client to immediately delete the specified cookie.
(nil, "mycookie")
# => "mycookie=; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT"
If the header is non-nil, it will be modified in place.
header = []
(header, "mycookie")
# => ["mycookie=; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT"]
header
# => ["mycookie=; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT"]
402 403 404 405 406 407 408 409 410 411 |
# File 'lib/rack/utils.rb', line 402 def (header, key, value = {}) if header header = Array(header) header << (key, value) else header = (key, value) end return header end |
.escape(s) ⇒ Object
URI escapes. (CGI style space to +)
38 39 40 |
# File 'lib/rack/utils.rb', line 38 def escape(s) URI.encode_www_form_component(s) end |
.escape_html(string) ⇒ Object
Escape ampersands, brackets and quotes to their HTML/XML entities.
187 188 189 |
# File 'lib/rack/utils.rb', line 187 def escape_html(string) string.to_s.gsub(ESCAPE_HTML_PATTERN){|c| ESCAPE_HTML[c] } end |
.escape_path(s) ⇒ Object
Like URI escaping, but with %20 instead of +. Strictly speaking this is true URI escaping.
44 45 46 |
# File 'lib/rack/utils.rb', line 44 def escape_path(s) ::URI::DEFAULT_PARSER.escape s end |
.forwarded_values(forwarded_header) ⇒ Object
145 146 147 148 149 150 151 152 153 154 155 |
# File 'lib/rack/utils.rb', line 145 def forwarded_values(forwarded_header) return nil unless forwarded_header forwarded_header = forwarded_header.to_s.gsub("\n", ";") forwarded_header.split(/\s*;\s*/).each_with_object({}) do |field, values| field.split(/\s*,\s*/).each do |pair| return nil unless pair =~ /\A\s*(by|for|host|proto)\s*=\s*"?([^"]+)"?\s*\Z/i (values[$1.downcase.to_sym] ||= []) << $2 end end end |
.get_byte_ranges(http_range, size) ⇒ Object
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 |
# File 'lib/rack/utils.rb', line 424 def get_byte_ranges(http_range, size) # See <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35> return nil unless http_range && http_range =~ /bytes=([^;]+)/ ranges = [] $1.split(/,\s*/).each do |range_spec| return nil unless range_spec =~ /(\d*)-(\d*)/ r0, r1 = $1, $2 if r0.empty? return nil if r1.empty? # suffix-byte-range-spec, represents trailing suffix of file r0 = size - r1.to_i r0 = 0 if r0 < 0 r1 = size - 1 else r0 = r0.to_i if r1.empty? r1 = size - 1 else r1 = r1.to_i return nil if r1 < r0 # backwards range is syntactically invalid r1 = size - 1 if r1 >= size end end ranges << (r0..r1) if r0 <= r1 end ranges end |
.key_space_limit ⇒ Object
77 78 79 80 |
# File 'lib/rack/utils.rb', line 77 def self.key_space_limit warn("`Rack::Utils.key_space_limit` is deprecated as this value no longer has an effect. It will be removed in Rack 3.1", uplevel: 1) 65536 end |
.key_space_limit=(v) ⇒ Object
82 83 84 |
# File 'lib/rack/utils.rb', line 82 def self.key_space_limit=(v) warn("`Rack::Utils.key_space_limit=` is deprecated and no longer has an effect. It will be removed in Rack 3.1", uplevel: 1) end |
.make_delete_cookie_header(header, key, value) ⇒ Object
366 367 368 369 370 |
# File 'lib/rack/utils.rb', line 366 def (header, key, value) warn("make_delete_cookie_header is deprecated and will be removed in Rack 3.1, use delete_set_cookie_header! instead", uplevel: 1) (header, key, value) end |
.param_depth_limit ⇒ Object
69 70 71 |
# File 'lib/rack/utils.rb', line 69 def self.param_depth_limit default_query_parser.param_depth_limit end |
.param_depth_limit=(v) ⇒ Object
73 74 75 |
# File 'lib/rack/utils.rb', line 73 def self.param_depth_limit=(v) self.default_query_parser = self.default_query_parser.new_depth_limit(v) end |
.parse_cookies(env) ⇒ Object
:call-seq:
parse_cookies(env) -> hash
Parse cookies from the provided request environment using parse_cookies_header. Returns a map of cookie key
to cookie value
.
({'HTTP_COOKIE' => 'myname=myvalue'})
# => {'myname' => 'myvalue'}
267 268 269 |
# File 'lib/rack/utils.rb', line 267 def (env) env[HTTP_COOKIE] end |
.parse_cookies_header(value) ⇒ Object
:call-seq:
parse_cookies_header(value) -> hash
Parse cookies from the provided header value
according to RFC6265. The syntax for cookie headers only supports semicolons. Returns a map of cookie key
to cookie value
.
('myname=myvalue; max-age=0')
# => {"myname"=>"myvalue", "max-age"=>"0"}
233 234 235 236 237 238 239 240 241 |
# File 'lib/rack/utils.rb', line 233 def (value) return {} unless value value.split(/; */n).each_with_object({}) do |, | next if .empty? key, value = .split('=', 2) [key] = (unescape(value) rescue value) unless .key?(key) end end |
.parse_nested_query(qs, d = nil) ⇒ Object
102 103 104 |
# File 'lib/rack/utils.rb', line 102 def parse_nested_query(qs, d = nil) Rack::Utils.default_query_parser.parse_nested_query(qs, d) end |
.parse_query(qs, d = nil, &unescaper) ⇒ Object
98 99 100 |
# File 'lib/rack/utils.rb', line 98 def parse_query(qs, d = nil, &unescaper) Rack::Utils.default_query_parser.parse_query(qs, d, &unescaper) end |
.q_values(q_value_header) ⇒ Object
134 135 136 137 138 139 140 141 142 143 |
# File 'lib/rack/utils.rb', line 134 def q_values(q_value_header) q_value_header.to_s.split(/\s*,\s*/).map do |part| value, parameters = part.split(/\s*;\s*/, 2) quality = 1.0 if parameters && (md = /\Aq=([\d.]+)/.match(parameters)) quality = md[1].to_f end [value, quality] end end |
.rfc2822(time) ⇒ Object
413 414 415 |
# File 'lib/rack/utils.rb', line 413 def rfc2822(time) time.rfc2822 end |
.select_best_encoding(available_encodings, accept_encoding) ⇒ Object
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 |
# File 'lib/rack/utils.rb', line 191 def select_best_encoding(available_encodings, accept_encoding) # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html = [] accept_encoding.each do |m, q| preference = available_encodings.index(m) || available_encodings.size if m == "*" (available_encodings - accept_encoding.map(&:first)).each do |m2| << [m2, q, preference] end else << [m, q, preference] end end encoding_candidates = .sort_by { |_, q, p| [-q, p] } .map!(&:first) unless encoding_candidates.include?("identity") encoding_candidates.push("identity") end .each do |m, q| encoding_candidates.delete(m) if q == 0.0 end (encoding_candidates & available_encodings)[0] end |
.set_cookie_header(key, value) ⇒ Object
:call-seq:
set_cookie_header(key, value) -> encoded string
Generate an encoded string using the provided key
and value
suitable for the set-cookie
header according to RFC6265. The value
may be an instance of either String
or Hash
.
If the cookie value
is an instance of Hash
, it considers the following cookie attribute keys: domain
, max_age
, expires
(must be instance of Time
), secure
, http_only
, same_site
and value
. For more details about the interpretation of these fields, consult [RFC6265 Section 5.2](datatracker.ietf.org/doc/html/rfc6265#section-5.2).
An extra cookie attribute escape_key
can be provided to control whether or not the cookie key is URL encoded. If explicitly set to false
, the cookie key name will not be url encoded (escaped). The default is true
.
("myname", "myvalue")
# => "myname=myvalue"
("myname", {value: "myvalue", max_age: 10})
# => "myname=myvalue; max-age=10"
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 |
# File 'lib/rack/utils.rb', line 294 def (key, value) case value when Hash key = escape(key) unless value[:escape_key] == false domain = "; domain=#{value[:domain]}" if value[:domain] path = "; path=#{value[:path]}" if value[:path] max_age = "; max-age=#{value[:max_age]}" if value[:max_age] expires = "; expires=#{value[:expires].httpdate}" if value[:expires] secure = "; secure" if value[:secure] httponly = "; httponly" if (value.key?(:httponly) ? value[:httponly] : value[:http_only]) same_site = case value[:same_site] when false, nil nil when :none, 'None', :None '; SameSite=None' when :lax, 'Lax', :Lax '; SameSite=Lax' when true, :strict, 'Strict', :Strict '; SameSite=Strict' else raise ArgumentError, "Invalid SameSite value: #{value[:same_site].inspect}" end value = value[:value] else key = escape(key) end value = [value] unless Array === value return "#{key}=#{value.map { |v| escape v }.join('&')}#{domain}" \ "#{path}#{max_age}#{expires}#{secure}#{httponly}#{same_site}" end |
.set_cookie_header!(headers, key, value) ⇒ Object
:call-seq:
set_cookie_header!(headers, key, value) -> header value
Append a cookie in the specified headers with the given cookie key
and value
using set_cookie_header.
If the headers already contains a set-cookie
key, it will be converted to an Array
if not already, and appended to.
336 337 338 339 340 341 342 343 344 345 346 |
# File 'lib/rack/utils.rb', line 336 def (headers, key, value) if header = headers[SET_COOKIE] if header.is_a?(Array) header << (key, value) else headers[SET_COOKIE] = [header, (key, value)] end else headers[SET_COOKIE] = (key, value) end end |
.status_code(status) ⇒ Object
610 611 612 613 614 615 616 |
# File 'lib/rack/utils.rb', line 610 def status_code(status) if status.is_a?(Symbol) SYMBOL_TO_STATUS_CODE.fetch(status) { raise ArgumentError, "Unrecognized status code #{status.inspect}" } else status.to_i end end |
.unescape(s, encoding = Encoding::UTF_8) ⇒ Object
Unescapes a URI escaped string with encoding
. encoding
will be the target encoding of the string returned, and it defaults to UTF-8
56 57 58 |
# File 'lib/rack/utils.rb', line 56 def unescape(s, encoding = Encoding::UTF_8) URI.decode_www_form_component(s, encoding) end |
.unescape_path(s) ⇒ Object
Unescapes the path component of a URI. See Rack::Utils.unescape for unescaping query parameters or form components.
50 51 52 |
# File 'lib/rack/utils.rb', line 50 def unescape_path(s) ::URI::DEFAULT_PARSER.unescape s end |
.valid_path?(path) ⇒ Boolean
637 638 639 |
# File 'lib/rack/utils.rb', line 637 def valid_path?(path) path.valid_encoding? && !path.include?(NULL_BYTE) end |
Instance Method Details
#clock_time ⇒ Object
:nocov:
92 93 94 |
# File 'lib/rack/utils.rb', line 92 def clock_time Process.clock_gettime(Process::CLOCK_MONOTONIC) end |
#secure_compare(a, b) ⇒ Object
:nocov:
460 461 462 463 464 |
# File 'lib/rack/utils.rb', line 460 def secure_compare(a, b) return false unless a.bytesize == b.bytesize OpenSSL.fixed_length_secure_compare(a, b) end |