capistrano-cable 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e1a47bf59656cff6458c37414595512d8fee87ad11ce021fa959f55d8ff8d96
-  data.tar.gz: 8760656360a1e0e92413131b47e125f0ae0d00c7421896955644ca210767f502
+  metadata.gz: b954ccd5824a22b8706c42c8e3935ad46d6bc57c2adf3a5ddb28bd75b1908b5a
+  data.tar.gz: c405063b580674e99877061c12476db5ee5300a23814adae59ba624797c45727
 SHA512:
-  metadata.gz: 2603c3875d4e470ef7c27d3360f7904584add2ca644f209d74d04eab98411c3f802ba91f8df1949965ebf809cea3c21a921562a4fc271304ad79aeee19abde7a
-  data.tar.gz: f4f5d9d77e6800ee48a958519d7554e906fefbbcb5b9291dfb293ff8adfddb0cc07f71d744bae5173fbe4591b6e42fa776496cee9f3a00c59dab6408ed169a22
+  metadata.gz: 4c33e8732a80681cbbc2d2fbe6a0ddf3c509321a45be8ce6668bdd9ecacdd3c8eca8c7330c74500f6e7a684d478566a998a86d24eddd4c0b97072c9527bda024
+  data.tar.gz: 6712410d5ae24f5744e966bf800294784a72e9c998170105ce885e9a4381252fef2e511d3b146e7cb2630e6eec2e94d56d0382b722e59d6316ca736856aa31a0

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-15
+
+- Replace `cable_port`, `cable_ssl_certificate` and `cable_ssl_certificate_key` with a single `cable_bind` option, defaulting to a unix socket in the shared directory
+- Enable systemd socket activation by default, so the listening socket survives a restart of the server
+- Install the systemd units at every deploy, before restarting the server
+- Stop the deploy on `deploy:starting` when a removed option is still set, instead of moving the server somewhere else in silence
+
 ## [0.1.0] - 2024-07-05
 
 - Initial release

data/README.md

@@ -44,9 +44,8 @@ Many options are available to customize the cable server configuration. Here are
 ```ruby
 # config/deploy.rb or config/deploy/<stage>.rb
 set :cable_role, :web
-set :cable_port, 29292
-# set :cable_ssl_certificate
-# set :cable_ssl_certificate_key
+set :cable_bind, -> { "unix://#{shared_path.join("tmp", "sockets", "cable.sock")}" }
+# set :cable_limit_nofile, 65536 # optional, to customize if `Errno::EMFILE: Too many open files` happens
 set :cable_rackup_file, 'cable/config.ru'
 set :cable_dir, -> { File.join(release_path, "cable") }
 set :cable_pidfile, -> { File.join(shared_path, "tmp", "pids", "cable.pid") }
@@ -54,14 +53,66 @@ set :cable_env, -> { fetch(:rack_env, fetch(:rails_env, fetch(:stage))) }
 set :cable_access_log, -> { File.join(shared_path, "log", "cable.access.log") }
 set :cable_error_log, -> { File.join(shared_path, "log", "cable.error.log") }
 set :cable_phased_restart, -> { true }
+set :cable_enable_socket_service, true
 set :cable_service_unit_env_files, -> { fetch(:service_unit_env_files, []) }
 set :cable_service_unit_env_vars, -> { fetch(:service_unit_env_vars, []) }
 set :cable_service_templates_path, fetch(:service_templates_path, "config/deploy/templates")
 ```
 See Capistrao::Cable::Systemd#set_defaults for more details.
 
