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}",
}.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


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

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

#configObject (readonly)

Returns the value of attribute config


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

def config
  @config
end

#hostObject (readonly)

Returns the value of attribute host


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

def host
  @host
end

#portObject (readonly)

Returns the value of attribute port


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

def port
  @port
end

#sessionObject (readonly)

Returns the value of attribute session


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

def session
  @session
end

#socketObject (readonly)

Returns the value of attribute socket


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

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)`


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

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

Instance Method Details

#closeObject

Closes the connection immediately.


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

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

#deleteObject

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


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

%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 85

#getObject

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


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

%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 85

#headObject

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


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

%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 85

#postObject

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


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

%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 108

#putObject

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


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

%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 108

#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)

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

def request(headers, body, options = {}, &block)
  raise ArgumentError, ":method and :path headers are required" unless headers[":method"] && headers[":path"]
  @session.request(headers, body, 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


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

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)

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

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