potluck-nginx 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c15060a79498a8616523a551ef3031549bbb8b09af0e6d7eb7e329c166b9e8d
-  data.tar.gz: bf716efed8715260cec9439c731e5c799073080fda9f25ebf19b8ea1e09d061b
+  metadata.gz: f489f7ab1e64d5447a26b87a96bfb1ceb50174cce9a25d9131e64ee1a06a7f66
+  data.tar.gz: 7f7518e1835ef8d454b2925bded018cc189fde565dedae2f8b8274f105531040
 SHA512:
-  metadata.gz: 99f5a935c622ec367f01a7852b1992ff1c687cfb575286e7e05b211eb98788b97fa7684f11cd1f1f7afe95ed46cb110a8589602dc8cb288bbfec2d0f9b5e522d
-  data.tar.gz: 4ccc0baa9b708d498bf46b7f925ba8e725eba121c0ed17e5a41d54f281972839a39fb5baa46db9dc153f7fbe88e06709596d62de9d9fdaf1e6503aa8e846c7e2
+  metadata.gz: c8cd92c4fdbd976b2330a433ff6cacac50ee143c2b90dd91776af91350b4540b304fc89f3ad0456acb108ad4f29affe37e58699c8ba122a3652eca86306f495c
+  data.tar.gz: 0f366d7c77baef42dae840b4e410c596623297bede06a7daa2c15c52d079b789118e89c8f7319d91012a74766e9baa033b416b8f56603a61ddd7200ff4de6d8e

data/lib/potluck/nginx/ssl.rb

@@ -3,7 +3,11 @@
 require('time')
 
 module Potluck
-  class Nginx < Dish
+  class Nginx < Service
+    ##
+    # SSL-specific configuration for Nginx. Provides self-signed certificate generation for use in
+    # developemnt.
+    #
     class SSL
       # Reference: https://ssl-config.mozilla.org/#server=nginx&config=intermediate&guideline=5.6
       DEFAULT_CONFIG = {
@@ -26,8 +30,18 @@ module Potluck
 
       attr_reader(:csr_file, :key_file, :crt_file, :dhparam_file, :config)
 
-      def initialize(nginx, dir, host, crt_file: nil, key_file: nil, dhparam_file: nil,
-          config: {})
+      ##
+      # Creates a new instance. Providing no SSL files will cue generation of a self-signed certificate.
+      #
+      # * +nginx+ - Nginx instance.
+      # * +dir+ - Directory where SSL files are located or should be written to.
+      # * +host+ - Name of the host for determining file names and generating a self-signed certificate.
+      # * +crt_file+ - Path to the CRT file (optional).
+      # * +key_file+ - Path to the KEY file (optional).
+      # * +dhparam_file+ - Path to the DH parameters file (optional).
+      # * +config+ - Nginx configuration hash (optional).
+      #
+      def initialize(nginx, dir, host, crt_file: nil, key_file: nil, dhparam_file: nil, config: {})
         @nginx = nginx
         @dir = dir
         @host = host
@@ -52,6 +66,11 @@ module Potluck
         }.merge!(DEFAULT_CONFIG).merge!(config)
       end
 
+      ##
+      # If SSL files were passed to SSL.new, does nothing. Otherwise checks if auto-generated SSL files
+      # exist and generates them if not. If they do exist, the expiration for the certificate is checked and
+      # the certificate regenerated if the expiration date is soon or in the past.
+      #
       def ensure_files
         return if !@auto_generated || (
           File.exists?(@csr_file) &&
@@ -88,6 +107,9 @@ module Potluck
 
       private
 
+      ##
+      # OpenSSL configuration content used when auto-generating an SSL certificate.
+      #
       def openssl_config
         <<~EOS
           [ req ]

data/lib/potluck/nginx/util.rb

@@ -2,7 +2,35 @@
 
 module Potluck
   class Nginx
+    ##
+    # Utility methods for Nginx class.
+    #
     class Util
+      ##
+      # Merges one or more other hashes into a hash by merging nested hashes rather than overwriting them as
+      # is the case with <tt>Hash#merge!</tt>.
+      #
+      # * +hashes+ - Hashes to deep merge. The first one will be modified with the result of the merge.
+      # * +arrays+ - True if arrays should be merged rather than overwritten (optional, default: false).
+      #
+      # Example:
+      #
+      #   h1 = {hello: {item1: 'world'}}
+      #   h2 = {hello: {item2: 'friend'}}
+      #
+      #   Util.deep_merge!(h1, h2)
+      #   # => {hello: {item1: 'world', item2: 'friend'}}
+      #
+      # By default, only hashes are merged and arrays are still overwritten as they are with
+      # <tt>Hash#merge!</tt>. But passing <tt>arrays: true</tt> will result in arrays being merged similarly
+      # to hashes. Example:
+      #
+      #   h1 = {hello: {item1: ['world']}}
+      #   h2 = {hello: {item1: ['friend']}}
+      #
+      #   Util.deep_merge!(h1, h2, arrays: true)
+      #   # => {hello: {item1: ['world', 'friend']}}
+      #
       def self.deep_merge!(*hashes, arrays: false)
         hash = hashes[0]
 

data/lib/potluck/nginx.rb

@@ -6,7 +6,14 @@ require_relative('nginx/ssl')
 require_relative('nginx/util')
 
 module Potluck
-  class Nginx < Dish
+  ##
+  # A Ruby interface for configuring and controlling Nginx. Each instance of this class manages a separate
+  # Nginx configuration file, which is loaded and unloaded from the base Nginx configuration when #start and
+  # #stop are called, respectively. Any number of Ruby processes can thus each manage their own Nginx
+  # configuration and control whether or not it is active without interfering with any other instances or
+  # non-Ruby processes leveraging Nginx.
+  #
+  class Nginx < Service
     CONFIG_NAME_ACTIVE = 'nginx.conf'
     CONFIG_NAME_INACTIVE = 'nginx-stopped.conf'
     ACTIVE_CONFIG_PATTERN = File.join(DIR, '*', CONFIG_NAME_ACTIVE).freeze
@@ -20,6 +27,32 @@ module Potluck
       stop: 'nginx -s stop',
     }.freeze
 
+    ##
+    # Creates a new instance.
+    #
+    # * +hosts+ - One or more hosts.
+    # * +port+ - Port that the upstream (Ruby web server) is running on.
+    # * +subdomains+ - One or more subdomains (optional).
+    # * +ssl+ - SSL configuration arguments to pass to SSL.new (optional).
+    # * +one_host+ - True if URLs should be normalized to the first host in +hosts+ (optional, default:
+    #   false).
+    # * +www+ - +true+ if URLs should be normalized to include 'www.' prefix, +false+ to exclude 'www.', and
+    #   +nil+ if either is acceptable (optional, default: +nil+).
+    # * +multiple_slashes+ - +false+ if any occurrence of multiple slashes in the path portion of the URL
+    #   should be normalized to a single slash (optional, default: +nil+).
+    # * +multiple_question_marks+ - +false+ if multiple question marks in the URL signifying the start of
+    #   the query string should be normalized to a single question mark (optional, default: +nil+).
+    # * +trailing_slash+ - +true+ if URLs should be normalized to include a trailing slash at the end of the
+    #   path portion, +false+ to strip any trailing slash, and +nil+ if either is acceptable (optional,
+    #   default: +nil+).
+    # * +trailing_question_mark+ - +true+ if URLs should be normalized to include a trailing question mark
+    #   when the query string is empty, +false+ to strip any trailing question mark, and +nil+ if either is
+    #   acceptable (optional, default: +nil+).
+    # * +config+ - Nginx configuration hash; see #config (optional).
+    # * +ensure_host_entries+ - True if +hosts+ should be added to system /etc/hosts file as mappings to
+    #   localhost (optional, default: false).
+    # * +args+ - Arguments to pass to Potluck::Service.new (optional).
+    #
     def initialize(hosts, port, subdomains: nil, ssl: nil, one_host: false, www: nil, multiple_slashes: nil,
         multiple_question_marks: nil, trailing_slash: nil, trailing_question_mark: nil, config: {},
         ensure_host_entries: false, **args)
