Class: WebPipe::Conn

Inherits:
Dry::Struct
  • Object
show all
Includes:
WebPipe::ConnSupport::Types, Container, Cookies, DrySchema, DryView, Flash, NotFound, Params, Rails, Redirect, Session, Url
Defined in:
lib/web_pipe/conn.rb

Overview

Struct and methods about web request and response data.

It is meant to contain all the data coming from a web request along with all the data needed to build a web response. It can be built with WebPipe::ConnSupport::Builder.

Besides data fetching methods and #rack_response, any other method returns a fresh new instance of it, so it is thought to be used in an immutable way and to allow chaining of method calls.

There are two subclasses (two types) for this: Ongoing and Halted. WebPipe::ConnSupport::Builder constructs a Ongoing struct, while #halt copies the data to a Halted instance. The intention of this is to halt operations on the web request/response cycle one a Halted instance is detected.

Examples:

WebPipe::ConnSupport::Builder.call(env).
  set_status(404).
  add_response_header('Content-Type', 'text/plain').
  set_response_body('Not found').
  halt

Direct Known Subclasses

Halted, Ongoing

Defined Under Namespace

Classes: Halted, Ongoing

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#bag ⇒ Bag[] (readonly)

Hash where anything can be stored. Keys must be symbols.

This can be used to store anything that is needed to be consumed downstream in a pipe of operations action on and returning WebPipe::Conn.

Returns:



212
 
# File 'lib/web_pipe/conn.rb', line 212

attribute :bag, Bag

#config ⇒ Bag[] (readonly)

Instance level configuration.

It is a hash where anything can be stored. Keys must be symbols.

The idea of it is for extensions to have somewhere to store user provided values they may need at some point.

Returns:



224
 
# File 'lib/web_pipe/conn.rb', line 224

attribute :config, Bag

#env ⇒ Env[] (readonly)

Rack env hash.

Returns:

See Also:



43
 
# File 'lib/web_pipe/conn.rb', line 43

attribute :env, Env

#host ⇒ Host[] (readonly)

Host being requested.

Examples:

'www.example.org'

Returns:



85
 
# File 'lib/web_pipe/conn.rb', line 85

attribute :host, Host

#ip ⇒ IP[] (readonly)

IP being requested.

Examples:

'192.168.1.1'

Returns:

  • (IP[]) 


95
 
# File 'lib/web_pipe/conn.rb', line 95

attribute :ip, Ip

#path_info ⇒ PathInfo[] (readonly)

Besides #script_name, the remainder path of the URL or the empty string if none. It is, at least, / when #script_name is empty.

This doesn't include the #query_string.

Examples:

'/foo/bar'.

Returns:



129
 
# File 'lib/web_pipe/conn.rb', line 129

attribute :path_info, PathInfo

#port ⇒ Port[] (readonly)

Port in which the request is made.

Examples:

443

Returns:



105
 
# File 'lib/web_pipe/conn.rb', line 105

attribute :port, Port

#query_string ⇒ QueryString[] (readonly)

Query String of the URL (everything after ? , or the empty string if none).

Examples:

'foo=bar&bar=foo'

Returns:



140
 
# File 'lib/web_pipe/conn.rb', line 140

attribute :query_string, QueryString

#request ⇒ Request[] (readonly)

Rack request.

Returns:

See Also:



52
 
# File 'lib/web_pipe/conn.rb', line 52

attribute :request, Request

#request_body ⇒ RequestBody[] (readonly)

Body sent by the request.

Examples:

'{ resource: "foo" }'

Returns:



150
 
# File 'lib/web_pipe/conn.rb', line 150

attribute :request_body, RequestBody

#request_headers ⇒ Headers[] (readonly)

Hash of request headers.

As per RFC2616, headers names are case insensitive. Here, they are normalized to PascalCase acting on dashes ('-').

Notice that when a rack server maps headers to CGI-like variables, both dashes and underscores (_) are treated as dashes. Here, they always remain as dashes.

Examples:

{ 'Accept-Charset' => 'utf8' }

Returns:

See Also:



169
 
# File 'lib/web_pipe/conn.rb', line 169

attribute :request_headers, Headers

#request_method ⇒ Method[] (readonly)

Method of the request.

It is not called :method in order not to collide with Object#method.

Examples:

:get

Returns:



75
 
# File 'lib/web_pipe/conn.rb', line 75

attribute :request_method, Method

#response_body ⇒ ResponseBody[] (readonly)

Returns Body sent by the response.

Examples:

['<html></html>']

Returns:



187
 
# File 'lib/web_pipe/conn.rb', line 187

attribute :response_body, ResponseBody

#response_headers ⇒ Headers[] (readonly)

Response headers.

Examples:


{ 'Content-Type' => 'text/html' }

Returns:

See Also:



200
 
