capistrano-data_plane_api 0.1.4 → 0.2.0

data/lib/capistrano/data_plane_api/deploy/args.rb

@@ -1,5 +1,7 @@
+# typed: true
 # frozen_string_literal: true
 
+require 'booleans/kernel_extension'
 require 'optparse'
 
 module Capistrano
@@ -9,11 +11,9 @@ module Capistrano
       # passed to the deployment script and saves them in
       # an object.
       class Args
-        # @return [Array<String>]
         PRINTABLE_ENV_VARS = %w[BRANCH NO_MIGRATIONS].freeze
 
-        # @param options [Array, nil]
-        # @return [self]
+        #: (Array[untyped]?) -> instance
         def self.parse(options = nil) # rubocop:disable Metrics/MethodLength, Style/ClassMethodsDefinitions
           args = new
 
@@ -28,7 +28,7 @@ module Capistrano
             parser.on(
               '-c',
               '--current',
-              'Deploy from the currently checked out branch'
+              'Deploy from the currently checked out branch',
             ) do |_val|
               args.branch = `git branch --show-current`.strip
               ::ENV['BRANCH'] = args.branch
@@ -37,22 +37,33 @@ module Capistrano
             parser.on(
               '-t',
               '--test',
-              'Show the commands that would be executed but do not carry out the deployment'
+              'Show the commands that would be executed but do not carry out the deployment',
             ) do |val|
               args.test = val
             end
 
+            parser.on(
+              '-C',
+              '--check',
+              'Test deployment dependencies. ' \
+              'Checks things like directory permissions, necessary utilities, ' \
+              'HaProxy backends and servers',
+            ) do |val|
+              args.check = val
+              args.rake = 'deploy:check' if val
+            end
+
             parser.on(
               '-g GROUP',
               '--group=GROUP',
-              'Deploy the code to every server in the passed HAProxy backend/group'
+              'Deploy the code to every server in the passed HAProxy backend/group',
             ) do |val|
               args.group = val
             end
 
             parser.on(
               '--no-haproxy',
-              'Do not modify the state of any server in HAProxy'
+              'Do not modify the state of any server in HAProxy',
             ) do |val|
               args.no_haproxy = val
               ::ENV['NO_HAPROXY'] = 'true'
@@ -60,7 +71,7 @@ module Capistrano
 
             parser.on(
               '--force-haproxy',
-              'Ignore the current state of servers in HAProxy'
+              'Ignore the current state of servers in HAProxy',
             ) do |val|
               args.force_haproxy = val
               ::ENV['FORCE_HAPROXY'] = 'true'
@@ -69,7 +80,7 @@ module Capistrano
             parser.on(
               '-o ONLY',
               '--only=ONLY',
-              'Deploy the code only to the passed servers in the same order'
+              'Deploy the code only to the passed servers in the same order',
             ) do |val|
               next unless val
 
@@ -79,7 +90,7 @@ module Capistrano
             parser.on(
               '-H',
               '--haproxy-config',
-              'Show the current HAProxy configuration'
+              'Show the current HAProxy configuration',
             ) do |val|
               next unless val
 
@@ -91,7 +102,7 @@ module Capistrano
             parser.on(
               '-S',
               '--haproxy-state',
-              'Show the current HAProxy state'
+              'Show the current HAProxy state',
             ) do |val|
               next unless val
 
@@ -103,7 +114,7 @@ module Capistrano
             parser.on(
               '-T',
               '--tasks',
-              'Print a list of all available deployment Rake tasks'
+              'Print a list of all available deployment Rake tasks',
             ) do |val|
               next unless val
 
@@ -117,7 +128,7 @@ module Capistrano
             parser.on(
               '-r RAKE',
               '--rake=RAKE',
-              'Carry out a particular Rake task on the server'
+              'Carry out a particular Rake task on the server',
             ) do |val|
               next unless val
 
@@ -132,7 +143,7 @@ module Capistrano
             parser.on(
               '-b BRANCH',
               '--branch=BRANCH',
-              'Deploy the code from the passed Git branch'
+              'Deploy the code from the passed Git branch',
             ) do |val|
               args.branch = val
               ::ENV['BRANCH'] = val
