elastic_beans 0.2.0 → 0.3.0

data/lib/elastic_beans/environment.rb

@@ -8,14 +8,28 @@ require "elastic_beans/environment/worker"
 require "elastic_beans/error"
 
 module ElasticBeans
+  # An Elastic Beanstalk environment which may or may not exist.
+  #
+  # This is an abstract class; use the provided factories in this class or use a subclass (contained within this
+  # namespace) directly.
   class Environment
+    # :category: Internal
     TEMPLATE_NAME = "base"
+    # :category: Internal
     TIER_NAME = "Webserver"
+    # :category: Internal
     TIER_TYPE = "Standard"
+    # :category: Internal
     WORKER_TEMPLATE_NAME_PATTERN = /worker-(?<queue>\w+)/
 
     attr_reader :name
 
+    # Create a new environment of a particular +type+.
+    # See the particular subclass being created for details on arguments.
+    # The name of the environment will be the application name, joined with the +type+ (and the queue in the case of a
+    # worker).
+    #
+    # Raises an error if the +type+ is not recognized.
     def self.new_by_type(type, application:, **args)
       name = "#{application.name}-#{type}"
       case type
@@ -33,6 +47,12 @@ module ElasticBeans
       end
     end
 
+    # Create a representation of an existing environment.
+    # Uses the +environment+ to discover the appropriate type (and queue, in the case of a worker).
+    # If the +environment+ type is not recognized, the tier will be inspected. If the tier is worker, then the
+    # "default" queue will be assumed.
+    #
+    # Raises an error if the +environment+ type or tier is not recognized.
     def self.new_from_existing(environment, application:, **args)
       app_name_pattern = /#{Regexp.escape(application.name)}/
       case environment.environment_name
@@ -73,6 +93,11 @@ module ElasticBeans
       @elastic_beanstalk = elastic_beanstalk
     end
 
+    # Creates the environment in Elastic Beanstalk.
+    # Blocks until the environment is Ready.
+    #
+    # Raises an error if the configuration template for this environment does not exist.
+    # Raises an error if the environment is not healthy.
     def create(version:, tags: {})
       begin
         elastic_beanstalk.describe_configuration_settings(
@@ -104,6 +129,10 @@ module ElasticBeans
       )
     end
 
