Class: Cybertrain::Response

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/http/response.rb

Overview

The response a request builds up on its way through the stack; the Server serializes it with #to_http. Headers keep the case they were set with, and Set-Cookie values live in their own list because one response may carry several.

Controller#response in an action. Controller#render, Controller#redirect_to and Controller#head set the status and body; use this object for headers and cookies. Content-Length is always computed, and Content-Type defaults to text/html; charset=utf-8. X-Content-Type-Options: nosniff and X-Frame-Options: SAMEORIGIN are added to every response that does not set them itself: to allow framing (an embeddable widget) or change the value, set the header with #set_header; the response’s own value is sent and nothing is doubled.

Examples:

response.set_header("Cache-Control", "no-store")
response.add_cookie(Cybertrain::Cookies.serialize("theme", "dark", max_age: 31_536_000))

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#body ⇒ String

The body, "" until set.

Returns:

  • (String)


96
97
98
# File 'cybertrain/http/response.rb', line 96

def body
  @body
end

#body_writer ⇒ BodyWriter?

The writer of a streaming response (docs/design.md D36), nil for an ordinary one.

Returns:



143
144
145
# File 'cybertrain/http/response.rb', line 143

def body_writer
  @body_writer
end

#cookies ⇒ Array<String> (readonly)

The Set-Cookie values added so far.

Returns:

  • (Array<String>)


119
120
121
# File 'cybertrain/http/response.rb', line 119

def cookies
  @cookies
end

#headers ⇒ Hash{String => String} (readonly)

The headers set so far, in the case they were set with; change them through #set_header and #drop_header.

Returns:

  • (Hash{String => String})


114
115
116
# File 'cybertrain/http/response.rb', line 114

def headers
  @headers
end

#status ⇒ Integer

The status code, 200 until set. The status line carries the reason phrase STATUS_TEXT gives the code; a code the table lacks (418, a non-standard code) is sent with the phrase “Unknown”.

Returns:



91
92
93
# File 'cybertrain/http/response.rb', line 91

def status
  @status
end

Class Method Details

.default_permissions_policy ⇒ String

Returns the default Permissions-Policy, “” for none.

Returns:

  • (String) —

    the default Permissions-Policy, “” for none



70
71
72
# File 'cybertrain/http/response.rb', line 70

def self.default_permissions_policy
  @default_permissions_policy
end

.default_permissions_policy=(value) ⇒ Object

Parameters:

  • value (String) —

    e.g. "camera=(), geolocation=(self)", or “” for none

Raises:

  • (ArgumentError) —

    on a CR or LF, changing nothing



77
78
79
80
81
82
83
84
# File 'cybertrain/http/response.rb', line 77

def self.default_permissions_policy=(value)
  text = value.to_s
  if text.include?("\r") || text.include?("\n")
    msg = "header Permissions-Policy must not contain CR or LF"
    raise ArgumentError, msg
  end
  @default_permissions_policy = text
end

Instance Method Details

Adds a Set-Cookie header; build the value with Cookies.serialize. Raises ArgumentError when the value contains CR or LF.

Parameters:

  • set_cookie_value (String)


276
277
278
279
# File 'cybertrain/http/response.rb', line 276

def add_cookie(set_cookie_value)
  reject_crlf!("Set-Cookie", set_cookie_value)
  @cookies << set_cookie_value
end

#content_type=(value) ⇒ Object

Parameters:

  • value (String) —

    e.g. "text/csv; charset=utf-8"



268
269
270
# File 'cybertrain/http/response.rb', line 268

def content_type=(value)
  set_header("Content-Type", value)
end

#drop_header(name) ⇒ nil

Removes the header of that name, whatever its case (every spelling when several were stored); a missing one is not an error. Returns nil (NOTES rules 10/34: one return type for the name). Edits @headers in place: headers is a public reader, so a Hash a before_action or middleware took earlier must still be the live one afterwards. The matching keys are collected first (never delete while iterating) and removed with Hash#delete. each_key, not keys.each: where @headers is boxed, keys dispatches over the program’s own keys methods (a model’s Errors#keys) and not to Hash#keys (NOTES rules 51 and 62).

Parameters:

  • name (String)

Returns:

  • (nil)


251
252
253
254
255
256
# File 'cybertrain/http/response.rb', line 251

def drop_header(name)
  gone = Array.new(0) { "" }
  @headers.each_key { |k| gone << k if HeaderName.same?(k, name) }
  gone.each { |k| @headers.delete(k) }
  nil
end

#header(name) ⇒ String?

Parameters:

  • name (String) —

    any case

Returns:

  • (String, nil)


261
262
263
264
# File 'cybertrain/http/response.rb', line 261

def header(name)
  key = header_key(name)
  key.nil? ? nil : @headers[key]
end

Adds a Set-Cookie header in place of any earlier one for the cookie name (a value starting "name="), so a cookie written twice in one request is sent once, with its last value (CookieJar writes through this). Raises ArgumentError, changing nothing, when the value contains CR or LF. The list is edited in place (cookies is a public reader).

Parameters:

Returns:

  • (nil)


290
291
292
293
294
295
296
297
298
299
# File 'cybertrain/http/response.rb', line 290

def replace_cookie(name, set_cookie)
  reject_crlf!("Set-Cookie", set_cookie)
  prefix = "#{name}="
  kept = Array.new(0) { "" }
  @cookies.each { |c| kept << c unless c.start_with?(prefix) }
  @cookies.clear
  kept.each { |c| @cookies << c }
  @cookies << set_cookie
  nil
end

#set_header(name, value) ⇒ Object

Replaces any existing header of the same name, whatever its case, keeping its position in the output. Raises ArgumentError when the name or value contains CR or LF (header injection / response splitting).

Parameters:

  • name (String)
  • value (String)

Raises:

  • (ArgumentError) —

    on a CR or LF



228
229
230
231
232
233
234
235
236
237
# File 'cybertrain/http/response.rb', line 228

def set_header(name, value)
  reject_crlf!(name, name)
  reject_crlf!(name, value)
  existing = header_key(name)
  if existing.nil? || existing == name
    @headers[name] = value
  else
    respell_header(existing, name, value)
  end
end

#streaming? ⇒ Boolean

Returns true when a BodyWriter is set.

Returns:



168
169
170
# File 'cybertrain/http/response.rb', line 168

def streaming?
  !@body_writer.nil?
end