Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation started...

  • Loading branch information...
commit 9f480819861a59eeb8b523c16b728512f8f4dda8 1 parent 9b6a73e
@mboeh authored
Showing with 81 additions and 14 deletions.
  1. +5 −0 Rakefile
  2. +16 −1 lib/naws/authentication.rb
  3. +60 −13 lib/naws/context.rb
View
5 Rakefile
@@ -1,2 +1,7 @@
require 'bundler'
+require 'rake/rdoctask'
+
Bundler::GemHelper.install_tasks
+Rake::RDocTask.new do |rd|
+ rd.rdoc_files.include("lib/**/*.rb")
+end
View
17 lib/naws/authentication.rb
@@ -1,6 +1,16 @@
require 'naws'
require 'openssl'
+# Contains the necessary information to authenticate an AWS request.
+#
+# The signature generated by this class is generally included in an HTTP
+# header or as a query string parameter.
+#
+# Left as an exercise for the reader: implement a subclass of this class which
+# calls out to an external process to perform signing, thus eliminating
+# the need to include the authentication data in the app.
+#
+# This class generates a SHA1 HMAC. If you need SHA256, consider subclassing.
class Naws::Authentication
attr_reader :access_key_id
@@ -10,10 +20,15 @@ def initialize(aws_id, aws_key)
@secret_access_key = aws_key
end
- def algorithm
+ def algorithm # :nodoc:
"SHA1"
end
+ # Signs the provided +string+ with the secret access key. Details on what
+ # this does and what +string+ should be are here:
+ #
+ # http://docs.amazonwebservices.com/Route53/latest/DeveloperGuide/index.html?RESTAuthentication.html
+ #
def aws_signature(string)
hash = OpenSSL::Digest::Digest.new('sha1')
[OpenSSL::HMAC.digest(hash, secret_access_key, string)].pack("m").chomp
View
73 lib/naws/context.rb
@@ -1,7 +1,24 @@
require 'uri'
+# A NAWS Context collects together the general information necessary to use
+# an AWS service. It keeps a Naws::Authentication object for requests to use,
+# it controls access to the Naws::Transport, and it keeps the XML namespace
+# and base URI used for requests.
+#
+# Libraries for each AWS service should inherit from this class.
class Naws::Context
+ # Creates a new context. All attributes can be set here or after the context
+ # is created.
+ #
+ # Naws::Context.new(
+ # :authentication => Naws::Authentication.new("KEY_ID", "KEY"),
+ # :uri => "http://example.com/apibase",
+ # :xmlns => "http://example.com/ns/api-1.0",
+ # :transport => :net_http
+ # )
+ #
+ # Refer to #authentication=, #uri=, #xmlns=, #transport= for values.
def initialize(options = {})
if options[:access_key_id].kind_of?(String) and options[:secret_access_key].kind_of?(String)
self.authentication = Naws::Authentication.new(options[:access_key_id], options[:secret_access_key])
@@ -10,22 +27,34 @@ def initialize(options = {})
end
self.uri = options[:uri] if options[:uri]
self.xmlns = options[:xmlns] if options[:xmlns]
- self.transport = resolve_transport(options[:transport]) if options[:transport]
+ self.transport = options[:transport] if options[:transport]
end
+ # The main XML namespace which should be used for XML requests generated
+ # by this context. This is primarily here to permit simple switching between
+ # API versions.
attr_accessor :xmlns
+ # Returns the Naws::Transport this context is currently configured to use.
attr_reader :transport
+
+ # Configures this context to use a new Naws::Transport. If +value+ is a
+ # Symbol, it is resolved into a class.
+ #
+ # Example:
+ #
+ # context.transport = :net_http
+ # context.transport.class.name # => "Naws::NetHttpTransport"
def transport=(value)
- if transport.kind_of?(Symbol)
- raise
- self.transport = resolve_transport_class.new
- else
- @transport = value
- end
+ self.transport = resolve_transport(value)
end
-
+
+ # The base URI used for requests generated by this API. The value returned
+ # is an instance of the +URI+ class.
attr_reader :uri
+
+ # Sets the base URI used for requests generated by this API. If a string is
+ # passed, it is parsed with +URI.parse+.
def uri=(value)
if value.kind_of?(URI)
@uri = value
@@ -34,7 +63,10 @@ def uri=(value)
end
end
+ # Returns the authentication object this context is currently configured to use.
attr_reader :authentication
+
+ # Configures this context to use a new authentication object.
def authentication=(value)
if value.nil? or value.respond_to?(:aws_signature)
@authentication = value
@@ -43,19 +75,34 @@ def authentication=(value)
end
end
+ # Looks up a request class for this context and instantiates it with the given
+ # +params+ and +options+. +name+ should be a Symbol and is translated thus:
+ #
+ # context.class.name # => Naws::Baz::Context
+ # context.request(:foo_bar).class.name # => "Naws::Baz::FooBarRequest"
def request(name, params = {}, options = {})
resolve_request_class("#{name}_request").new(self, params, options)
end
- def execute(name, params = {}, options = {}, &blk)
- execute_request(request(name, params, options), &blk)
+ # Looks up and creates a request for this context (with #request) and
+ # immediately executes it (with #execute_request).
+ def execute(name, params = {}, options = {}, &callback)
+ execute_request(request(name, params, options), &callback)
end
- def execute_request(request, &blk)
- transport.execute(request, request.response_class, &blk)
+ # Executes the given request across this context's transport. If a +callback+
+ # is provided, the request will be executed asynchronously (if possible) and
+ # the callback called when the request completes (see
+ # Naws::Transport#execute).
+ def execute_request(request, &callback)
+ transport.execute(request, request.response_class, &callback)
end
- # TODO: it should be possible to calibrate this to the published AWS time
+ # Returns the time which should be used for AWS request timestamps. This time
+ # is used to prevent duplicate requests and for generating authentication
+ # signatures.
+ #
+ # TODO: it should be possible to calibrate this to the published AWS time.
def aws_time
Time.now
end
Please sign in to comment.
Something went wrong with that request. Please try again.