elastic_beans 0.2.0 → 0.3.0

data/lib/elastic_beans/command/set_env.rb

@@ -3,14 +3,15 @@ require "elastic_beans/error/environments_not_ready"
 
 module ElasticBeans
   module Command
+    # :nodoc: all
     class SetEnv
-      USAGE = "setenv -a APPLICATION KEY=value [KEY=value]..."
+      USAGE = "setenv KEY=[value] [KEY=[value]]..."
       DESC = "Update environment variables in the Elastic Beanstalk application"
       LONG_DESC = <<-LONG_DESC
 Update environment variables in the Elastic Beanstalk application.
-Updates all running environments and configuration templates resulting from `configure`.
+These are stored in S3 to avoid the 4096-byte limit on environment variables in Elastic Beanstalk.
+Restarts all running environments so they load the updated environment.
 
-Requires the application name.
 Requires AWS credentials to be set in the environment, i.e. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
       LONG_DESC
 

data/lib/elastic_beans/command/talk.rb

@@ -1,5 +1,6 @@
 module ElasticBeans
   module Command
+    # :nodoc: all
     class Talk
       BEANSTALK = <<-BEANSTALK
 ...........................,:~~:............................

data/lib/elastic_beans/command/version.rb

@@ -1,5 +1,6 @@
 module ElasticBeans
   module Command
+    # :nodoc: all
     class Version
       def initialize(ui:)
         @ui = ui

data/lib/elastic_beans/command.rb

@@ -8,6 +8,8 @@ require "elastic_beans/command/talk"
 require "elastic_beans/command/version"
 
 module ElasticBeans
+  # :nodoc: all
+  # @!visibility private
   module Command
   end
 end

data/lib/elastic_beans/configuration_template/base.rb

@@ -2,13 +2,19 @@ require "elastic_beans/error"
 
 module ElasticBeans
   class ConfigurationTemplate
+    # The "base" configuration template stored in the Elastic Beanstalk application.
+    # Common settings are stored here, such as networking settings and environment variables.
+    # Used as a "source configuration" when creating other configuration templates, so that new templates share the
+    # existing configuration.
     class Base < ElasticBeans::ConfigurationTemplate
+      # The solution stack used for a new application. Should not be hardcoded, but here we are.
       SOLUTION_STACK_NAME = "64bit Amazon Linux 2016.09 v2.2.0 running Ruby 2.3 (Puma)"
 
       def initialize(**args)
         super(name: "base", **args)
       end
 
+      # Overrides ElasticBeans::ConfigurationTemplate#upsert to add the solution stack to the base configuration.
       def upsert(**args)
         @option_settings = build_option_settings(**args)
         if configuration_settings_description
@@ -32,16 +38,18 @@ module ElasticBeans
 
       protected
 
+      # Constructs the common configuration for all environments.
+      # +network+, +database_url+, +secret_key_base+, +keypair+, and +iam+ are all required on first run.
       def build_option_settings(
         network: nil,
         database_url: nil,
         secret_key_base: nil,
+        keypair: nil,
+        iam: nil,
         image_id: nil,
         instance_type: nil,
-        keypair: nil,
         min_size: nil,
         max_size: nil,
-        iam: nil,
         **_
       )
         instance_profile_setting = template_option_setting(namespace: "aws:autoscaling:launchconfiguration", option_name: "IamInstanceProfile", override: instance_profile(iam))
@@ -126,6 +134,8 @@ module ElasticBeans
         network.vpc if network
       end
 
+      # :nodoc: all
+      # @!visibility private
       class MissingInstanceProfileError < ElasticBeans::Error
         def message
           "Could not find Elastic Beanstalk instance profile." \

data/lib/elastic_beans/configuration_template/exec.rb

@@ -3,6 +3,8 @@ require "elastic_beans/error"
 
 module ElasticBeans
   class ConfigurationTemplate
+    # The "exec" configuration template stored in the Elastic Beanstalk application.
+    # Settings for the exec environment are stored here, such as the exec queue URL and the logging endpoint.
     class Exec < ElasticBeans::ConfigurationTemplate::Base
       def initialize(**args)
         super(name: "exec", **args)
@@ -10,6 +12,8 @@ module ElasticBeans
 
       protected
 
