poms 1.2.2 → 2.0.0.a

data/lib/poms/api/auth.rb

@@ -1,3 +1,5 @@
+require 'base64'
+
 module Poms
   module Api
     # This module can be used to create an authentication header for the Poms
@@ -5,36 +7,54 @@ module Poms
     #
     # see: http://wiki.publiekeomroep.nl/display/npoapi/Algemeen
     module Auth
-      # Create an auth header for the Poms API. This is a codified string
-      # consisting of a message that is hashed with a secret.
-      #
-      # @see message
-      # @param secret The Poms API secret key
-      # @param message The message that needs to be hashed.
-      def self.encode(secret, message)
+      module_function
+
+      extend SingleForwardable
+
+      delegate %i(origin secret key) => :@credentials
+
+      # @param request The prepared request
+      # @param credentials The Poms API credentials
+      # @param clock Defaults to current time, but can be provided as Time
+      def sign(request, credentials, clock = Time.now)
+        @credentials = credentials
+        timestamp = clock.rfc822
+        message = generate_message(request.uri, timestamp)
+
+        request['Origin'] = origin
+        request['X-NPO-Date'] = timestamp
+        request['Authorization'] = "NPO #{key}:#{encrypt(message)}"
+        request
+      end
+
+      # Create a message for the Authorization header. This is an encrypted
+      # stringconsisting of a message that is hashed with a shared secret.
+      def encrypt(message)
         sha256 = OpenSSL::Digest.new('sha256')
         digest = OpenSSL::HMAC.digest(sha256, secret, message)
-        Base64.encode64(digest)
+        Base64.encode64(digest).strip
       end
 
-      # Creates the header that is used for authenticating a request to the Poms
-      # API.
-      #
-      # @param uri The uri that is being requested
-      # @param origin The origin header
-      # @param date The date as an RFC822 string
-      # @param params The url params as a ruby hash
-      def self.message(uri, origin, date, params = {})
-        params_string = params.sort.map do |key, value|
-          "#{key}:#{value}"
-        end.join(',') if params.present?
+      # Creates a message in the required format as specified by POMS
+      # documentation.
+      # @param uri The Addressable::URI
+      # @param timestamp An rfc822 formatted timestamp
+      def generate_message(uri, timestamp)
         [
           "origin:#{origin}",
-          "x-npo-date:#{date}",
-          "uri:#{uri}",
-          params_string
+          "x-npo-date:#{timestamp}",
+          "uri:#{uri.path}",
+          params_string(uri.query_values)
         ].compact.join(',')
       end
+
+      # Convert a hash of parameters to the format expected by the message
+      def params_string(params)
+        return unless params
+        params.map { |key, value| "#{key}:#{value}" }.sort.join(',')
+      end
+
+      private_class_method :generate_message, :encrypt, :params_string
     end
   end
 end

data/lib/poms/api/client.rb

@@ -0,0 +1,58 @@
+require 'poms/api/drivers/net_http'
+require 'poms/api/request'
+require 'poms/api/auth'
+require 'poms/errors'
+
+module Poms
+  module Api
+    # The Client module isolates all HTTP interactions, regardless of the driver
+    # module to implement the actual operations. Use the Client module to build
+    # signed requests and execute them.
+    #
+    # @see Poms::Api::Drivers::NetHttp
+    module Client
+      extend Drivers::NetHttp
+
+      module_function
+
+      def get(uri, credentials, headers = {})
+        handle_response(
+          execute(
+            Auth.sign(
+              prepare_get(uri, headers),
+              credentials
+            )
+          )
+        )
+      end
+
+      def post(uri, body, credentials, headers = {})
+        handle_response(
+          execute(
+            Auth.sign(
+              prepare_post(uri, body, headers),
+              credentials
+            )
+          )
+        )
+      end
+
+      def handle_response(response)
+        case response.code
+        when 400..499 then raise Errors::HttpMissingError, response.code
+        when 500..599 then raise Errors::HttpServerError, response.code
+        else
+          response
+        end
+      end
+
+      def prepare_get(uri, headers = {})
+        Request.get(uri, nil, headers)
+      end
+
+      def prepare_post(uri, body, headers = {})
+        Request.post(uri, body, headers)
+      end
+    end
+  end
+end

data/lib/poms/api/drivers/net_http.rb

@@ -0,0 +1,69 @@
+require 'net/https'
+require 'poms/api/response'
+require 'poms/errors'
+
+module Poms
+  module Api
+    module Drivers
+      # The NetHttp driver is a special module that can be used to implement the
+      # HTTP operations in the Client module. This is done by including a driver
+      # module into the client.
+      #
+      # This module isolates all knowledge of Net::HTTP.
+      #
+      # @see Poms::Api::Client
+      module NetHttp
+        NET_HTTP_ERRORS = [
+          Timeout::Error,
+          Errno::EINVAL,
+          Errno::ECONNRESET,
+          EOFError,
+          Net::HTTPBadResponse,
+          Net::HTTPHeaderSyntaxError,
+          Net::ProtocolError
+        ].freeze
+
+        def execute(request_description)
+          response = attempt_request(
+            request_description.uri,
+            prepare_request(request_description)
+          )
+          Response.new(response.code, response.body, response.to_hash)
+        end
+
+        private
+
+        def attempt_request(uri, request)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+            http.open_timeout = 5
+            http.read_timeout = 5
+            http.request(request)
+          end
+        rescue *NET_HTTP_ERRORS => e
+          raise Errors::HttpError,
+                "An error (#{e.class}) occured while processing your request."
+        end
+
+        def prepare_request(request_description)
+          request = request_to_net_http_request(request_description)
+          request.body = request_description.body.to_s
+          request_description.each_header do |key, value|
+            request[key] = value
+          end
+          request
+        end
+
+        def request_to_net_http_request(request_description)
+          uri = request_description.uri
+          if request_description.get?
+            Net::HTTP::Get.new(uri)
+          elsif request_description.post?
+            Net::HTTP::Post.new(uri)
+          else
+            raise ArgumentError, 'can only execute GET or POST requests'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poms/api/json_client.rb

@@ -0,0 +1,35 @@
+require 'poms/api/client'
+
+module Poms
+  module Api
+    # The JsonClient module is a wrapper around the regular Client module. It
+    # requests and responses to handle JSON-formatted bodies.
+    module JsonClient
+      DEFAULT_HEADERS = {
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json'
+      }.freeze
+
+      module_function
+
+      def get(uri, credentials, headers = {})
+        response = Client.get(
+          uri,
+          credentials,
+          DEFAULT_HEADERS.merge(headers)
+        )
+        JSON.parse(response.body)
+      end
+
+      def post(uri, body, credentials, headers = {})
+        response = Client.post(
+          uri,
+          body.to_json,
+          credentials,
+          DEFAULT_HEADERS.merge(headers)
+        )
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/poms/api/pagination_client.rb

@@ -0,0 +1,67 @@
+require 'poms/api/json_client'
+
+module Poms
+  module Api
+    # Creates lazy Enumerators to handle pagination of the Poms API and performs
+    # the request on demand.
+    module PaginationClient
+      module_function
+
+      def get(uri, credentials)
+        execute(uri) do |page_uri|
+          Api::JsonClient.get(page_uri, credentials)
+        end
+      end
+
+      def post(uri, body, credentials)
+        execute(uri) do |page_uri|
+          Api::JsonClient.post(page_uri, body, credentials)
+        end
+      end
+
+      def execute(uri)
+        Enumerator.new do |yielder|
+          page = Page.new(uri)
+          loop do
+            page.execute { |page_uri| yield page_uri }
+            page.items.each { |item| yielder << item }
+            raise StopIteration if page.final?
+            page = page.next_page
+          end
+        end.lazy
+      end
+
+      # Keep track of number of items and how many have been retrieved
+      class Page
+        def initialize(uri, offset = 0)
+          uri.query_values = { offset: offset }
+          @uri = uri
+        end
+
+        def next_page
+          self.class.new(uri, next_index)
+        end
+
+        def final?
+          next_index >= response['total']
+        end
+
+        def items
+          response['items']
+        end
+
+        def execute
+          @response = yield uri
+        end
+
+        private
+
+        attr_reader :response, :uri
+
+        def next_index
+          response['offset'] + response['max']
+        end
+      end
+    end
+  end
+end

