startapp 0.1.6

data/lib/rhc/commands/apps.rb

@@ -0,0 +1,20 @@
+require 'rhc/commands/base'
+
+module RHC::Commands
+  class Apps < Base
+    summary "List all your applications"
+    description "Display the list of applications that you own. Includes information about each application."
+    def run
+      applications = rest_client.applications(:include => :cartridges).sort
+
+      info "In order to deploy applications, you must create a domain with 'app setup' or 'app create-domain'." and return 1 if applications.empty? && rest_client.domains.empty?
+
+      applications.each{ |a| display_app(a, a.cartridges) }.blank? and
+        info "No applications. Use 'app create-app'." and
+        return 1
+
+      success "You have #{applications.length} applications"
+      0
+    end
+  end
+end

data/lib/rhc/commands/authorization.rb

@@ -0,0 +1,115 @@
+module RHC::Commands
+  class Authorization < Base
+
+    summary "Manage your authorization tokens"
+    syntax "<action>"
+    description <<-DESC
+      An authorization token grants access to the StartApp REST API with a
+      set of privileges called 'scopes' for a limited time.  You can add an
+      optional note to each authorization token to assist you in remembering
+      why it was created.
+
+      To see all your authorizations, run 'app authorizations'.
+
+      To view the list of scopes supported by this server, run the
+      'app add-authorization' command with no arguments.
+
+      These commands manage your authorization tokens on the server - if you
+      want to clear your authorization tokens from the current machine use
+      'app logout'
+      DESC
+    default_action :help
+
+    summary "Show the authorization tokens for your account"
+    description <<-DESC
+      Shows the full list of authorization tokens on your account. You
+      can add, edit, or delete authorizations with subcommands.
+
+      An authorization token grants access to the StartApp REST API with
+      a set of privileges called 'scopes' for a limited time.  You can
+      add an optional note to each authorization token to assist you in
+      remembering what is available.
+      DESC
+    alias_action 'authorizations', :root_command => true
+
+    def list
+      rest_client.authorizations.each{ |auth| paragraph{ display_authorization(auth, token_for_user) } } or info "No authorizations"
+
+      0
+    end
+
+    option "--scopes SCOPES", "A comma delimited list of scopes (e.g. 'scope1,scope2')"
+    option "--note NOTE", "A description of this authorization (optional)"
+    option "--expires-in SECONDS", "The number of seconds before this authorization expires (optional)"
+    summary "Add an authorization to your account"
+    syntax "--scopes SCOPES [--note NOTE] [--expires-in SECONDS]"
+    description <<-DESC
+      Add an authorization to your account. An authorization token grants
+      access to the StartApp REST API with a set of privileges called 'scopes'
+      for a limited time.  You can add an optional note to each authorization
+      token to assist you in remembering what is available.
+
+      To view the list of scopes supported by this server, run this command
+      without any options.
+
+      You may pass multiple scopes to the --scopes option inside of double
+      quotes (--scopes \"scope1 scope2\") or by separating them with commas
+      (--scopes scope1,scope2).
+
+      The server will enforce a maximum and default expiration that may
+      differ for each scope. If you request an expiration longer than the
+      server maximum, you will be given the default value.
+      DESC
+    def add
+      unless options.scopes.to_s.strip.present?
+        say "When adding an authorization, you must specify which permissions clients will have."
+        scope_help
+        say "Run 'app authorization add --help' to see more options"
+        return 0
+      end
+
+      say "Adding authorization ... "
+      auth = rest_client.add_authorization(:scope => options.scopes, :note => options.note, :expires_in => options.expires_in)
+      success "done"
+      paragraph{ display_authorization(auth) }
+
+      0
+    end
+
+    summary "Delete one or more authorization tokens"
+    syntax "<token_or_id> [...<token_or_id>]"
+    description <<-DESC
+      Delete one or more of the authorization tokens associated with
+      your account. After deletion, any clients using the token will
+      no longer have access to StartApp and will need to reauthenticate.
+      DESC
+    argument :auth_token, "The token you wish to delete", ['--auth-token TOKEN'], :type => :list
+    def delete(tokens)
+      raise ArgumentError, "You must specify one or more tokens to delete" if tokens.blank?
+      say "Deleting authorization ... "
+      tokens.each{ |token| rest_client.delete_authorization(token) }
+      success "done"
+      0
+    end
+
+    summary "Delete all authorization tokens from your account"
+    description <<-DESC
+      Delete all the authorization tokens associated with your account.
+      After deletion, any clients using those tokens will need to
+      reauthenticate.
+      DESC
+    def delete_all
+      say "Deleting all authorizations ... "
+      rest_client.delete_authorizations
+      success "done"
+      0
+    end
+
+    protected
+      def scope_help
+        descriptions = rest_client.authorization_scope_list
+        paragraph{ say table(descriptions, :header => ['Scope', 'Description']) }
+        paragraph{ say "You may pass multiple scopes to the --scopes option inside of double quotes (--scopes \"scope1 scope2\") or by separating them with commas (--scopes scope1,scope2)." }
+      end
+  end
+end

data/lib/rhc/commands/base.rb

@@ -0,0 +1,174 @@
+require 'commander'
+require 'commander/delegates'
+require 'rhc/helpers'
+require 'rhc/wizard'
+require 'rhc/config'
+require 'rhc/commands'
+require 'rhc/exceptions'
+require 'rhc/context_helper'
+
+class RHC::Commands::Base
+
+  attr_writer :options, :config
+
+  def initialize(options=Commander::Command::Options.new,
+                 config=RHC::Config.new)
+    @options, @config = options, config
+  end
+
+  protected
+    include RHC::Helpers
+    include RHC::ContextHelpers
+
+    attr_reader :options, :config
+
+    # Return a client object capable of making calls
+    # to the OpenShift API that transforms intent
+    # and options, to remote calls, and then handle
+    # the output (or failures) into exceptions and
+    # formatted object output.  Most interactions
+    # should be through this call pattern.
+    def rest_client(opts={})
+      @rest_client ||= begin
+          auth = RHC::Auth::Basic.new(options)
+          auth = RHC::Auth::Token.new(options, auth, token_store) if (options.use_authorization_tokens || options.token) && !(options.rhlogin && options.password)
+          debug "Authenticating with #{auth.class}"
+          client_from_options(:auth => auth)
+        end
+
+        if opts[:min_api] && opts[:min_api].to_f > @rest_client.api_version_negotiated.to_f
+          raise RHC::ServerAPINotSupportedException.new(opts[:min_api], @rest_client.api_version_negotiated)
+        end
+
+      @rest_client
+    end
+
+    def token_store
+      @token_store ||= RHC::Auth::TokenStore.new(config.home_conf_path)
+    end
+
+    def help(*args)
+      raise ArgumentError, "Please specify an action to take"
+    end
+
+    class InvalidCommand < StandardError ; end
+
+    def self.method_added(method)
+      return if self == RHC::Commands::Base
+      return if private_method_defined? method
+      return if protected_method_defined? method
+
+      prefix = self.object_name
+      method_name = method.to_s == 'run' ? nil : method.to_s.gsub("_", "-")
+      name = [prefix, method_name].compact
+      raise InvalidCommand, "Either object_name must be set or a non default method defined" if name.empty?
+
+      aliases.each{ |a| a[:action].unshift(prefix) unless a[:root_command] } if prefix
+
+      RHC::Commands.add((@options || {}).merge({
+        :name => name,
+        :class => self,
+        :method => method
+      }));
+
+      @options = nil
+    end
+
+    def self.object_name(value=nil)
+      @object_name ||= begin
+          value ||= if self.name && !self.name.empty?
+            self.name.split('::').last
+          end
+          value.to_s.split(/(?=[A-Z])/).join('-').downcase if value
+        end
+    end
+
+    def self.description(*args)
+      o = args.join(' ')
+      options[:description] = o.strip_heredoc
+    end
+    def self.summary(value)
+      options[:summary] = value
+    end
+    def self.syntax(value)
+      options[:syntax] = value
+    end
+    #def self.deprecated(msg)
+    #  options[:deprecated] = msg
+    #end
+    def self.suppress_wizard
+      @suppress_wizard = true
+    end
+
+    def self.suppress_wizard?
+      @suppress_wizard
+    end
+
+    #
+    # Provide an alias to the command.  The alias will not be shown in help, but will
+    # be available in autocompletion and at execution time.
+    #
+    # Supported options:
+    #
+    #   :deprecated - if true, a warning will be displayed when the command is executed
+    #   :root_command - if true, do not prepend the object name to the command
+    #
+    def self.alias_action(action, options={})
+      options[:action] = action.is_a?(Array) ? action : action.to_s.split(' ')
+      aliases << options
+    end
+
+    def self.option(switches, description, options={})
+      options_metadata << {:switches => switches,
+                           :description => description,
+                           :required => options[:required],
+                           :covered_by => options[:covered_by],
+                           :deprecated => options[:deprecated],
+                           :type => options[:type],
+                           :hide => options[:hide],
+                           :default => options[:default],
+                          }
+    end
+
+    def self.argument(name, description, switches=[], options={})
+      arg_type = options[:type]
+
+      option_symbol = Commander::Runner.switch_to_sym(switches.last)
+      args_metadata << {:name => name,
+                        :description => description,
+                        :switches => switches,
+                        :option_symbol => option_symbol,
+                        :covered_by => options[:covered_by],
+                        :optional => options[:optional],
+                        :default => options[:default],
+                        :allow_nil => options[:allow_nil],
+                        :hide => options[:hide],
+                        :type => arg_type}
+    end
+
+    def self.default_action(action)
+      options[:default] = action unless action == :help
+      name = self.object_name
+      raise InvalidCommand, "object_name must be set" if name.empty?
+
+      RHC::Commands.add((@options || {}).merge({
+        :name => name,
+        :class => self,
+        :method => options[:default]
+      }));
+    end
+
+  private
+    def self.options_metadata
+      options[:options] ||= []
+    end
+    def self.args_metadata
+      options[:args] ||= []
+    end
+    def self.aliases
+      options[:aliases] ||= []
+    end
+    def self.options
+      @options ||= {}
+    end
+end

data/lib/rhc/commands/cartridge.rb

@@ -0,0 +1,329 @@
+require 'rhc/commands/base'
+require 'rhc/cartridge_helpers'
+
+module RHC::Commands
+  class Cartridge < Base
+    summary "Manage your application cartridges"
+    syntax "<action>"
+    description <<-DESC
+      Cartridges add functionality to StartApp applications.  Each application
+      has one web cartridge to listen for HTTP requests, and any number
+      of addon cartridges.  Addons may include databases like MySQL and Mongo,
+      administrative tools like phpMyAdmin, or build clients like Jenkins.
+
+      Most cartridges that listen for incoming network traffic are placed on
+      one or more gears (a small server instance).  Other cartridges may be
+      available across all of the gears of an application to listen for changes
+      (like Jenkins) or provide environment variables.
+
+      Use the 'cartridges' command to see a list of all available cartridges.
+      Add a new cartridge to your application with 'add-cartridge'. StartApp
+      also supports downloading cartridges - pass a URL in place of the cartridge
+      name and we'll download and install that cartridge into your app.  Keep
+      in mind that these cartridges receive no security updates.  Note that
+      not all StartApp servers allow downloaded cartridges.
+
+      For scalable applications, use the 'cartridge-scale' command on the web
+      cartridge to set the minimum and maximum scale.
+
+      Commands that affect a cartridge within an application will affect all
+      gears the cartridge is installed to.
+      DESC
+    default_action :help
+
+    summary "List available cartridges"
+    syntax ''
+    option ["-v", "--verbose"], "Display more details about each cartridge"
+    alias_action :"app cartridge list", :root_command => true, :deprecated => true
+    alias_action :"cartridges", :root_command => true
+    def list
+      carts = rest_client.cartridges.sort_by{ |c| "#{c.type == 'standalone' && 1}_#{c.tags.include?('experimental') ? 1 : 0}_#{(c.display_name || c.name).downcase}" }
+
+      pager
+
+      if options.verbose
+        carts.each do |c|
+          paragraph do
+            name = c.name
+            name += '*' if c.usage_rate?
+            name = c.display_name != c.name && "#{color(c.display_name, :cyan)} [#{name}]" || name
+            tags = c.tags - RHC::Rest::Cartridge::HIDDEN_TAGS
+            say header([name, "(#{c.only_in_existing? ? 'addon' : 'web'})"])
+            say c.description
+            paragraph{ say "Tagged with: #{tags.sort.join(', ')}" } if tags.present?
+            paragraph{ say format_usage_message(c) } if c.usage_rate?
+            paragraph{ warn "Does not receive automatic security updates" } unless c.automatic_updates?
+          end
+        end
+      else
+        say table(carts.collect do |c|
+          [[c.name, c.usage_rate? ? " (*)" : "", c.automatic_updates? ? '' : ' (!)'].join(''),
+           c.display_name,
+           c.only_in_existing? ? 'addon' : 'web',
+          ]
+        end)
+      end
+
+      paragraph{ say "Note: Web cartridges can only be added to new applications." }
+      paragraph{ say "(*) denotes a cartridge with additional usage costs." } if carts.any?(&:usage_rate?)
+      paragraph{ say "(!) denotes a cartridge that will not receive automatic security updates." } unless options.verbose || carts.none?(&:automatic_updates?)
+
+      0
+    end
+
+    summary "Add a cartridge to your application"
+    syntax "<cartridge_type> [--namespace NAME] [--app NAME]"
+    takes_application
+    option ["-e", "--env VARIABLE=VALUE"], "Environment variable(s) to be set on this cartridge, or path to a file containing environment variables", :type => :list
+    option ["-g", "--gear-size SIZE"], "Gear size controls how much memory and CPU your cartridge can use"
+    argument :cart_type, "The type of the cartridge you are adding (run 'app cartridge list' to obtain a list of available cartridges)", ["-c", "--cartridge cart_type"]
+    alias_action :"app cartridge add", :root_command => true, :deprecated => true
+    def add(cart_type)
+      cart = check_cartridges(cart_type, :from => not_standalone_cartridges).first
+
+      say "Adding #{cart.short_name} to application '#{options.app}' ... "
+
+      say format_usage_message(cart) if cart.usage_rate?
+
+      rest_app = find_app(:include => :cartridges)
+
+      supports_env_vars = rest_app.supports_add_cartridge_with_env_vars?
+      supports_gear_size = rest_app.supports_add_cartridge_with_gear_size?
+
+      cart.environment_variables = collect_env_vars(options.env).map { |item| item.to_hash } if options.env && supports_env_vars
+      cart.gear_size = options.gear_size if options.gear_size && supports_gear_size
+
+      rest_cartridge = rest_app.add_cartridge(cart)
+
+      success "done"
+
+      rest_cartridge.environment_variables = cart.environment_variables if cart.environment_variables.present?
+
+      paragraph{ display_cart(rest_cartridge) }
+      paragraph{ say "Use 'app env --help' to manage environment variable(s) on this cartridge and application." } if cart.environment_variables.present?
+      paragraph{ warn "Server does not support environment variables." if options.env && !supports_env_vars  }
+      paragraph{ warn "Server does not support gear sizes for cartridges." if options.gear_size && !supports_gear_size  }
+      paragraph{ rest_cartridge.messages.each { |msg| success msg } }
+
+      0
+    end
+
+    summary "Show useful information about a cartridge"
+    syntax "<cartridge> [--namespace NAME] [--app NAME]"
+    takes_application
+    argument :cartridge, "The name of the cartridge", ["-c", "--cartridge cart_type"]
+    def show(cartridge)
+      rest_app = find_app(:include => :cartridges)
+      rest_cartridge = check_cartridges(cartridge, :from => rest_app.cartridges).first
+
+      display_cart(rest_cartridge)
+
+      0
+    end
+
+    summary "Remove a cartridge from your application"
+    syntax "<cartridge> [--namespace NAME] [--app NAME]"
+    argument :cartridge, "The name of the cartridge you are removing", ["-c", "--cartridge cartridge"]
+    takes_application
+    option ["--confirm"], "Pass to confirm removing the cartridge"
+    alias_action :"app cartridge remove", :root_command => true, :deprecated => true
+    def remove(cartridge)
+      rest_app = find_app(:include => :cartridges)
+      rest_cartridge = check_cartridges(cartridge, :from => rest_app.cartridges).first
+
+      confirm_action "Removing a cartridge is a destructive operation that may result in loss of data associated with the cartridge.\n\nAre you sure you wish to remove #{rest_cartridge.name} from '#{rest_app.name}'?"
+
+      say "Removing #{rest_cartridge.name} from '#{rest_app.name}' ... "
+      rest_cartridge.destroy
+      success "removed"
+
+      paragraph{ rest_cartridge.messages.each { |msg| success msg } }
+
+      0
+    end
+
+    summary "Start a cartridge"
+    syntax "<cartridge> [--namespace NAME] [--app NAME]"
+    argument :cart_type, "The name of the cartridge you are stopping", ["-c", "--cartridge cartridge"]
+    takes_application
+    alias_action :"app cartridge start", :root_command => true, :deprecated => true
+    def start(cartridge)
+      cartridge_action(cartridge, :start, 'Starting %s ... ')
+      0
+    end
+
+    summary "Stop a cartridge"
+    syntax "<cartridge> [--namespace NAME] [--app NAME]"
+    argument :cart_type, "The name of the cartridge you are stopping", ["-c", "--cartridge cartridge"]
+    takes_application
+    alias_action :"app cartridge stop", :root_command => true, :deprecated => true
+    def stop(cartridge)
+      cartridge_action(cartridge, :stop, 'Stopping %s ... ')
+      0
+    end
+
+    summary "Restart a cartridge"
+    syntax "<cartridge_type> [--namespace NAME] [--app NAME]"
+    argument :cart_type, "The name of the cartridge you are restarting", ["-c", "--cartridge cartridge"]
+    takes_application
+    alias_action :"app cartridge restart", :root_command => true, :deprecated => true
+    def restart(cartridge)
+      cartridge_action(cartridge, :restart, 'Restarting %s ... ')
+      0
+    end
+
+    summary "Get current the status of a cartridge"
+    syntax "<cartridge> [--namespace NAME] [--app NAME]"
+    argument :cart_type, "The name of the cartridge you are getting the status of", ["-c", "--cartridge cartridge"]
+    takes_application
+    alias_action :"app cartridge status", :root_command => true, :deprecated => true
+    def status(cartridge)
+      rest_app = find_app(:include => :cartridges)
+      rest_cartridge = check_cartridges(cartridge, :from => rest_app.cartridges).first
+      results { rest_cartridge.status.each{ |msg| say msg['message'] } }
+      0
+    end
+
+    summary "Reload the cartridge's configuration"
+    syntax "<cartridge> [--namespace NAME] [--app NAME]"
+    argument :cart_type, "The name of the cartridge you are reloading", ["-c", "--cartridge cartridge"]
+    takes_application
+    alias_action :"app cartridge reload", :root_command => true, :deprecated => true
+    def reload(cartridge)
+      cartridge_action(cartridge, :reload, 'Reloading %s ... ')
+      0
+    end
+
+    summary "Set the scale range for a cartridge"
+    description <<-DESC
+      Each cartridge capable of scaling may have a minimum and a maximum set, although within that range
+      each type of cartridge may make decisions to autoscale.  Web cartridges will scale based on incoming
+      request traffic - see https://www.openshift.com/developers/scaling for more information. Non web
+      cartridges such as databases may require specific increments of scaling (1, 3, 5) in order to
+      properly function.  Please consult the cartridge documentation for more on specifics of scaling.
+
+      Set both values the same to guarantee a scale value.  You may specify both values with the argument
+      'multiplier' or use '--min' and '--max' independently.
+
+      Scaling may take several minutes or more if the server must provision multiple gears. Your operation
+      will continue in the background if your client is disconnected.
+      DESC
+    syntax "<cartridge> [multiplier] [--namespace NAME] [--app NAME] [--min min] [--max max]"
+    argument :cartridge, "The name of the cartridge you are scaling", ["-c", "--cartridge cartridge"]
+    argument :multiplier, "The number of instances of this cartridge you need", [], :optional => true, :hide => true
+    takes_application
+    option ["--min min", Integer], "Minimum scaling value"
+    option ["--max max", Integer], "Maximum scaling value"
+    def scale(cartridge, multiplier)
+      options.default(:min => Integer(multiplier), :max => Integer(multiplier)) if multiplier rescue raise ArgumentError, "Multiplier must be a positive integer."
+
+      raise RHC::MissingScalingValueException unless options.min || options.max
+
+      rest_app = find_app(:include => :cartridges)
+      rest_cartridge = check_cartridges(cartridge, :from => rest_app.cartridges).first
+
+      raise RHC::CartridgeNotScalableException unless rest_cartridge.scalable?
+
+      warn "This operation will run until the application is at the minimum scale and may take several minutes."
+      say "Setting scale range for #{rest_cartridge.name} ... "
+
+      cart = rest_cartridge.set_scales({
+        :scales_from => options.min,
+        :scales_to   => options.max
+      })
+
+      success "done"
+      paragraph{ display_cart(cart) }
+
+      0
+    rescue RHC::Rest::TimeoutException => e
+      raise unless e.on_receive?
+      info "The server has closed the connection, but your scaling operation is still in progress.  Please check the status of your operation via 'app show-app'."
+      1
+    end
+
+    summary 'View/manipulate storage on a cartridge'
+    syntax '<cartridge> -a app [--show] [--add|--remove|--set amount] [--namespace NAME]'
+    argument :cart_type, "The name of the cartridge", ["-c", "--cartridge cart_type"], :type => :list
+    takes_application
+    option ["--show"], "Show the current base and additional storage capacity"
+    option ["--add amount"], "Add the indicated amount to the additional storage capacity"
+    option ["--remove amount"], "Remove the indicated amount from the additional storage capacity"
+    option ["--set amount"], "Set the specified amount of additional storage capacity"
+    option ["-f", "--force"], "Force the action"
+    def storage(cartridge)
+      cartridges = Array(cartridge)
+      rest_client(:min_api => 1.3).api
+      rest_app = find_app(:include => :cartridges)
+
+      # Pull the desired action
+      #
+      actions = options.__hash__.keys & [:show, :add, :remove, :set]
+
+      # Ensure that only zero or one action was selected
+      raise RHC::AdditionalStorageArgumentsException if actions.length > 1
+
+      operation = actions.first || :show
+      amount = options.__hash__[operation]
+
+      # Perform a storage change action if requested
+      if operation == :show
+        results do
+          if cartridges.length == 0
+            display_cart_storage_list rest_app.cartridges
+          else
+            check_cartridges(cartridge, :from => rest_app.cartridges).each do |cart|
+              display_cart_storage_info cart, cart.display_name
+            end
+          end
+        end
+      else
+        raise RHC::MultipleCartridgesException,
+          'Exactly one cartridge must be specified for this operation' if cartridges.length != 1
+
+        rest_cartridge = check_cartridges(cartridge, :from => rest_app.cartridges).first
+        amount = amount.match(/^(\d+)(GB)?$/i)
+        raise RHC::AdditionalStorageValueException if amount.nil?
+
+        # If the amount is specified, find the regex match and convert to a number
+        amount = amount[1].to_i
+        total_amount = rest_cartridge.additional_gear_storage
+
+        if operation == :add
+          total_amount += amount
+        elsif operation == :remove
+          if amount > total_amount && !options.force
+            raise RHC::AdditionalStorageRemoveException
+          else
+            total_amount = [total_amount - amount, 0].max
+          end
+        else
+          total_amount = amount
+        end
+
+        say "Set storage on cartridge ... "
+        cart = rest_cartridge.set_storage(:additional_gear_storage => total_amount)
+        success "set to #{total_amount}GB"
+        paragraph{ display_cart_storage_info cart }
+      end
+
+      0
+    end
+
+    private
+      include RHC::CartridgeHelpers
+
+      def cartridge_action(cartridge, action, message=nil)
+        rest_app = find_app(:include => :cartridges)
+        rest_cartridge = check_cartridges(cartridge, :from => rest_app.cartridges).first
+        say message % [rest_cartridge.name] if message
+        result = rest_cartridge.send(action)
+        resp = [result, rest_cartridge, rest_app]
+        if message
+          success "done"
+          result.messages.each{ |s| paragraph{ say s } }
+        end
+        resp
+      end
+  end
+end