daemon_controller 1.2.0 → 3.0.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZTczYjIwNTI5YjU3OTZmN2YyNzY0ZmYzOGE0MjA2YjJkNDE3OTZjYQ==
-  data.tar.gz: !binary |-
-    MTUyNDIxMmExMmNlMTFjOWQ1ZjVhODdmM2ExOTUwMTQ2YTk0MjM2MQ==
+SHA256:
+  metadata.gz: bd4f2d08b82c7340e6b00c8a97e63f66a6677fbc28e9b705ecb6c53d75701e00
+  data.tar.gz: 11bc6d68d7837db49c123b5e2b08fc932bf60c1b0c29742e7e891e66d8f4f82a
 SHA512:
-  metadata.gz: !binary |-
-    NjdlNDgzYWVhNDg4NDQwMGFhMjM2Mjg3Njg2NTkyN2U1ZThiOTM0MjRjNmNl
-    ODBmMGQxMWIwYTc3ZmRlYTJlZmQwNGNiOGQ1MmZiNDE2MzI1NTFjZGY3NjE3
-    MWQ1ZjExYzc1ZTI2MDM3YTc2ZjhhZjJmMGFkZDZkMTY2NTQzYmI=
-  data.tar.gz: !binary |-
-    ZWI1NmQ1Y2U5NjRlZGUxZDE0ODA3NTMwMDQ2NWM5NjlkMjYxZTgxYTFkYTA2
-    ZWY2NjUxYjczZTQ5YWJjODM1MWZlODQxY2UyOTc2M2I5NjVmOGUwNTZmMWNl
-    MGZkZTUwODg0NDFjNmU2MzZlODI2ZTZhZmZiMmYwYjEwMWQ1ZDg=
+  metadata.gz: c29f7ea6b92d607774bef4f42dba2e03215f85078079fb3febd404cf87efff8f0536e03ba870234c72925f7404142dba2bf73217d7586175328d6611ba72e3d8
+  data.tar.gz: 1b5d67e7165fb4c2ba1c667c774e089a5a5029e57ba47dd1f91cbcd17e2dcdef7136947b0d115d71b7db9c154013043f9da01428d55659898eee198bd1ca3d3a

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2008-2014 Phusion
+Copyright (c) 2008-2025 Asynchronous B.V.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -17,4 +17,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
-

data/{README.markdown → README.md}

@@ -12,11 +12,11 @@ It provides the following functionality:
 *   Starting daemons. If the daemon fails to start then an exception will be
     raised. *daemon_controller* can even detect failures that occur after the
     daemon has already daemonized.
-    
+
     Starting daemons is done in a race-condition-free manner. If another
     process using *daemon_controller* is trying to start the same daemon,
     then *daemon_controller* will guarantee serialization.
-    
+
     *daemon_controller* also raises an exception if it detects that the daemon
     is already started.
 *   Connecting to a daemon, starting it if it's not already started. This too
@@ -25,53 +25,11 @@ It provides the following functionality:
 *   Stopping daemons.
 *   Checking whether a daemon is running.
 
