google_storage 0.0.3 → 0.1.1

data/lib/google_storage/bucket.rb

@@ -2,7 +2,16 @@
 module GoogleStorage
   class Client
 
-    def list_buckets(options={})
+    ###
+    #
+    # <b>Lists all buckets available within your project</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#getservice
+    #
+    ###
+
+    def list_buckets
+      options = {}
       options[:send_goog_project_id] = true
       resp = get(nil, '/', options)
       resp_obj = Crack::XML.parse(resp.body)
@@ -15,12 +24,24 @@ module GoogleStorage
       return resp_obj
     end
 
-    def list_acls_for_bucket(bucket, options={})
-      resp = get(bucket, '/?acl', options)
+    ###
+    #
+    # <b>Lists the ACL that has been applied to a bucket</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#getbucket
+    #
+    # Example:
+    #
+    #   client.bucket_acls('bucket_name')
+    #
+    ###
+
+    def bucket_acls(bucket_name, options={})
+      resp = get(bucket_name, '/?acl', options)
       resp_obj = Crack::XML.parse(resp.body)
       if resp_obj["AccessControlList"]
         resp_obj[:success] = true
-        resp_obj[:bucket_name] = bucket
+        resp_obj[:bucket_name] = bucket_name
         resp_obj[:acl] = resp_obj["AccessControlList"]
         resp_obj[:raw] = Crack::XML.parse(resp.body)
         resp_obj.each_key {|key| resp_obj.delete(key) unless key == :success || key == :bucket_name || key == :acl || key == :raw }
@@ -28,27 +49,56 @@ module GoogleStorage
       return resp_obj
     end
 
-    alias :bucket_acls :list_acls_for_bucket
+    ###
+    #
+    # <b>Creates a new bucket for your project and applies the 'project-private' ACL by default</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#putbucket
+    #
+    # You can apply a different ACL to a bucket by passing in an :x_goog_acl option and applying one of the predefined ACL's
+    #
+    # Example:
+    #
+    #     client.create_bucket('bucket_name')                                <-- private bucket
+    #     client.create_bucket('bucket_name', :x_goog_acl => 'public-read')  <-- public readable bucket
+    #
+    # Available Options:
+    #
+    #   :x_goog_acl => 'public-read'
+    #
+    ###
 
-    def create_bucket(bucket, options={})
+    def create_bucket(bucket_name, options={})
       options[:send_goog_project_id] = true
-      resp = put(bucket, '/', options)
+      resp = put(bucket_name, '/', options)
       resp_obj = Crack::XML.parse(resp.body)
       if resp.code == "200"
         resp_obj.clear
         resp_obj[:success] = true
-        resp_obj[:bucket_name] = bucket
+        resp_obj[:bucket_name] = bucket_name
         resp_obj[:message] = "Bucket created"
       end
       return resp_obj
     end
 
-    def get_bucket(bucket, options={})
-      resp = get(bucket, '/', options)
+    ###
+    #
+    # <b>Returns a list of all Objects within a specified bucket</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#getbucket
+    #
+    # Example:
+    #
+    #     client.get_bucket('bucket_name')
+    #
+    ###
+
+    def get_bucket(bucket_name, options={})
+      resp = get(bucket_name, '/', options)
       resp_obj = Crack::XML.parse(resp.body)
       if resp.code == "200"
         resp_obj[:success] = true
-        resp_obj[:bucket_name] = bucket
+        resp_obj[:bucket_name] = bucket_name
         contents = resp_obj["ListBucketResult"]["Contents"] ? Array.new : nil
         resp_obj["ListBucketResult"]["Contents"].is_a?(Array) ? \
           (contents = resp_obj["ListBucketResult"]["Contents"]) : \
@@ -60,14 +110,26 @@ module GoogleStorage
       return resp_obj
     end
 
-    alias :bucket_contents :get_bucket
+    ###
+    #
+    # <b>Deletes a specified bucket from your project</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#deletebucket
+    #
+    # *Note:* You can only delete an empty bucket
+    #
+    # Example:
+    #
+    #     client.delete_bucket('bucket_name')
+    #
+    ###
 