+    # Deploys the specified version label to the environment.
+    # Blocks until the environment is Ready.
+    #
+    # Raises an error if the environment is not healthy.
     def deploy_version(version_label)
       elastic_beanstalk.update_environment(
         environment_name: name,
@@ -118,6 +147,10 @@ module ElasticBeans
       raise UnhealthyEnvironmentError.new(environment_name: name, cause: e)
     end
 
+    # Restarts the environment application servers.
+    # Blocks until the environment is Ready.
+    #
+    # Raises an error if the environment is not healthy.
     def restart
       elastic_beanstalk.restart_app_server(environment_name: name)
       wait_environment(wait_status: "Updating", wait_health_status: "Info")
@@ -126,6 +159,10 @@ module ElasticBeans
       retry
     end
 
+    # Updates the environment configuration to change the minimum and maximum size of the autoscaling group.
+    # Blocks until the environment is Ready.
+    #
+    # Raises an error if the environment is not healthy.
     def scale(min_size:, max_size:)
       option_settings = [
         {namespace: "aws:autoscaling:asg", option_name: "MinSize", value: min_size},
@@ -137,12 +174,17 @@ module ElasticBeans
       )
       wait_environment(wait_status: "Updating", wait_health_status: "Info")
     rescue ::Aws::ElasticBeanstalk::Errors::InvalidParameterValue
-      raise MissingEnvironmentError.new(environment_name: name)
+      raise MissingEnvironmentError.new(environment: self, application: application)
     rescue ::Aws::ElasticBeanstalk::Errors::Throttling
       sleep 5
       retry
     end
 
+    # Updates the environment configuration with its configuration template.
+    # Handy when the configuration template has been updated and you want those changes to take effect immediately.
+    # Blocks until the environment is Ready.
+    #
+    # Raises an error if the environment is not healthy.
     def update_configuration
       elastic_beanstalk.update_environment(
         environment_name: name,
@@ -151,31 +193,42 @@ module ElasticBeans
       )
       wait_environment(wait_status: "Updating", wait_health_status: "Info")
     rescue ::Aws::ElasticBeanstalk::Errors::InvalidParameterValue
-      raise MissingEnvironmentError.new(environment_name: name)
+      raise MissingEnvironmentError.new(environment: self, application: application)
     rescue ::Aws::ElasticBeanstalk::Errors::Throttling
       sleep 5
       retry
     end
 
+    # Returns the Elastic Beanstalk CNAME, set for a webserver environment.
+    #
+    # Raises an error if the environment does not exist.
     def cname
       environment = environment_description
       unless environment
-        raise MissingEnvironmentError.new(environment_name: name)
+        raise MissingEnvironmentError.new(environment: self, application: application)
       end
       environment.cname
     end
 
+    # Returns the status of the environment in Elastic Beanstalk.
+    #
+    # Raises an error if the environment does not exist.
     def status
       environment = environment_description
       unless environment
-        raise MissingEnvironmentError.new(environment_name: name)
+        raise MissingEnvironmentError.new(environment: self, application: application)
       end
       environment.status
     end
 
     protected
 
-    attr_reader :application, :version, :elastic_beanstalk
+    # :category: Internal
+    attr_reader :application
+    # :category: Internal
+    attr_reader :version
+    # :category: Internal
+    attr_reader :elastic_beanstalk
 
     def environment_description
       elastic_beanstalk.describe_environments(
@@ -245,38 +298,39 @@ module ElasticBeans
       )
     end
 
+    # :nodoc: all
+    # @!visibility private
     class MissingConfigurationError < ElasticBeans::Error
       def message
         require "elastic_beans/command/configure"
         <<-MESSAGE
-Some configuration must be set before creating an environment:
+Some configuration is missing and must be set before creating an environment.
+Please re-run `#{command_as_string "configure"}`.
 
-* keypair
-* SSL configuration
-* environment variables that Rails always requires
-    * DATABASE_URL
-    * SECRET_KEY_BASE
-
-    #{$0} #{ElasticBeans::Command::Configure::USAGE}
+#{`#{$0} help configure`}
         MESSAGE
       end
     end
 
+    # :nodoc: all
+    # @!visibility private
     class MissingEnvironmentError < ElasticBeans::Error
-      def initialize(environment_name:)
-        @environment_name = environment_name
+      def initialize(environment:, application:)
+        @environment = environment
+        @application = application
       end
 
       def message
         require "elastic_beans/command/create"
         <<-MESSAGE
-Environment `#{@environment_name}' does not exist. Try creating it!
-
-    #{$0} #{ElasticBeans::Command::Create::USAGE}
+Environment `#{@environment.name}' does not exist.
+Please run `#{command_as_string "create #{@environment.type} -a #{@application.name}"}`.
         MESSAGE
       end
     end
 
+    # :nodoc: all
+    # @!visibility private
     class UnhealthyEnvironmentError < ElasticBeans::Error
       include Nesty::NestedError
 
@@ -296,6 +350,8 @@ Environment `#{@environment_name}' does not exist. Try creating it!
       end
     end
 
+    # :nodoc: all
+    # @!visibility private
     class UnknownEnvironmentType < ElasticBeans::Error
       def initialize(environment_type:)
         @environment_type = environment_type

data/lib/elastic_beans/error/environments_not_ready.rb

@@ -1,5 +1,7 @@
 require "elastic_beans/error"
 
+# :nodoc: all
+# @!visibility private
 class EnvironmentsNotReady < ElasticBeans::Error
   def initialize(environments:)
     @environments = environments

data/lib/elastic_beans/error.rb

@@ -1,6 +1,7 @@
 require "shellwords"
 
 module ElasticBeans
+  # The superclass for errors raised within ElasticBeans.
   class Error < StandardError
     protected
 

data/lib/elastic_beans/exec/init.rb

@@ -3,6 +3,8 @@ require "fileutils"
 require "net/http"
 require "uri"
 
+# :nodoc: all
+# @!visibility private
 class Init
   LOGFILE = "/var/log/elastic_beans_exec.log"
   PIDFILE = "/var/run/elastic_beans_exec.pid"

data/lib/elastic_beans/exec/sqs_consumer.rb

@@ -2,6 +2,8 @@ require "json"
 require "net/http"
 require "uri"
 
+# :nodoc: all
+# @!visibility private
 class SQSConsumer
   def initialize(logfile:, queue_url:, sqs:, logging_endpoint: nil)
     @logfile = logfile

data/lib/elastic_beans/network.rb

@@ -1,6 +1,7 @@
 require "elastic_beans/aws/cloudformation_stack"
 
 module ElasticBeans
+  # The networking CloudFormation stack provided to configure.
   class Network
     APPLICATION_SECURITY_GROUP_KEY = "ApplicationSecurityGroup"
     APPLICATION_SUBNET_KEY = "ApplicationSubnet"

data/lib/elastic_beans/rack/exec.rb

@@ -4,6 +4,11 @@ require "action_dispatch"
 
 module ElasticBeans
   module Rack
+    # A middleware that can convert specially-crafted paths into commands and enqueue them for execution using
+    # ElasticBeans::Application#enqueue_command.
+    # Load it in your Rails application so the "scheduler" environment enqueues commands for execution.
+    #
+    # Only accepts localhost requests from `aws-sqsd`.
     class Exec
       FAILURE = ['500', {'Content-type' => 'text/plain'}, [""]]
       SUCCESS = ['200', {'Content-type' => 'text/plain'}, [""]]

data/lib/elastic_beans/ui.rb

@@ -1,4 +1,6 @@
 module ElasticBeans
+  # :nodoc: all
+  # @!visibility private
   class UI
     attr_reader :stdout, :stderr
 

data/lib/elastic_beans/version.rb

@@ -1,3 +1,3 @@
 module ElasticBeans
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elastic_beans
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Adam Stegman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-12 00:00:00.000000000 Z
+date: 2016-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk