simplyq 0.8.0rc

data/lib/simplyq/api/event_api.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Simplyq
+  module API
+    class EventAPI
+      attr_reader :client
+
+      API_PATH = "/v1/application/{app_id}/event"
+      API_RETRIEVE_PATH = "/v1/application/{app_id}/event/{event_id}"
+      API_DELIVERY_ATTEMPTS_PATH = "/v1/application/{app_id}/event/{event_id}/delivery_attempt"
+      API_DELIVERY_ATTEMPT_PATH = "/v1/application/{app_id}/event/{event_id}/delivery_attempt/{delivery_attempt_id}/"
+      API_ENDPOINTS_PATH = "/v1/application/{app_id}/event/{event_id}/endpoint"
+      API_RETRY_PATH = "/v1/application/{app_id}/endpoint/{endpoint_id}/event/{event_id}"
+
+      # Initializes a new API object.
+      #
+      # @param client [Simplyq::Client] the client object that will be used to
+      #   make HTTP requests.
+      def initialize(client)
+        @client = client
+      end
+
+      def retrieve(application_id, event_id)
+        path = API_RETRIEVE_PATH.gsub("{app_id}", application_id.to_s).gsub("{event_id}", event_id.to_s)
+
+        data, status, headers = client.call_api(:get, path)
+        decerialize(data)
+      end
+
+      def list(application_id, params = {})
+        path = API_PATH.gsub("{app_id}", application_id.to_s)
+
+        data, status, headers = client.call_api(:get, path, { query_params: params })
+        decerialize_list(data, params: params, list_args: [application_id])
+      end
+
+      def create(application_id, event)
+        path = API_PATH.gsub("{app_id}", application_id.to_s)
+
+        data, status, headers = client.call_api(:post, path, { body: build_model(event).to_h })
+        decerialize(data)
+      end
+
+      def retrieve_delivery_attempts(application_id, event_id, params = {})
+        path = API_DELIVERY_ATTEMPTS_PATH.gsub("{app_id}", application_id.to_s).gsub("{event_id}", event_id.to_s)
+
+        data, status, headers = client.call_api(:get, path, { query_params: params })
+        decerialize_delivery_attempts_list(data, params: params, list_args: [application_id, event_id])
+      end
+
+      def retrieve_endpoints(application_id, event_id, params = {})
+        path = API_ENDPOINTS_PATH.gsub("{app_id}", application_id.to_s).gsub("{event_id}", event_id.to_s)
+
+        data, status, headers = client.call_api(:get, path, { query_params: params })
+        decerialize_endpoints_list(data, params: params, list_args: [application_id, event_id])
+      end
+
+      def retry(application_id, endpoint_id, event_id)
+        path = API_RETRY_PATH.gsub("{app_id}", application_id.to_s)
+                             .gsub("{endpoint_id}", endpoint_id.to_s)
+                             .gsub("{event_id}", event_id.to_s)
+
+        data, status, headers = client.call_api(:post, path)
+        status == 202
+      end
+
+      def retrieve_delivery_attempt(application_id, event_id, delivery_attempt_id)
+        path = API_DELIVERY_ATTEMPT_PATH.gsub("{app_id}", application_id.to_s)
+                                        .gsub("{event_id}", event_id.to_s)
+                                        .gsub("{delivery_attempt_id}", delivery_attempt_id.to_s)
+
+        data, status, headers = client.call_api(:get, path)
+        decerialize_delivery_attempt(data)
+      end
+
+      private def build_model(data)
+        return data if data.is_a?(Simplyq::Model::Event)
+        raise ArgumentError, "Invalid data must be a Simplyq::Model::Event or Hash" unless data.is_a?(Hash)
+
+        Simplyq::Model::Event.from_hash(data)
+      end
+
+      private def decerialize(json_data)
+        data = body_to_json(json_data)
+
+        Simplyq::Model::Event.from_hash(data)
+      end
+
+      private def decerialize_delivery_attempt(json_data)
+        data = body_to_json(json_data)
+
+        Simplyq::Model::DeliveryAttempt.from_hash(data)
+      end
+
+      private def decerialize_list(json_data, params: {}, list_args: [])
+        data = body_to_json(json_data)
+
+        Simplyq::Model::List.new(
+          Simplyq::Model::Event, data,
+          api_method: :list,
+          list_args: list_args,
+          filters: params, api: self
+        )
+      end
+
+      private def decerialize_delivery_attempts_list(json_data, params: {}, list_args: [])
+        data = body_to_json(json_data)
+
+        Simplyq::Model::List.new(
+          Simplyq::Model::DeliveryAttempt, data,
+          api_method: :retrieve_delivery_attempts,
+          list_args: list_args,
+          filters: params, api: self
+        )
+      end
+
+      private def decerialize_endpoints_list(json_data, params: {}, list_args: [])
+        data = body_to_json(json_data)
+
+        Simplyq::Model::List.new(
+          Simplyq::Model::Endpoint, data,
+          api_method: :retrieve_endpoints,
+          list_args: list_args,
+          filters: params, api: self
+        )
+      end
+
+      private def body_to_json(body)
+        return if body.nil?
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        raise Simplyq::APIError.new("Invalid JSON in response body.", http_body: body)
+      end
+    end
+  end
+end

