jeff 0.6.4 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 237d96394f884df5250ed73a02edd178581025bf
-  data.tar.gz: 6da5c616420819d2fceee08136521521e84395ba
+  metadata.gz: 3f7158c532ec3dae4f1536ea70d1f3db88014dcd
+  data.tar.gz: 9c85321983f671dbde03310f437bb77e65169a99
 SHA512:
-  metadata.gz: ffad5ced35b9a4c30e77497984be97501c167480b9aaae017c5191c44363bfc5b9367bde5df265a21172a6038f9f90a950f118ed32ef893dece199b93e12dd58
-  data.tar.gz: c07df5ac211256101a75524e4324692ff54a389136b2d618822a48dd69835269916ca168efe6827938e1e9551b93cf1b7ddecd52d22b3b68b1479a770911f99d
+  metadata.gz: c25346ce0feb21e3d09e5ec1b155b8a6f3bcb0b3cdb5722d384a0ca1065a670f01d5793676ce674ba18425e63ec51bc87a64c0d46a8536176b0eba8bc044ec27
+  data.tar.gz: 993c1b39c3ce3ffc9b9ef200edb568b8603640d0e68c3d88f0ea63a60cd6033dcec285af8654b2db399a4f910d5e61a639d0880dfd3434e80e851ba8ac341123

data/Gemfile

@@ -1,6 +1,3 @@
 source 'https://rubygems.org'
 gemspec
-
-
-gem 'rake'
-gem 'jruby-openssl', :platform => :jruby
+gem 'jruby-openssl', platform: :jruby

data/README.md

@@ -1,11 +1,29 @@
 # Jeff
 
-[Serially or in parallel, Monsieur Jeff will diligently sign your Amazon Web
-Services requests.][sign]
+Jeff mixes in client behaviour for Amazon Web Services (AWS) which require
+[Signature version 2 authentication][sig].
 
-:heart::heart::heart:
+![jeff][jef]
 
-![jeff][jeff]
+## Usage
 
-[sign]: http://docs.amazonwebservices.com/general/latest/gr/signature-version-2.html
-[jeff]: http://f.cl.ly/items/0i1H1h071z1K0N3V2x06/bezos.png
+A minimal example:
+
+```ruby
+Request = Struct.new(:aws_access_key_id, :aws_secret_access_key) do
+  include Jeff
+
+  def aws_endpoint; 'https://mws.amazonservices.com/Products/2011-10-01'; end
+end
+
+req = Request.new('foo', 'bar')
+res = req.get(query: { 'Action' => 'GetServiceStatus' })
+
+puts res.body.match(/Status>([^<]+)/)[1]
+```
+
+[Vacuum][vac] provides an example implementation.
+
+[sig]: http://docs.amazonwebservices.com/general/latest/gr/signature-version-2.html
+[vac]: https://github.com/hakanensari/vacuum
+[jef]: http://f.cl.ly/items/0a3R3J0k1R2f423k1q2l/jeff.jpg

data/jeff.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |gem|
   gem.authors       = ['Hakan Ensari']
   gem.email         = ['hakan.ensari@papercavalier.com']
   gem.description   = %q{An Amazon Web Services client}
-  gem.summary       = %q{AWS client}
+  gem.summary       = %q{An AWS client}
   gem.homepage      = 'https://github.com/papercavalier/jeff'
 
   gem.files         = `git ls-files`.split($\)
@@ -15,7 +15,9 @@ Gem::Specification.new do |gem|
   gem.require_paths = ['lib']
   gem.version       = Jeff::VERSION
 
-  gem.add_dependency 'excon', '~> 0.23.0'
+  gem.add_dependency 'excon', '~> 0.25.0'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rake'
 
   gem.required_ruby_version = '>= 1.9'
 end

data/lib/jeff.rb

@@ -1,173 +1,152 @@
-require 'base64'
-require 'digest/md5'
+# Our only external dependency. Excon is currently my preferred HTTP client in
+# Ruby.
 require 'excon'
+
+# Standard library dependencies.
+require 'base64'
+require 'openssl'
 require 'time'
 
-require 'jeff/secret'
 require 'jeff/version'
 