-To enable SSL, set the `cable_ssl_certificate` and `cable_ssl_certificate_key` options.
-The both are required to enable SSL.
+### Where the server listens
+
+`cable_bind` is the only option about listening. It takes a Puma bind string, or
+an array of them:
+
+```ruby
+set :cable_bind, "unix:///home/myapp/public_html/shared/tmp/sockets/cable.sock"
+set :cable_bind, "tcp://0.0.0.0:28090"
+set :cable_bind, "ssl://0.0.0.0:28090?cert=/path/cert.pem&key=/path/key.pem"
+```
+
+By default the server listens on a unix socket in the shared directory, which
+keeps it unreachable from the outside and saves picking a free port on every
+host. The socket directory is created by `cable:install`; the web server in
+front then proxies to that socket path instead of a host and port, the way it
+proxies to any other unix socket.
+
+A unix socket path has to be absolute: write `unix:///path/to/cable.sock`, with
+three slashes.
+
+### Socket activation
+
+With `cable_enable_socket_service` (enabled by default), systemd owns the
+listening socket and hands it over to Puma. The socket stays open while the
+service restarts, so connections are queued in the backlog instead of being
+refused, and the server is started on the first request if it is not running
+yet.
+
+The `ListenStream` of the socket unit is the address of each `cable_bind`: Puma
+matches the socket it receives against its own binds, so both are always
+written from the same option.
+
+## Migrating to 0.2.0
+
+`cable_port`, `cable_ssl_certificate` and `cable_ssl_certificate_key` are gone,
+replaced by `cable_bind`. A deploy that still sets one of them stops on
+`deploy:starting`, before anything is uploaded, with a message telling what to
+write instead. `cable:install` refuses to run too, for setups that install the
+plugin without its hooks.
+
+Nothing else to do on the Capistrano side: the systemd units are now installed
+at every deploy, before the server is restarted, so upgrading the gem and
+deploying is enough to move an app to its socket.
+
+The one manual step is the web server, which has to proxy to the socket instead
+of the port. If both can't be changed in the same window, keep the port for
+now:
+
+```ruby
+set :cable_bind, "tcp://0.0.0.0:28090"
+```
+
+and move to the default socket in a later deploy.
 
 ## Development
 

data/lib/capistrano/cable/bind.rb

@@ -1,34 +1,38 @@
+# frozen_string_literal: true
+
 module Capistrano
   module Cable
-    class Bind < Struct.new(:full_address, :kind, :address)
-      def unix?
-        kind == :unix
-      end
+    # A Puma bind, as given to `set :cable_bind`:
+    #
+    #   unix:///home/app/shared/tmp/sockets/cable.sock
+    #   tcp://0.0.0.0:28090
+    #   ssl://0.0.0.0:28090?cert=/path/cert.pem&key=/path/key.pem
+    #
+    # `address` is the part systemd needs for its `ListenStream`: Puma matches
+    # the socket handed over by systemd against its own binds by address, so
+    # both have to be written exactly the same way.
+    class Bind
+      SCHEMES = %w[tcp ssl unix].freeze
 
-      def ssl?
-        kind == :ssl
-      end
+      attr_reader :address
 
-      def tcp
-        kind == :tcp || ssl?
-      end
+      def initialize(bind)
+        @bind = bind.to_s
+        scheme, rest = @bind.split(":", 2)
+        @scheme = scheme
+        @address = rest.to_s.delete_prefix("//").split("?").first.to_s
 
-      def local
-        if unix?
-          self
-        else
-          self.class.new(
-            localize_address(full_address),
-            kind,
-            localize_address(address)
-          )
-        end
+        raise ArgumentError, "Unsupported cable_bind #{@bind.inspect}, expected #{SCHEMES.join("://, ")}://" unless SCHEMES.include?(@scheme)
+        raise ArgumentError, "Empty address in cable_bind #{@bind.inspect}" if @address.empty?
+        raise ArgumentError, "cable_bind #{@bind.inspect} needs an absolute socket path" if unix? && !@address.start_with?("/")
       end
 
-      private
+      def unix?
+        @scheme == "unix"
+      end
 
-      def localize_address(address)
-        address.gsub(/0\.0\.0\.0(.+)/, "127.0.0.1\\1")
+      def to_s
+        @bind
       end
     end
   end

data/lib/capistrano/cable/systemd.rb

@@ -1,10 +1,23 @@
 require "capistrano/plugin"
+require "erb"
+require "stringio"
 require_relative "bind"
 
 module Capistrano
   module Cable
     class Systemd < Capistrano::Plugin
