contractful 0.1.0

data/lib/contractful/resource.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Contractful
+  # A class that can be instantiated for access to a RESTful resource,
+  # including authentication.
+  #
+  # Example:
+  #
+  #   resource = Contractful::Resource.new('http://some/resource')
+  #   jpg = resource.get(:accept => 'image/jpg')
+  #
+  # With HTTP basic authentication:
+  #
+  #   resource = Contractful::Resource.new('http://protected/resource', :user => 'user', :password => 'password')
+  #   resource.delete
+  #
+  # With a timeout (seconds):
+  #
+  #   Contractful::Resource.new('http://slow', :read_timeout => 10)
+  #
+  # With an open timeout (seconds):
+  #
+  #   Contractful::Resource.new('http://behindfirewall', :open_timeout => 10)
+  #
+  # You can also use resources to share common headers. For headers keys,
+  # symbols are converted to strings. Example:
+  #
+  #   resource = Contractful::Resource.new('http://some/resource', :headers => { :client_version => 1 })
+  #
+  # This header will be transported as Client-Version (symbol keys are split
+  # on underscores and capitalized; no X- prefix is added)
+  #
+  # Use the [] syntax to allocate subresources:
+  #
+  #   site = Contractful::Resource.new('http://example.com', :user => 'adam', :password => 'mypasswd')
+  #   site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
+  #
+  class Resource
+    attr_reader :url, :options, :block
+
+    def initialize(url, options = {}, backwards_compatibility = nil, &block)
+      @url = url
+      @block = block
+      # compatibility with previous versions
+      @options = if options.instance_of?(Hash)
+                   options
+                 else
+                   { user: options, password: backwards_compatibility }
+                 end
+    end
+
+    def get(additional_headers = {}, &block)
+      headers = (options[:headers] || {}).merge(additional_headers)
+      Request.execute(options.merge(
+                        method: :get,
+                        url: url,
+                        headers: headers,
+                        log: log
+                      ), &block || @block)
+    end
+
+    def head(additional_headers = {}, &block)
+      headers = (options[:headers] || {}).merge(additional_headers)
+      Request.execute(options.merge(
+                        method: :head,
+                        url: url,
+                        headers: headers,
+                        log: log
+                      ), &block || @block)
+    end
+
+    def post(payload, additional_headers = {}, &block)
+      headers = (options[:headers] || {}).merge(additional_headers)
+      Request.execute(options.merge(
+                        method: :post,
+                        url: url,
+                        payload: payload,
+                        headers: headers,
+                        log: log
+                      ), &block || @block)
+    end
+
+    def put(payload, additional_headers = {}, &block)
+      headers = (options[:headers] || {}).merge(additional_headers)
+      Request.execute(options.merge(
+                        method: :put,
+                        url: url,
+                        payload: payload,
+                        headers: headers,
+                        log: log
+                      ), &block || @block)
+    end
+
+    def patch(payload, additional_headers = {}, &block)
+      headers = (options[:headers] || {}).merge(additional_headers)
+      Request.execute(options.merge(
+                        method: :patch,
+                        url: url,
+                        payload: payload,
+                        headers: headers,
+                        log: log
+                      ), &block || @block)
+    end
+
+    def delete(additional_headers = {}, &block)
+      headers = (options[:headers] || {}).merge(additional_headers)
+      Request.execute(options.merge(
+                        method: :delete,
+                        url: url,
+                        headers: headers,
+                        log: log
+                      ), &block || @block)
+    end
+
+    def to_s
+      url
+    end
+
+    def user
+      options[:user]
+    end
+
+    def password
+      options[:password]
+    end
+
+    def headers
+      options[:headers] || {}
+    end
+
+    def read_timeout
+      options[:read_timeout]
+    end
+
+    def open_timeout
+      options[:open_timeout]
+    end
+
+    def log
+      options[:log] || Contractful.log
+    end
+
+    # Construct a subresource, preserving authentication.
+    #
+    # Example:
+    #
+    #   site = Contractful::Resource.new('http://example.com', 'adam', 'mypasswd')
+    #   site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
+    #
+    # This is especially useful if you wish to define your site in one place and
+    # call it in multiple locations:
+    #
+    #   def orders
+    #     Contractful::Resource.new('http://example.com/orders', 'admin', 'mypasswd')
+    #   end
+    #
+    #   orders.get                     # GET http://example.com/orders
+    #   orders['1'].get                # GET http://example.com/orders/1
+    #   orders['1/items'].delete       # DELETE http://example.com/orders/1/items
+    #
+    # Nest resources as far as you want:
+    #
+    #   site = Contractful::Resource.new('http://example.com')
+    #   posts = site['posts']
+    #   first_post = posts['1']
+    #   comments = first_post['comments']
+    #   comments.post 'Hello', :content_type => 'text/plain'
+    #
+    def [](suburl, &new_block)
+      if block_given?
+        self.class.new(concat_urls(url, suburl), options, &new_block)
+      elsif block
+        self.class.new(concat_urls(url, suburl), options, &block)
+      else
+        self.class.new(concat_urls(url, suburl), options)
+      end
+    end
+
+    def concat_urls(url, suburl) # :nodoc:
+      url = url.to_s
+      suburl = suburl.to_s
+      if url.slice(-1, 1) == '/' or suburl.slice(0, 1) == '/'
+        url + suburl
+      else
+        "#{url}/#{suburl}"
+      end
+    end
+  end
+end

