puma-plugin-systemd 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d95c99f2ab14c60a427044c641e5f234f893ec37e93109e1f397ca1a9c85c963
+  data.tar.gz: c07ddd26e9c4e5d696630acce253a40e103365d5f027f873348e91af0eba05f8
+SHA512:
+  metadata.gz: 2e60e0544635e3dfe77ba87ce582735b4aeeef686ee1ffcb46cf9f8a00cfd279c4817557c8917a387f457406b762b362450a43017e1a1e12ff3f585e55069344
+  data.tar.gz: f072b1fd233dcec72b18265012edb6d48e3d4c52c2e2752ceb2ec0e103151b22a13a8eed28f42f8e914615fae82289f7caf6a4b0e8b491d96a6775e55409c91b

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+#I�Z�Q%'�$[S��F��Fc��T����3��Z�|��P�)lݯm	������!�W�R?���QH+s.�?򼷿z(t'�݆�[�T�]F�J�mcG��Z
+d��5|��������^��4Y�C5�Kf2$���k�.� n��@2B$�g4���!H�MZU6�^�����S
2�a�;����,

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Samuel Cochran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.md

@@ -0,0 +1,127 @@
+# Puma Systemd Plugin
+
+[Puma][puma] integration with [systemd](systemd) for better daemonising under
+modern Linux systemds: notify, status, watchdog.
+
+* Notify systemd when puma has booted and is [ready to handle requests][ready]
+* Publish puma stats as systemd [service status][status] for a quick overview
+* Use the [watchdog][watchdog] to make sure your puma processes are healthy
+  and haven't locked up or run out of memory
+
+Puma already natively supports [socket activation][socket-activation].
+
+  [puma]: https://github.com/puma/puma
+  [systemd]: https://www.freedesktop.org/wiki/Software/systemd/
+  [ready]: https://www.freedesktop.org/software/systemd/man/sd_notify.html#READY=1
+  [status]: https://www.freedesktop.org/software/systemd/man/sd_notify.html#STATUS=...
+  [watchdog]: https://www.freedesktop.org/software/systemd/man/sd_notify.html#WATCHDOG=1
+  [socket-activation]: http://github.com/puma/puma/blob/master/docs/systemd.md#socket-activation
+
+## Installation
+
+Add this gem to your Gemfile with puma and then bundle:
+
+```ruby
+gem "puma"
+gem "puma-plugin-systemd"
+```
+
+Add it to your puma config:
+
+```ruby
+# config/puma.rb
+
+bind "http://127.0.0.1:9292"
+
+workers 2
+threads 8, 16
+
+plugin :systemd
+```
+
+## Usage
+
+### Notify
+
+Make sure puma is being started using a [systemd service unit][systemd-service]
+with `Type=notify`, something like:
+
+```ini
+# puma.service
+[Service]
+Type=notify
+User=puma
+WorkingDirectory=/app
+ExecStart=/app/bin/puma -C config/puma.rb -e production
+ExecReload=/bin/kill -USR1 $MAINPID
+ExecRestart=/bin/kill -USR2 $MAINPID
+Restart=always
+KillMode=mixed
+```
+
+  [systemd-service]: https://www.freedesktop.org/software/systemd/man/systemd.service.html
+
+### Status
+
+Running in notify mode as above should just start publishing puma stats as
+systemd status. Running `systemctl status puma.service` or similar should
+result in a Status line in your status output:
+
+```
+app@web:~$ sudo systemctl status puma.service
+● puma.service - puma
+   Loaded: loaded (/etc/systemd/system/puma.service; enabled; vendor preset: enabled)
+   Active: active (running) since Mon 2016-10-24 00:26:55 UTC; 5s ago
+ Main PID: 32234 (ruby2.3)
+   Status: "puma 3.6.0 cluster: 2/2 workers: 16 threads, 0 backlog"
+    Tasks: 10
+   Memory: 167.9M
+      CPU: 7.150s
+   CGroup: /system.slice/puma.service
+           ├─32234 puma 3.6.0 (unix:///app/tmp/sockets/puma.sock?backlog=1024) [app]
+           ├─32251 puma: cluster worker 0: 32234 [app]
+           └─32253 puma: cluster worker 1: 32234 [app]
+
+Oct 24 00:26:10 web systemd[30762]: puma.service: Executing: /app/bin/puma -C config/puma.rb -e production
+Oct 24 00:54:58 web puma[32234]: [32234] Puma starting in cluster mode...
+Oct 24 00:54:58 web puma[32234]: [32234] * Version 3.6.0 (ruby 2.3.1-p112), codename: Sleepy Sunday Serenity
+Oct 24 00:54:58 web puma[32234]: [32234] * Min threads: 8, max threads: 64
+Oct 24 00:26:55 web puma[32234]: [32234] * Environment: production
+Oct 24 00:26:55 web puma[32234]: [32234] * Process workers: 2
+Oct 24 00:26:55 web puma[32234]: [32234] * Phased restart available
+Oct 24 00:26:55 web puma[32234]: [32234] * Listening on unix:///app/tmp/sockets/puma.sock?backlog=1024
+Oct 24 00:26:55 web puma[32234]: [32234] Use Ctrl-C to stop
+Oct 24 00:26:55 web puma[32234]: [32234] * systemd: notify ready
+Oct 24 00:26:55 web puma[32234]: [32251] + Gemfile in context: /app/Gemfile
+Oct 24 00:26:55 web systemd[1]: Started puma.
+Oct 24 00:26:55 web puma[32234]: [32234] * systemd: watchdog detected (30000000usec)
+Oct 24 00:26:55 web puma[32234]: [32253] + Gemfile in context: /app/Gemfile
+```
+
+### Watchdog
+
+Adding a `WatchdogSec=30` or similar to your systemd service file will tell
+puma systemd to ping systemd at half the specified interval to ensure the
+service is running and healthy.
+
+## Development
+
+After checking out the repo, run `script/setup` to install dependencies. Then,
+run `rake test` to run the tests. You can also run `script/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/sj26/puma-plugin-systemd.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][license].
+
+  [license]: http://opensource.org/licenses/MIT

data/lib/puma/plugin/systemd/version.rb

@@ -0,0 +1,7 @@
+module Puma
+  module Plugin
+    module Systemd
+      VERSION = "0.1.1"
+    end
+  end
+end

data/lib/puma/plugin/systemd.rb

@@ -0,0 +1,270 @@
+# coding: utf-8, frozen_string_literal: true
+
+require "json"
+require "puma/plugin"
+
+require_relative "systemd/version"
+
+# Puma systemd plugin
+#
+# Uses systemd notify to let systemd know a little about what puma is doing, so
+# you know when your system has *actually* started and is ready to take
+# requests.
+#
+Puma::Plugin.create do
+  # Give us a way to talk to systemd.
+  #
+  # It'd be great to use systemd-notify for the whole shebang, but there's a
+  # critical error introducing a race condition:
+  #
+  #   https://github.com/systemd/systemd/issues/2739
+  #
+  # systemd-notify docs:
+  #
+  #   https://www.freedesktop.org/software/systemd/man/systemd-notify.html
+  #
+  # We could use sd-daemon (sd_notify and friends) but they require a C
+  # extension, and are really just fancy wrappers for blatting datagrams at a
+  # socket advertised via ENV. See the docs:
+  #
+  #   https://www.freedesktop.org/software/systemd/man/sd-daemon.html
+  #
+  class Systemd
+    # Do we have a systemctl binary? This is a good indicator whether systemd
+    # is installed at all.
+    def present?
+      ENV["PATH"].split(":").any? { |dir| File.exists?(File.join(dir, "systemctl")) }
+    end
+
+    # Is the system currently booted with systemd?
+    #
+    # We could check for the systemd run directory directly, but we can't be
+    # absolutely sure of it's location and breaks encapsulation. We can be sure
+    # that systemctl is present on a systemd system and understand whether
+    # systemd is running. The systemd-notify binary actually recommends this.
+    #
+    #   An alternate way to check for this state is to call systemctl(1) with
+    #   the is-system-running command. It will return "offline" if the system
+    #   was not booted with systemd.
+    #
+    # See also sd_booted:
+    #
+    #   https://www.freedesktop.org/software/systemd/man/sd_booted.html
+    #
+    def booted?
+      IO.popen(["systemctl", "is-system-running"], &:read).chomp != "offline"
+    end
+
+    # Are we running within a systemd unit that expects us to notify?
+    def notify?
+      ENV.include?("NOTIFY_SOCKET")
+    end
+
+    # Open a persistent notify socket.
+    #
+    # Ruby doesn't have a nicer way to open a unix socket as a datagram.
+    #
+    private def notify_socket
+      @notify_socket ||= Socket.new(Socket::AF_UNIX, Socket::SOCK_DGRAM, 0).tap do |socket|
+        socket.connect(Socket.pack_sockaddr_un(ENV["NOTIFY_SOCKET"]))
+        socket.close_on_exec = true
+      end
+    end
+
+    # Send a raw notify message.
+    #
+    #   https://www.freedesktop.org/software/systemd/man/sd_notify.html
+    #
+    private def notify(message)
+      notify_socket.sendmsg(message, Socket::MSG_NOSIGNAL)
+    end
+
+    # Tell systemd we are now the main pid
+    def notify_pid
+      notify("MAINPID=#{$$}")
+    end
+
+    # Tell systemd we're fully started and ready to handle requests
+    def notify_ready
+      notify("READY=1")
+    end
+
+    # Tell systemd our status
+    def notify_status(status)
+      notify("STATUS=#{status}")
+    end
+
+    # Tell systemd we're restarting
+    def notify_reloading
+      notify("RELOADING=1")
+    end
+
+    # Tell systemd we're still alive
+    def notify_watchdog
+      notify("WATCHDOG=1")
+    end
+
+    # Has systemd asked us to watchdog?
+    #
+    # https://www.freedesktop.org/software/systemd/man/sd_watchdog_enabled.html
+    #
+    def watchdog?
+      ENV.include?("WATCHDOG_USEC") &&
+        (!ENV.include?("WATCHDOG_PID") || ENV["WATCHDOG_PID"].to_i == $$)
+    end
+
+    # How long between pings until the watchdog will think we're unhealthy?
+    def watchdog_usec
+      ENV["WATCHDOG_USEC"].to_i
+    end
+  end
+
+  # Take puma's stats and construct a sensible status line for Systemd
+  class Status
+    def initialize(stats)
+      @stats = stats
+    end
+
+    def clustered?
+      stats.has_key? "workers"
+    end
+
+    def workers
+      stats.fetch("workers", 1)
+    end
+
+    def booted_workers
+      stats.fetch("booted_workers", 1)
+    end
+
+    def running
+      if clustered?
+        stats["worker_status"].map { |s| s["last_status"].fetch("running", 0) }.inject(0, &:+)
+      else
+        stats.fetch("running", 0)
+      end
+    end
+
+    def backlog
+      if clustered?
+        stats["worker_status"].map { |s| s["last_status"].fetch("backlog", 0) }.inject(0, &:+)
+      else
+        stats.fetch("backlog", 0)
+      end
+    end
+
+    def to_s
+      if clustered?
+        "puma #{Puma::Const::VERSION} cluster: #{booted_workers}/#{workers} workers: #{running} threads, #{backlog} backlog"
+      else
+        "puma #{Puma::Const::VERSION}: #{running} threads, #{backlog} backlog"
+      end
+    end
+  end
+
+  # Puma creates the plugin when encountering `plugin` in the config.
+  def initialize(loader)
+    # This is a Puma::PluginLoader
+    @loader = loader
+  end
+
+  # We can start doing something when we have a launcher:
+  def start(launcher)
+    @launcher = launcher
+
+    # Log relevant ENV in debug
+    @launcher.events.debug "systemd: NOTIFY_SOCKET=#{ENV["NOTIFY_SOCKET"].inspect}"
+    @launcher.events.debug "systemd: WATCHDOG_PID=#{ENV["WATCHDOG_PID"].inspect}"
+    @launcher.events.debug "systemd: WATCHDOG_USEC=#{ENV["WATCHDOG_USEC"].inspect}"
+
+    # Only install hooks if systemd is present, the systemd is booted by
+    # systemd, and systemd has asked us to notify it of events.
+    @systemd = Systemd.new
+    if @systemd.present? && @systemd.booted? && @systemd.notify?
+      @launcher.events.debug "systemd: detected running inside systemd, registering hooks"
+      register_hooks
+    else
+      @launcher.events.debug "systemd: not running within systemd, doing nothing"
+    end
+  end
+
+  private
+
+  # Are we a single process worker, or do we have worker processes?
+  #
+  # Copied from puma, it's private:
+  # https://github.com/puma/puma/blob/v3.6.0/lib/puma/launcher.rb#L267-L269
+  #
+  def clustered?
+    (@launcher.options[:workers] || 0) > 0
+  end
+
+  def register_hooks
+    (@launcher.config.options[:on_restart] ||= []) << method(:restart)
+    @launcher.events.on_booted(&method(:booted))
+    in_background(&method(:status_loop))
+    in_background(&method(:watchdog_loop)) if @systemd.watchdog?
+  end
+
+  def booted
+    @launcher.events.log "* systemd: notify ready"
+    begin
+      @systemd.notify_ready
+    rescue
+      @launcher.events.error "! systemd: notify ready failed:\n  #{$!.to_s}\n  #{$!.backtrace.join("\n    ")}"
+    end
+  end
+
+  def restart(launcher)
+    @launcher.events.log "* systemd: notify reloading"
+    begin
+      @systemd.notify_reloading
+    rescue
+      @launcher.events.error "! systemd: notify reloading failed:\n  #{$!.to_s}\n  #{$!.backtrace.join("\n    ")}"
+    end
+  end
+
+  def fetch_stats
+    JSON.parse(@launcher.stats)
+  end
+
+  def status
+    Status.new(fetch_stats)
+  end
+
+  # Update systemd status event second or so
+  def status_loop
+    loop do
+      @launcher.events.debug "systemd: notify status"
+      begin
+        @systemd.notify_status(status.to_s)
+      rescue
+        @launcher.events.error "! systemd: notify status failed:\n  #{$!.to_s}\n  #{$!.backtrace.join("\n    ")}"
+      ensure
+        sleep 1
+      end
+    end
+  end
+
+  # If watchdog is configured we'll send a ping at about half the timeout
+  # configured in systemd as recommended in the docs.
+  def watchdog_loop
+    @launcher.events.log "* systemd: watchdog detected (#{@systemd.watchdog_usec}usec)"
+
+    # Ruby wants seconds, and the docs suggest notifying halfway through the
+    # timeout.
+    sleep_seconds = @systemd.watchdog_usec / 1000.0 / 1000.0 / 2.0
+
+    loop do
+      begin
+        @launcher.events.debug "systemd: notify watchdog"
+        @systemd.notify_watchdog
+      rescue
+        @launcher.events.error "! systemd: notify watchdog failed:\n  #{$!.to_s}\n  #{$!.backtrace.join("\n    ")}"
+      ensure
+        @launcher.events.debug "systemd: sleeping #{sleep_seconds}s"
+        sleep sleep_seconds
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: puma-plugin-systemd
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Samuel Cochran
+autorequire: 
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDKDCCAhCgAwIBAgIBBTANBgkqhkiG9w0BAQUFADA6MQ0wCwYDVQQDDARzajI2
+  MRQwEgYKCZImiZPyLGQBGRYEc2oyNjETMBEGCgmSJomT8ixkARkWA2NvbTAeFw0x
+  NzA3MzEwNTQ3MDVaFw0xODA3MzEwNTQ3MDVaMDoxDTALBgNVBAMMBHNqMjYxFDAS
+  BgoJkiaJk/IsZAEZFgRzajI2MRMwEQYKCZImiZPyLGQBGRYDY29tMIIBIjANBgkq
+  hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsr60Eo/ttCk8GMTMFiPr3GoYMIMFvLak
+  xSmTk9YGCB6UiEePB4THSSA5w6IPyeaCF/nWkDp3/BAam0eZMWG1IzYQB23TqIM0
+  1xzcNRvFsn0aQoQ00k+sj+G83j3T5OOV5OZIlu8xAChMkQmiPd1NXc6uFv+Iacz7
+  kj+CMsI9YUFdNoU09QY0b+u+Rb6wDYdpyvN60YC30h0h1MeYbvYZJx/iZK4XY5zu
+  4O/FL2ChjL2CPCpLZW55ShYyrzphWJwLOJe+FJ/ZBl6YXwrzQM9HKnt4titSNvyU
+  KzE3L63A3PZvExzLrN9u09kuWLLJfXB2sGOlw3n9t72rJiuBr3/OQQIDAQABozkw
+  NzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIEsDAdBgNVHQ4EFgQU99dfRjEKFyczTeIz
+  m3ZsDWrNC80wDQYJKoZIhvcNAQEFBQADggEBADGiXpvK754s0zTFx3y31ZRDdvAI
+  lA209JIjUlDyr9ptCRadihyfF2l9/hb+hLemiPEYppzG6vEK1TIyzbAR36yOJ8CX
+  4vPkCXLuwHhs6UIRbwN+IEy41nsIlBxmjLYei8h3t/G2Vm2oOaLdbjDXS+Srl9U8
+  shsE8ft81PxSQfzEL7Mr9cC9XvWbHW+SyTpfGm8rAtaqZkNeke4U8a0di4oz2EfA
+  P4lSfmXxsd1C71ckIp0cyXkPhyTtpyS/5hq9HhuUNzEHkSDe36/Rd1xYKV5JxMC2
+  YAttWFUs06lor2q1wwncPaMtUtbWwW35+1IV6xhs2rFY6DD/I6ZkK3GnHdY=
+  -----END CERTIFICATE-----
+date: 2018-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 
+email: sj26@sj26.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/puma/plugin/systemd.rb
+- lib/puma/plugin/systemd/version.rb
+homepage: https://github.com/sj26/puma-plugin-systemd
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.5
+signing_key: 
+specification_version: 4
+summary: 'Puma integration with systemd: notify, status, watchdog'
+test_files: []

metadata.gz.sig

@@ -0,0 +1 @@
+tз��&��Sf��ԈcJ��쌮���Zg+2~���N>MVpnRqJc$��] ML������q�l���b��ݨ^��C�e��:f͗��+���KW~�Q�����s�Ċm_d)D�Ku��Ȼ�!�$�*���9�b/��4E\��]�Jp�o��$��T��z