Class: Plum::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/plum/client.rb

Constant Summary collapse

DEFAULT_CONFIG = 
{
  http2: true,
  scheme: "https",
  hostname: nil,
  verify_mode: OpenSSL::SSL::VERIFY_PEER,
  ssl_context: nil,
  http2_settings: {},
  user_agent: "plum/#{Plum::VERSION}",
  auto_decode: true,
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host, port = nil, config = {}) ⇒ Client

Creates a new HTTP client.

Parameters:

  • host (String | IO) —

    the host to connect, or IO object.

  • port (Integer) (defaults to: nil) —

    the port number to connect

  • config (Hash<Symbol, Object>) (defaults to: {}) —

    the client configuration



29
30
31
32
33
34
35
36
37
38
 
# File 'lib/plum/client.rb', line 29

def initialize(host, port = nil, config = {})
  if host.is_a?(IO)
    @socket = host
  else
    @host = host
    @port = port || (config[:scheme] == "https" ? 443 : 80)
  end
  @config = DEFAULT_CONFIG.merge(hostname: host).merge(config)
  @started = false
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



15
16
17
 
# File 'lib/plum/client.rb', line 15

def config
  @config
end

#host ⇒ Object (readonly)

Returns the value of attribute host.



15
16
17
 
# File 'lib/plum/client.rb', line 15

def host
  @host
end

#port ⇒ Object (readonly)

Returns the value of attribute port.



15
16
17
 
# File 'lib/plum/client.rb', line 15

def port
  @port
end

#session ⇒ Object (readonly)

Returns the value of attribute session.



16
17
18
 
# File 'lib/plum/client.rb', line 16

def session
  @session
end

#socket ⇒ Object (readonly)

Returns the value of attribute socket.



16
17
18
 
# File 'lib/plum/client.rb', line 16

def socket
  @socket
end

Class Method Details

.start(host, port = nil, config = {}, &block) ⇒ Object

Creates a new HTTP client and starts communication. A shorthand for ‘Plum::Client.new(args).start(&block)`



20
21
22
23
 
# File 'lib/plum/client.rb', line 20

def self.start(host, port = nil, config = {}, &block)
  client = self.new(host, port, config)
  client.start(&block)
end

Instance Method Details

#close ⇒ Object

Closes the connection immediately.



70
71
72
73
74
 
# File 'lib/plum/client.rb', line 70

def close
  @session.close if @session
ensure
  @socket.close if @socket
end

#delete ⇒ Object

Shorthand method for ‘#request`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished



101
102
103
104
105
106
107
108
 
# File 'lib/plum/client.rb', line 101

%w(GET HEAD DELETE).each { |method|
  define_method(:"#{method.downcase}!") do |path, options = {}, &block|
    resume _request_helper(method, path, nil, options, &block)
  end
  define_method(:"#{method.downcase}") do |path, options = {}, &block|
    _request_helper(method, path, nil, options, &block)
  end
}

#delete! ⇒ Object

Shorthand method for ‘Client#resume(Client#request(*args))`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished




# File 'lib/plum/client.rb', line 86

#get ⇒ Object

Shorthand method for ‘#request`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished



101
102
103
104
105
106
107
108
 
# File 'lib/plum/client.rb', line 101

%w(GET HEAD DELETE).each { |method|
  define_method(:"#{method.downcase}!") do |path, options = {}, &block|
    resume _request_helper(method, path, nil, options, &block)
  end
  define_method(:"#{method.downcase}") do |path, options = {}, &block|
    _request_helper(method, path, nil, options, &block)
  end
}

#get! ⇒ Object

Shorthand method for ‘Client#resume(Client#request(*args))`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished




# File 'lib/plum/client.rb', line 86

#head ⇒ Object

Shorthand method for ‘#request`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished



101
102
103
104
105
106
107
108
 
# File 'lib/plum/client.rb', line 101

%w(GET HEAD DELETE).each { |method|
  define_method(:"#{method.downcase}!") do |path, options = {}, &block|
    resume _request_helper(method, path, nil, options, &block)
  end
  define_method(:"#{method.downcase}") do |path, options = {}, &block|
    _request_helper(method, path, nil, options, &block)
  end
}

#head! ⇒ Object

Shorthand method for ‘Client#resume(Client#request(*args))`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished




# File 'lib/plum/client.rb', line 86

#post ⇒ Object

Shorthand method for ‘#request`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • body (String) —

    the request body

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished



124
125
126
127
128
129
130
131
 
# File 'lib/plum/client.rb', line 124

%w(POST PUT).each { |method|
  define_method(:"#{method.downcase}!") do |path, body, options = {}, &block|
    resume _request_helper(method, path, body, options, &block)
  end
  define_method(:"#{method.downcase}") do |path, body, options = {}, &block|
    _request_helper(method, path, body, options, &block)
  end
}

#post! ⇒ Object

Shorthand method for ‘Client#resume(Client#request(*args))`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • body (String) —

    the request body

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished




# File 'lib/plum/client.rb', line 109

#put ⇒ Object

Shorthand method for ‘#request`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • body (String) —

    the request body

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished



124
125
126
127
128
129
130
131
 
# File 'lib/plum/client.rb', line 124

%w(POST PUT).each { |method|
  define_method(:"#{method.downcase}!") do |path, body, options = {}, &block|
    resume _request_helper(method, path, body, options, &block)
  end
  define_method(:"#{method.downcase}") do |path, body, options = {}, &block|
    _request_helper(method, path, body, options, &block)
  end
}

#put! ⇒ Object

Shorthand method for ‘Client#resume(Client#request(*args))`

Parameters:

  • path (String) —

    the absolute path to request (translated into :path header)

  • body (String) —

    the request body

  • options (Hash<Symbol, Object>) —

    the request options

  • block (Proc) —

    if specified, calls the block when finished




# File 'lib/plum/client.rb', line 109

#request(headers, body, options = {}, &block) ⇒ Object

Creates a new HTTP request.

Parameters:

  • headers (Hash<String, String>) —

    the request headers

  • body (String) —

    the request body

  • options (Hash<Symbol, Object>) (defaults to: {}) —

    request options

  • block (Proc) —

    if passed, it will be called when received response headers.

Raises:

  • (ArgumentError) 


81
82
83
84
 
# File 'lib/plum/client.rb', line 81

def request(headers, body, options = {}, &block)
  raise ArgumentError, ":method and :path headers are required" unless headers[":method"] && headers[":path"]
  @session.request(headers, body, @config.merge(options), &block)
end

#resume(response = nil) ⇒ Response

Resume communication with the server, until the specified (or all running) requests are complete.

Parameters:

  • response (Response) (defaults to: nil) —

    if specified, waits only for the response

Returns:

  • (Response) —

    if parameter response is specified



60
61
62
63
64
65
66
67
 
# File 'lib/plum/client.rb', line 60

def resume(response = nil)
  if response
    @session.succ until response.failed? || response.finished?
    response
  else
    @session.succ until @session.empty?
  end
end

#start(&block) ⇒ Object

Starts communication. If block passed, waits for asynchronous requests and closes the connection after calling the block.

Raises:

  • (IOError) 


42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/plum/client.rb', line 42

def start(&block)
  raise IOError, "Session already started" if @started
  _start
  if block_given?
    begin
      ret = yield(self)
      resume
      return ret
    ensure
      close
    end
  end
  self
end