-# Mixes in Amazon Web Services (AWS) client behaviour.
+# Jeff mixes in client behaviour for Amazon Web Services (AWS) that require
+# Signature version 2 authentication.
+#
+# It's Jeff, as in Jeff Bezos.
 module Jeff
-  MissingEndpoint = Class.new(ArgumentError)
-  MissingKey      = Class.new(ArgumentError)
-  MissingSecret   = Class.new(ArgumentError)
-
-  UNRESERVED = /([^\w.~-]+)/
-
-  # A User-Agent header that identifies the application, its version number,
-  # and programming language.
-  #
-  # Amazon recommends to include one in requests to AWS endpoints.
-  USER_AGENT = "Jeff/#{VERSION} (Language=Ruby; #{`hostname`.chomp})"
-
-  def self.included(base)
-    base.extend ClassMethods
-
-    base.headers 'User-Agent'       => USER_AGENT
-
-    base.params  'AWSAccessKeyId'   => -> { key },
-                 'SignatureVersion' => '2',
-                 'SignatureMethod'  => 'HmacSHA256',
-                 'Timestamp'        => -> { Time.now.utc.iso8601 }
+  # Converts a query value to a sorted query string.
+  Query = Struct.new(:values) do
+    def to_s
+      values.sort.map { |k, v| "#{k}=#{ Utils.escape(v) }" }.join('&')
+    end
   end
 
-  # Internal: Build a sorted query.
-  #
-  # hsh - A hash of query parameters specific to the request.
-  #
-  # Returns a query String.
-  def build_query(hsh)
-    params
-      .merge(hsh)
-      .sort
-      .map { |k, v| "#{k}=#{ escape(v) }" }
-      .join('&')
+  # Calculates an MD5sum for file being uploaded.
+  Content = Struct.new(:body) do
+    def md5
+      Base64.encode64(OpenSSL::Digest::MD5.digest(body)).strip
+    end
   end
 
-  # Internal: Returns an Excon::Connection.
-  def connection
-    @connection ||= Excon.new(endpoint, headers: headers, expects: 200)
-  end
+  # Signs an AWS request.
+  Request = Struct.new(:method, :host, :path, :query_string) do
+    def sign(aws_secret_access_key)
+      Signature.new(aws_secret_access_key).sign(string_to_sign)
+    end
 
-  # Internal: Gets the String AWS endpoint.
-  #
-  # Raises a MissingEndpoint error if endpoint is missing.
-  def endpoint
-    @endpoint or raise MissingEndpoint
+    def string_to_sign
+      [method, host, path, query_string].join("\n")
+    end
   end
 
-  # Sets the String AWS endpoint.
-  attr_writer :endpoint
-
-  # Internal: Returns the Hash default headers.
-  def headers
-    self.class.headers
-  end
+  # Calculates an RFC 2104-compliant HMAC signature.
+  Signature = Struct.new(:secret) do
+    SHA256 = OpenSSL::Digest::SHA256.new
 
-  # Internal: Gets the String AWS access key id.
-  #
-  # Raises a MissingKey error if key is missing.
-  def key
-    @key or raise MissingKey
+    def sign(message)
+      Base64.encode64(OpenSSL::HMAC.digest(SHA256, secret, message)).strip
+    end
   end
 
-  # Sets the String AWS access key id.
-  attr_writer :key
+  # Because Ruby's CGI escapes ~, we have to resort to writing our own escape.
+  module Utils
+    UNRESERVED = /([^\w.~-]+)/
 
-  # Internal: Returns the Hash default request parameters.
-  def params
-    self.class.params.reduce({}) do |a, (k, v)|
-      a.update k => (v.respond_to?(:call) ? instance_exec(&v) : v)
+    def self.escape(val)
+      val.to_s.gsub(UNRESERVED) do
+        '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
+      end
     end
   end
 
-  # Internal: Gets the Jeff::Secret.
+  # Amazon recommends to include a User-Agent header with every request to 
+  # identify the application, its version number, programming language, and
+  # host.
   #