+      # Options dropped in favour of :cable_bind. They are still looked up so
+      # that a stale setting stops the deploy before it does anything, instead
+      # of silently moving the server to another address.
+      REMOVED_OPTIONS = {
+        cable_port: 'set :cable_bind, "tcp://0.0.0.0:<port>"',
+        cable_ssl_certificate: 'set :cable_bind, "ssl://0.0.0.0:<port>?cert=<cert>&key=<key>"',
+        cable_ssl_certificate_key: 'set :cable_bind, "ssl://0.0.0.0:<port>?cert=<cert>&key=<key>"'
+      }.freeze
+
       def register_hooks
+        before "deploy:starting", "cable:check"
+        after "deploy:finished", "cable:install"
         after "deploy:finished", "cable:smart_restart"
       end
 
@@ -14,8 +27,8 @@ module Capistrano
 
       def set_defaults
         set_if_empty :cable_role, :web
-        set_if_empty :cable_port, 29292
-        set_if_empty :cable_rackup_file, 'cable/config.ru'
+        set_if_empty :cable_bind, -> { "unix://#{shared_path.join("tmp", "sockets", "cable.sock")}" }
+        set_if_empty :cable_rackup_file, "cable/config.ru"
         set_if_empty :cable_dir, -> { File.join(release_path, "cable") }
         set_if_empty :cable_pidfile, -> { File.join(shared_path, "tmp", "pids", "cable.pid") }
         set_if_empty :cable_env, -> { fetch(:rack_env, fetch(:rails_env, fetch(:stage))) }
@@ -25,9 +38,8 @@ module Capistrano
 
         set_if_empty :cable_systemctl_bin, -> { fetch(:systemctl_bin, "/bin/systemctl") }
         set_if_empty :cable_service_unit_name, -> { "#{fetch(:application)}_cable_#{fetch(:stage)}" }
-        set_if_empty :cable_enable_socket_service, false
+        set_if_empty :cable_enable_socket_service, true
         set_if_empty :cable_socket_unit_name, -> { "#{fetch(:application)}_cable_#{fetch(:stage)}.socket" }
-        # set_if_empty :cable_bind, -> { "unix:/tmp/#{fetch(:app_domain)}.sock" }
 
         set_if_empty :cable_service_unit_env_files, -> { fetch(:service_unit_env_files, []) }
         set_if_empty :cable_service_unit_env_vars, -> { fetch(:service_unit_env_vars, []) }
@@ -47,6 +59,13 @@ module Capistrano
         append :bundle_bins, "puma", "pumactl"
       end
 
+      def check_removed_options!
+        messages = REMOVED_OPTIONS.select { |option, _| fetch(option) }.map do |option, replacement|
+          ":#{option} is not supported anymore, use :cable_bind instead (#{replacement})"
+        end
+        raise ArgumentError, messages.join("\n") if messages.any?
+      end
+
       def expanded_bundle_command
         backend.capture(:echo, SSHKit.config.command_map[:bundle]).strip
       end
@@ -72,7 +91,7 @@ module Capistrano
 
       def sudo_if_needed(*command)
         if fetch(:cable_systemctl_user) == :system
-          backend.sudo command.map(&:to_s).join(" ")
+          backend.sudo command.join(" ")
         else
           backend.execute(*command)
         end
@@ -103,12 +122,6 @@ module Capistrano
           role.user
       end
 
-      def cable_bind
-        Array(fetch(:cable_bind)).collect do |bind|
-          "bind '#{bind}'"
-        end.join("\n")
-      end
-
       def service_unit_type
         ## Jruby don't support notify
         return "simple" if RUBY_ENGINE == "jruby"
@@ -120,11 +133,7 @@ module Capistrano
       def puma_options
         options = []
         options << "--no-config"
-        if fetch(:cable_ssl_certificate) && fetch(:cable_ssl_certificate_key)
-          options << "--bind 'ssl://0.0.0.0:#{fetch(:cable_port)}?key=#{fetch(:cable_ssl_certificate_key)}&cert=#{fetch(:cable_ssl_certificate)}'"
-        else
-          options << "--port #{fetch(:cable_port)}"
-        end
+        cable_binds.each { |bind| options << "--bind '#{bind}'" }
         options << "--environment #{fetch(:cable_env)}"
         options << "--pidfile #{fetch(:cable_pidfile)}" if fetch(:cable_pidfile)
         options << "--threads #{fetch(:cable_threads)}" if fetch(:cable_threads)
