Module: Cyberweb::REST::Helpers
- Included in:
- Base
- Defined in:
- lib/cyberweb/REST/base/helpers/helpers.rb,
lib/cyberweb/REST/base/helpers/stream.rb
Overview
#
Methods available to routes, before/after filters, and views.
#
Defined Under Namespace
Classes: Stream
Constant Summary collapse
- ETAG_KINDS =
#
ETAG_KINDS
#
%i( strong weak )
Instance Method Summary collapse
-
#attachment(filename = nil, disposition = :attachment) ⇒ Object
# === attachment.
-
#back ⇒ Object
back.
-
#bad_request? ⇒ Boolean
whether or not the status is set to 400.
-
#body(value = nil, &block) ⇒ Object
# === body.
-
#cache_control(*values) ⇒ Object
# === cache_control.
-
#client_error? ⇒ Boolean
whether or not the status is set to 4xx.
-
#content_type(type = nil, params = {}) ⇒ Object
# === content_type.
-
#error(code, body = nil) ⇒ Object
# === error.
-
#etag(value, options = {}) ⇒ Object
etag.
-
#expires(amount, *values) ⇒ Object
# === expires.
-
#headers(hash = nil) ⇒ Object
# === headers.
-
#informational? ⇒ Boolean
informational?.
-
#last_modified(time) ⇒ Object
# === last_modified.
-
#logger ⇒ Object
# === logger.
-
#mime_type(type) ⇒ Object
# === mime_type.
-
#not_found(body = nil) ⇒ Object
# === not_found.
-
#not_found? ⇒ Boolean
whether or not the status is set to 404.
-
#redirect(uri, *args) ⇒ Object
# === redirect.
-
#redirect? ⇒ Boolean
whether or not the status is set to 3xx.
-
#send_file(path, opts = {}) ⇒ Object
# === send_file.
-
#server_error? ⇒ Boolean
whether or not the status is set to 5xx.
-
#session ⇒ Object
# === session.
-
#status(value = nil) ⇒ Object
# === status.
-
#stream(keep_open = false) ⇒ Object
# === stream.
-
#success? ⇒ Boolean
whether or not the status is set to 2xx.
-
#time_for(value) ⇒ Object
# === time_for.
-
#uri(addr = nil, absolute = true, add_script_name = true) ⇒ Object
(also: #url, #to)
# === uri.
Instance Method Details
#attachment(filename = nil, disposition = :attachment) ⇒ Object
#
attachment
Set the Content-Disposition to “attachment” with the specified filename, instructing the user agents to prompt to save.
#
352 353 354 355 356 357 358 359 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 352 def (filename = nil, disposition = :attachment) response['Content-Disposition'] = disposition.to_s.dup return unless filename params = format('; filename="%s"', File.basename(filename)) response['Content-Disposition'] << params ext = File.extname(filename) content_type(ext) unless response['Content-Type'] || ext.empty? end |
#back ⇒ Object
back
Sugar for redirect (example: redirect back)
257 258 259 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 257 def back request.referer end |
#bad_request? ⇒ Boolean
whether or not the status is set to 400
294 295 296 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 294 def bad_request? status == 400 end |
#body(value = nil, &block) ⇒ Object
#
body
Set or retrieve the response body. When a block is given, evaluation is deferred until the body is read with #each.
#
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 424 def body( value = nil, &block ) if block_given? def block.each; yield(call) end response.body = block elsif value # Rack 2.0 returns a Rack::File::Iterator here instead of # Rack::File as it was in the previous API. unless request.head? || value.is_a?(Rack::File::Iterator) || value.is_a?(Stream) headers.delete 'Content-Length' end response.body = value else response.body end end |
#cache_control(*values) ⇒ Object
#
cache_control
Specify response freshness policy for HTTP caches (Cache-Control header). Any number of non-value directives (:public, :private, :no_cache, :no_store, :must_revalidate, :proxy_revalidate) may be passed along with a Hash of value directives (:max_age, :s_maxage).
cache_control :public, :must_revalidate, :max_age => 60
=> Cache-Control: public, must-revalidate, max-age=60
See RFC 2616 / 14.9 for more on standard cache control directives:
https://tools.ietf.org/html/rfc2616#section-14.9.1
#
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 150 def cache_control(*values) if values.last.is_a?(Hash) hash = values.pop hash.reject! { |_k, v| v == false } hash.reject! { |k, v| values << k if v == true } else hash = {} end values.map! { |value| value.to_s.tr('_', '-') } hash.each do |key, value| key = key.to_s.tr('_', '-') value = value.to_i if %w[max-age s-maxage].include? key values << "#{key}=#{value}" end response['Cache-Control'] = values.join(', ') if values.any? end |
#client_error? ⇒ Boolean
whether or not the status is set to 4xx
279 280 281 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 279 def client_error? status.between? 400, 499 end |
#content_type(type = nil, params = {}) ⇒ Object
#
content_type
Set the Content-Type of the response body given a media type or file extension.
#
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 324 def content_type(type = nil, params = {}) return response['Content-Type'] unless type default = params.delete :default mime_type = mime_type(type) || default raise format('Unknown media type: %p', type) if mime_type.nil? mime_type = mime_type.dup unless params.include?(:charset) || settings.add_charset.all? { |p| !(p === mime_type) } params[:charset] = params.delete('charset') || settings.default_encoding end params.delete :charset if mime_type.include? 'charset' unless params.empty? mime_type << (mime_type.include?(';') ? ', ' : ';') mime_type << params.map do |key, val| val = val.inspect if val =~ /[";,]/ "#{key}=#{val}" end.join(', ') end response['Content-Type'] = mime_type end |
#error(code, body = nil) ⇒ Object
#
error
Halt processing and return the error status provided.
#
56 57 58 59 60 61 62 63 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 56 def error(code, body = nil) if code.respond_to? :to_str body = code.to_str code = 500 end response.body = body unless body.nil? halt code end |
#etag(value, options = {}) ⇒ Object
etag
Set the response entity tag (HTTP ‘ETag’ header) and halt if conditional GET matches. The value
argument is an identifier that uniquely identifies the current version of the resource. The kind
argument indicates whether the etag should be used as a :strong (default) or :weak cache validator.
When the current request includes an ‘If-None-Match’ header with a matching etag, execution is immediately halted. If the request method is GET or HEAD, a ‘304 Not Modified’ response is sent.
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 227 def etag(value, = {}) # Before touching this code, please double check RFC 2616 14.24 and 14.26. = { kind: } unless Hash === kind = [:kind] || :strong new_resource = .fetch(:new_resource) { request.post? } unless ETAG_KINDS.include?(kind) raise ArgumentError, ':strong or :weak expected' end value = format('"%s"', value) value = "W/#{value}" if kind == :weak response['ETag'] = value return unless success? || status == 304 if etag_matches?(env['HTTP_IF_NONE_MATCH'], new_resource) halt(request.safe? ? 304 : 412) end if env['HTTP_IF_MATCH'] return if etag_matches?(env['HTTP_IF_MATCH'], new_resource) halt 412 end nil end |
#expires(amount, *values) ⇒ Object
#
expires
Set the Expires header and Cache-Control/max-age directive. Amount can be an integer number of seconds in the future or a Time object indicating when the response should be considered “stale”.
The remaining “values” arguments are passed to the #cache_control helper:
expires 500, :public, :must_revalidate
=> Cache-Control: public, must-revalidate, max-age=500
=> Expires: Mon, 08 Jun 2009 08:50:17 GMT
#
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 117 def expires(amount, *values) values << {} unless values.last.is_a?(Hash) if amount.is_a? Integer time = Time.now + amount.to_i max_age = amount else time = time_for amount max_age = time - Time.now end values.last.merge!(max_age: max_age) { |_key, v1, v2| v1 || v2 } cache_control(*values) response['Expires'] = time.httpdate end |
#headers(hash = nil) ⇒ Object
#
headers
Set multiple response headers with Hash.
#
70 71 72 73 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 70 def headers(hash = nil) response.headers.merge! hash if hash response.headers end |
#informational? ⇒ Boolean
informational?
whether or not the status is set to 1xx
264 265 266 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 264 def informational? status.between? 100, 199 end |
#last_modified(time) ⇒ Object
#
last_modified
Set the last modified time of the resource (HTTP ‘Last-Modified’ header) and halt if conditional GET matches. The time
argument is a Time, DateTime, or other object that responds to to_time
.
When the current request includes an ‘If-Modified-Since’ header that is equal or later than the time specified, execution is immediately halted with a ‘304 Not Modified’ response.
#
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 196 def last_modified(time) return unless time time = time_for time response['Last-Modified'] = time.httpdate return if env['HTTP_IF_NONE_MATCH'] if (status == 200) && env['HTTP_IF_MODIFIED_SINCE'] # compare based on seconds since epoch since = Time.httpdate(env['HTTP_IF_MODIFIED_SINCE']).to_i halt 304 if since >= time.to_i end if (success? || (status == 412)) && env['HTTP_IF_UNMODIFIED_SINCE'] # compare based on seconds since epoch since = Time.httpdate(env['HTTP_IF_UNMODIFIED_SINCE']).to_i halt 412 if since < time.to_i end rescue ArgumentError end |
#logger ⇒ Object
#
logger
Access shared logger object.
#
89 90 91 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 89 def logger request.logger end |
#mime_type(type) ⇒ Object
#
mime_type
Look up a media type by file extension in Rack’s mime registry.
#
98 99 100 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 98 def mime_type(type) Base.mime_type(type) end |
#not_found(body = nil) ⇒ Object
#
not_found
Halt processing and return a 404 Not Found.
#
414 415 416 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 414 def not_found(body = nil) error 404, body end |
#not_found? ⇒ Boolean
whether or not the status is set to 404
289 290 291 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 289 def not_found? status == 404 end |
#redirect(uri, *args) ⇒ Object
#
redirect
Halt processing and redirect to the URI provided.
#
395 396 397 398 399 400 401 402 403 404 405 406 407 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 395 def redirect(uri, *args) if (env['HTTP_VERSION'] == 'HTTP/1.1') && (env['REQUEST_METHOD'] != 'GET') status 303 else status 302 end # ======================================================================= # # According to RFC 2616 section 14.30, "the field value consists of a # single absolute URI". # ======================================================================= # response['Location'] = uri(uri.to_s, settings.absolute_redirects?, settings.prefixed_redirects?) halt(*args) end |
#redirect? ⇒ Boolean
whether or not the status is set to 3xx
274 275 276 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 274 def redirect? status.between? 300, 399 end |
#send_file(path, opts = {}) ⇒ Object
#
send_file
Use the contents of the file at path
as the response body.
#
366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 366 def send_file(path, opts = {}) if opts[:type] || !response['Content-Type'] content_type opts[:type] || File.extname(path), default: 'application/octet-stream' end disposition = opts[:disposition] filename = opts[:filename] disposition = :attachment if disposition.nil? && filename filename = path if filename.nil? (filename, disposition) if disposition last_modified opts[:last_modified] if opts[:last_modified] file = Rack::File.new(File.dirname(settings.app_file)) result = file.serving(request, path) result[1].each { |k, v| headers[k] ||= v } headers['Content-Length'] = result[1]['Content-Length'] opts[:status] &&= Integer(opts[:status]) halt (opts[:status] || result[0]), result[2] rescue Errno::ENOENT not_found end |
#server_error? ⇒ Boolean
whether or not the status is set to 5xx
284 285 286 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 284 def server_error? status.between? 500, 599 end |
#session ⇒ Object
#
session
Access the underlying Rack session.
#
80 81 82 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 80 def session request.session end |
#status(value = nil) ⇒ Object
#
status
Set or retrieve the response status code.
#
447 448 449 450 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 447 def status(value = nil) response.status = Rack::Utils.status_code(value) if value response.status end |
#stream(keep_open = false) ⇒ Object
#
stream
Allows to start sending data to the client even though later parts of the response body have not yet been generated.
The close parameter specifies whether Stream#close should be called after the block has been executed. This is only relevant for evented servers like Rainbows.
#
179 180 181 182 183 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 179 def stream(keep_open = false) scheduler = env['async.callback'] ? EventMachine : Stream current = @params.dup body Stream.new(scheduler, keep_open) { |out| with_params(current) { yield(out) } } end |
#success? ⇒ Boolean
whether or not the status is set to 2xx
269 270 271 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 269 def success? status.between? 200, 299 end |
#time_for(value) ⇒ Object
#
time_for
Generates a Time object from the given value. Used by #expires and #last_modified.
#
304 305 306 307 308 309 310 311 312 313 314 315 316 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 304 def time_for(value) if value.is_a? Numeric Time.at value elsif value.respond_to? :to_s Time.parse value.to_s else value.to_time end rescue ArgumentError => e raise e rescue Exception raise ArgumentError, "unable to convert #{value.inspect} to a Time object" end |
#uri(addr = nil, absolute = true, add_script_name = true) ⇒ Object Also known as: url, to
#
uri
Generates the absolute URI for a given path in the app.
Takes Rack routers and reverse proxies into account.
#
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 30 def uri( addr = nil, absolute = true, add_script_name = true ) return addr if addr =~ /\A[a-z][a-z0-9+.\-]*:/i uri = [host = ''] if absolute host << "http#{'s' if request.secure?}://" host << if request.forwarded? || (request.port != (request.secure? ? 443 : 80)) request.host_with_port else request.host end end uri << request.script_name.to_s if add_script_name uri << (addr || request.path_info).to_s File.join(uri) end |