-  # Raises a MissingSecret error if secret is missing.
-  def secret
-    @secret or raise MissingSecret
+  # If not happy, override.
+  USER_AGENT = "Jeff/#{VERSION} (Language=Ruby; #{`hostname`.chomp})"
+
+  def self.included(base)
+    base.extend(ClassMethods)
+
+    # Common parameters required by all AWS requests.
+    #
+    # Add other common parameters using `Jeff.params` if required in your
+    # implementation.
+    base.params(
+      'AWSAccessKeyId'   => -> { aws_access_key_id },
+      'SignatureVersion' => '2',
+      'SignatureMethod'  => 'HmacSHA256',
+      'Timestamp'        => -> { Time.now.utc.iso8601 }
+    )
   end
 
-  # Sets the AWS secret key.
-  #
-  # key - A String secret.
-  #
-  # Returns a Jeff::Secret.
-  def secret=(key)
-    @secret = Secret.new(key)
+  # An HTTP connection. It's reusable, which, as the author of Excon puts it,
+  # is more performant!
+  def connection
+    @connection ||= Excon.new(endpoint,
+      headers: { 'User-Agent' => USER_AGENT },
+      expects: 200,
+      omit_default_port: true
+    )
   end
 
+  # Accessors for required AWS attributes.
+  attr_accessor :aws_endpoint, :aws_access_key_id, :aws_secret_access_key
+
+  # We'll keep these around so we don't break dependent libraries.
+  alias endpoint aws_endpoint
+  alias endpoint= aws_endpoint=
+  alias key aws_access_key_id
+  alias key= aws_access_key_id=
+  alias secret aws_secret_access_key
+  alias secret= aws_secret_access_key=
+
   # Generate HTTP request verb methods.
   Excon::HTTP_VERBS.each do |method|
     eval <<-DEF