data/lib/poms/api/request.rb

@@ -1,43 +1,41 @@
-require 'poms/api/auth'
+require 'forwardable'
 
 module Poms
   module Api
-    # A request to the Poms API. Does the authentication and allows you to
-    # execute the request.
+    # The `Request` object is an implementation-agnostic description of an HTTP
+    # request, representing a combination of an HTTP method, URI, body and
+    # headers.
     class Request
-      # Create a new request to the Poms API. The request is initialized with a
-      # URI to be called and the key, secret and origin that are needed for
-      # authentication.
-      #
-      # @param uri The full URI to call on the Poms API
-      # @param key The api key
-      # @param secret The secret that goes with the api key
-      # @param origin The whitelisted origin for this api key
-      def initialize(uri, key, secret, origin)
-        @uri = uri
-        @path = URI(@uri).path
-        @key = key
-        @secret = secret
-        @origin = origin
+      extend Forwardable
+      def_delegators :@headers, :[], :[]=
+      def_delegator :@headers, :each, :each_header
+
+      attr_reader :uri, :body
+
+      def self.get(*args)
+        new(:get, *args)
       end
 
-      # Executes the request.
-      def call
-        open(@uri, headers)
+      def self.post(*args)
+        new(:post, *args)
       end
 
-      private
+      def initialize(method, uri, body = nil, headers = {})
+        @method = method.to_sym
+        unless %i(get post).include?(@method)
+          raise ArgumentError, 'method should be :get or :post'
+        end
+        @uri = uri
+        @body = body.to_s
+        @headers = headers.to_h
+      end
+
+      def get?
+        @method == :get
+      end
 
-      def headers
-        date = Time.now.rfc822
-        origin = @origin
-        message = Auth.message(@path, @origin, date)
-        encoded_message = Auth.encode(@secret, message)
-        {
-          'Origin' => origin,
-          'X-NPO-Date' => date,
-          'Authorization' => "NPO #{@key}:#{encoded_message}"
-        }
+      def post?
+        @method == :post
       end
     end
   end

data/lib/poms/api/response.rb

@@ -0,0 +1,31 @@
+module Poms
+  module Api
+    # Response is an implementation-agnostic representation of an HTTP-response,
+    # composing a HTTP status code, body and hash of headers.
+    class Response
+      # @return [Fixnum]
+      attr_reader :code
+
+      # @return [String]
+      attr_reader :body
+
+      # @return [Hash]
+      attr_reader :headers
+
+      def initialize(code, body, headers)
+        @code = code.to_i
+        @body = body.to_s
+        @headers = headers.to_h
+        freeze
+      end
+
+      def eql?(other)
+        other.is_a?(self.class) &&
+          code == other.code &&
+          body == other.body &&
+          headers == other.headers
+      end
+      alias == eql?
+    end
+  end
+end

data/lib/poms/api/search.rb

@@ -0,0 +1,38 @@
+require 'poms/timestamp'
+
+module Poms
+  module Api
+    # Map search parameters to POMS specific format
+    module Search
+      TIME_PARAMS = {
+        starts_at: 'begin',
+        ends_at: 'end'
+      }.freeze
+
+      def self.build(options)
+        return {} if options.empty?
+        all = options.map do |key, value|
+          case key
+          when :starts_at, :ends_at
+            time_params(key, value)
+          when :type
+            { 'facets' => { 'subsearch' => { 'types' => value } } }
+          end
+        end
+        all.reduce(&:deep_merge)
+      end
+
+      private_class_method
+
+      def self.time_params(key, value)
+        {
+          'searches' => {
+            'sortDates' => {
+              TIME_PARAMS[key] => Timestamp.to_unix_ms(value)
+            }
+          }
+        }
+      end
+    end
+  end
+end