-    def delete_bucket(bucket, options={})
-      resp = delete(bucket, '/', options)
+    def delete_bucket(bucket_name, options={})
+      resp = delete(bucket_name, '/', options)
       return Crack::XML.parse(resp.body) unless resp.code == "204"
       resp_obj = {}
       resp_obj[:success] = true
-      resp_obj[:bucket_name] = bucket
+      resp_obj[:bucket_name] = bucket_name
       resp_obj[:message] = "Bucket deleted"
       return resp_obj
     end

data/lib/google_storage/client.rb

@@ -5,8 +5,60 @@ require 'google_storage/object'
 require 'yaml'
 
 module GoogleStorage
+
+  ###
+  #
+  # ==Buckets & Objects
+  #
+  # Buckets are the basic containers that hold all of your data. There is only one Google namespace so every bucket across the
+  # entire namespace has to be uniquely named so you may find that some bucket names have already been taken.
+  #
+  # You can have multiple folders and files within a bucket but you can't nest buckets inside of each other.
+  #
+  # Objects are basically just another name for Files, stored within Google Storage. Google Storage stores Objects in 2 parts,
+  # holding both the object data and the object metadata. The metadata just holds key value data that describes the objects
+  # properties.
+  #
+  # ==Predefined ACL's (Access Control Lists)
+  #
+  # ACL's allow you to control permission settings on Objects and Buckets
+  #
+  # Google Storage uses access control lists (ACLs) to manage object and bucket access.
+  # ACLs are the mechanism you use to share objects with other users and allow other users to access your buckets and objects.
+  #
+  # At the moment, this google_storage gem only supports the following pre-defined ACL's. I'll add support for custom ACL's soon.
+  #
+  # project-private ::        Gives permission to the project team based on their roles. Anyone who is part of the team has READ permission and project owners and project editors have FULL_CONTROL permission. This is the default ACL that's applied when you create a bucket.
+  # private ::                Gives the requester FULL_CONTROL permission for a bucket or object. This is the default ACL that's applied when you upload an object.
+  # public-read ::            Gives the requester FULL_CONTROL permission and gives all anonymous users READ permission. When you apply this to an object, anyone on the Internet can read the object without authenticating.
+  # public-read-write ::      Gives the requester FULL_CONTROL permission and gives all anonymous users READ and WRITE permission. This ACL applies only to buckets.
+  # authenticated-read ::     Gives the requester FULL_CONTROL permission and gives all authenticated Google account holders READ permission.
+  # bucket-owner-read ::      Gives the requester FULL_CONTROL permission and gives the bucket owner READ permission. This is used only with objects.
+  # bucket-owner-full-control :: Gives the requester FULL_CONTROL permission and gives the bucket owner FULL_CONTROL permission. This is used only with objects.
+  #
+  ###
   
   class Client
+
+  ###
+  #
+  # <b>You need to initialize a client to be able to make requests with the google_storage gem</b>
+  #
+  # Example:
+  #
+  # The following will look for google_storage.yml in your rails config directory
+  #
+  #   client = GoogleStorage::Client.new
+  #
+  # Otherwise you can pass in the path to the google_storage.yml
+  #
+  #   client = GoogleStorage::Client.new(:config_yml => 'C:/example_path/google_storage.yml')
+  #
+  # Other options:
+  #
+  #   :debug => true      <-- This will output all debug information from the HTTP requests to $stderr
+  #
+  ###
     
     def initialize(options = {})
 