-## Installation with RubyGems
-
-    gem install daemon_controller
-
-This gem is signed using PGP with the [Phusion Software Signing key](http://www.phusion.nl/about/gpg). That key in turn is signed by [the rubygems-openpgp Certificate Authority](http://www.rubygems-openpgp-ca.org/).
-
-You can verify the authenticity of the gem by following [The Complete Guide to Verifying Gems with rubygems-openpgp](http://www.rubygems-openpgp-ca.org/blog/the-complete-guide-to-verifying-gems-with-rubygems-openpgp.html).
-
-## Installation on Ubuntu
-
-Use our [PPA](https://launchpad.net/~phusion.nl/+archive/misc):
-
-    sudo add-apt-repository ppa:phusion.nl/misc
-    sudo apt-get update
-    sudo apt-get install ruby-daemon-controller
-
-## Installation on Debian
-
-Our Ubuntu Lucid packages are compatible with Debian 6.
+## Installation
 
-    sudo sh -c 'echo deb http://ppa.launchpad.net/phusion.nl/misc/ubuntu lucid main > /etc/apt/sources.list.d/phusion-misc.list'
-    sudo sh -c 'echo deb-src http://ppa.launchpad.net/phusion.nl/misc/ubuntu lucid main >> /etc/apt/sources.list.d/phusion-misc.list'
-    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 2AC745A50A212A8C
-    sudo apt-get update
-    sudo apt-get install ruby-daemon-controller
-
-## Installation on RHEL, CentOS and Amazon Linux
-
-Enable our YUM repository:
-
-    # RHEL 6, CentOS 6
-    curl -L https://oss-binaries.phusionpassenger.com/yumgems/phusion-misc/el.repo | \
-      sudo tee /etc/yum.repos.d/phusion-misc.repo
-    
-    # Amazon Linux
-    curl -L https://oss-binaries.phusionpassenger.com/yumgems/phusion-misc/amazon.repo | \
-      sudo tee /etc/yum.repos.d/phusion-misc.repo
-
-Install our package:
-
-    sudo yum install rubygem-daemon_controller
-
-## Resources
-
-*   [Website](https://github.com/FooBarWidget/daemon_controller)
-*   [RDoc](http://rdoc.info/projects/FooBarWidget/daemon_controller)
-*   [Git repository](git://github.com/FooBarWidget/daemon_controller.git)
+```bash
+gem install daemon_controller
+```
 
 
 What is it for?
@@ -123,13 +81,15 @@ daemon varies. We've observed that waiting a fixed amount of time is by far the
 most common way. For example, UltraSphinx's daemon starting code looks like
 this:
 
-    system "searchd --config '#{Ultrasphinx::CONF_PATH}'"
-    sleep(4) # give daemon a chance to write the pid file
-    if ultrasphinx_daemon_running?
-       say "started successfully"
-    else
-       say "failed to start"
-    end
+```ruby
+system "searchd --config '#{Ultrasphinx::CONF_PATH}'"
+sleep(4) # give daemon a chance to write the pid file
+if ultrasphinx_daemon_running?
+  say "started successfully"
+else
+  say "failed to start"
+end
+```
 
 This is in no way a slam against UltraSphinx. However, if the daemon starts in
 200 miliseconds, then the user who issued the start command will be waiting for
@@ -168,11 +128,11 @@ From the problem descriptions, it would become apparent that our wishlist is as
 follows. Why is this wishlist often not implemented? Let's go over them.
 
  -  **A daemon should be automatically started on demand, instead of requiring the user to manually start it.**
-    
+
     The most obvious problems are related to concurrency. Suppose that your web
     application has a search box, and you want to start the search daemon if it
     isn't already started, then connect to. Two problems will arise:
-    
+
      *  Suppose that Rails process A is still starting the daemon. At the same
         time, another visitor tries to search something, and Rails process B
         notices that the daemon is not running. If B tries to start the daemon
@@ -183,24 +143,24 @@ follows. Why is this wishlist often not implemented? Let's go over them.
         start. For example, if you wait 2 seconds, then try to connect to the
         daemon, and the daemon isn't done initializing yet, then it will seem as
         if the daemon failed to start.
-    
+
     These are the most probable reasons why people don't try to write
     auto-starting code, and instead require the user to start the daemon
     manually.
-    
+
     These problems, as well as several less obvious problems, are closely
     related to the next few points.
-    
+
  -  **The daemon starter must wait until the daemon is done initializing, no longer and no shorter**
-    
+
     Because only after the daemon is fully initialized, is it safe to connect
     to it. And because the user should not have to wait longer than he really
     has to. During startup, the daemon will have to be continuously checked
     whether it's done initializing or whether an error occured. Writing this
     code can be quite a hassle, which is why most people don't do it.
-    
+
  -  **The daemon starter must report any startup errors**
-    
+
     If the daemon starting command - e.g. `sphinx -c config_file.conf`,
     `apachectl start` or `mongrel_rails cluster::start` - reports startup
     errors, then all is fine as long as the user is starting the command from a
@@ -208,16 +168,16 @@ follows. Why is this wishlist often not implemented? Let's go over them.
     already gone into the background. Such errors are only reported to the log
     file.
     *The daemon starter should also check the log file for any startup errors.*
-    
+
     Furthermore, it should be able to raise startup errors as exceptions. This
     allows the the application to decide what to do with the error. For less
     experienced system administrators, the error might be displayed in the
     browser, allowing the administrators to become aware of the problem without
     forcing them to manually check the log files. Or the error might be emailed
     to a system administrator's email address.
-    
+
  -  **The daemon starter must be able to correct stale or corrupted PID files**
-    
+
     If the PID file is stale, or for some reason has been corrupted, then the
     daemon starter must be able to cope with that.
     *It should check whether the PID file contains a valid PID, and whether the PID exists.*
@@ -292,28 +252,28 @@ or [God](http://god.rubyforge.org/). Rather, it is a solution to the following
 problem:
 
 > **Hongli:** hey Ninh, do a 'git pull', I just implemented awesome searching
->    features in our application!  
->   **Ninh:** cool. *pulls from repository*  
->   **Ninh:** hey Hongli, it doesn't work.  
-> **Hongli:** what do you mean, it doesn't work?  
->   **Ninh:** it says "connection refused", or something  
+>    features in our application!
+>   **Ninh:** cool. *pulls from repository*
+>   **Ninh:** hey Hongli, it doesn't work.
+> **Hongli:** what do you mean, it doesn't work?
+>   **Ninh:** it says "connection refused", or something
 > **Hongli:** oh I forgot to mention it, you have to run the Sphinx search
 >    daemon before it works. type "rake sphinx:daemon:start" to do
->    that  
+>    that
 >   **Ninh:** great. but now I get a different error. something about
->    BackgrounDRb.  
+>    BackgrounDRb.
 > **Hongli:** oops, I forgot to mention this too. you need to start the
->    BackgrounDRb server with "rake backgroundrb:start_server"  
+>    BackgrounDRb server with "rake backgroundrb:start_server"
 >   **Ninh:** okay, so every time I want to use this app, I have to type
 >    "rake sphinx:daemon:start", "rake backgroundrb:start_server" and
->    "./script/server"?  
+>    "./script/server"?
 > **Hongli:** yep
 
 Imagine the above conversation becoming just:
 
 > **Hongli:** hey Ninh, do a 'git pull', I just implemented awesome searching
->    features in our application!  
->   **Ninh:** cool. *pulls from repository*  
+>    features in our application!
+>   **Ninh:** cool. *pulls from repository*
 >   **Ninh:** awesome, it works!
 
 This is not something that can be achieved with Monit/God. Monit/God are for
@@ -327,7 +287,7 @@ without having to start the daemons manually.
 Tutorial #1: controlling Apache
 ===============================
 
-Suppose that you're a [Phusion Passenger](http://www.modrails.com/) developer,
+Suppose that you're a [Phusion Passenger](https://www.phusionpasseenger.com/) developer,
 and you need to write tests for the Apache module. In particular, you want to
 test whether the different Phusion Passenger configuration directives are
 working as expected. Obviously, to test the Apache module, the Apache web
@@ -342,29 +302,30 @@ server must be running. For every test, you will want the unit test suite to:
 
 That can be done with the following code:
 
-    require 'daemon_controller'
-    
-    File.open("apache.conf", "w") do |f|
-       f.write("PidFile apache.pid\n")
-       f.write("LogFile apache.log\n")
-       f.write("Listen 1234\n")
-       f.write(... other relevant configuration options ...)
-    end
-    
-    controller = DaemonController.new(
-       :identifier    => 'Apache web server',
-       :start_command => 'apachectl -f apache.conf -k start',
-       :ping_command  => [:tcp, 'localhost', 1234],
-       :pid_file      => 'apache.pid',
-       :log_file      => 'apache.log',
-       :start_timeout => 25
-    )
-    controller.start
-    
-    .... apache is now started ....
-    .... some test code here ....
-    
-    controller.stop
+```ruby
+require "daemon_controller"
+
+File.open("apache.conf", "w") do |f|
+  f.write("PidFile apache.pid\n")
+  f.write("LogFile apache.log\n")
+  f.write("Listen 1234\n")
+  f.write(... other relevant configuration options ...)
+end
+
+controller = DaemonController.new(
+  identifier: "Apache web server",
+  start_command: "apachectl -f apache.conf -k start",
+  ping_command: [:tcp, "localhost", 1234],
+  pid_file: "apache.pid",
+  log_file: "apache.log"
+)
+controller.start
+
+# .... apache is now started ....
+# .... some test code here ....
+
+controller.stop
+```
 
 The `File.open` line is obvious: it writes the relevant Apache configuration
 file.
@@ -372,8 +333,8 @@ file.
 The next line is for creating a new DaemonController object. We pass a
 human-readable identifier for this daemon ("Apache web server") to the
 constructor. This is used for generating friendlier error messages.
-We also tell it how Apache is supposed to be started (`:start_command`), how to
-check whether it can be connected to (`:ping_command`), and where its PID file
+We also tell it how Apache is supposed to be started (`start_command:`), how to
+check whether it can be connected to (`ping_command:`), and where its PID file
 and log file is. If Apache failed with an error during startup, then it will be
 reported. If Apache failed with an error after it has gone into the background,
 then that will be reported too: the given log file is monitored for new error
@@ -381,7 +342,8 @@ messages.
 Finally, a timeout of 25 seconds is given. If Apache doesn't start within 25
 seconds, then an exception will be raised.
 
-The ping command is just a `Proc` which returns true or false. If the Proc
+The ping command specifies which socket to connect to in order to check whether
+the daemon is ready. It can also be a `Proc` which returns true or false. If the Proc
 raises `Errno::ECONNREFUSED`, then that's also interpreted by DaemonController
 as meaning that the daemon isn't responding yet.
 
@@ -428,41 +390,43 @@ isn't running.
 
 This can be achieved with the following code:
 
-    require 'daemon_controller'
-    
-    class SearchServer
-       SEARCH_SERVER_PORT = 1234
-    
-       def initialize
-          @controller = DaemonController.new(
-             :identifier => 'Sphinx search server',
-             :start_command => "searchd -c config/sphinx.conf",
-             :before_start => method(:before_start),
-             :ping_command => [:tcp, 'localhost', SEARCH_SERVER_PORT],
-             :pid_file => 'tmp/pids/sphinx.pid',
-             :log_file => 'log/sphinx.log')
-       end
-       
-       def query(search_terms)
-          socket = @controller.connect do
-             TCPSocket.new('localhost', SEARCH_SERVER_PORT)
-          end
-          send_query(socket, search_terms)
-          return retrieve_results(socket)
-       end
-       
-    private
-       def before_start
-          generate_configuration_file
-          if !index_exists?
-             generate_index
-          end
-       end
-       
-       ...
+```ruby
+require "daemon_controller"
+
+class SearchServer
+  SEARCH_SERVER_PORT = 1234
+
+  def initialize
+    @controller = DaemonController.new(
+      identifier: "Sphinx search server",
+      start_command: "searchd -c config/sphinx.conf",
+      before_start: method(:before_start),
+      ping_command: [:tcp, "localhost", SEARCH_SERVER_PORT],
+      pid_file: "tmp/pids/sphinx.pid",
+      log_file: "log/sphinx.log")
+  end
+
+  def query(search_terms)
+    socket = @controller.connect do
+      TCPSocket.new("localhost", SEARCH_SERVER_PORT)
+    end
+    send_query(socket, search_terms)
+    retrieve_results(socket)
+  end
+
+private
+  def before_start
+    generate_configuration_file
+    if !index_exists?
+      generate_index
     end
+  end
 
-Notice the `:before_start` option. We pass a block of code which is to be run,
+  # ...
+end
+```
+
+Notice the `before_start:` option. We pass a block of code which is to be run,
 just before the daemon is started. This block, along with starting the daemon,
 is completely serialized. That is, if you're inside the block, then it's
 guaranteed that no other process is running this block at the same time as well.
@@ -506,11 +470,11 @@ synchronization. This has a few implications:
    Multiple threads can safely use daemon_controller concurrently. Multiple
    processes can safely use daemon_controller concurrently. There will be no
    race conditions.
-   
+
    However `flock()` is not implemented on Solaris. daemon_controller, if
    used in MRI does not currently work on Solaris. You need to use JRuby
    which does not use `flock()` to implement `File#flock`.
-   
+
  * On JRuby `File#flock` is implemented through the Java file locking API,
    which on Unix is implemented with the `fcntl()` system calls. This is a
    different kind of lock with very strange semantics.
@@ -524,7 +488,7 @@ synchronization. This has a few implications:
      cannot be used to synchronize threads. If a thread has obtained a file
      lock, then another thread within the same JVM process will not block upon
      trying to lock the same file.
-   
+
    In other words, if you're on JRuby then don't concurrently access
    daemon_controller from multiple threads without manual locking. Also be
    careful with mixing MRI processes that use daemon_controller with JRuby
@@ -534,5 +498,7 @@ synchronization. This has a few implications:
 API documentation
 =================
 
-Detailed API documentation is available in the form of inline comments in
-`lib/daemon_controller.rb`.
+Detailed API documentation is available here:
+- [Configuration options](doc/OPTIONS.md)
+- [Stop flow](doc/STOP_FLOW.md)
+- Inline comments in `lib/daemon_controller.rb`.