class Limeade::Client

Client for accessing the LimeSurvey RemoteControl API from Ruby.

Public Class Methods

new(endpoint, username, password, retry_options = {}) click to toggle source

Instantiate a client and setup a connection to the LimeSurvey RemoteControl API. Passes configuration for the Faraday::Request::Retry mechanism. @see Faraday::Request::Retry

@param endpoint [String] The URI for your account's API. @param username [String] The username for your account. @param password [String] The password for your account. @param retry_options [Hash] The options for Faraday::Request::Retry. @option retry_options [Integer] :max (2) Maximum number of retries. @option retry_options [Float] :interval (0) Pause in seconds between retries. @option retry_options [Float] :interval_randomness (0) The maximum random interval amount

expressed as a float between 0 and 1 to use in addition to the interval.

@option retry_options [Float] :max_interval (Float::MAX) An upper limit for the interval. @option retry_options [Float] :backoff_factor (1) The amount to multiply each successive

retry's interval amount by in order to provide backoff.

@option retry_options [Array<Error, String>] :exceptions ([Errno::ETIMEDOUT, 'Timeout::Error',

Error::TimeoutError, Faraday::Error::RetriableResponse]) The list of exceptions
to handle. Exceptions can be given as Class, Module, or String.

@option retry_options [Array<Symbol>] :methods (Faraday::Request::Retry::IDEMPOTENT_METHODS)

A list of HTTP methods to retry without calling retry_if.  Pass an empty Array to call
retry_if for all exceptions.

@option retry_options [Proc] :retry_if (return false) Block that will receive the env object

and the exception raised and decides whether to retry regardless of the retry count.
This would be useful if the exception produced is non-recoverable or if the the HTTP method
called is not idempotent.

@option retry_options [Proc] :retry_block Block that is executed after every retry. Request

environment, middleware options, current number of retries and the exception are passed to
the block as parameters.

@raise [InvalidCredentialsError] The username and password combination is not valid. @raise [ServerError] The API endpoint server is having issues. An error code and message are

included.

@raise [InvalidResponseError] The API endpoint is returning malformed JSON RPC responses.

A descriptive message details the problem.

@raise [URI::InvalidURIError] The API endpoint URI is not valid.

# File lib/limeade/client.rb, line 42
def initialize(endpoint, username, password, retry_options = {})
  @json_rpc = Limeade::JSON_RPC.new(endpoint, retry_options)
  @username = username
  @password = password
  @session_key = get_session_key
end

Public Instance Methods

connected?() click to toggle source

Is the client ready to send requests to the endpoint? @return [Boolean] true if the client is ready; false otherwise.

# File lib/limeade/client.rb, line 51
def connected?
  @session_key && @json_rpc
end
disconnect() click to toggle source

Release resources for this client locally and at the endpoint. @return [Boolean] true if the resources were released; false if client has already disconnected.

# File lib/limeade/client.rb, line 57
def disconnect
  if connected?
    release_session_key
    @json_rpc = nil
    @session_key = nil
    true
  else
    false
  end
end
method_missing(method, *arguments) click to toggle source

Handle LimeSurvey RemoteControl API calls invoked on the client by invoking them on the endpoint. @param method [Symbol] the method invoked @param arguments [Array] the arguments to the method

@raise [ServerError] The API endpoint server is having issues. An error code and message are included. @raise [InvalidResponseError] The API endpoint is returning malformed JSON RPC responses. A descriptive message

@return [Object] the result of invoking the method on the endpoint

Calls superclass method
# File lib/limeade/client.rb, line 76
def method_missing(method, *arguments)
  if API_METHODS.include? method
    process_request(method, *arguments)
  else
    super
  end
end
respond_to_missing?(method_name, include_private = false) click to toggle source
Calls superclass method
# File lib/limeade/client.rb, line 84
def respond_to_missing?(method_name, include_private = false)
  API_METHODS.include?(method_name) || super
end

Private Instance Methods

get_session_key() click to toggle source

Get a session key from the endpoint

@raise [InvalidCredentialsError] The username and password combination is not valid. @raise [ServerError] The API endpoint server is having issues. An error code and message are included. @raise [InvalidResponseError] The API endpoint is returning malformed JSON RPC responses. A descriptive message

details the problem.

@return [String] the session key

# File lib/limeade/client.rb, line 137
def get_session_key
  response = @json_rpc.invoke(:get_session_key, @username, @password)
  raise(InvalidCredentialsError, (response['status'] || response.inspect)) if response.is_a?(Hash)
  response
end
process_request(method_name, *arguments) click to toggle source

Send an LimeSurvey RemoteControl API call to the endpoint and handle the response. @param method [Symbol] the method invoked @param arguments [Array] the arguments to the method

@raise [ServerError] The API endpoint server is having issues. An error code and message are included. @raise [InvalidResponseError] The API endpoint is returning malformed JSON RPC responses. A descriptive message

@return [Object] the result of invoking the method on the endpoint

# File lib/limeade/client.rb, line 98
def process_request(method_name, *arguments)
  raise DisconnectedError unless connected?
  result = @json_rpc.invoke(method_name, @session_key, *arguments)
  if result.is_a?(Hash) && result['status']
    case result['status']
    when 'OK'
      true
    when 'No surveys found'
      []
    when 'No Tokens found'
      []
    when 'No survey participants table'
      false
    when /(left to send)|(No candidate tokens)$/
      result
    when /Invalid surveyid$/i
      nil
    when /Invalid session key$/i
      raise NoSessionError
    else
      raise APIError.new(method_name, result['status'])
    end
  else
    result
  end
rescue NoSessionError
  # Get a fresh session and retry the call.
  @session_key = get_session_key
  retry
end
release_session_key() click to toggle source

Release a session key on the endpoint

@raise [ServerError] The API endpoint server is having issues. An error code and message are included. @raise [InvalidResponseError] The API endpoint is returning malformed JSON RPC responses. A descriptive message

@return [String] “OK”

# File lib/limeade/client.rb, line 149
def release_session_key
  @json_rpc.invoke(:release_session_key, @session_key)
end