+      # Constructs the configuration for the exec environment.
+      # +logging_endpoint+, if provided, must be a valid HTTPS URL.
       def build_option_settings(logging_endpoint: nil, **_)
         if logging_endpoint
           begin
@@ -36,6 +40,8 @@ module ElasticBeans
         super + settings
       end
 
+      # :nodoc: all
+      # @!visibility private
       class InvalidLoggingEndpointError < ElasticBeans::Error
         def initialize(logging_endpoint:)
           @logging_endpoint = logging_endpoint

data/lib/elastic_beans/configuration_template/scheduler.rb

@@ -1,5 +1,7 @@
 module ElasticBeans
   class ConfigurationTemplate
+    # The "scheduler" configuration template stored in the Elastic Beanstalk application.
+    # Settings for the scheduler environment are stored here.
     class Scheduler < ElasticBeans::ConfigurationTemplate::Base
       def initialize(**args)
         super(name: "scheduler", **args)
@@ -7,6 +9,8 @@ module ElasticBeans
 
       protected
 
+      # Constructs the configuration for the scheduler environment.
+      # No special options here!
       def build_option_settings(**_)
         super + [
           template_option_setting(namespace: "aws:elasticbeanstalk:application", option_name: "Application Healthcheck URL", default: "HTTP:80/"),

data/lib/elastic_beans/configuration_template/webserver.rb

@@ -2,6 +2,8 @@ require "elastic_beans/error"
 
 module ElasticBeans
   class ConfigurationTemplate
+    # The "webserver" configuration template stored in the Elastic Beanstalk application.
+    # Settings for the webserver environment are stored here.
     class Webserver < ElasticBeans::ConfigurationTemplate::Base
       def initialize(**args)
         super(name: "webserver", **args)
@@ -9,10 +11,12 @@ module ElasticBeans
 
       protected
 
-      def build_option_settings(network: nil, public_key: nil, ssl_certificate_id: nil, **_)
+      # Constructs the configuration for the webserver environment.
+      # All arguments are required on first run.
+      def build_option_settings(network: nil, public_key: nil, ssl_certificate_arn: nil, **_)
         public_key_policy_names_setting = template_option_setting(namespace: "aws:elb:policies:backendencryption", option_name: "PublicKeyPolicyNames", default: "backendkey")
         public_key_setting = template_option_setting(namespace: "aws:elb:policies:#{public_key_policy_names_setting[:value]}", option_name: "PublicKey", override: public_key)
-        ssl_certificate_setting = template_option_setting(namespace: "aws:elb:listener:443", option_name: "SSLCertificateId", override: ssl_certificate_id)
+        ssl_certificate_setting = template_option_setting(namespace: "aws:elb:listener:443", option_name: "SSLCertificateId", override: ssl_certificate_arn)
         if public_key_setting[:value].nil? || ssl_certificate_setting[:value].nil?
           raise NoEncryptionSettingsError
         end
@@ -42,13 +46,16 @@ module ElasticBeans
         network.elb_security_groups[0] if network
       end
 
+      # :nodoc: all
+      # @!visibility private
       class NoEncryptionSettingsError < ElasticBeans::Error
         def message
           require "elastic_beans/command/configure"
           <<-MESSAGE
-Missing required end-to-end encryption settings. Make sure to specify SSL certificate ID and public key.
+Missing required end-to-end encryption settings.
+Please re-run `#{command_as_string "configure"}` and make sure to specify SSL certificate ARN and internal public key.
 
-      #{$0} #{ElasticBeans::Command::Configure::USAGE}
+#{`#{$0} help configure`}
           MESSAGE
         end
       end

data/lib/elastic_beans/configuration_template/worker.rb

@@ -1,5 +1,8 @@
 module ElasticBeans
   class ConfigurationTemplate
+    # The worker configuration templates stored in the Elastic Beanstalk application.
+    # Settings for the worker environments are stored here.
+    # This class is used to construct multiple worker configuration templates, one per queue.
     class Worker < ElasticBeans::ConfigurationTemplate::Base
       attr_reader :queue
 
@@ -10,6 +13,9 @@ module ElasticBeans
 
       protected
 
+      # Constructs the configuration for the worker environments.
+      # No special arguments, the +queue+ name is stored from the initializer and is used to look up the appropriate
+      # URL.
       def build_option_settings(**_)
         super + [
           template_option_setting(namespace: "aws:elasticbeanstalk:application", option_name: "Application Healthcheck URL", default: "HTTP:80/"),

data/lib/elastic_beans/configuration_template.rb

@@ -5,11 +5,20 @@ require "elastic_beans/configuration_template/webserver"
 require "elastic_beans/configuration_template/worker"
 
 module ElasticBeans
+  # An Elastic Beanstalk saved configuration (also known as a configuration template) 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 ConfigurationTemplate
+    # :category: Internal
     WORKER_TEMPLATE_NAME_PATTERN = /\Aworker-(?<queue>\w+)\z/
 
     attr_reader :name
 
+    # Create a new configuration template of a particular +type+.
+    # See the particular subclass being created for details on arguments.
+    #
+    # Raises an error if the +type+ is not recognized.
     def self.new_by_type(type, **args)
       case type
       when "base"
@@ -27,6 +36,10 @@ module ElasticBeans
       end
     end
 
+    # Create a representation of an existing configuration template.
+    # Uses the +template_name+ to discover the appropriate type (and queue, in the case of a worker).
+    #
+    # Raises an error if the +template_name+ is not recognized.
     def self.new_from_existing(template_name, **args)
       case template_name
       when "base"
@@ -45,6 +58,7 @@ module ElasticBeans
       end
     end
 
+    # :category: Internal
     def initialize(
       name:,
       application:,
@@ -56,6 +70,7 @@ module ElasticBeans
       @elastic_beanstalk = elastic_beanstalk
     end
 
+    # :category: Internal
     def option_settings
       # do not fetch option settings from Elastic Beanstalk, because those cannot be naively used.
       # the set built in #build_option_settings is what we care about.
@@ -63,6 +78,9 @@ module ElasticBeans
       raise MissingConfigurationError
     end
 
+    # Create or update the configuration template in Elastic Beanstalk.
+    # Arguments are passed to #build_option_settings.
+    # See the appropriate subclass for what the arguments should be.
     def upsert(**args)
       @option_settings = build_option_settings(**args)
       if configuration_settings_description
@@ -86,7 +104,10 @@ module ElasticBeans
 
     protected
 
-    attr_reader :application, :elastic_beanstalk
+    # :category: Internal
+    attr_reader :application
+    # :category: Internal
+    attr_reader :elastic_beanstalk
 
     def build_option_settings(**_)
       []
@@ -123,6 +144,8 @@ module ElasticBeans
       option_setting.merge!(value: setting[:value])
     end
 
+    # :nodoc: all
+    # @!visibility private
     class InvalidConfigurationError < ElasticBeans::Error
       include Nesty::NestedError
 
@@ -139,6 +162,8 @@ module ElasticBeans
       end
     end
 
+    # :nodoc: all
+    # @!visibility private
     class MissingConfigurationError < ElasticBeans::Error
       include Nesty::NestedError
 
@@ -149,23 +174,19 @@ module ElasticBeans
       def message
         require "elastic_beans/command/configure"
         msg = <<-MESSAGE
-Some configuration must be set before creating an environment:
-
-* keypair
-* SSL configuration
-* environment variables that Rails always requires
-    * DATABASE_URL
-    * SECRET_KEY_BASE
-
-    #{$0} #{ElasticBeans::Command::Configure::USAGE}
+Some configuration is missing and must be set before creating or updating an environment.
         MESSAGE
         if nested
-          msg = "The error from AWS was \"#{nested.message}\"\n#{msg}"
+          msg << "The error from AWS was \"#{nested.message}\"\n#{msg}\n"
+        else
+          msg << "Please re-run `#{command_as_string "configure"}`.\n\n#{`#{$0} help configure`}"
         end
         msg
       end
     end
 
+    # :nodoc: all
+    # @!visibility private
     class UnknownConfigurationType < ElasticBeans::Error
       def initialize(type:)
         @type = type

data/lib/elastic_beans/dns_entry.rb

@@ -2,6 +2,8 @@ require "timeout"
 require "elastic_beans/error"
 
 module ElasticBeans
+  # :nodoc: all
+  # @!visibility private
   class DnsEntry
     DNS_NAME_PATTERN = /\A[^.]+\.[^.]+\.[^.]+\z/
 

data/lib/elastic_beans/env_vars.rb

@@ -3,6 +3,9 @@ require "aws-sdk"
 require "elastic_beans/error"
 
 module ElasticBeans
+  # Interfaces with environment variable storage for the Elastic Beanstalk application.
+  # Environment variables are stored in JSON in S3 to avoid the 4096-byte limit on environment variables in Elastic
+  # Beanstalk. An ebextension is used to inject these into the environment variables on the running instance.
   class EnvVars
     def initialize(application:, s3:)
       @application = application
@@ -13,6 +16,7 @@ module ElasticBeans
       @s3_key ||= "#{application.name}/env_vars.json"
     end
 
+    # Updates the environment variables stored in S3 by merging it with the given +env_hash+.
     def update(env_hash)
       body = env_script(existing_env_hash.merge(env_hash))
       s3.put_object(bucket: application.bucket_name, key: s3_key, body: body)
@@ -37,6 +41,8 @@ module ElasticBeans
       raise CannotAccessConfigError.new(bucket_name: application.bucket_name, key: s3_key)
     end
 
+    # :nodoc: all
+    # @!visibility private
     class CannotAccessConfigError < ElasticBeans::Error
       def initialize(bucket_name:, key:)
         @bucket_name = bucket_name

data/lib/elastic_beans/environment/exec.rb

@@ -1,14 +1,23 @@
 module ElasticBeans
   class Environment
+    # The "exec" environment for executing one-off commands.
     class Exec < ElasticBeans::Environment
-      protected
-
-      TEMPLATE_NAME = "exec"
+      # :category: Internal
+      TYPE = "exec"
+      # :category: Internal
       TIER_NAME = "Worker"
+      # :category: Internal
       TIER_TYPE = "SQS/HTTP"
 
+      # Returns "exec"
+      def type
+        TYPE
+      end
+
+      protected
+
       def template_name
-        TEMPLATE_NAME
+        type
       end
 
       def tier_name

data/lib/elastic_beans/environment/scheduler.rb

@@ -1,14 +1,23 @@
 module ElasticBeans
   class Environment
+    # The "scheduler" environment for processing periodic tasks.
     class Scheduler < ElasticBeans::Environment
-      protected
-
-      TEMPLATE_NAME = "scheduler"
+      # :category: Internal
+      TYPE = "scheduler"
+      # :category: Internal
       TIER_NAME = "Worker"
+      # :category: Internal
       TIER_TYPE = "SQS/HTTP"
 
+      # Returns "scheduler"
+      def type
+        TYPE
+      end
+
+      protected
+
       def template_name
-        TEMPLATE_NAME
+        type
       end
 
       def tier_name

data/lib/elastic_beans/environment/webserver.rb

@@ -1,14 +1,23 @@
 module ElasticBeans
   class Environment
+    # The "webserver" environment for responding to web requests.
     class Webserver < ElasticBeans::Environment
-      protected
-
-      TEMPLATE_NAME = "webserver"
+      # :category: Internal
+      TYPE = "webserver"
+      # :category: Internal
       TIER_NAME = "Webserver"
+      # :category: Internal
       TIER_TYPE = "Standard"
 
+      # Returns "webserver"
+      def type
+        TYPE
+      end
+
+      protected
+
       def template_name
-        TEMPLATE_NAME
+        type
       end
 
       def tier_name

data/lib/elastic_beans/environment/worker.rb

@@ -1,6 +1,15 @@
 module ElasticBeans
   class Environment
+    # The worker environments for background job execution.
+    # This class is used to construct multiple worker environments, one per queue.
     class Worker < ElasticBeans::Environment
+      # :category: Internal
+      TYPE = "worker"
+      # :category: Internal
+      TIER_NAME = "Worker"
+      # :category: Internal
+      TIER_TYPE = "SQS/HTTP"
+
       attr_reader :queue
 
       def initialize(name, queue:, **_)
@@ -8,13 +17,15 @@ module ElasticBeans
         @queue = queue
       end
 
-      protected
+      # Returns "worker"
+      def type
+        TYPE
+      end
 
-      TIER_NAME = "Worker"
-      TIER_TYPE = "SQS/HTTP"
+      protected
 
       def template_name
-        @template_name ||= "worker-#{queue}"
+        @template_name ||= "#{type}-#{queue}"
       end
 
       def tier_name