@@ -49,13 +82,16 @@ module Potluck
       @trailing_question_mark = trailing_question_mark
       @additional_config = config
 
-      FileUtils.mkdir_p(DIR)
       FileUtils.mkdir_p(@dir)
 
       @config_file_active = File.join(@dir, CONFIG_NAME_ACTIVE).freeze
       @config_file_inactive = File.join(@dir, CONFIG_NAME_INACTIVE).freeze
     end
 
+    ##
+    # Ensures this instance's configuration file is active and starts Nginx if it's managed. If Nginx is
+    # already running, a reload signal is sent to the process after activating the configuration file.
+    #
     def start
       return unless manage?
 
@@ -71,6 +107,13 @@ module Potluck
       status == :active ? reload : super
     end
 
+    ##
+    # Ensures this instance's configuration file is inactive and optionally stops the Nginx process if it's
+    # managed.
+    #
+    # * +hard+ - True if the Nginx process should be stopped, false to just inactivate this instance's
+    #   configuration file and leave Nginx running (optional, default: false).
+    #
     def stop(hard = false)
       return unless manage?
 
@@ -79,14 +122,29 @@ module Potluck
       hard || status != :active ? super() : reload
     end
 
+    ##
+    # Reloads Nginx if it's managed.
+    #
     def reload
       return unless manage?
 
       run('nginx -s reload')
     end
 
+    ##
+    # Returns the content for the Nginx configuration file as a string.
+    #
+    def config_file_content
+      self.class.to_nginx_config(config)
+    end
+
     private
 
+    ##
+    # Returns a hash representation of the Nginx configuration file content. Any configuration passed to
+    # Nginx.new is deep-merged into a base configuration hash, meaning nested hashes are merged rather than
+    # overwritten (see Util.deep_merge!).
+    #
     def config
       host_subdomains_regex = ([@host] + @subdomains).join('|')
       hosts_subdomains_regex = (@hosts + @subdomains).join('|')
@@ -111,14 +169,15 @@ module Potluck
           'server_name' => (@hosts + @subdomains).join(' '),
 
           'gzip' => 'on',
-          'gzip_types' => 'application/javascript application/json text/css text/plain',
+          'gzip_types' => 'application/javascript application/json application/xml text/css '\
+            'text/javascript text/plain',
 
           'add_header' => {
             repeat: true,
-            'Referrer-Policy' => 'same-origin',
-            'X-Frame-Options' => 'DENY',
-            'X-XSS-Protection' => '\'1; mode=block\'',
-            'X-Content-Type-Options' => 'nosniff',
+            'Referrer-Policy' => '\'same-origin\' always',
+            'X-Frame-Options' => '\'DENY\' always',
+            'X-XSS-Protection' => '\'1; mode=block\' always',
+            'X-Content-Type-Options' => '\'nosniff\' always',
           },
         }, @ssl ? @ssl.config : {}).merge!(
           'location /' => {
@@ -128,6 +187,7 @@ module Potluck
               set $r 0;
               set $s $scheme;
               set $h $host;
+              set $port #{@ssl ? '443' : '80'};
               set $p '';
               set $u '';
               set $q '';
@@ -147,7 +207,7 @@ module Potluck
               end}
 
               if ($scheme = #{@other_scheme}) { set $s #{@scheme}; set $r 1; }
-              if ($http_host ~ :[0-9]+$) { set $p :#{@ssl ? '4433' : '8080'}; }
+              if ($http_host ~ :([0-9]+)$) { set $p :$1; set $port $1; }
               if ($request_uri ~ ^([^\\?]+)(\\?+.*)?$) { set $u $1; set $q $2; }
 
               #{'if ($u ~ //) { set $u $uri; set $r 1; }' if @multiple_slashes == false}
@@ -174,11 +234,11 @@ module Potluck
             'proxy_redirect' => 'off',
             'proxy_set_header' => {
               repeat: true,
-              'Host' => @host,
+              'Host' => '$http_host',
               'X-Real-IP' => '$remote_addr',
               'X-Forwarded-For' => '$proxy_add_x_forwarded_for',
               'X-Forwarded-Proto' => @ssl ? 'https' : 'http',
-              'X-Forwarded-Port' => @ssl ? '443' : '80',
+              'X-Forwarded-Port' => '$port',
             },
           },
         ),
@@ -189,20 +249,33 @@ module Potluck
       config
     end
 
+    ##
+    # Writes the Nginx configuration to the (inactive) configuration file.
+    #
     def write_config
       File.open(@config_file_inactive, 'w') do |file|
-        file.write(self.class.to_nginx_config(config))
+        file.write(config_file_content)
       end
     end
 
+    ##
+    # Renames the inactive Nginx configuration file to its active name.
+    #
     def activate_config
       FileUtils.mv(@config_file_inactive, @config_file_active)
     end
 
+    ##
+    # Renames the active Nginx configuration file to its inactive name.
+    #
     def deactivate_config
       FileUtils.mv(@config_file_active, @config_file_inactive) if File.exists?(@config_file_active)
     end
 
+    ##
+    # Ensures hosts are mapped to localhost in the system /etc/hosts file. Useful in development. Uses sudo
+    # to perform the write, which will prompt for the system user's password.
+    #
     def ensure_host_entries
       content = File.read('/etc/hosts')
       missing_entries = (@hosts + @subdomains).each_with_object([]) do |h, a|
@@ -222,6 +295,11 @@ module Potluck
       )
     end
 