data/lib/contractful/response.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Contractful
+  # A Response from Contractful, you can access the response body, the code or the headers.
+  #
+  class Response < String
+    include AbstractResponse
+
+    # Return the HTTP response body.
+    #
+    # Future versions of Contractful will deprecate treating response objects
+    # directly as strings, so it will be necessary to call `.body`.
+    #
+    # @return [String]
+    #
+    def body
+      # Benchmarking suggests that "#{self}" is fastest, and that caching the
+      # body string in an instance variable doesn't make it enough faster to be
+      # worth the extra memory storage.
+      String.new(self)
+    end
+
+    # Convert the HTTP response body to a pure String object.
+    #
+    # @return [String]
+    def to_s
+      body
+    end
+
+    # Convert the HTTP response body to a pure String object.
+    #
+    # @return [String]
+    def to_str
+      body
+    end
+
+    # Parse the response body as JSON and return the result.
+    #
+    # This is a convenience wrapper around `JSON.parse(body)`. Any keyword
+    # arguments are forwarded to `JSON.parse`, so for example:
+    #
+    #   response.json                          # => {"a" => 1}
+    #   response.json(symbolize_names: true)   # => {a: 1}
+    #
+    # Raises `JSON::ParserError` if the body is not valid JSON. Note that the
+    # return value is a plain parsed data structure, not a Response object.
+    #
+    # @param kwargs [Hash] keyword arguments forwarded to JSON.parse
+    #
+    # @return [Object] the parsed JSON data structure (typically Hash or Array)
+    #
+    def json(**kwargs)
+      JSON.parse(to_s, **kwargs)
+    end
+
+    def inspect
+      "<Contractful::Response #{code.inspect} #{body_truncated(10).inspect}>"
+    end
+
+    # Initialize a Response object. Because Contractful::Response is
+    # (unfortunately) a subclass of String for historical reasons,
+    # Response.create is the preferred initializer.
+    #
+    # @param [String, nil] body The response body from the Net::HTTPResponse
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [Contractful::Request] request
+    # @param [Time] start_time
+    def self.create(body, net_http_res, request, start_time = nil)
+      result = new(body || '')
+
+      result.response_set_vars(net_http_res, request, start_time)
+      fix_encoding(result)
+
+      result
+    end
+
+    # Set the String encoding according to the 'Content-Type: charset' header,
+    # if possible.
+    def self.fix_encoding(response)
+      charset = Contractful::Utils.get_encoding_from_headers(response.headers)
+      encoding = nil
+
+      begin
+        encoding = Encoding.find(charset) if charset
+      rescue ArgumentError
+        response.log << "No such encoding: #{charset.inspect}" if response.log
+      end
+
+      return unless encoding
+
+      response.force_encoding(encoding)
+
+      response
+    end
+
+    private
+
+    def body_truncated(length)
+      b = body
+      if b.length > length
+        # b[0..length] is inclusive, returning length+1 chars before the
+        # ellipsis — use b[0, length] for an exact cut.
+        "#{b[0, length]}..."
+      else
+        b
+      end
+    end
+  end
+end