data/lib/simplyq/client.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Simplyq
+  class Client
+    HEADER_AUTHORIZATION = "Authorization"
+
+    USER_AGENT = "simplyq-ruby/#{Simplyq::VERSION}"
+
+    attr_reader :config
+
+    # Initialize client to connect to SimplyQ API
+    #
+    # @param config_options [Simplyq::Configuration|Hash] a configuration object or a hash of configuration options
+    def initialize(config_options = {})
+      @config = case config_options
+                when Hash
+                  Simplyq::Configuration.setup do |config|
+                    config_options.each do |key, value|
+                      config.send("#{key}=", value)
+                    end
+                  end
+                when Simplyq::Configuration
+                  config_options
+                else
+                  raise ArgumentError, "Invalid configuration options #{config_options}"
+                end
+      @default_headers = {
+        "Content-Type" => "application/json",
+        "User-Agent" => USER_AGENT
+      }
+    end
+
+    def applications
+      @applications ||= Simplyq::API::ApplicationAPI.new(self)
+    end
+
+    def endpoints
+      @endpoints ||= Simplyq::API::EndpointAPI.new(self)
+    end
+
+    def events
+      @events ||= Simplyq::API::EventAPI.new(self)
+    end
+
+    def check_api_key!
+      raise AuthenticationError, "No API key provided." unless config.api_key
+
+      raise AuthenticationError, "Invalid API key as it includes spaces" if config.api_key =~ /\s/
+    end
+
+    ERROR_MESSAGE_CONNECTION =
+      "Unexpected error communicating when trying to connect to " \
+      "SimplyQ (%s). You may be seeing this message because your DNS is not " \
+      "working or you don't have an internet connection.  To check, try " \
+      "running `host api.simplyq.com` from the command line."
+    ERROR_MESSAGE_SSL =
+      "Could not establish a secure connection to SimplyQ (%s), you " \
+      "may need to upgrade your OpenSSL version. To check, try running " \
+      "`openssl s_client -connect api.simplyq.com:443` from the command " \
+      "line."
+
+    ERROR_MESSAGE_TIMEOUT_SUFFIX =
+      "Please check your internet connection and try again. " \
+      "If this problem persists, you should check SimplyQ's service " \
+      "status at https://simplyq.statuspage.io, or let us know at " \
+      "support@simplyq.io."
+
+    ERROR_MESSAGE_TIMEOUT_CONNECT =
+      "Timed out connecting to SimplyQ (%s). #{ERROR_MESSAGE_TIMEOUT_SUFFIX}"
+
+    ERROR_MESSAGE_TIMEOUT_READ =
+      "Timed out communicating with SimplyQ (%s). #{ERROR_MESSAGE_TIMEOUT_SUFFIX}"
+
+    NETWORK_ERROR_MESSAGES_MAP = {
+      EOFError => ERROR_MESSAGE_CONNECTION,
+      Errno::ECONNREFUSED => ERROR_MESSAGE_CONNECTION,
+      Errno::ECONNRESET => ERROR_MESSAGE_CONNECTION,
+      Errno::EHOSTUNREACH => ERROR_MESSAGE_CONNECTION,
+      Errno::ETIMEDOUT => ERROR_MESSAGE_TIMEOUT_CONNECT,
+      SocketError => ERROR_MESSAGE_CONNECTION,
+
+      Net::OpenTimeout => ERROR_MESSAGE_TIMEOUT_CONNECT,
+      Net::ReadTimeout => ERROR_MESSAGE_TIMEOUT_READ,
+
+      Faraday::TimeoutError => ERROR_MESSAGE_TIMEOUT_READ,
+      Faraday::ConnectionFailed => ERROR_MESSAGE_CONNECTION,
+
+      OpenSSL::SSL::SSLError => ERROR_MESSAGE_SSL,
+      Faraday::SSLError => ERROR_MESSAGE_SSL
+    }.freeze
+    private_constant :NETWORK_ERROR_MESSAGES_MAP
+
+    # Call an API with given options.
+    #
+    # @return [Array<(Object, Integer, Hash)>] an array of 3 elements:
+    #   the data deserialized from response body (could be nil), response status code and response headers.
+    def call_api(http_method, path, opts = {})
+      check_api_key!
+
+      begin
+        response = connection.public_send(http_method.to_sym.downcase) do |req|
+          build_request(http_method, path, req, opts)
+        end
+
+        config.logger.debug "HTTP response body ~BEGIN~\n#{response.body}\n~END~\n" if config.debugging
+
+        unless response.success?
+          if response.status.zero?
+            # Errors from libcurl will be made visible here
+            raise ApiError.new(response.reason_phrase, http_status: 0)
+          else
+            raise specific_http_error(response, get_http_error_data(response).merge(params: opts[:query_params]))
+          end
+        end
+      rescue *NETWORK_ERROR_MESSAGES_MAP.keys => e
+        handle_network_error(e)
+      end
+
+      [response.body, response.status, response.headers]
+    end
+
+    def handle_network_error(error)
+      errors, message = NETWORK_ERROR_MESSAGES_MAP.detect do |(e, _)|
+        error.is_a?(e)
+      end
+
+      if errors.nil?
+        message = "Unexpected error #{error.class.name} communicating " \
+                  "with SimplyQ. Please let us know at support@simplyq.io."
+      end
+
+      message = message % config.base_url
+      message += "\n\n(Network error: #{error.message})"
+
+      raise APIConnectionError.new(message, http_status: 0, error: error)
+    end
+
+    def get_http_error_data(response)
+      body = safe_json_parse_body(response)
+      if body.is_a?(Hash)
+        message = body[:error] || body[:message]
+
+        message = "Invalid request" if message.nil? && body[:errors]
+
+        return {
+          message: message,
+          errors: body[:errors],
+          code: body[:code]
+        }
+      end
+
+      { message: response.reason_phrase }
+    end
+
+    def safe_json_parse_body(response)
+      return nil if response.body.nil?
+
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def specific_http_error(resp, error_data = {})
+      # The standard arguments that are passed to API exceptions
+      opts = {
+        http_body: resp.body,
+        http_headers: resp.headers,
+        http_status: resp.status,
+        code: error_data[:code]
+      }
+
+      case resp.status
+      when 400, 404, 422
+        case error_data[:type]
+        when "idempotency_error"
+          IdempotencyError.new(error_data[:message], **opts)
+        else
+          InvalidRequestError.new(
+            error_data[:message], error_data[:param],
+            **opts.merge(errors: error_data[:errors])
+          )
+        end
+      when 401
+        AuthenticationError.new(error_data[:message] || resp.reason_phrase, **opts)
+      when 402
+        PaymentRequiredError.new(error_data[:message] || resp.reason_phrase, **opts)
+      when 403
+        PermissionError.new(error_data[:message] || resp.reason_phrase, **opts)
+      when 429
+        RateLimitError.new(error_data[:message] || resp.reason_phrase, **opts)
+      else
+        APIError.new(error_data[:message] || resp.reason_phrase, **opts)
+      end
+    end
+
+    def build_request_url(path)
+      # Add leading and trailing slashes to path
+      path = "/#{path}".gsub(%r{/+}, "/")
+      @config.base_url + path
+    end
+
+    # Builds the HTTP request
+    #
+    # @param [String] http_method HTTP method/verb (e.g. POST)
+    # @param [String] path URL path (e.g. /account/new)
+    # @option opts [Hash] :header_params Header parameters
+    # @option opts [Hash] :query_params Query parameters
+    # @option opts [Hash] :form_params Query parameters
+    # @option opts [Object] :body HTTP body (JSON/XML)
+    # @return [Faraday::Request] A Faraday Request
+    def build_request(http_method, path, request, opts = {})
+      url = build_request_url(path)
+      http_method = http_method.to_sym.downcase
+
+      header_params = @default_headers.merge(opts[:header_params] || {})
+      query_params = opts[:query_params] || {}
+      form_params = opts[:form_params] || {}
+
+      header_params[HEADER_AUTHORIZATION] = config.auth_api_key
+
+      if %i[post patch put delete].include?(http_method)
+        req_body = build_request_body(header_params, form_params, opts[:body])
+        config.logger.debug "HTTP request body param ~BEGIN~\n#{req_body}\n~END~\n" if config.debugging
+      end
+      request.headers = header_params
+      request.body = req_body
+
+      # Overload default options only if provided
+      request.options.timeout = config.timeout if config.timeout
+
+      request.url url
+      request.params = query_params
+      download_file(request) if opts[:return_type] == "File" || opts[:return_type] == "Binary"
+      request
+    end
+
+    # Builds the HTTP request body
+    #
+    # @param [Hash] header_params Header parameters
+    # @param [Hash] form_params Query parameters
+    # @param [Object] body HTTP body (JSON/XML)
+    # @return [String] HTTP body data in the form of string
+    def build_request_body(header_params, form_params, body)
+      # http form
+      if header_params["Content-Type"] == "application/x-www-form-urlencoded"
+        data = URI.encode_www_form(form_params)
+      elsif header_params["Content-Type"] == "multipart/form-data"
+        data = {}
+        form_params.each do |key, value|
+          data[key] = case value
+                      when ::File, ::Tempfile
+                        Faraday::FilePart.new(value.path, "application/octet-stream", value.path)
+                      when ::Array, nil
+                        # let Faraday handle Array and nil parameters
+                        value
+                      else
+                        value.to_s
+                      end
+        end
+      elsif body
+        data = body.is_a?(String) ? body : body.to_json
+      else
+        data = nil
+      end
+      data
+    end
+
+    def connection
+      @connection ||= build_connection
+    end
+
+    def build_connection
+      Faraday.new(url: config.base_url, ssl: ssl_options, proxy: config.proxy) do |conn|
+        basic_auth(conn)
+        config.configure_middleware(conn)
+        yield(conn) if block_given?
+        conn.adapter(Faraday.default_adapter)
+      end
+    end
+
+    def ssl_options
+      {
+        ca_file: config.ssl_ca_file,
+        verify: config.ssl_verify,
+        verify_mode: config.ssl_verify_mode,
+        client_cert: config.ssl_client_cert,
+        client_key: config.ssl_client_key
+      }
+    end
+
+    def basic_auth(conn)
+      if config.username && config.password
+        if Gem::Version.new(Faraday::VERSION) >= Gem::Version.new("2.0")
+          conn.request(:authorization, :basic, config.username, config.password)
+        else
+          conn.request(:basic_auth, config.username, config.password)
+        end
+      end
+    end
+  end
+end