@@ -140,7 +151,7 @@ module Capistrano
 
             parser.on(
               '--no-migrations',
-              'Do not carry out migrations'
+              'Do not carry out migrations',
             ) do |val|
               args.no_migrations = val
               ::ENV['NO_MIGRATIONS'] = 'true'
@@ -153,56 +164,79 @@ module Capistrano
           args
         end
 
-        # @return [String, nil] Git branch that the code will be deployed to
+        # Git branch that the code will be deployed to
+        #
+        #: String?
         attr_accessor :branch
-        # @return [Boolean] Runs in test mode if true, only prints commands without executing them
+
+        # Runs in test mode if true, only prints commands without executing them
+        #
+        #: bool
         attr_accessor :test
-        # @return [String, nil] Name of the HAProxy server group/backend
+
+        # Name of the HAProxy server group/backend
+        #
+        #: String?
         attr_accessor :group
-        # @return [Boolean]
+
+        #: bool
         attr_accessor :no_haproxy
-        # @return [Boolean]
+
+        #: bool
         attr_accessor :no_migrations
-        # @return [Boolean]
+
+        #: bool
         attr_accessor :force_haproxy
-        # @return [Array<String>, nil] Ordered list of servers to which the app will be deployed
+
+        # Ordered list of servers to which the app will be deployed
+        #
+        #: Array[String]?
         attr_accessor :only
-        # @return [String, nil] Rake command that will be called remotely (`deploy` by default)
+
+        # Rake command that will be called remotely (`deploy` by default)
+        #
+        #: String?
         attr_accessor :rake
-        # @return [String, nil] Name of the deployment stage/server
+
+        # Name of the deployment stage/server
+        #
+        #: String?
         attr_accessor :stage
 
+        # Checks deployment dependencies
+        #: bool
+        attr_accessor :check
+
         alias test? test
 
+        #: -> void
         def initialize
           @rake = 'deploy'
         end
 
-        # @return [Boolean]
+        #: -> bool
         def only?
           return false if @only.nil?
 
           @only.any?
         end
 
-        # @return [void]
+        #: -> void
         def prepare_if_one_server
           return unless one_server?
 
-          server, backend = ::Capistrano::DataPlaneApi.find_server_and_backend(@stage)
-          @only = [server['name']]
-          @group = backend['name']
+          server, backend = ::Capistrano::DataPlaneApi.find_server_and_backend(T.must(@stage))
+          @only = [T.must(server.name)]
+          @group = backend.name
         end
 
-        # @param stage [String, Symbol, nil]
-        # @return [String]
+        #: (String | Symbol | nil) -> String
         def deploy_command(stage = nil)
           used_stage = stage || self.stage
           "cap #{used_stage} #{rake}"
         end
 
-        # @param stage [String, Symbol, nil]
-        # @return [String]
+        #: (String | Symbol | nil) -> String
         def humanized_deploy_command(stage = nil)
           result = ::String.new
           PRINTABLE_ENV_VARS.each do |env_var_name|
@@ -215,24 +249,21 @@ module Capistrano
           result
         end
 
-        # @param key [Symbol, String]
-        # @return [Object]
+        #: (Symbol | String) -> Object
         def [](key)
           public_send(key)
         end
 
-        # @param key [Symbol, String]
-        # @param val [Object]
-        # @return [Object]
+        #: (Symbol | String, Object) -> Object
         def []=(key, val)
           public_send("#{key}=", val)
         end
 
         private
 
-        # @return [Boolean]
+        #: -> bool
         def one_server?
-          @stage && @group.nil?
+          Boolean(@stage && @group.nil?)
         end
       end
     end

data/lib/capistrano/data_plane_api/deploy/deployment_stats.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 require_relative 'helper'
@@ -7,58 +8,59 @@ module Capistrano
     module Deploy
       # Represents a collection of deployment stats for particular servers.
       class DeploymentStats
-        # @return [Capistrano::DataPlaneApi::Configuration::Backend, nil]
-        #   Configuration data of a particular HAProxy backend
+        # Configuration data of a particular HAProxy backend
+        #
+        #: Capistrano::DataPlaneApi::Configuration::Backend?
         attr_accessor :backend
 
-        # @return [Time, nil]
+        #: Time?
         attr_accessor :start_time
 
-        # @return [Time, nil]
+        #: Time?
         attr_accessor :end_time
 
-        # @return [Hash{String => Deploy::ServerStats}]
+        #: Hash[String, Deploy::ServerStats]
         attr_accessor :server_stats
 
-        # @return [Boolean]
-        attr_accessor :success
+        #: Symbol
+        attr_accessor :state
 
+        #: -> void
         def initialize
           @backend = nil
           @start_time = nil
           @end_time = nil
-          @success = true
-          @server_stats = {}
+          @state = T.let(:pending, Symbol)
+          @server_stats = T.let({}, T::Hash[String, Deploy::ServerStats])
+          @seconds = T.let(nil, T.nilable(Integer))
+          @update_states_in_stats = T.let(false, T::Boolean)
         end
 
-        # @param key [String]
-        # @return [Deploy::ServerStats]
+        #: (String) -> Deploy::ServerStats
         def [](key)
-          @server_stats[key]
+          @server_stats.fetch(key)
         end
 
-        # @param key [String]
-        # @param val [Deploy::ServerStats]
+        #: (String, Deploy::ServerStats) -> void
         def []=(key, val)
           @server_stats[key] = val
         end
 
-        # @param servers [Array<Capistrano::DataPlaneApi::Configuration::Server>, Capistrano::DataPlaneApi::Configuration::Server]
-        # @return [void]
+        #: (Array[Configuration::Server] | Configuration::Server) -> void
         def create_stats_for(servers)
           servers = *servers
 
           servers.each do |server|
-            @server_stats[server.name] = ServerStats.new(server.name, @backend.name)
+            @server_stats[server.name] = ServerStats.new(server.name, T.must(@backend&.name))
           end
         end
 
-        # @return [String]
+        #: -> String
         def to_s
           update_states_in_stats
 
           time_string = COLORS.bold.yellow ::Time.now.to_s
-          if success
+          if state == :success
             state = COLORS.bold.green 'Successful'
             time_sentence = 'took'
           else
@@ -68,8 +70,8 @@ module Capistrano
 
           result = ::String.new
           result << "\n#{time_string}\n\n"
-          result << "#{state} deployment to #{::Capistrano::DataPlaneApi.humanize_backend_name(@backend)}\n"
-          result << "  #{time_sentence} #{Helper.humanize_time(seconds)}\n"
+          result << "#{state} deployment to #{::Capistrano::DataPlaneApi.humanize_backend_name(T.must(@backend))}\n"
+          result << "  #{time_sentence} #{Helper.humanize_time(T.must(seconds))}\n"
 
           @server_stats.each_value do |stats|
             result << "\n#{stats}"
@@ -78,14 +80,15 @@ module Capistrano
           result
         end
 
-        # @return [Integer, nil] How much time has the deployment taken
+        # How much time has the deployment taken
+        #: -> Integer?
         def seconds
-          @seconds ||= Helper.seconds_since(@start_time, to: @end_time)
+          @seconds ||= Helper.seconds_since(T.must(@start_time), to: T.must(@end_time))
         end
 
         private
 
-        # @return [void]
+        #: -> void
         def update_states_in_stats
           return if @update_states_in_stats
 
@@ -93,9 +96,10 @@ module Capistrano
           update_states_in_stats!
         end
 
+        #: -> void
         def update_states_in_stats!
           server_states = begin
-            ::Capistrano::DataPlaneApi.get_backend_servers_settings(@backend.name).body
+            ::Capistrano::DataPlaneApi.get_backend_servers_settings(T.must(@backend&.name)).body
           rescue Error
             nil
           end

data/lib/capistrano/data_plane_api/deploy/group.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Capistrano
@@ -7,28 +8,30 @@ module Capistrano
       # in a particular HAProxy backend/group.
       class Group
         class << self
-          # @param args [DeployArgs]
-          # @return [void]
+          #: (Args) -> Symbol
           def call(args)
             new(args).call
           end
         end
 
-        # @param args [DeployArgs]
+        #: (Args) -> void
         def initialize(args)
           @args = args
-          @deployment_stats = DeploymentStats.new
+          @deployment_stats = T.let(DeploymentStats.new, DeploymentStats)
+          @backend = T.let(nil, T.nilable(Configuration::Backend))
+          @servers = T.let(nil, T.nilable(T::Array[Configuration::Server]))
         end
 
-        # @return [Boolean, nil] Whether the deployment has been successful
+        # Whether the deployment has been successful
+        #: -> Symbol
         def call
-          @backend = ::Capistrano::DataPlaneApi.find_backend(@args.group)
+          @backend = ::Capistrano::DataPlaneApi.find_backend(T.must(@args.group))
           @servers = servers(@backend)
           start_deployment
 
-          success = nil
-          @servers.each do |server|
-            server_stats = @deployment_stats[server.name]
+          state = :pending
+          @servers&.each do |server|
+            server_stats = @deployment_stats[T.must(server.name)]
             puts COLORS.bold.blue("Deploying the app to `#{server.stage}` -- `#{@backend.name}:#{server.name}`")
 
             puts @args.humanized_deploy_command(server.stage)
@@ -38,27 +41,34 @@ module Capistrano
 
             server_stats.start_time = ::Time.now
             deploy_command = @args.deploy_command(server.stage)
-            success = system deploy_command
+            case system deploy_command
+            when true
+              state = :success
+            when false
+              state = :failed
+            when nil
+              state = :pending
+            end
 
             server_stats.end_time = ::Time.now
-            server_stats.success = success
+            server_stats.state = state
 
-            next if success
+            next if state == :success
 
             puts COLORS.bold.red("Command `#{deploy_command}` failed")
             break
           end
 
-          return if @args.test?
+          return :pending if @args.test?
 
-          finish_deployment(success: success)
+          finish_deployment(state: state)
           print_summary
-          success
+          state
         end
 
         private
 
-        # @return [void]
+        #: -> void
         def start_deployment
           @deployment_stats.tap do |d|
             d.start_time = ::Time.now
@@ -67,25 +77,24 @@ module Capistrano
           end
         end
 
-        # @param success [Boolean]
-        def finish_deployment(success: true)
+        #: (Symbol) -> void
+        def finish_deployment(state: :success)
           @deployment_stats.end_time = ::Time.now
-          @deployment_stats.success = success
+          @deployment_stats.state = state
         end
 
-        # @return [void]
+        #: -> void
         def print_summary
           puts @deployment_stats
         end
 
-        # @param backend [Capistrano::DataPlaneApi::Configuration::Backend]
-        # @return [Array<Capistrano::DataPlaneApi::Configuration::Server>]
+        #: (Configuration::Backend) -> Array[Configuration::Server]?
         def servers(backend)
           return backend.servers unless @args.only?
 
           chosen_servers = []
-          @args.only.each do |current_server_name|
-            backend.servers.each do |server|
+          @args.only&.each do |current_server_name|
+            backend.servers&.each do |server|
               next unless server.name == current_server_name || server.stage == current_server_name
 
               chosen_servers << server

data/lib/capistrano/data_plane_api/deploy/helper.rb

@@ -1,3 +1,4 @@
+# typed: true
 # frozen_string_literal: true
 
 module Capistrano
@@ -8,8 +9,7 @@ module Capistrano
       module Helper
         extend self
 
-        # @param seconds [Integer]
-        # @return [String]
+        #: (Integer) -> String
         def humanize_time(seconds)
           hours = seconds / 3600
           rest_seconds = seconds - (hours * 3600)
@@ -39,9 +39,7 @@ module Capistrano
         # Calculate how many seconds have passed
         # since the given point in time.
         #
-        # @param time [Time]
-        # @param to [Time]
-        # @return [Integer]
+        #: (Time, Time) -> Integer
         def seconds_since(time, to: ::Time.now)
           (to - time).to_i
         end