@@ -156,10 +165,11 @@ module Capistrano
       end
 
       def cable_binds
-        Array(fetch(:cable_bind)).map do |m|
-          etype, address = /(tcp|unix|ssl):\/{1,2}(.+)/.match(m).captures
-          Bind.new(m, etype.to_sym, address)
-        end
+        Array(fetch(:cable_bind)).map { |bind| Bind.new(bind) }
+      end
+
+      def cable_socket_dirs
+        cable_binds.select(&:unix?).map { |bind| File.dirname(bind.address) }.uniq
       end
     end
   end

data/lib/capistrano/cable/version.rb

@@ -2,6 +2,6 @@
 
 module Capistrano
   module Cable
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/lib/capistrano/tasks/systemd.rake

@@ -3,8 +3,14 @@
 git_plugin = self
 
 namespace :cable do
+  desc "Check Cable configuration"
+  task :check do
+    git_plugin.check_removed_options!
+  end
+
   desc "Install Cable systemd service"
   task :install do
+    git_plugin.check_removed_options!
     on roles(fetch(:cable_role)) do |role|
       upload_compiled_template = lambda do |template_name, unit_filename|
         git_plugin.upload_template_cable template_name, "#{fetch(:tmp_dir)}/#{unit_filename}", role
@@ -17,6 +23,8 @@ namespace :cable do
         end
       end
 
+      git_plugin.cable_socket_dirs.each { |dir| execute :mkdir, "-p", dir }
+
       upload_compiled_template.call("cable.service", "#{fetch(:cable_service_unit_name)}.service")
 
       if fetch(:cable_enable_socket_service)

data/lib/capistrano/templates/cable.service.erb

@@ -12,11 +12,12 @@
 [Unit]
 Description=Cable HTTP Server for <%= "#{fetch(:application)} (#{fetch(:stage)})" %>
 <%= "Requires=#{fetch(:cable_socket_unit_name)}" if fetch(:cable_enable_socket_service) %>
-After=syslog.target network.target
+After=syslog.target network.target<%= " #{fetch(:cable_socket_unit_name)}" if fetch(:cable_enable_socket_service) %>
 
 [Service]
 Type=<%= service_unit_type %>
 WatchdogSec=30
+<%="LimitNOFILE=#{fetch(:cable_limit_nofile)}" if fetch(:cable_limit_nofile) %>
 <%="User=#{cable_user(@role)}" if fetch(:cable_systemctl_user) == :system %>
 <%="PIDFile=#{fetch(:cable_pidfile)}" if fetch(:cable_pidfile) %>
 WorkingDirectory=<%= current_path %>

data/lib/capistrano/templates/cable.socket.erb

@@ -3,17 +3,19 @@ Description=Cable Puma HTTP Server Accept Sockets for <%= "#{fetch(:application)
 
 [Socket]
 <% cable_binds.each do |bind| -%>
-<%= "ListenStream=#{bind.local.address}" %>
+ListenStream=<%= bind.address %>
 <% end -%>
 
 # Don't let systemd accept the request, wait for Cable to do that.
 # Systemd will start the cable service upon first request if it wasn't started.
 #
-# You might also want to set your Nginx upstream to have a fail_timeout large enough to accomodate your app's
-# startup time.
+# Systemd keeps the socket open across restarts of the service: connections are
+# queued in the backlog instead of being refused while Cable boots.
+#
+# You might also want to give the web server in front a connection timeout large
+# enough to accommodate your app's startup time.
 Accept=no
-<%= "NoDelay=true" if fetch(:cable_systemctl_user) == :system %>
-ReusePort=true
+<%= "NoDelay=true" unless cable_binds.all?(&:unix?) %>
 Backlog=1024
 
 SyslogIdentifier=<%= fetch(:cable_socket_unit_name) %>

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-cable
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Brice TEXIER
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano
@@ -51,7 +50,6 @@ metadata:
   homepage_uri: https://github.com/codeur/capistrano-cable#readme
   source_code_uri: https://github.com/codeur/capistrano-cable
   changelog_uri: https://github.com/codeur/capistrano-cable/releases
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -66,8 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: ActionCable integration for Capistrano
 test_files: []