fog 0.0.58 → 0.0.59

data/README.rdoc

@@ -1,64 +1,44 @@
 = fog
 
-fog helps you interact with cloud services. fog is a work in progress.
+fog helps you interact with cloud services.
 
-== Install
+The quick and dirty, top to bottom:
+* Models provide a simplified interface, making clouds easier to work with and switch between.
+* Requests allow power users to get the most out of the features of each individual cloud.
+* Mocks make testing and integrating a breeze.
 
-  sudo gem install fog
+Put them together and you get a great cloud computing experience, but we are getting ahead of ourselves...
 
 == Getting Started
 
-You can start stumbling around as soon as you install with the fog command line tool.
-After installing, just type 'fog' to get started.
-If you don't have credentials setup it will let you know what to do.
-
-Then just start playing around, fog should let you know if you are forget things.
-
-For example if you try to create a server but leave out stuff:
-
-  server = AWS.servers.create
+  sudo gem install fog
 
-You'll get reminded that things are missing.
+Now just type 'fog' to trying stuff out, confident that fog should let you know what you need to do. Here is an example of wading through server creation for Amazon Elastic Compute Cloud:
 
+  >> server = AWS.servers.create
   ArgumentError: image_id is required for this operation
+  >> server = AWS.servers.create(:image_id => 'ami-5ee70037')
+  <Fog::AWS::EC2::Server [...]>
+  >> server.destroy # cleanup after yourself or regret it, trust me
+  true
 
-So just add the missing stuff and you are off to the races:
-
-  server = AWS.servers.create(:image_id => 'ami-5ee70037')
-
-But don't forget to cleanup or you'll regret it when you get the bill:
+== Collections
 
-  server.destroy
+Nouns like Images and Servers are collections, which form the interface to the cloud.
+Collections provide all, create, get and new methods.
+* all fetches every object of that type from the cloud.
+* create initializes a new record locally and then persists it to the cloud.
+* get fetches a single object by its identity.
+* new initializes a new record locally.
 
-Rinse, repeat, enjoy!
+Common compute nouns are flavors, images and servers.
 
-== Working with Servers
+Common storage nouns are directory and file.
 
-Lets boot up a server on EC2
+As an example, we'll try initializing and persisting a rackspace server:
 
   require 'fog'
 
