Class: Rbeapi::Eapilib::EapiConnection

Inherits:
Object
  • Object
show all
Defined in:
lib/rbeapi/eapilib.rb

Overview

The EapiConnection provides a base class for building eAPI connection instances with a specific transport for connecting to Arista EOS devices. This class handles sending and receiving eAPI calls using JSON-RPC. This class should not need to be directly instantiated.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(transport) ⇒ EapiConnection

The connection contains the transport.

Parameters:

  • transport (Net::HTTP) —

    The HTTP transport to use for sending and receive eAPI request and response messages.



136
137
138
139
 
# File 'lib/rbeapi/eapilib.rb', line 136

def initialize(transport)
  @transport = transport
  @error = nil
end

Instance Attribute Details

#error ⇒ Object (readonly)

Returns the value of attribute error.



127
128
129
 
# File 'lib/rbeapi/eapilib.rb', line 127

def error
  @error
end

#open_timeout ⇒ Object (readonly)

Returns the value of attribute open_timeout.



128
129
130
 
# File 'lib/rbeapi/eapilib.rb', line 128

def open_timeout
  @open_timeout
end

#read_timeout ⇒ Object (readonly)

Returns the value of attribute read_timeout.



129
130
131
 
# File 'lib/rbeapi/eapilib.rb', line 129

def read_timeout
  @read_timeout
end

Instance Method Details

#authentication(opts = {}) ⇒ Object

Configures the connection authentication values (username and password). The authentication values are used to authenticate the eAPI connection. Using authentication is only required for connections that use Http or Https transports.

Parameters:

  • opts (Hash) (defaults to: {}) —

    The authentication parameters.

Options Hash (opts):

  • username (String) —

    The username to use to authenticate with eAPI. Default is ‘admin’.

  • password (String) —

    The password to use to authenticate with eAPI. Default is ”.



154
155
156
157
 
# File 'lib/rbeapi/eapilib.rb', line 154

def authentication(opts = {})
  @username = opts.fetch(:username, 'admin')
  @password = opts.fetch(:password, '')
end

#execute(commands, opts = {}) ⇒ Array<Hash>

Executes the commands on the destination node and returns the response from the node.

Parameters:

  • commands (Array) —

    The ordered list of commands to execute on the destination node.

  • opts (Hash) (defaults to: {}) —

    Optional keyword arguments.

Options Hash (opts):

  • encoding (String) —

    Used to specify the encoding to be used for the response. Valid encoding values are json or text.

  • open_timeout (Float) —

    Number of seconds to wait for the eAPI connection to open.

  • read_timeout (Float) —

    Number of seconds to wait for one block of eAPI results to be read (via one read(2) call).

Returns:

  • (Array<Hash>) —

    This method will return the array of responses for each command executed on the node.

Raises:

  • (CommandError) —

    Raises a CommandError if rescued from the send method and adds the list of commands to the exception message.

  • (ConnectionError) —

    Raises a ConnectionError if rescued and adds the list of commands to the exception message.



321
322
323
324
325
326
327
328
329
330
 
# File 'lib/rbeapi/eapilib.rb', line 321

def execute(commands, opts = {})
  @error = nil
  request = request(commands, opts)
  response = send(request, opts)
  return response['result']
rescue ConnectionError, CommandError => exc
  exc.commands = commands
  @error = exc
  raise
end

#request(commands, opts = {}) ⇒ Hash

Generates the eAPI JSON request message.

Examples:

eAPI Request

{
  "jsonrpc": "2.0",
  "method": "runCmds",
  "params": {
    "version": 1,
    "cmds": [
      <commands>
    ],
    "format": [json, text],
  }
  "id": <reqid>
}

Parameters:

  • commands (Array) —

    The ordered set of commands that should be included in the eAPI request.

  • opts (Hash) (defaults to: {}) —

    Optional keyword arguments.

Options Hash (opts):

  • id (String) —

    The value to use for the eAPI request id. If not provided,the object_id for the connection instance will be used.

  • format (String) —

    The encoding formation to pass in the eAPI request. Valid values are json or text. The default value is json.

Returns:

  • (Hash) —

    Returns a Ruby hash of the request message that is suitable to be JSON encoded and sent to the destination node.



207
208
209
210
211
212
213
214
 
# File 'lib/rbeapi/eapilib.rb', line 207

def request(commands, opts = {})
  id = opts.fetch(:reqid, object_id)
  format = opts.fetch(:format, 'json')
  cmds = [*commands]
  params = { 'version' => 1, 'cmds' => cmds, 'format' => format }
  { 'jsonrpc' => '2.0', 'method' => 'runCmds',
    'params' => params, 'id' => id }
end

#send(data, opts) ⇒ Hash

This method will send the request to the node over the specified transport and return a response message with the contents from the eAPI response. eAPI responds to request messages with either a success message or failure message.

Examples:

eAPI Response - success

{
  "jsonrpc": "2.0",
  "result": [
    {},
    {},
    {
      "warnings": [
        <message>
      ]
    },
  ],
  "id": <reqid>
}

eAPI Response - failure

{
  "jsonrpc": "2.0",
  "error": {
    "code": <int>,
    "message": <string>,
    "data": [
      {},
      {},
      {
        "errors": [
          <message>
        ]
      }
    ]
  },
  "id": <reqid>
}

Parameters:

  • data (Hash) —

    A hash containing the body of the request message. This should be a valid eAPI request message.

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • open_timeout (Float) —

    Number of seconds to wait for the eAPI connection to open.

  • read_timeout (Float) —

    Number of seconds to wait for one block of eAPI results to be read (via one read(2) call).

Returns:

  • (Hash) —

    Returns the response message as a Ruby hash object.

Raises:

  • (CommandError) —

    Raised if an eAPI failure response is return from the destination node.



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/rbeapi/eapilib.rb', line 269

def send(data, opts)
  request = Net::HTTP::Post.new('/command-api')
  request.body = JSON.dump(data)
  request.basic_auth @username, @password

  open_timeout = opts.fetch(:open_timeout, @open_timeout)
  read_timeout = opts.fetch(:read_timeout, @read_timeout)

  begin
    @transport.open_timeout = open_timeout
    @transport.read_timeout = read_timeout
    response = @transport.request(request)
    decoded = JSON(response.body)

    if decoded.include?('error')
      code = decoded['error']['code']
      msg = decoded['error']['message']
      raise CommandError.new(msg, code)
    end
  rescue Timeout::Error
    raise ConnectionError, 'unable to connect to eAPI'
  end

  decoded
end

#timeouts(opts = {}) ⇒ Object

Configures the connection timeout values (open_timeout and read_timeout). The timeout values are used for the eAPI connection.

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • open_timeout (Float) —

    Number of seconds to wait for the eAPI connection to open. Default is DEFAULT_HTTP_OPEN_TIMEOUT.

  • read_timeout (Float) —

    Number of seconds to wait for one block of eAPI results to be read (via one read(2) call). Default is DEFAULT_HTTP_READ_TIMEOUT.



170
171
172
173
 
# File 'lib/rbeapi/eapilib.rb', line 170

def timeouts(opts = {})
  @open_timeout = opts.fetch(:open_timeout, DEFAULT_HTTP_OPEN_TIMEOUT)
  @read_timeout = opts.fetch(:read_timeout, DEFAULT_HTTP_READ_TIMEOUT)
end