cfoundry 0.2.0 → 0.2.1

data/lib/cfoundry/app.rb

@@ -6,23 +6,67 @@ require "tmpdir"
 require "cfoundry/zip"
 
 module CFoundry
+  # Class for representing a user's application on a given target (via
+  # Client).
+  #
+  # Goes not guarantee that the app exists; used for both app creation and
+  # retrieval, as the attributes are all lazily retrieved. Setting attributes
+  # does not perform any requests; use #update! to commit your changes.
   class App
+    # Application name.
     attr_reader :name
 
+    # Application instance count.
+    attr_accessor :total_instances
+
+    # Services bound to the application.
+    attr_accessor :services
+
+    # Application environment variables.
+    attr_accessor :env
+
+    # Application memory limit.
+    attr_accessor :memory
+
+    # Application framework.
+    attr_accessor :framework
+
+    # Application runtime.
+    attr_accessor :runtime
+
+    # Application startup command.
+    #
+    # Used for standalone apps.
+    attr_accessor :command
+
+    # Application debug mode.
+    attr_accessor :debug_mode
+
+    # Application state.
+    attr_accessor :state
+    alias_method :status, :state
+
+    # URIs mapped to the application.
+    attr_accessor :uris
+    alias_method :urls, :uris
+
+
+    # Create an App object.
+    #
+    # You'll usually call Client#app instead
     def initialize(name, client, manifest = nil)
       @name = name
       @client = client
       @manifest = manifest
     end
 
-    def inspect
+    def inspect # :nodoc:
       "#<App '#@name'>"
     end
 
-    def manifest
-      @manifest ||= @client.rest.app(@name)
-    end
-
+    # Delete the application from the target.
+    #
+    # Keeps the metadata, but clears target-specific state from it.
     def delete!
       @client.rest.delete_app(@name)
 
@@ -33,11 +77,15 @@ module CFoundry
       end
     end
 
+    # Create the application on the target.
+    #
+    # Call this after setting the various attributes.
     def create!
       @client.rest.create_app(@manifest.merge("name" => @name))
       @manifest = nil
     end
 
+    # Check if the application exists on the target.
     def exists?
       @client.rest.app(@name)
       true
@@ -45,16 +93,19 @@ module CFoundry
       false
     end
 
+    # Retrieve all of the instances of the app, as Instance objects.
     def instances
       @client.rest.instances(@name).collect do |m|
         Instance.new(@name, m["index"], @client, m)
       end
     end
 
+    # Retrieve application statistics, e.g. CPU load and memory usage.
     def stats
       @client.rest.stats(@name)
     end
 
+    # Update application attributes. Does not restart the application.
     def update!(what = {})
       # TODO: hacky; can we not just set in meta field?
       # we write to manifest["debug"] but read from manifest["meta"]["debug"]
@@ -64,19 +115,28 @@ module CFoundry
       @manifest = nil
     end
 
+    # Stop the application.
     def stop!
       update! "state" => "STOPPED"
     end
 
+    # Start the application.
     def start!
       update! "state" => "STARTED"
     end
 
+    # Restart the application.
     def restart!
       stop!
       start!
     end
 
+    # Determine application health.
+    #
+    # If all instances are running, returns "RUNNING". If only some are
+    # started, returns the precentage of them that are healthy.
+    #
+    # Otherwise, returns application's status.
     def health
       s = state
       if s == "STARTED"
@@ -97,20 +157,26 @@ module CFoundry
       end
     end
 
+    # Check that all application instances are running.
     def healthy?
       # invalidate cache so the check is fresh
       @manifest = nil
       health == "RUNNING"
     end
+    alias_method :running?, :healthy?
 
+    # Is the application stopped?
     def stopped?
       state == "STOPPED"
     end
 
+    # Is the application started?
+    #
+    # Note that this does not imply that all instances are running. See
+    # #healthy?
     def started?
       state == "STARTED"
     end