data/lib/contractful/utils.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'http/accept'
+
+module Contractful
+  # Various utility methods
+  module Utils
+    # Return encoding from an HTTP header hash.
+    #
+    # We use the RFC 7231 specification and do not impose a default encoding on
+    # text. This differs from the older RFC 2616 behavior, which specifies
+    # using ISO-8859-1 for text/* content types without a charset.
+    #
+    # Strings will use the default encoding when this method returns nil. This
+    # default is likely to be UTF-8 for Ruby >= 2.0
+    #
+    # @param headers [Hash<Symbol,String>]
+    #
+    # @return [String, nil] Return the string encoding or nil if no header is
+    #   found.
+    #
+    # @example
+    #   >> get_encoding_from_headers({:content_type => 'text/plain; charset=UTF-8'})
+    #   => "UTF-8"
+    #
+    def self.get_encoding_from_headers(headers)
+      type_header = headers[:content_type]
+      return nil unless type_header
+
+      begin
+        _content_type, params = cgi_parse_header(type_header)
+      rescue HTTP::Accept::ParseError
+        nil
+      else
+        params['charset']
+      end
+    end
+
+    # Parse a Content-Type like header.
+    #
+    # Return the main content-type and a hash of params.
+    #
+    # @param [String] line
+    # @return [Array(String, Hash)]
+    #
+    def self.cgi_parse_header(line)
+      types = HTTP::Accept::MediaTypes.parse(line)
+
+      raise HTTP::Accept::ParseError.new('Found no types in header line') if types.empty?
+
+      [types.first.mime_type, types.first.parameters]
+    end
+
+    # Serialize a ruby object into HTTP query string parameters.
+    #
+    # There is no standard for doing this, so we choose our own slightly
+    # idiosyncratic format. The output closely matches the format understood by
+    # Rails, Rack, and PHP.
+    #
+    # If you don't want handling of complex objects and only want to handle
+    # simple flat hashes, you may want to use `URI.encode_www_form` instead,
+    # which implements HTML5-compliant URL encoded form data.
+    #
+    # @param [Hash,ParamsArray] object The object to serialize
+    #
+    # @return [String] A string appropriate for use as an HTTP query string
+    #
+    # @see flatten_params
+    #
+    # @see URI.encode_www_form
+    #
+    # @see See also Object#to_query in ActiveSupport
+    # @see http://php.net/manual/en/function.http-build-query.php
+    #   http_build_query in PHP
+    # @see See also Rack::Utils.build_nested_query in Rack
+    #
+    # Notable differences from the ActiveSupport implementation:
+    #
+    # - Empty hash and empty array are treated the same as nil instead of being
+    #   omitted entirely from the output. Rather than disappearing, they will
+    #   appear to be nil instead.
+    #
+    # It's most common to pass a Hash as the object to serialize, but you can
+    # also use a ParamsArray if you want to be able to pass the same key with
+    # multiple values and not use the rack/rails array convention.
+    #
+    # @since 2.0.0
+    #
+    # @example Simple hashes
+    #   >> encode_query_string({foo: 123, bar: 456})
+    #   => 'foo=123&bar=456'
+    #
+    # @example Simple arrays
+    #   >> encode_query_string({foo: [1,2,3]})
+    #   => 'foo[]=1&foo[]=2&foo[]=3'
+    #
+    # @example Nested hashes
+    #   >> encode_query_string({outer: {foo: 123, bar: 456}})
+    #   => 'outer[foo]=123&outer[bar]=456'
+    #
+    # @example Deeply nesting
+    #   >> encode_query_string({coords: [{x: 1, y: 0}, {x: 2}, {x: 3}]})
+    #   => 'coords[][x]=1&coords[][y]=0&coords[][x]=2&coords[][x]=3'
+    #
+    # @example Null and empty values
+    #   >> encode_query_string({string: '', empty: nil, list: [], hash: {}})
+    #   => 'string=&empty&list&hash'
+    #
+    # @example Nested nulls
+    #   >> encode_query_string({foo: {string: '', empty: nil}})
+    #   => 'foo[string]=&foo[empty]'
+    #
+    # @example Multiple fields with the same name using ParamsArray
+    #   >> encode_query_string(Contractful::ParamsArray.new([[:foo, 1], [:foo, 2], [:foo, 3]]))
+    #   => 'foo=1&foo=2&foo=3'
+    #
+    # @example Nested ParamsArray
+    #   >> encode_query_string({foo: Contractful::ParamsArray.new([[:a, 1], [:a, 2]])})
+    #   => 'foo[a]=1&foo[a]=2'
+    #
+    #   >> encode_query_string(Contractful::ParamsArray.new([[:foo, {a: 1}], [:foo, {a: 2}]]))
+    #   => 'foo[a]=1&foo[a]=2'
+    #
+    def self.encode_query_string(object)
+      flatten_params(object, true).map { |k, v| v.nil? ? k : "#{k}=#{v}" }.join('&')
+    end
+
+    # Transform deeply nested param containers into a flat array of [key,
+    # value] pairs.
+    #
+    # @example
+    #   >> flatten_params({key1: {key2: 123}})
+    #   => [["key1[key2]", 123]]
+    #
+    # @example
+    #   >> flatten_params({key1: {key2: 123, arr: [1,2,3]}})
+    #   => [["key1[key2]", 123], ["key1[arr][]", 1], ["key1[arr][]", 2], ["key1[arr][]", 3]]
+    #
+    # @param object [Hash, ParamsArray] The container to flatten
+    # @param uri_escape [Boolean] Whether to URI escape keys and values
+    # @param parent_key [String] Should not be passed (used for recursion)
+    # @param depth [Integer] Should not be passed (used for recursion).
+    #   Hard cap at MAX_FLATTEN_DEPTH to prevent SystemStackError on
+    #   cyclically-referenced or adversarially-nested input.
+    #
+    MAX_FLATTEN_DEPTH = 100
+
+    def self.flatten_params(object, uri_escape = false, parent_key = nil, depth = 0)
+      unless object.is_a?(Hash) || object.is_a?(ParamsArray) ||
+             (parent_key && object.is_a?(Array))
+        raise ArgumentError.new('expected Hash or ParamsArray, got: ' + object.inspect)
+      end
+
+      if depth > MAX_FLATTEN_DEPTH
+        raise ArgumentError,
+              "flatten_params nested deeper than #{MAX_FLATTEN_DEPTH} levels " \
+              '(reject input, or raise MAX_FLATTEN_DEPTH if you have a ' \
+              'legitimate use case)'
+      end
+
+      # transform empty collections into nil, where possible
+      return [[parent_key, nil]] if object.empty? && parent_key
+
+      # This is essentially .map(), but we need to do += for nested containers
+      object.reduce([]) do |result, item|
+        if object.is_a?(Array)
+          # item is already the value
+          k = nil
+          v = item
+        else
+          # item is a key, value pair
+          k, v = item
+          k = escape(k.to_s) if uri_escape
+        end
+
+        processed_key = parent_key ? "#{parent_key}[#{k}]" : k
+
+        case v
+        when Array, Hash, ParamsArray
+          result.concat flatten_params(v, uri_escape, processed_key, depth + 1)
+        else
+          v = escape(v.to_s) if uri_escape && v
+          result << [processed_key, v]
+        end
+      end
+    end
+
+    # Encode string for safe transport by URI or form encoding. This uses a CGI
+    # style escape, which transforms ` ` into `+` and various special
+    # characters into percent encoded forms.
+    #
+    # This calls URI.encode_www_form_component for the implementation. The only
+    # difference between this and CGI.escape is that it does not escape `*`.
+    # http://stackoverflow.com/questions/25085992/
+    #
+    # @see URI.encode_www_form_component
+    #
+    def self.escape(string)
+      URI.encode_www_form_component(string)
+    end
+  end
+end