# File 'lib/web_pipe/conn.rb', line 200

attribute :response_headers, Headers

#scheme ⇒ Scheme[] (readonly)

Scheme of the request.

Examples:

:http

Returns:



62
 
# File 'lib/web_pipe/conn.rb', line 62

attribute :scheme, Scheme

#script_name ⇒ ScriptName[] (readonly)

Script name in the URL, or the empty string if none.

Examples:

'index.rb'

Returns:



115
 
# File 'lib/web_pipe/conn.rb', line 115

attribute :script_name, ScriptName

#status ⇒ Status[] (readonly)

Status sent by the response.

Examples:

200

Returns:



179
 
# File 'lib/web_pipe/conn.rb', line 179

attribute :status, Status

Instance Method Details

#add(key, value) ⇒ Conn

Writes an item to the #bag.

If it already exists, it is overwritten.

Parameters:

  • key (Symbol)
  • value (Object)

Returns:



330
331
332
333
334
 
# File 'lib/web_pipe/conn.rb', line 330

def add(key, value)
  new(
    bag: bag.merge(key => value)
  )
end

#add_config(key, value) ⇒ Conn

Writes an item to #config.

If it already exists, it is overwritten.

Parameters:

  • key (Symbol)
  • value (Object)

Returns:



358
359
360
361
362
 
# File 'lib/web_pipe/conn.rb', line 358

def add_config(key, value)
  new(
    config: config.merge(key => value)
  )
end

#add_flash(key, value) ⇒ Object Originally defined in module Flash

Adds an item to the flash bag to be consumed by next request.

Parameters:

  • key (String)
  • value (String)

#add_flash_now(key, value) ⇒ Object Originally defined in module Flash

Adds an item to the flash bag to be consumed by the same request in process.

Parameters:

  • key (String)
  • value (String)

#add_response_header(key, value) ⇒ Conn

Adds given pair to response headers.

key is normalized.

Parameters:

  • key (String)
  • value (String)

Returns:

See Also:



283
284
285
286
287
288
289
 
# File 'lib/web_pipe/conn.rb', line 283

def add_response_header(key, value)
  new(
    response_headers: ConnSupport::Headers.add(
      response_headers, key, value
    )
  )
end

#add_session(key, value) ⇒ Conn Originally defined in module Session

Adds given key/value pair to the session.

Parameters:

  • key (SESSION_KEY[]) —

    Session key

  • value (Any) —

    Value

Returns:

#base_url ⇒ String Originally defined in module Url

Base part of the URL.

This is #scheme and #host, adding #port unless it is the default one for the scheme.

Examples:

'https://example.org'
'http://example.org:8000'

Returns:

  • (String)

#clear_session ⇒ Conn Originally defined in module Session

Deletes everything from the session.

Returns:

#container ⇒ Any Originally defined in module Container

Returns WebPipe::Conn#config :container value

Returns:

  • (Any)

#delete_cookie(key, opts = Types::EMPTY_HASH) ⇒ Object Originally defined in module Cookies

Parameters:

#delete_response_header(key) ⇒ Conn

Deletes pair with given key from response headers.

It accepts a non normalized key.

Parameters:

  • key (String)

Returns:

See Also:



300
301
302
303
304
305
306
 
# File 'lib/web_pipe/conn.rb', line 300

def delete_response_header(key)
  new(
    response_headers: ConnSupport::Headers.delete(
      response_headers, key
    )
  )
end

#delete_session(key) ⇒ Conn Originally defined in module Session

Deletes given key form the session.

Parameters:

Returns:

#fetch(key, default = Types::Undefined) ⇒ Object

Reads an item from #bag.

registered in the bag.

Parameters:

  • key (Symbol)

Returns:

  • (Object)

Raises:

  • ConnSupport::KeyNotFoundInBagError when key is not



316
317
318
319
320
 
# File 'lib/web_pipe/conn.rb', line 316

def fetch(key, default = Types::Undefined)
  return bag.fetch(key, default) unless default == Types::Undefined

  bag.fetch(key) { raise ConnSupport::KeyNotFoundInBagError, key }
end

#fetch_config(key, default = Types::Undefined) ⇒ Object

Reads an item from #config.

present in #config.

Parameters:

  • key (Symbol)

Returns:

  • (Object)

Raises:

  • ConnSupport::KeyNotFoundInConfigError when key is not



344
345
346
347
348
 
# File 'lib/web_pipe/conn.rb', line 344

def fetch_config(key, default = Types::Undefined)
  return config.fetch(key, default) unless default == Types::Undefined

  config.fetch(key) { raise ConnSupport::KeyNotFoundInConfigError, key }
end

#fetch_session(*args, &block) ⇒ Any Originally defined in module Session

Fetches given key from the session.

Parameters:

  • key (SESSION_KEY[]) —

    Session key to fetch

  • default (Any) —

    Default value if key is not found