data/lib/simplyq/configuration.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Simplyq
+  class Configuration
+    # Defines API keys used with API Key authentications.
+    attr_accessor :api_key
+
+    # Defines the api version
+    attr_accessor :api_version
+
+    # Defines the logger used for debugging.
+    # Default to `Rails.logger` (when in Rails) or logging to STDOUT.
+    #
+    # @return [#debug]
+    attr_accessor :logger
+
+    # Defines the username used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :username
+
+    # Defines the password used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :password
+
+    # Set this to false to skip client side validation in the operation.
+    # Default to true.
+    # @return [true, false]
+    attr_accessor :client_side_validation
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL certificate when calling API from https server.
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :ssl_verify
+
+    ### TLS/SSL setting
+    # Any `OpenSSL::SSL::` constant (see https://ruby-doc.org/stdlib-2.5.1/libdoc/openssl/rdoc/OpenSSL/SSL.html)
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    attr_accessor :ssl_verify_mode
+
+    ### TLS/SSL setting
+    # Set this to customize the certificate file to verify the peer.
+    #
+    # @return [String] the path to the certificate file
+    attr_accessor :ssl_ca_file
+
+    ### TLS/SSL setting
+    # Client certificate file (for client certificate)
+    attr_accessor :ssl_client_cert
+
+    ### TLS/SSL setting
+    # Client private key file (for client certificate)
+    attr_accessor :ssl_client_key
+
+    ### Proxy setting
+    # HTTP Proxy settings
+    attr_accessor :proxy
+
+    attr_accessor :timeout
+
+    attr_accessor :base_url
+
+    attr_accessor :debugging
+
+    attr_reader :open_timeout
+    attr_reader :read_timeout
+    attr_reader :write_timeout
+
+    def self.setup
+      new.tap do |instance|
+        yield(instance) if block_given?
+      end
+    end
+
+    def initialize
+      @timeout = 30
+      @open_timeout = 30
+      @read_timeout = 80
+      @write_timeout = 30
+
+      @client_side_validation = true
+
+      @base_url = "https://api.simplyq.io"
+      @middlewares = Hash.new { |h, k| h[k] = [] }
+      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+
+      yield(self) if block_given?
+    end
+
+    # The default Configuration object.
+    def self.default
+      Configuration.new
+    end
+
+    # Gets Basic Auth token string
+    def basic_auth_token
+      "Basic #{["#{username}:#{password}"].pack("m").delete("\r\n")}"
+    end
+
+    def auth_api_key
+      "Bearer #{@api_key}"
+    end
+
+    # TODO: Remove
+    # def base_path=(base_path)
+    #   # Add leading and trailing slashes to base_path
+    #   @base_path = "/#{base_path}".gsub(%r{/+}, "/")
+    #   @base_path = "" if @base_path == "/"
+    # end
+
+    # TODO: Remove
+    # Returns base URL for specified operation based on server settings
+    # def base_url(operation = nil)
+    #   index = server_operation_index.fetch(operation, server_index)
+    #   return "#{scheme}://#{[host, base_path].join("/").gsub(%r{/+}, "/")}".sub(%r{/+\z}, "") if index.nil?
+
+    #   server_url(index, server_operation_variables.fetch(operation, server_variables),
+    #              operation_server_settings[operation])
+    # end
+
+    # Adds middleware to the stack
+    def use(*middleware)
+      set_faraday_middleware(:use, *middleware)
+    end
+
+    # Adds request middleware to the stack
+    def request(*middleware)
+      set_faraday_middleware(:request, *middleware)
+    end
+
+    # Adds response middleware to the stack
+    def response(*middleware)
+      set_faraday_middleware(:response, *middleware)
+    end
+
+    # Adds Faraday middleware setting information to the stack
+    #
+    # @example Use the `set_faraday_middleware` method to set middleware information
+    #   config.set_faraday_middleware(:request, :retry, max: 3, methods: [:get, :post], retry_statuses: [503])
+    #   config.set_faraday_middleware(:response, :logger, nil, { bodies: true, log_level: :debug })
+    #   config.set_faraday_middleware(:use, Faraday::HttpCache, store: Rails.cache, shared_cache: false)
+    #   config.set_faraday_middleware(:insert, 0, FaradayMiddleware::FollowRedirects, { standards_compliant: true, limit: 1 })
+    #   config.set_faraday_middleware(:swap, 0, Faraday::Response::Logger)
+    #   config.set_faraday_middleware(:delete, Faraday::Multipart::Middleware)
+    #
+    # @see https://github.com/lostisland/faraday/blob/v2.3.0/lib/faraday/rack_builder.rb#L92-L143
+    def set_faraday_middleware(operation, key, *args, &block)
+      unless %i[request response use insert insert_before insert_after swap delete].include?(operation)
+        raise ArgumentError, "Invalid faraday middleware operation #{operation}. Must be" \
+                             " :request, :response, :use, :insert, :insert_before, :insert_after, :swap or :delete."
+      end
+
+      @middlewares[operation] << [key, args, block]
+    end
+    ruby2_keywords(:set_faraday_middleware) if respond_to?(:ruby2_keywords, true)
+
+    # Set up middleware on the connection
+    def configure_middleware(connection)
+      return if @middlewares.empty?
+
+      %i[request response use insert insert_before insert_after swap].each do |operation|
+        next unless @middlewares.key?(operation)
+
+        @middlewares[operation].each do |key, args, block|
+          connection.builder.send(operation, key, *args, &block)
+        end
+      end
+
+      if @middlewares.key?(:delete)
+        @middlewares[:delete].each do |key, _args, _block|
+          connection.builder.delete(key)
+        end
+      end
+    end
+  end
+end