+    ##
+    # Ensures Nginx's base configuration file contains an include statement for Potluck's Nginx
+    # configuration files. Sudo is not used, so Nginx's base configuration file must be writable by the
+    # system user running this Ruby process.
+    #
     def ensure_include
       config_file = `nginx -t 2>&1`[TEST_CONFIG_REGEX, :config]
       config_content = File.read(config_file)
@@ -232,6 +310,57 @@ module Potluck
       end
     end
 
+    ##
+    # Converts a hash to an Nginx configuration file content string. Keys should be strings and values
+    # either strings or hashes. A +nil+ value in a hash will result in that key-value pair being omitted.
+    #
+    # * +hash+ - Hash to convert to the string content of an Nginx configuration file.
+    # * +indent+ - Number of spaces to indent; used when the method is called recursively and should not be
+    #   set explicitly (optional, default: 0).
+    # * +repeat+ - Value to prepend to each entry of the hash; used when the method is called recursively
+    #   and should not be set explicitly (optional).
+    #
+    # Symbol keys in hashes are used as special directives. Including <tt>repeat: true</tt> will cause the
+    # parent hash's key for the child hash to be prefixed to each line of the output. Example:
+    #
+    #   {
+    #     # ...
+    #
+    #     'add_header' => {
+    #       repeat: true,
+    #       'X-Frame-Options' => 'DENY',
+    #       'X-Content-Type-Options' => 'nosniff',
+    #     }
+    #   }
+    #
+    # Result:
+    #
+    #   # ...
+    #
+    #   add_header X-Frame-Options DENY;
+    #   add_header X-Content-Type-Options nosniff;
+    #
+    # A hash containing <tt>raw: '...'</tt> can be used to include a raw chunk of text rather than key-value
+    # pairs. Example:
+    #
+    #   {
+    #     # ...
+    #
+    #     'location /' => {
+    #       raw: """
+    #         if ($scheme = https) { ... }
+    #         if ($host ~ ^www.) { ... }
+    #       """,
+    #     }
+    #   }
+    #
+    # Result:
+    #
+    #   location / {
+    #     if ($scheme = https) { ... }
+    #     if ($host ~ ^www.) { ... }
+    #   }
+    #
     def self.to_nginx_config(hash, indent: 0, repeat: nil)
       hash.each_with_object(+'') do |(k, v), config|
         next if v.nil?
@@ -253,6 +382,9 @@ module Potluck
       end
     end
 
+    ##
+    # Content of the launchctl plist file.
+    #
     def self.plist
       super(
         <<~EOS

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: potluck-nginx
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-16 00:00:00.000000000 Z
+date: 2021-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: potluck
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.3
+        version: 0.0.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.3
+        version: 0.0.4
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -92,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: A Ruby manager for Nginx.