class Rbeapi::Eapilib::EapiConnection

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.

Attributes

error[R]
open_timeout[R]
read_timeout[R]

Public Class Methods

new(transport) click to toggle source

The connection contains the transport.

@param transport [Net::HTTP] The HTTP transport to use for sending

and receive eAPI request and response messages.
# File lib/rbeapi/eapilib.rb, line 136
def initialize(transport)
  @transport = transport
  @error = nil
end

Public Instance Methods

authentication(opts = {}) click to toggle source

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.

@param opts [Hash] The authentication parameters.

@option opts username [String] The username to use to

authenticate with eAPI. Default is 'admin'.

@option opts password [String] The password to use to

authenticate with eAPI. Default is ''.
# File lib/rbeapi/eapilib.rb, line 154
def authentication(opts = {})
  @username = opts.fetch(:username, 'admin')
  @password = opts.fetch(:password, '')
end
execute(commands, opts = {}) click to toggle source

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

@param commands [Array] The ordered list of commands to execute

on the destination node.

@param opts [Hash] Optional keyword arguments.

@option opts encoding [String] Used to specify the encoding to be

used for the response. Valid encoding values are json or text.

@option opts open_timeout [Float] Number of seconds to wait for the

eAPI connection to open.

@option opts read_timeout [Float] Number of seconds to wait for one

block of eAPI results to be read (via one read(2) call).

@return [Array<Hash>] This method will return the array of responses

for each command executed on the node.

@raise [CommandError] Raises a CommandError if rescued from the

send method and adds the list of commands to the exception message.

@raise [ConnectionError] Raises a ConnectionError if rescued and

adds the list of commands to the exception message.
# 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 = {}) click to toggle source

Generates the eAPI JSON request message.

@example eAPI Request

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

@param commands [Array] The ordered set of commands that should

be included in the eAPI request.

@param opts [Hash] Optional keyword arguments.

@option 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.

@option opts format [String] The encoding formation to pass in

the eAPI request. Valid values are json or text. The default
value is json.

@return [Hash] Returns a Ruby hash of the request message that is

suitable to be JSON encoded and sent to the destination node.
# 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) click to toggle source

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.

@example eAPI Response - success

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

@example eAPI Response - failure

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

@param data [Hash] A hash containing the body of the request

message. This should be a valid eAPI request message.

@option opts open_timeout [Float] Number of seconds to wait for the

eAPI connection to open.

@option opts read_timeout [Float] Number of seconds to wait for one

block of eAPI results to be read (via one read(2) call).

@return [Hash] Returns the response message as a Ruby hash object.

@raise [CommandError] Raised if an eAPI failure response is return

from the destination node.
# 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 = {}) click to toggle source

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

@option opts open_timeout [Float] Number of seconds to wait for the

eAPI connection to open. Default is DEFAULT_HTTP_OPEN_TIMEOUT.

@option opts 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.
# 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