@@ -50,20 +102,21 @@ Example: GoogleStorage::Client.new(:config_yml => 'path to your google storage y
       @host           = options[:host] ? options[:host] : 'commondatastorage.googleapis.com'
     end
 
-    def google_storage_id(id)
-      case id
-        when :you
-          @gsid_you
-        when :owners
-          @gsid_owners
-        when :editors
-          @gsid_editors
-        when :team
-          @gsid_team
-      end
-    end
 
     private
+
+      def google_storage_id(id)
+        case id
+          when :you
+            @gsid_you
+          when :owners
+            @gsid_owners
+          when :editors
+            @gsid_editors
+          when :team
+            @gsid_team
+        end
+      end
       
       def get(bucket, path, options={})
         http_request(Net::HTTP::Get, bucket, path, options)

data/lib/google_storage/object.rb

@@ -4,9 +4,25 @@ require 'digest/md5'
 module GoogleStorage
   class Client
 
-    def get_object(bucket, filename, options={})
+    ###
+    #
+    # <b>Returns a Google Storage Object inside of a Hash</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#getobject
+    #
+    # Example:
+    #
+    #   Returns a Hash containing your object
+    #     client.get_object('bucket_name', 'example_image.jpg')
+    #
+    #   Or write the file directly to your file system
+    #     client.get_object('bucket_name', 'example_image.jpg', :write_to_file => 'C:/example/file.jpg')
+    #
+    ###
+
+    def get_object(bucket_name, filename, options={})
       filename.gsub!(/^\//, "")
-      resp = get(bucket, "/#{filename}", options)
+      resp = get(bucket_name, "/#{filename}", options)
       return Crack::XML.parse(resp.body) unless resp.code == "200"
       resp_obj = {}
       if options[:write_to_file]
@@ -30,7 +46,32 @@ module GoogleStorage
       return resp_obj
     end
 
-    def put_object(bucket, filename, options={})
+    ###
+    #
+    # <b>Uploads an Object to Google Storage, or updates if using the same filename</b>
+    #
+    # If no :x_goog_acl option is supplied, a 'private' ACL is applied by default
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#putobject
+    #
+    # *Note:* If no content type is specified then Google defaults to using 'binary/octet-stream'
+    #
+    # Example:
+    #
+    #   client.put_object('bucket_name', 'file.jpg', :path_to_file => 'C:/example/file.jpg')
+    #   client.put_object('bucket_name', 'file.jpg', :data => File.read('C:/example/file.jpg'))
+    #
+    # Available Options:
+    #
+    #   :x_goog_acl => 'public-read'
+    #   :content_type => 'image/jpeg'     <-- It's recommended to always include the content type
+    #   :path_to_file => 'path_to_file_you_want_to_upload'
+    #   :data => [binary_data]
+    #
+    #
+    ###
+
+    def put_object(bucket_name, filename, options={})
       filename.gsub!(/^\//, "")
       if options[:path_to_file]
         begin
@@ -46,23 +87,37 @@ module GoogleStorage
         end
         options[:data] = @data
       end
-      resp = put(bucket, "/#{filename}", options)
+      resp = put(bucket_name, "/#{filename}", options)
       public_file = (options[:x_goog_acl] && options[:x_goog_acl].match(/public/))
       return Crack::XML.parse(resp.body) unless resp.code == "200"
       resp_obj = {}
       resp_obj[:success]      = true
       resp_obj[:message]      = "Object added successfully"
       resp_obj[:filename]     = filename
-      resp_obj[:content_type] = options[:content_type]
-      resp_obj[:url]          = public_file ? "http://#{@host}/#{bucket}/#{filename}" : \
-                                              "https://sandbox.google.com/storage/#{bucket}/#{filename}"
+      resp_obj[:content_type] = options[:content_type] ? options[:content_type] : 'binary/octet-stream'
+      resp_obj[:url]          = public_file ? "http://#{@host}/#{bucket_name}/#{filename}" : \
+                                              "https://sandbox.google.com/storage/#{bucket_name}/#{filename}"
       resp_obj[:url_type]     = public_file ? "public" : "private"
       return resp_obj
     end
 
-    def list_acls_for_object(bucket, filename, options={})
+    alias :upload_object :put_object
+
+    ###
+    #
+    # <b>Lists the ACL that has been applied to a particular object</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#getobject
+    #
+    # Example:
+    #
+    #   client.object_acls('bucket_name', 'file.jpg')
+    #
+    ###
+
+    def object_acls(bucket_name, filename, options={})
       filename.gsub!(/^\//, "")
-      resp = get(bucket, "/#{filename}?acl", options)
+      resp = get(bucket_name, "/#{filename}?acl", options)
       resp_obj = Crack::XML.parse(resp.body)
       if resp_obj["AccessControlList"]
         resp_obj[:success] = true
@@ -74,11 +129,21 @@ module GoogleStorage
       return resp_obj
     end
 
-    alias :object_acls :list_acls_for_object
+    ###
+    #
+    # <b>Returns the metadata of an Object stored</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#headobject
+    #
+    # Example:
+    #
+    #   client.object_head('bucket_name', 'file.jpg')
+    #
+    ###
 
-    def head_object(bucket, filename, options={})
+    def object_head(bucket_name, filename, options={})
       filename.gsub!(/^\//, "")
-      resp = head(bucket, "/#{filename}", options)
+      resp = head(bucket_name, "/#{filename}", options)
       return resp.header unless resp.code == "200"
       resp_obj = {}
       resp_obj[:success]          = true
@@ -92,11 +157,21 @@ module GoogleStorage
       return resp_obj
     end
 
-    alias :object_head :head_object
+    ###
+    #
+    # <b>Deletes an Object from your bucket</b>
+    #
+    # Google Ref: http://code.google.com/apis/storage/docs/reference-methods.html#deleteobject
+    #
+    # Example:
+    #
+    #   client.delete_object('bucket_name', 'file.jpg')
+    #
+    ###
 
-    def delete_object(bucket, filename, options={})
+    def delete_object(bucket_name, filename, options={})
       filename.gsub!(/^\//, "")
-      resp = delete(bucket, "/#{filename}", options)
+      resp = delete(bucket_name, "/#{filename}", options)
       return Crack::XML.parse(resp.body) unless resp.code == "204"
       resp_obj = {}
       resp_obj[:success]          = true

data/lib/google_storage/request.rb

@@ -4,6 +4,8 @@ require 'cgi'
 module GoogleStorage
   class Client
 
+    protected
+
     def construct_post_request(host, path, headers={}, params={}, options={})
       headers["Host"]           = host
       headers["Date"]           = Time.now.utc.strftime('%a, %d %b %Y %H:%M:%S GMT')
@@ -16,7 +18,7 @@ module GoogleStorage
       raise "\nYou need to acquire a refresh_token before you can make requests to the Google API\n" unless @refresh_token
       headers["Host"]               = host
       headers["Date"]               = Time.now.utc.strftime('%a, %d %b %Y %H:%M:%S GMT')
-      headers["Content-Type"]       = options[:content_type] ? options[:content_type] : 'application/x-www-form-urlencoded'
+      headers["Content-Type"]       = options[:content_type] ? options[:content_type] : 'binary/octet-stream'
       headers["Content-Length"]     = (options[:data] ? options[:data].size : 0).to_s
       headers["x-goog-api-version"] = @api_version
       headers["x-goog-project-id"]  = @project_id if options[:send_goog_project_id]
@@ -32,50 +34,51 @@ module GoogleStorage
 
       _http_request(host, path, method, headers, param_string, options[:data])
     end
-    
+
     private
-      def _post_http_request(host, path, params, headers, data=nil)
-        http = Net::HTTP.new(host, 443)
-        http.use_ssl = true
-        http.set_debug_output $stderr if @debug
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
 
-        data ||= params_to_data_string(params)
-        resp = http.post(path, data, headers)
+    def _post_http_request(host, path, params, headers, data=nil)
+      http = Net::HTTP.new(host, 443)
+      http.use_ssl = true
+      http.set_debug_output $stderr if @debug
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
 
-        return resp.body
-      end
+      data ||= params_to_data_string(params)
+      resp = http.post(path, data, headers)
 
+      return resp.body
+    end
 
-      def _http_request(host, path, method, headers, param_string, data=nil)
-        http = Net::HTTP.new(host, 443)
-        http.use_ssl = true
-        http.set_debug_output $stderr if @debug
-        http.read_timeout = @timeout ? @timeout : 15
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-
-        req = method.new(path + param_string)
-          headers.each do |key, value|
-            req[key.to_s] = value
-          end
 
-        response = http.start { http.request(req, data) }
-        return response
-        rescue Timeout::Error
-          $stderr.puts "Timeout accessing #{path}: #{$!}"
-          nil
-        rescue
-          $stderr.puts "Error accessing #{path}: #{$!}"
-          nil
-      end
+    def _http_request(host, path, method, headers, param_string, data=nil)
+      http = Net::HTTP.new(host, 443)
+      http.use_ssl = true
+      http.set_debug_output $stderr if @debug
+      http.read_timeout = @timeout ? @timeout : 15
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
 
-      def params_to_data_string(params)
-        return "" if params.empty?
-        esc_params = params.collect do |p|
-          encoded = (CGI::escape(p[0].to_s) + "=" + CGI::escape(p[1].to_s))
-          encoded.gsub('+', '%20')
+      req = method.new(path + param_string)
+        headers.each do |key, value|
+          req[key.to_s] = value
         end
-        "#{esc_params.join('&')}"
+
+      response = http.start { http.request(req, data) }
+      return response
+      rescue Timeout::Error
+        $stderr.puts "Timeout accessing #{path}: #{$!}"
+        nil
+      rescue
+        $stderr.puts "Error accessing #{path}: #{$!}"
+        nil
+    end
+
+    def params_to_data_string(params)
+      return "" if params.empty?
+      esc_params = params.collect do |p|
+        encoded = (CGI::escape(p[0].to_s) + "=" + CGI::escape(p[1].to_s))
+        encoded.gsub('+', '%20')
       end
+      "#{esc_params.join('&')}"
+    end
   end
 end

data/lib/google_storage/token.rb

@@ -22,6 +22,8 @@ module GoogleStorage
       "Failed to acquire a refresh token. Something went wrong. Try getting a new Auth code."
     end
 
+    protected
+
     def refresh_access_token(token, options={})
       options['grant_type'] = 'refresh_token'
       post_request('accounts.google.com', '/o/oauth2/token', token, options)

data/lib/google_storage/version.rb

@@ -1,3 +1,3 @@
 module GoogleStorage
-  VERSION = "0.0.3"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google_storage
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,20 +9,19 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-06-24 00:00:00.000000000 +10:00
-default_executable: 
+date: 2011-06-28 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: crack
-  requirement: &9643716 !ruby/object:Gem::Requirement
+  requirement: &10204272 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *9643716
+  version_requirements: *10204272
 description: A Ruby client library for using the new Google Storage API v2 using OAuth2.0
 email:
 - lucas@lucashills.com
@@ -32,9 +31,27 @@ extra_rdoc_files:
 - README.textile
 files:
 - .gitignore
+- .yardopts
 - Gemfile
 - README.textile
 - Rakefile
+- doc/GoogleStorage.html
+- doc/GoogleStorage/Client.html
+- doc/GoogleStorage/InstallGenerator.html
+- doc/_index.html
+- doc/class_list.html
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
+- doc/file.README.html
+- doc/file_list.html
+- doc/frames.html
+- doc/index.html
+- doc/js/app.js
+- doc/js/full_list.js
+- doc/js/jquery.js
+- doc/method_list.html
+- doc/top-level-namespace.html
 - examples/examples.rb
 - google_storage.gemspec
 - lib/generators/google_storage/install/install_generator.rb
@@ -47,7 +64,6 @@ files:
 - lib/google_storage/request.rb
 - lib/google_storage/token.rb
 - lib/google_storage/version.rb
-has_rdoc: true
 homepage: https://github.com/2potatocakes/google_storage
 licenses: []
 post_install_message: 
@@ -68,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.5
 signing_key: 
 specification_version: 3
 summary: Google Storage for Developers is a RESTful service for storing and accessing