-      def #{method}(opts = {})
-        opts.update(:method => :#{method}, :omit_default_port => true)
-        connection.request(build_options(opts))
+      def #{method}(options = {})
+        options.store(:method, :#{method})
+        connection.request(build_options(options))
       end
     DEF
   end
 
   private
 
-  def build_options(opts)
-    if opts[:body]
-      opts[:headers] ||= {}
-      opts[:headers].update('Content-MD5' => calculate_md5(opts[:body]))
+  def build_options(options)
+    # Add a Content-MD5 header if we're uploading a file.
+    if options.has_key?(:body)
+      md5 = Content.new(options[:body]).md5
+      (options[:headers] ||= {}).store('Content-MD5', md5)
     end
 
-    sign(opts)
-  end
-
-  def calculate_md5(body)
-    Base64.encode64(Digest::MD5.digest(body)).strip
-  end
-
-  def escape(val)
-    val.to_s.gsub(UNRESERVED) do
-      '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
-    end
-  end
-
-  def sign(opts)
-    query = build_query(opts[:query] || {})
-
-    string_to_sign = [
-      opts[:method].upcase,
-      connection.data[:host],
-      opts[:path] || connection.data[:path],
-      query
-    ].join("\n")
-    signature = secret.sign(string_to_sign)
-
-    opts.update(query: [
-       query,
-       "Signature=#{escape(signature)}"
-    ].join('&'))
+    # Build the query string.
+    values = self.class.params
+      .reduce({}) { |a, (k, v)|
+        a.update(k => (v.respond_to?(:call) ? instance_exec(&v) : v))
+      }
+      .merge(options.fetch(:query, {}))
+    query_string = Query.new(values).to_s
+
+    # Generate a signature.
+    signature = Request
+      .new(
+        options[:method].upcase,
+        connection.data[:host],
+        options[:path] || connection.data[:path],
+        query_string
+      )
+      .sign(aws_secret_access_key)
+
+    # Return options after appending an escaped signature to query.
+    options.update(query: "#{query_string}&Signature=#{Utils.escape(signature)}")
   end
 
   module ClassMethods
-    # Gets/Updates the default headers.
-    #
-    # hsh - A Hash of headers.
-    #
-    # Returns the Hash headers.
-    def headers(hsh = nil)
-      @headers ||= {}
-      @headers.update(hsh) if hsh
-
-      @headers
-    end
-
-    # Gets/Updates the default request parameters.
-    #
-    # hsh - A Hash of parameters (default: nil).
-    #
-    # Returns the Hash parameters.
-    def params(hsh = nil)
-      @params ||= {}
-      @params.update(hsh) if hsh
-
-      @params
+    # Gets and optionally updates the default request parameters.
+    def params(hsh = {})
+      (@params ||= {}).update(hsh)
     end
   end
 end

data/lib/jeff/version.rb

@@ -1,3 +1,3 @@
 module Jeff
-  VERSION = '0.6.4'
+  VERSION = '0.7.0'
 end

data/spec/jeff_spec.rb

@@ -11,18 +11,6 @@ describe Jeff do
     end
   end
 
-  it 'has a User-Agent request header' do
-    assert @klass.headers.has_key?('User-Agent')
-  end
-
-  it 'configures request headers' do
-    @klass.instance_eval do
-      headers 'Foo' => 'bar'
-    end
-
-    assert @klass.headers.has_key?('Foo')
-  end
-
   it 'has the required request query parameters' do
     %w(AWSAccessKeyId SignatureMethod SignatureVersion Timestamp)
       .each { |key| assert @klass.params.has_key?(key) }
@@ -32,48 +20,28 @@ describe Jeff do
     @klass.instance_eval do
       params 'Foo' => 'bar'
     end
-
     assert @klass.params.has_key?('Foo')
   end
 
-  it 'requires an endpoint' do
-    proc { @klass.new.endpoint }.must_raise Jeff::MissingEndpoint
-  end
-
-  it 'requires a key' do
-    proc { @klass.new.key }.must_raise Jeff::MissingKey
-  end
-
-  it 'requires a secret' do
-    proc { @klass.new.secret }.must_raise Jeff::MissingSecret
-  end
-
   it 'sorts the request query parameters of the client lexicographically' do
-    client = @klass.new
-    client.key = 'foo'
-    query = client.build_query 'A10' => 1, 'A1' => 1
-
-    query.must_match(/^A1=1&A10=.*Timestamp/)
+    query = Jeff::Query.new('A10' => 1, 'A1' => 1)
+    query.to_s.must_equal('A1=1&A10=1')
   end
 
-  it 'sets the request headers of the client connection' do
+  it 'sets a User-Agent header for the client connection' do
     client = @klass.new
     client.endpoint = 'http://example.com/'
-
-    client.connection.data[:headers].must_equal @klass.headers
+    client.connection.data[:headers]['User-Agent'].wont_be_nil
   end
 
   Excon::HTTP_VERBS.each do |method|
     it "makes a #{method.upcase} request" do
       Excon.stub({ }, { status: 200 })
-
       client = @klass.new
       client.endpoint = 'http://example.com/'
       client.key = 'foo'
       client.secret = 'bar'
-
       client.send(method).status.must_equal 200
-
       Excon.stubs.clear
     end
   end
@@ -82,14 +50,11 @@ describe Jeff do
     Excon.stub({ }) do |params|
       { body: params[:headers]['Content-MD5'] }
     end
-
     client = @klass.new
     client.endpoint = 'http://example.com/'
     client.key = 'foo'
     client.secret = 'bar'
-
     client.post(body: 'foo').body.wont_be_empty
-
     Excon.stubs.clear
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jeff
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.7.0
 platform: ruby
 authors:
 - Hakan Ensari
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-11 00:00:00.000000000 Z
+date: 2013-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -16,14 +16,42 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.23.0
+        version: 0.25.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.23.0
+        version: 0.25.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: An Amazon Web Services client
 email:
 - hakan.ensari@papercavalier.com
@@ -39,7 +67,6 @@ files:
 - Rakefile
 - jeff.gemspec
 - lib/jeff.rb
-- lib/jeff/secret.rb
 - lib/jeff/version.rb
 - spec/jeff_spec.rb
 homepage: https://github.com/papercavalier/jeff
@@ -61,9 +88,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.2
+rubygems_version: 2.0.5
 signing_key: 
 specification_version: 4
-summary: AWS client
+summary: An AWS client
 test_files:
 - spec/jeff_spec.rb

data/lib/jeff/secret.rb

@@ -1,17 +0,0 @@
-require 'base64'
-require 'openssl'
-
-module Jeff
-  class Secret
-    SHA256 = OpenSSL::Digest::SHA256.new
-
-    def initialize(key)
-      @key = key
-    end
-
-    def sign(message)
-      digest = OpenSSL::HMAC.digest(SHA256, @key, message)
-      Base64.encode64(digest).chomp
-    end
-  end
-end