-  # initialize a connection to Amazon Elastic Compute Cloud
-  connection = Fog::AWS::EC2.new(
-    :aws_access_key_id => id,
-    :aws_secret_access_key => key
-  )
-
-  # boot a gentoo server
-  server = connection.servers.new(:image_id => 'ami-5ee70037')
-  # you might also want to add the server to security groups, which goes like this:
-  # AWS.servers.create(:image_id => 'ami-5ee70037', :groups => ['web', 'db'])
-
-  # wait for it to be ready to do stuff
-  server.wait_for { ready? }
-
-  # DO STUFF
-
-  # shutdown the server
-  server.destroy
-
-Now we will try again, but with Rackspace
-
   # initialize a connection to Rackspace Servers
   connection = Fog::Rackspace::Servers.new(
     :rackspace_api_key => key,
@@ -76,53 +56,57 @@ Now we will try again, but with Rackspace
   # shutdown the server
   server.destroy
 
-== Working with Directories and Files
+== Models
 
-  require 'fog'
+Many of the collection methods return individual objects, which provide destroy, save and wait_for methods.
+* destroy will destroy the persisted object from the cloud
+* save will persist the object to the cloud
+* wait_for takes a block and waits for either the block to return true for the object or for a timeout (defaults to 10 minutes)
 
-  # initialize a connection to Amazon Simple Storage Solution
-  connection = Fog::AWS::S3.new(
-    :aws_access_key_id => id,
-    :aws_secret_access_key => key
-  )
+== Mocks
+
+Mocking provides an in memory representation of clouds as you make different requests.
+This representation allows subsequent calls to mimic the behavior of the cloud while eliminating the cost and time needed to actually run tests against various providers.
+Mocking is easy to use, just write any functions as you normally would and then in your tests ensure you call:
+
+  Fog.mock!
+
+Make sure you call it first (before you initialize any connections) and all your calls should now run in mock mode.
+If you run into the edges of mock implementation it should let you know that they haven't been implemented yet.
 
-  # create a directory
-  directory = connection.directory.create(:name => 'directoryname')
+== Requests
 
-  # create a new file in your directory
-  directory.files.create(:key => 'filename', :body => 'filebody')
+Requests allow you to dive deeper when the models just can't cut it.
+For instance, ec2 provides methods related to reserved instances that don't have any models (yet anyway).
+You can get a description of your reserved instances like this:
 
-  # connect to your directory
-  directory = connection.directories.get('directoryname')
+  $ fog
+  >> AWS[:ec2].describe_reserved_instances
+  #<Excon::Response [...]>
 
-  # get your file
-  file = directory.files.get('filename')
+It will return an excon response, which has headers and body methods. Both give nice ruby hash representations of the result.
 
-  # delete the file
-  file.destroy
+== Go forth and conquer
 
-  # delete the directory
-  directory.destroy
+That should give you some stuff to try and places to look.
 
-== More info
+You should try out the (varying) support fog has for:
+* AWS [EC2, S3, SimpleDB]
+* Rackspace [Files, Servers]
+* Slicehost
+* Terremark vCloud Express
+
+Enjoy, and let me know what I can do to continue improving fog!
 
 * Follow {@geemus}[http://twitter.com/geemus] on Twitter.
 * See upcoming work in the {tracker}[http://www.pivotaltracker.com/projects/54635].
 * Report bugs in {issues}[http://github.com/geemus/fog/issues].
 
-== Supports
-
-* AWS EC2
-* AWS S3
-* AWS SimpleDB (no models yet)
-* Rackspace Files (no models yet, just getting started on requests)
-* Rackspace Servers (some requests, server model, just getting started)
-
 == Copyright
 
 (The MIT License)
 
-Copyright (c) 2009 {geemus (Wesley Beary)}[http://github.com/geemus]
+Copyright (c) 2010 {geemus (Wesley Beary)}[http://github.com/geemus]
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/VERSION.yml

@@ -1,5 +1,5 @@
 --- 
 :major: 0
 :minor: 0
-:patch: 58
+:patch: 59
 :build: 

data/fog.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{fog}
-  s.version = "0.0.58"
+  s.version = "0.0.59"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["geemus (Wesley Beary)"]
-  s.date = %q{2010-03-17}
+  s.date = %q{2010-03-26}
   s.default_executable = %q{fog}
   s.description = %q{brings clouds to you}
   s.email = %q{geemus@gmail.com}

data/lib/fog.rb

@@ -17,36 +17,25 @@ $LOAD_PATH.unshift __DIR__ unless
   $LOAD_PATH.include?(__DIR__) ||
   $LOAD_PATH.include?(File.expand_path(__DIR__))
 
+require 'fog/collection'
+require 'fog/connection'
+require 'fog/model'
+require 'fog/parser'
+require 'fog/aws'
+require 'fog/rackspace'
+require 'fog/slicehost'
+require 'fog/terremark'
+
 module Fog
 
   class MockNotImplemented < StandardError; end
 
   def self.mock!
     @mocking = true
-    self.reload
   end
 
   def self.mocking?
     !!@mocking
   end
 
-  def self.dependencies
-    [
-      'fog/collection.rb',
-      'fog/connection.rb',
-      'fog/model.rb',
-      'fog/parser.rb',
-      'fog/aws.rb',
-      'fog/rackspace.rb',
-      'fog/slicehost.rb',
-      'fog/terremark.rb'
-      ]
-  end
-
-  def self.reload
-    self.dependencies.each {|dependency| load(dependency)}
-  end
-
 end
-
-Fog.dependencies.each {|dependency| require(dependency)}

data/lib/fog/aws.rb

@@ -1,19 +1,10 @@
+require 'fog/aws/ec2.rb'
 require 'fog/aws/s3'
 require 'fog/aws/simpledb'
 
 module Fog
   module AWS
 
-    def self.dependencies
-      [
-        'fog/aws/ec2.rb'
-      ]
-    end
-
-    def self.reload
-      self.dependencies.each {|dependency| load(dependency)}
-    end
-
     def self.indexed_param(key, values)
       params = {}
       [*values].each_with_index do |value, index|
@@ -22,161 +13,154 @@ module Fog
       params
     end
 
-    if Fog.mocking?
-      srand(Time.now.to_i)
-
-      class Mock
-
-        def self.availability_zone
-          "us-east-1" << random_selection('abcd', 1)
-        end
+    class Mock
 
-        def self.box_usage
-          sprintf("%0.10f", rand / 100).to_f
-        end
+      def self.availability_zone
+        "us-east-1" << random_selection('abcd', 1)
+      end
 
-        def self.console_output
-          'This is my console. There are many like it, but this one is mine. My console is my best friend. It is my life. I must master it as I master my life. My console, without me, is useless. Without my console, I am useless.'
-        end
+      def self.box_usage
+        sprintf("%0.10f", rand / 100).to_f
+      end
 
-        def self.etag
-          hex(32)
-        end
+      def self.console_output
+        'This is my console. There are many like it, but this one is mine. My console is my best friend. It is my life. I must master it as I master my life. My console, without me, is useless. Without my console, I am useless.'
+      end
 
-        def self.image
-          path = []
-          (rand(3) + 2).times do
-            path << letters(rand(9) + 8)
-          end
-          {
-            "imageOwnerId"  => letters(rand(5) + 4),
-            "productCodes"  => [],
-            "kernelId"      => kernel_id,
-            "ramdiskId"     => ramdisk_id,
-            "imageState"    => "available",
-            "imageId"       => image_id,
-            "architecture"  => "i386",
-            "isPublic"      => true,
-            "imageLocation" => path.join('/'),
-            "imageType"     => "machine"
-          }
-        end
+      def self.etag
+        hex(32)
+      end
 
-        def self.image_id
-          "ami-#{hex(8)}"
-        end
+      def self.image
+        path = []
+        (rand(3) + 2).times do
+          path << letters(rand(9) + 8)
+        end
+        {
+          "imageOwnerId"  => letters(rand(5) + 4),
+          "productCodes"  => [],
+          "kernelId"      => kernel_id,
+          "ramdiskId"     => ramdisk_id,
+          "imageState"    => "available",
+          "imageId"       => image_id,
+          "architecture"  => "i386",
+          "isPublic"      => true,
+          "imageLocation" => path.join('/'),
+          "imageType"     => "machine"
+        }
+      end
 
-        def self.key_fingerprint
-          fingerprint = []
-          20.times do
-            fingerprint << hex(2)
-          end
-          fingerprint.join(':')
-        end
+      def self.image_id
+        "ami-#{hex(8)}"
+      end
 
-        def self.image_id
-          "ami-#{hex(8)}"
+      def self.key_fingerprint
+        fingerprint = []
+        20.times do
+          fingerprint << hex(2)
         end
+        fingerprint.join(':')
+      end
 
-        def self.instance_id
-          "i-#{hex(8)}"
-        end
+      def self.image_id
+        "ami-#{hex(8)}"
+      end
 
-        def self.ip_address
-          ip = []
-          4.times do
-            ip << numbers(rand(3) + 1).to_i.to_s # remove leading 0
-          end
-          ip.join('.')
-        end
+      def self.instance_id
+        "i-#{hex(8)}"
+      end
 
-        def self.kernel_id
-          "aki-#{hex(8)}"
+      def self.ip_address
+        ip = []
+        4.times do
+          ip << numbers(rand(3) + 1).to_i.to_s # remove leading 0
         end
+        ip.join('.')
+      end
 
-        def self.key_material
-          key_material = ['-----BEGIN RSA PRIVATE KEY-----']
-          20.times do
-            key_material << base64(76)
-          end
-          key_material << base64(67) + '='
-          key_material << '-----END RSA PRIVATE KEY-----'
-          key_material.join("\n")
-        end
+      def self.kernel_id
+        "aki-#{hex(8)}"
+      end
 
-        def self.owner_id
-          numbers(12)
+      def self.key_material
+        key_material = ['-----BEGIN RSA PRIVATE KEY-----']
+        20.times do
+          key_material << base64(76)
         end
+        key_material << base64(67) + '='
+        key_material << '-----END RSA PRIVATE KEY-----'
+        key_material.join("\n")
+      end
 
-        def self.ramdisk_id
-          "ari-#{hex(8)}"
-        end
+      def self.owner_id
+        numbers(12)
+      end
 
-        def self.request_id
-          request_id = []
-          request_id << hex(8)
-          3.times do
-            request_id << hex(4)
-          end
-          request_id << hex(12)
-          request_id.join('-')
-        end
+      def self.ramdisk_id
+        "ari-#{hex(8)}"
+      end
 
-        def self.reservation_id
-          "r-#{hex(8)}"
+      def self.request_id
+        request_id = []
+        request_id << hex(8)
+        3.times do
+          request_id << hex(4)
         end
+        request_id << hex(12)
+        request_id.join('-')
+      end
 
-        def self.snapshot_id
-          "snap-#{hex(8)}"
-        end
+      def self.reservation_id
+        "r-#{hex(8)}"
+      end
 
-        def self.volume_id
-          "vol-#{hex(8)}"
-        end
+      def self.snapshot_id
+        "snap-#{hex(8)}"
+      end
 
-        private
+      def self.volume_id
+        "vol-#{hex(8)}"
+      end
 
-        def self.random_selection(characters, length)
-          selection = ''
-          length.times do
-            position = rand(characters.length)
-            selection << characters[position..position]
-          end
-          selection
-        end
+      private
 
-        def self.letters(length)
-          random_selection(
-            'abcdefghijklmnopqrstuvwxyz',
-            length
-          )
+      def self.random_selection(characters, length)
+        selection = ''
+        length.times do
+          position = rand(characters.length)
+          selection << characters[position..position]
         end
+        selection
+      end
 
-        def self.numbers(length)
-          random_selection(
-            '0123456789',
-            length
-          )
-        end
+      def self.letters(length)
+        random_selection(
+          'abcdefghijklmnopqrstuvwxyz',
+          length
+        )
+      end
 
-        def self.hex(length)
-          random_selection(
-            '0123456789abcdef',
-            length
-          )
-        end
+      def self.numbers(length)
+        random_selection(
+          '0123456789',
+          length
+        )
+      end
 
-        def self.base64(length)
-          random_selection(
-            "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
-            length
-          )
-        end
+      def self.hex(length)
+        random_selection(
+          '0123456789abcdef',
+          length
+        )
+      end
 
+      def self.base64(length)
+        random_selection(
+          "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+          length
+        )
       end
-    end
 
+    end
   end
 end
-
-Fog::AWS.reload