data/lib/contractful/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Gem version constants for contractful.
+module Contractful
+  VERSION_INFO = [0, 1, 0].freeze
+  VERSION = VERSION_INFO.map(&:to_s).join('.').freeze
+
+  def self.version
+    VERSION
+  end
+end

data/lib/contractful/windows/root_certs.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'ffi'
+
+# Adapted from Puppet, Copyright (c) Puppet Labs Inc,
+# licensed under the Apache License, Version 2.0.
+#
+# https://github.com/puppetlabs/puppet/blob/bbe30e0a/lib/puppet/util/windows/root_certs.rb
+
+# Represents a collection of trusted root certificates.
+#
+# @api public
+class Contractful::Windows::RootCerts
+  include Enumerable
+  extend FFI::Library
+
+  typedef :ulong, :dword
+  typedef :uintptr_t, :handle
+
+  def initialize(roots)
+    @roots = roots
+  end
+
+  # Enumerates each root certificate.
+  # @yieldparam cert [OpenSSL::X509::Certificate] each root certificate
+  # @api public
+  def each(&block)
+    @roots.each(&block)
+  end
+
+  # Returns a new instance.
+  # @return [Contractful::Windows::RootCerts] object constructed from current root certificates
+  def self.instance
+    new(load_certs)
+  end
+
+  # Returns an array of root certificates.
+  #
+  # @return [Array<[OpenSSL::X509::Certificate]>] an array of root certificates
+  # @api private
+  def self.load_certs
+    certs = []
+
+    # This is based on a patch submitted to openssl:
+    # http://www.mail-archive.com/openssl-dev@openssl.org/msg26958.html
+    ptr = FFI::Pointer::NULL
+    store = CertOpenSystemStoreA(nil, 'ROOT')
+    begin
+      while (ptr = CertEnumCertificatesInStore(store, ptr)) and !ptr.null?
+        context = CertContext.new(ptr)
+        cert_buf = context[:pbCertEncoded].read_bytes(context[:cbCertEncoded])
+        begin
+          certs << OpenSSL::X509::Certificate.new(cert_buf)
+        rescue StandardError => e
+          warn("Failed to import root certificate: #{e.inspect}")
+        end
+      end
+    ensure
+      CertCloseStore(store, 0)
+    end
+
+    certs
+  end
+
+  # typedef ULONG_PTR HCRYPTPROV_LEGACY;
+  # typedef void *HCERTSTORE;
+
+  # FFI mapping of the Windows CERT_CONTEXT structure returned by
+  # CertEnumCertificatesInStore.
+  class CertContext < FFI::Struct
+    layout(
+      :dwCertEncodingType, :dword,
+      :pbCertEncoded,      :pointer,
+      :cbCertEncoded,      :dword,
+      :pCertInfo,          :pointer,
+      :hCertStore,         :handle
+    )
+  end
+
+  # HCERTSTORE
+  # WINAPI
+  # CertOpenSystemStoreA(
+  #   __in_opt HCRYPTPROV_LEGACY hProv,
+  #   __in LPCSTR szSubsystemProtocol
+  #   );
+  ffi_lib :crypt32
+  attach_function :CertOpenSystemStoreA, %i[pointer string], :handle
+
+  # PCCERT_CONTEXT
+  # WINAPI
+  # CertEnumCertificatesInStore(
+  #   __in HCERTSTORE hCertStore,
+  #   __in_opt PCCERT_CONTEXT pPrevCertContext
+  #   );
+  ffi_lib :crypt32
+  attach_function :CertEnumCertificatesInStore, %i[handle pointer], :pointer
+
+  # BOOL
+  # WINAPI
+  # CertCloseStore(
+  #   __in_opt HCERTSTORE hCertStore,
+  #   __in DWORD dwFlags
+  #   );
+  ffi_lib :crypt32
+  attach_function :CertCloseStore, %i[handle dword], :bool
+end

data/lib/contractful/windows.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Contractful
+  # Windows-specific support code (root certificate store loading).
+  module Windows
+  end
+end
+
+require_relative 'windows/root_certs' if Contractful::Platform.windows?