-    alias_method :running?, :started?
 
     { :total_instances => "instances",
       :state => "state",
@@ -130,10 +196,12 @@ module CFoundry
       end
     end
 
+    # Shortcut for uris[0]
     def uri
       uris[0]
     end
 
+    # Shortcut for uris = [x]
     def uri=(x)
       self.uris = [x]
     end
@@ -141,12 +209,12 @@ module CFoundry
     alias :url :uri
     alias :url= :uri=
 
-    def framework
+    def framework # :nodoc:
       manifest["staging"]["framework"] ||
         manifest["staging"]["model"]
     end
 
-    def framework=(v)
+    def framework=(v) # :nodoc:
       @manifest ||= {}
       @manifest["staging"] ||= {}
 
@@ -157,12 +225,12 @@ module CFoundry
       end
     end
 
-    def runtime
+    def runtime # :nodoc:
       manifest["staging"]["runtime"] ||
         manifest["staging"]["stack"]
     end
 
-    def runtime=(v)
+    def runtime=(v) # :nodoc:
       @manifest ||= {}
       @manifest["staging"] ||= {}
 
@@ -173,39 +241,47 @@ module CFoundry
       end
     end
 
-    def command
+
+    def command # :nodoc:
       manifest["staging"]["command"]
     end
 
-    def command=(v)
+    def command=(v) # :nodoc:
       @manifest ||= {}
       @manifest["staging"] ||= {}
       @manifest["staging"]["command"] = v
     end
 
-    def memory
+
+    def memory # :nodoc:
       manifest["resources"]["memory"]
     end
 
-    def memory=(v)
+    def memory=(v) # :nodoc:
       @manifest ||= {}
       @manifest["resources"] ||= {}
       @manifest["resources"]["memory"] = v
     end
 
-    def debug_mode
-      manifest.fetch("debug") { manifest["meta"] && manifest["meta"]["debug"] }
+
+    def debug_mode # :nodoc:
+      manifest.fetch("debug") do
+        manifest["meta"] && manifest["meta"]["debug"]
+      end
     end
 
-    def debug_mode=(v)
+    def debug_mode=(v) # :nodoc:
       @manifest ||= {}
       @manifest["debug"] = v
     end
 
+
+    # Bind services to application.
     def bind(*service_names)
       update!("services" => services + service_names)
     end
 
+    # Unbind services from application.
     def unbind(*service_names)
       update!("services" =>
                 services.reject { |s|
@@ -213,16 +289,46 @@ module CFoundry
                 })
     end
 
+    # Retrieve file listing under path for the first instance of the application.
+    #
+    # [path]
+    #   A sequence of strings representing path segments.
+    #
+    #   For example, <code>files("foo", "bar")</code> for +foo/bar+.
     def files(*path)
       Instance.new(@name, 0, @client).files(*path)
     end
 
+    # Retrieve file contents for the first instance of the application.
+    #
+    # [path]
+    #   A sequence of strings representing path segments.
+    #
+    #   For example, <code>files("foo", "bar")</code> for +foo/bar+.
     def file(*path)
       Instance.new(@name, 0, @client).file(*path)
     end
 
+    # Default paths to exclude from upload payload.
+    #
+    # Value: .git, _darcs, .svn
     UPLOAD_EXCLUDE = %w{.git _darcs .svn}
 
+    # Upload application's code to target. Do this after #create! and before
+    # #start!
+    #
+    # [path]
+    #   A path pointing to either a directory, or a .jar, .war, or .zip
+    #   file.
+    #
+    #   If a .vmcignore file is detected under the given path, it will be used
+    #   to exclude paths from the payload, similar to a .gitignore.
+    #
+    # [check_resources]
+    #   If set to `false`, the entire payload will be uploaded
+    #   without checking the resource cache.
+    #
+    #   Only do this if you know what you're doing.
     def upload(path, check_resources = true)
       unless File.exist? path
         raise "invalid application path '#{path}'"
@@ -248,6 +354,10 @@ module CFoundry
 
     private
 
+    def manifest
+      @manifest ||= @client.rest.app(@name)
+    end
+
     def prepare_package(path, to)
       if path =~ /\.(jar|war|zip)$/
         CFoundry::Zip.unpack(path, to)
@@ -291,6 +401,9 @@ module CFoundry
       end
     end
 
+    # Minimum size for an application payload to bother checking resources.
+    #
+    # Value: 64kb
     RESOURCE_CHECK_LIMIT = 64 * 1024
 
     def determine_resources(path)
@@ -349,9 +462,17 @@ module CFoundry
       files && files.select { |f| File.socket? f }
     end
 
+    # Class represnting a running instance of an application.
     class Instance
-      attr_reader :app, :index, :manifest
+      # The application this instance belongs to.
+      attr_reader :app
 
+      # Application instance number.
+      attr_reader :index
+
+      # Create an Instance object.
+      #
+      # You'll usually call App#instances instead
       def initialize(appname, index, client, manifest = {})
         @app = appname
         @index = index
@@ -359,33 +480,43 @@ module CFoundry
         @manifest = manifest
       end
 
-      def inspect
+      def inspect # :nodoc:
         "#<App::Instance '#@app' \##@index>"
       end
 
+      # Instance state.
       def state
         @manifest["state"]
       end
       alias_method :status, :state
 
+      # Instance start time.
       def since
         Time.at(@manifest["since"])
       end
 
+      # Instance debugger data. If instance is in debug mode, returns a hash
+      # containing :ip and :port keys.
       def debugger
         return unless @manifest["debug_ip"] and @manifest["debug_port"]
-        { "ip" => @manifest["debug_ip"],
-          "port" => @manifest["debug_port"]
+
+        { :ip => @manifest["debug_ip"],
+          :port => @manifest["debug_port"]
         }
       end
 
+      # Instance console data. If instance has a console, returns a hash
+      # containing :ip and :port keys.
       def console
         return unless @manifest["console_ip"] and @manifest["console_port"]
-        { "ip" => @manifest["console_ip"],
-          "port" => @manifest["console_port"]
+
+        { :ip => @manifest["console_ip"],
+          :port => @manifest["console_port"]
         }
       end
 
+      # True if instance is starting or running, false if it's down or
+      # flapping.
       def healthy?
         case state
         when "STARTING", "RUNNING"
@@ -395,12 +526,24 @@ module CFoundry
         end
       end
 
+      # Retrieve file listing under path for this instance.
+      #
+      # [path]
+      #   A sequence of strings representing path segments.
+      #
+      #   For example, <code>files("foo", "bar")</code> for +foo/bar+.
       def files(*path)
         @client.rest.files(@app, @index, *path).split("\n").collect do |entry|
           path + [entry.split(/\s+/, 2)[0]]
         end
       end
 
+      # Retrieve file contents for this instance.
+      #
+      # [path]
+      #   A sequence of strings representing path segments.
+      #
+      #   For example, <code>files("foo", "bar")</code> for +foo/bar+.
       def file(*path)
         @client.rest.files(@app, @index, *path)
       end

data/lib/cfoundry/client.rb

@@ -5,39 +5,53 @@ require "cfoundry/user"
 
 
 module CFoundry
+  # The primary API entrypoint. Wraps RESTClient to provide nicer return
+  # values. Initialize with the target and, optionally, an auth token. These
+  # are the only two internal states.
   class Client
-    attr_reader :rest
+    attr_reader :rest #:nodoc:
 
-    def initialize(*args)
+    # Create a new Client for interfacing with the given target.
+    #
+    # A token may also be provided to skip the login step.
+    def initialize(target = "http://api.cloudfoundry.com", token = nil)
       @rest = RESTClient.new(*args)
     end
 
+    # The current target URL of the client.
     def target
       @rest.target
     end
 
+    # Current proxy user. Usually nil.
     def proxy
       @rest.proxy
     end
 
-    def proxy=(x)
-      @rest.proxy = x
+    # Set the proxy user for the client. Must be authorized as an
+    # administrator for this to have any effect.
+    def proxy=(email)
+      @rest.proxy = email
     end
 
+    # Is the client tracing API requests?
     def trace
       @rest.trace
     end
 
-    def trace=(x)
-      @rest.trace = x
+    # Set the tracing flag; if true, API requests and responses will be
+    # printed out.
+    def trace=(bool)
+      @rest.trace = bool
     end
 
 
-    # Cloud metadata
+    # Retrieve target metadata.
     def info
       @rest.info
     end
 
+    # Retrieve available services. Returned as a Hash from vendor => metadata.
     def system_services
       services = {}
 
@@ -55,12 +69,13 @@ module CFoundry
       services
     end
 
+    # Retrieve available runtimes.
     def system_runtimes
       @rest.system_runtimes
     end
 
 
-    # Users
+    # Retrieve user list. Admin-only.
     def users
       @rest.users.collect do |json|
         CFoundry::User.new(
@@ -71,47 +86,67 @@ module CFoundry
       end
     end
 
+    # Construct a User object. The return value is lazy, and no requests are
+    # made from this alone.
+    #
+    # This should be used for both user creation (after calling User#create!)
+    # and retrieval.
     def user(email)
       CFoundry::User.new(email, self)
     end
 
+    # Create a user on the target and return a User object representing them.
     def register(email, password)
       @rest.create_user(:email => email, :password => password)
       user(email)
     end
 
+    # Authenticate with the target. Sets the client token.
     def login(email, password)
       @rest.token =
         @rest.create_token({ :password => password }, email)["token"]
     end
 
+    # Clear client token. No requests are made for this.
     def logout
       @rest.token = nil
     end
 
+    # Is an authentication token set on the client?
     def logged_in?
       !!@rest.token
     end
 
 
-    # Applications
+    # Retreive all of the current user's applications.
     def apps
       @rest.apps.collect do |json|
         CFoundry::App.new(json["name"], self, json)
       end
     end
 
+    # Construct an App object. The return value is lazy, and no requests are
+    # made from this method alone.
+    #
+    # This should be used for both app creation (after calling App#create!)
+    # and retrieval.
     def app(name)
       CFoundry::App.new(name, self)
     end
 
-    # Services
+
+    # Retrieve all of the current user's services.
     def services
       @rest.services.collect do |json|
         CFoundry::Service.new(json["name"], self, json)
       end
     end
 
+    # Construct a Service object. The return value is lazy, and no requests are
+    # made from this method alone.
+    #
+    # This should be used for both service creation (after calling
+    # Service#create!) and retrieval.
     def service(name)
       CFoundry::Service.new(name, self)
     end

data/lib/cfoundry/errors.rb

@@ -1,28 +1,32 @@
 module CFoundry
+  # Exception representing errors returned by the API.
   class APIError < RuntimeError
-    class << self
-      attr_reader :error_code, :description
+    class << self # :nodoc:
+      attr_reader :error_code, :description # :nodoc:
 
-      def setup(code, description = nil)
+      def setup(code, description = nil) # :nodoc:
         @error_code = code
         @description = description
       end
     end
 
+    # Create an APIError with a given error code and description.
     def initialize(error_code = nil, description = nil)
       @error_code = error_code
       @description = description
     end
 
+    # A number representing the error.
     def error_code
       @error_code || self.class.error_code
     end
 
+    # A description of the error.
     def description
       @description || self.class.description
     end
 
-    def to_s
+    def to_s # :nodoc:
       if error_code
         "#{error_code}: #{description}"
       else
@@ -31,31 +35,40 @@ module CFoundry
     end
   end
 
+  # Generic exception thrown when accessing something that doesn't exist (e.g.
+  # getting info of unknown application).
   class NotFound < APIError
     setup(404, "entity not found or inaccessible")
   end
 
+  # Lower-level exception for when we cannot connect to the target.
   class TargetRefused < APIError
     @description = "target refused connection"
 
+    # Error message.
     attr_reader :message
 
+    # Message varies as this represents various network errors.
     def initialize(message)
       @message = message
     end
 
-    def to_s
+    def to_s # :nodoc:
       "#{description} (#{@message})"
     end
   end
 
+  # Exception raised when an application payload fails to upload.
   class UploadFailed < APIError
     setup(402)
   end
 
+  # Exception raised when access is denied to something, either because the
+  # user is not logged in or is not an administrator.
   class Denied < APIError
-    attr_reader :error_code, :description
+    attr_reader :error_code, :description # :nodoc:
 
+    # Initialize, with a default error code and message.
     def initialize(
         error_code = 200,
         description = "Operation not permitted")
@@ -64,13 +77,16 @@ module CFoundry
     end
   end
 
+  # Exception raised when the response is unexpected; usually from a server
+  # error.
   class BadResponse < StandardError
+    # Initialize, with the HTTP response code and body.
     def initialize(code, body = nil)
       @code = code
       @body = body
     end
 
-    def to_s
+    def to_s # :nodoc:
       "target failed to handle our request due to an internal error (#{@code})"
     end
   end

data/lib/cfoundry/restclient.rb

@@ -5,7 +5,7 @@ require "cfoundry/errors"
 
 
 module CFoundry
-  class RESTClient
+  class RESTClient # :nodoc:
     attr_accessor :target, :token, :proxy, :trace
 
     def initialize(

data/lib/cfoundry/service.rb

@@ -1,29 +1,58 @@
 module CFoundry
+  # Class for representing a user's service on a given target (via Client).
+  #
+  # Goes not guarantee that the service exists; used for both service creation
+  # and retrieval, as the attributes are all lazily retrieved. Setting
+  # attributes does not perform any requests; use #update! to commit your
+  # changes.
   class Service
+    # Service name.
     attr_reader :name
 
+    # Service type (e.g. key-value).
+    attr_accessor :type
+
+    # Service vendor (redis, mysql, etc.).
+    attr_accessor :vendor
+
+    # Service version.
+    attr_accessor :version
+
+    # Service properties.
+    attr_accessor :properties
+
+    # Service tier. Usually "free" for now.
+    attr_accessor :tier
+
+    # Service metadata.
+    attr_accessor :meta
+
+    # Create a Service object.
+    #
+    # You'll usually call Client#service instead.
     def initialize(name, client, manifest = nil)
       @name = name
       @client = client
       @manifest = manifest
     end
 
-    def inspect
+    def inspect # :nodoc:
       "#<Service '#@name'>"
     end
 
-    def manifest
-      @manifest ||= @client.rest.service(@name)
-    end
-
+    # Delete the service from the target.
     def delete!
       @client.rest.delete_service(@name)
     end
 
+    # Create the service on the target.
+    #
+    # Call this after setting the various attributes.
     def create!
       @client.rest.create_service(@manifest.merge("name" => @name))
     end
 
+    # Check if the service exists on the target.
     def exists?
       @client.rest.service(@name)
       true
@@ -31,10 +60,12 @@ module CFoundry
       false
     end
 
+    # Timestamp of when the service was created.
     def created
       Time.at(meta["created"])
     end
 
+    # Timestamp of when the service was last updated.
     def updated
       Time.at(meta["updated"])
     end
@@ -55,5 +86,11 @@ module CFoundry
         @manifest[attr] = v
       end
     end
+
+    private
+
+    def manifest
+      @manifest ||= @client.rest.service(@name)
+    end
   end
 end

data/lib/cfoundry/user.rb

@@ -1,34 +1,46 @@
 module CFoundry
+  # Class for representing a user on a given target (via Client).
+  #
+  # Goes not guarantee that the user exists; used for both user creation and
+  # retrieval, as the attributes are all lazily retrieved. Setting attributes
+  # does not perform any requests; use #update! to commit your changes.
   class User
+    # User email.
     attr_reader :email
 
+
+    # Create a User object.
+    #
+    # You'll usually call Client#user instead
     def initialize(email, client, manifest = nil)
       @email = email
       @client = client
       @manifest = manifest
     end
 
-    def inspect
+    def inspect # :nodoc:
       "#<User '#@email'>"
     end
 
-    def manifest
-      @manifest ||= @client.rest.user(@email)
-    end
-
+    # Delete the user from the target.
     def delete!
       @client.rest.delete_user(@email)
     end
 
+    # Create the user on the target.
+    #
+    # Call this after setting the various attributes.
     def create!
       @client.rest.create_user(@manifest.merge("email" => @email))
     end
 
+    # Update user attributes.
     def update!(what = {})
       @client.rest.update_user(@email, manifest.merge(what))
       @manifest = nil
     end
 
+    # Check if the user exists on the target.
     def exists?
       @client.rest.user(@email)
       true
@@ -36,12 +48,22 @@ module CFoundry
       false
     end
 
+    # Check if the user is an administrator.
     def admin?
       manifest["admin"]
     end
 
+    # Set the user's password.
+    #
+    # Call #update! after using this.
     def password=(str)
       manifest["password"] = str
     end
+
+    private
+
+    def manifest
+      @manifest ||= @client.rest.user(@email)
+    end
   end
 end

data/lib/cfoundry/version.rb

@@ -1,3 +1,4 @@
-module CFoundry
-  VERSION = "0.2.0"
+module CFoundry # :nodoc:
+  # CFoundry library version number.
+  VERSION = "0.2.1"
 end

data/lib/cfoundry/zip.rb

@@ -1,11 +1,16 @@
-require 'zip/zipfilesystem'
+require "zip/zipfilesystem"
 
 module CFoundry
+  # Generic Zpi API. Uses rubyzip underneath, but may be changed in the future
+  # to use system zip command if necessary.
   module Zip
+    # Directory entries to exclude from packing.
     PACK_EXCLUSION_GLOBS = ['..', '.', '*~', '#*#', '*.log']
 
     module_function
 
+    # Get the entries in the zip file. Returns an array of the entire
+    # contents, recursively (not just top-level).
     def entry_lines(file)
       entries = []
       ::Zip::ZipFile.foreach(file) do |zentry|
@@ -14,6 +19,7 @@ module CFoundry
       entries
     end
 
+    # Unpack a zip +file+ to directory +dest+.
     def unpack(file, dest)
       ::Zip::ZipFile.foreach(file) do |zentry|
         epath = "#{dest}/#{zentry}"
@@ -23,6 +29,7 @@ module CFoundry
       end
     end
 
+    # Determine what files in +dir+ to pack.
     def files_to_pack(dir)
       Dir.glob("#{dir}/**/*", File::FNM_DOTMATCH).select do |f|
         File.exists?(f) &&
@@ -32,6 +39,7 @@ module CFoundry
       end
     end
 
+    # Package directory +dir+ as file +zipfile+.
     def pack(dir, zipfile)
       files = files_to_pack(dir)
       return false if files.empty?

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cfoundry
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Alex Suraci
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-05-31 00:00:00 Z
+date: 2012-06-02 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rest-client