Yield Returns:

  • Default value if key is not found and default is not given

Returns:

  • (Any)

Raises:

  • KeyError When key is not found and not default nor block are given

#flash ⇒ Rack::Flash::FlashHash Originally defined in module Flash

Returns the flash bag.

is not being used as middleware

Returns:

  • (Rack::Flash::FlashHash)

#full_path ⇒ String Originally defined in module Url

URL full path.

This is #path with #query_string if present.

Examples:

'/users?id=1'

Returns:

  • (String)

#halt ⇒ Halted

Copies all the data to a Halted instance and returns it.

Returns:



387
388
389
 
# File 'lib/web_pipe/conn.rb', line 387

def halt
  Halted.new(attributes)
end

#halted? ⇒ Bool

Returns whether the instance is Halted.

Returns:

  • (Bool) 


394
395
396
 
# File 'lib/web_pipe/conn.rb', line 394

def halted?
  is_a?(Halted)
end

#helpers ⇒ Object Originally defined in module Rails

See Also:

#not_found ⇒ WebPipe::Conn::Halted Originally defined in module NotFound

Generates the not-found response

Returns:

See Also:

#params(transformation_specs = Types::Undefined) ⇒ Any Originally defined in module Params

Parameters:

  • transformation_specs (Array<Symbol, Array>, Types::Undefined) (defaults to: Types::Undefined)

Returns:

  • (Any)

#path ⇒ String Originally defined in module Url

URL path.

This is #script_name and #path_info.

Examples:

'index.rb/users'

Returns:

  • (String)

#rack_response ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds response in the way rack expects.

It is useful to finish a rack application built with a WebPipe::Conn. After every desired operation has been done, this method has to be called before giving control back to rack.

Returns:

  • [Array]



375
376
377
378
379
380
381
 
# File 'lib/web_pipe/conn.rb', line 375

def rack_response
  [
    status,
    response_headers,
    response_body
  ]
end

#redirect(location, code = 302) ⇒ Object Originally defined in module Redirect

Parameters:

  • location (String)
  • code (Integer) (defaults to: 302)

#render(*args) ⇒ Object Originally defined in module Rails

#request_cookies ⇒ Hash Originally defined in module Cookies

Returns:

  • (Hash)

#sanitized_params ⇒ Object Originally defined in module DrySchema

#session ⇒ Rack::Session::Abstract::SessionHash Originally defined in module Session

Returns Rack::Session's hash

Returns:

  • (Rack::Session::Abstract::SessionHash)

#set_cookie(key, value, opts = Types::EMPTY_HASH) ⇒ Object Originally defined in module Cookies

Parameters:

  • key (String)
  • value (String)
  • opts (SET_COOKIE_OPTIONS[]) (defaults to: Types::EMPTY_HASH)

#set_response_body(content) ⇒ Conn

Sets response body.

As per rack specification, the response body must respond to #each. Here, when given content responds to :each it is set as it is as the new response body. Otherwise, what is set is a one item array of it.

Parameters:

  • content (#each, String)

Returns:

See Also:



249
250
251
252
253
 
# File 'lib/web_pipe/conn.rb', line 249

def set_response_body(content)
  new(
    response_body: content.respond_to?(:each) ? content : [content]
  )
end

#set_response_headers(headers) ⇒ Conn

Sets response headers.

Substitues everything that was present as response headers by the new given hash.

Headers keys are normalized.

Parameters:

  • headers (Hash)

Returns:

See Also:



267
268
269
270
271
 
# File 'lib/web_pipe/conn.rb', line 267

def set_response_headers(headers)
  new(
    response_headers: ConnSupport::Headers.normalize(headers)
  )
end

#set_status(code) ⇒ Conn

Sets response status code.

Parameters:

  • code (StatusCode)

Returns:



231
232
233
234
235
 
# File 'lib/web_pipe/conn.rb', line 231

def set_status(code)
  new(
    status: code
  )
end

#url ⇒ String Originally defined in module Url

Request URL.

This is the same as #base_url plus #full_path.

Examples:

'http://www.example.org:8000/users?id=1'

Returns:

  • (String)

#url_helpers ⇒ Object Originally defined in module Rails

See Also:

#view(view_spec, **kwargs) ⇒ Object Originally defined in module DryView

Sets string output of a view as response body.

If the view is not a Hanami::View instance, it is resolved from the configured container.

kwargs is used as the input for the view (the arguments that Hanami::View#call receives). If they doesn't contain an explicit context: key, it can be added through the injection of the result of a lambda present in context's :view_context.(see Hanami::View::Context#with).

Parameters:

  • view_spec (Hanami::View, Any)
  • kwargs (Hash) —

    Arguments to pass along to Hanami::View#call

Returns:

  • WebPipe::Conn