nginx_stage 0.3.0

data/lib/nginx_stage/configuration.rb

@@ -0,0 +1,418 @@
+require 'yaml'
+
+module NginxStage
+  # An object that stores the configuration options to control NginxStage's
+  # behavior.
+  module Configuration
+    #
+    # Global
+    #
+
+    # Location of ERB templates used as NGINX configs
+    # @return [String] the ERB templates root path
+    attr_accessor :template_root
+
+    #
+    # NGINX-specific configuration options
+    #
+
+    # The reverse proxy daemon user used to access the sockets
+    # @return [String] the reverse-proxy-daemon user
+    attr_accessor :proxy_user
+
+    # Path to system-installed NGINX binary
+    # @return [String] the system-installed NGINX binary
+    attr_accessor :nginx_bin
+
+    # A whitelist of signals that can be sent to the NGINX process
+    # @return [Array<Symbol>] whitelist of NGINX process signals
+    attr_accessor :nginx_signals
+
+    # Path to system-installed NGINX mime.types config file
+    # @return [String] the system-installed NGINX mime.types config
+    attr_accessor :mime_types_path
+
+    # Path to system-installed Passenger locations.ini file
+    # @return [String] the system-installed Passenger locations.ini
+    attr_accessor :passenger_root
+
+    # Path to system-installed Ruby binary
+    # @return [String] the system-installed Ruby binary
+    attr_accessor :passenger_ruby
+
+    # Path to system-installed NodeJS binary
+    # @return [String] the system-installed NodeJS binary
+    attr_accessor :passenger_nodejs
+
+    # Path to system-installed python binary
+    # @return [String] the system-installed python binary
+    attr_accessor :passenger_python
+
+    #
+    # per-user NGINX configuration options
+    #
+
+    # Root location where per-user NGINX configs are generated
+    # Path to generated per-user NGINX config file
+    # @example User Bob's nginx config
+    #   pun_config_path(user: 'bob')
+    #   #=> "/var/log/nginx/config/puns/bob.conf"
+    # @param user [String] the user of the nginx process
+    # @return [String] the path to the per-user nginx config file
+    def pun_config_path(user:)
+      File.expand_path @pun_config_path % {user: user}
+    end
+
+    attr_writer :pun_config_path
+
+    # Path to user's personal tmp root
+    # @example User Bob's nginx tmp root
+    #   pun_tmp_root(user: 'bob')
+    #   #=> "/var/lib/nginx/tmp/bob"
+    # @param user [String] the user of the nginx process
+    # @return [String] the path to the tmp root
+    def pun_tmp_root(user:)
+      File.expand_path @pun_tmp_root % {user: user}
+    end
+
+    attr_writer :pun_tmp_root
+
+    # Path to the user's personal access.log
+    # @example User Bob's nginx access log
+    #   pun_access_log_path(user: 'bob')
+    #   #=> "/var/log/nginx/bob/access.log"
+    # @param user [String] the user of the nginx process
+    # @return [String] the path to the nginx access log
+    def pun_access_log_path(user:)
+      File.expand_path @pun_access_log_path % {user: user}
+    end
+
+    attr_writer :pun_access_log_path
+
+    # Path to the user's personal error.log
+    # @example User Bob's nginx error log
+    #   pun_error_log_path(user: 'bob')
+    #   #=> "/var/log/nginx/bob/error.log"
+    # @param user [String] the user of the nginx process
+    # @return [String] the path to the nginx error log
+    def pun_error_log_path(user:)
+      File.expand_path @pun_error_log_path % {user: user}
+    end
+
+    attr_writer :pun_error_log_path
+
+    # Path to the user's per-user NGINX pid file
+    # @example User Bob's pid file
+    #   pun_pid_path(user: 'bob')
+    #   #=> "/var/run/nginx/bob/passenger.pid"
+    # @param user [String] the user of nginx process
+    # @return [String] the path to the pid file
+    def pun_pid_path(user:)
+      File.expand_path @pun_pid_path % {user: user}
+    end
+
+    attr_writer :pun_pid_path
+
+    # Path to the user's per-user NGINX socket file
+    # @example User Bob's socket file
+    #   socket_path(user: 'bob')
+    #   #=> "/var/run/nginx/bob/passenger.sock"
+    # @param user [String] the user of nginx process
+    # @return [String] the path to the socket file
+    def pun_socket_path(user:)
+      File.expand_path @pun_socket_path % {user: user}
+    end
+
+    attr_writer :pun_socket_path
+
+    # Path to the local filesystem root where the per-user Nginx serves files
+    # from with the sendfile feature
+    # @example Filesystem root for user Bob
+    #   pun_sendfile_root(user: 'bob')
+    #   #=> "/"
+    # @param user [String] the user of the nginx process
+    # @return [String] the path to the filesystem root that is served
+    def pun_sendfile_root(user:)
+      File.expand_path @pun_sendfile_root % {user: user}
+    end
+
+    attr_writer :pun_sendfile_root
+
+    # The internal URI used to access the filesystem for downloading files from
+    # the browser, not including any base-uri
+    # @example
+    #   pun_sendfile_uri
+    #   #=> "/sendfile"
+    # @return [String] the internal URI used to access filesystem
+    attr_accessor :pun_sendfile_uri
+
+    # List of hashes that help define the location of the app configs for the
+    # per-user NGINX config. These will be arguments for {#app_config_path}.
+    # @example User Bob's app configs
+    #   pun_app_configs(user: 'bob')
+    #   #=> [ {env: :dev, owner: 'bob', name: '*'},
+    #         {env: :usr, owner: '*', name: '*'} ]
+    # @param user [String] the user of the nginx process
+    # @return [Array<Hash>] list of hashes detailing app config locations
+    def pun_app_configs(user:)
+      @pun_app_configs.map do |envmt|
+        envmt.each_with_object({}) do |(k, v), h|
+          h[k] = v.respond_to?(:%) ? (v % {user: user}) : v
+          h[k] = v.to_sym if k == :env
+        end
+      end
+    end
+
+    attr_writer :pun_app_configs
+
+    #
+    # per-user NGINX app configuration options
+    #
+
+    # Path to generated NGINX app config
+    # @example Dev app owned by Bob
+    #   app_config_path(env: :dev, owner: 'bob', name: 'rails1')
+    #   #=> "/var/lib/nginx/config/apps/dev/bob/rails1.conf"
+    # @example User app owned by Dan
+    #   app_config_path(env: :usr, owner: 'dan', name: 'fillsim')
+    #   #=> "/var/lib/nginx/config/apps/usr/dan/fillsim.conf"
+    # @param env [Symbol] environment the app is run under
+    # @param owner [String] the owner of the app
+    # @param name [String] the name of the app
+    # @return [String] the path to the nginx app config on the local filesystem
+    def app_config_path(env:, owner:, name:)
+      File.expand_path @app_config_path[env] % {env: env, owner: owner, name: name}
+    end
+
+    attr_writer :app_config_path
+
+    # Path to the app root on the local filesystem
+    # @example App root for dev app owned by Bob
+    #   app_root(env: :dev, owner: 'bob', name: 'rails1')
+    #   #=> "~bob/ondemand/dev/rails1"
+    # @example App root for user app owned by Dan
+    #   app_root(env: :usr, owner: 'dan', name: 'fillsim')
+    #   #=> "/var/www/ood/apps/usr/dan/gateway/fillsim"
+    # @param env [Symbol] environment the app is run under
+    # @param owner [String] the owner of the app
+    # @param name [String] the name of the app
+    # @return [String] the path to the app root on the local filesystem
+    # @raise [InvalidRequest] if the environment specified doesn't exist
+    def app_root(env:, owner:, name:)
+      File.expand_path(
+        @app_root.fetch(env) do
+          raise InvalidRequest, "invalid request environment: #{env}"
+        end % {env: env, owner: owner, name: name}
+      )
+    end
+
+    attr_writer :app_root
+
+    # The URI used to access the app from the browser, not including any base-uri
+    # @example URI for dev app owned by Bob
+    #   app_request_uri(env: :dev, owner: 'bob', name: 'rails1')
+    #   #=> "/dev/rails1"
+    # @example URI for user app owned by Dan
+    #   app_request_uri(env: :dev, owner: 'dan', name: 'fillsim')
+    #   #=> "/usr/dan/fillsim"
+    # @param env [Symbol] environment the app is run under
+    # @param owner [String] the owner of the app
+    # @param name [String] the name of the app
+    # @return [String] the URI used to access a given app
+    # @raise [InvalidRequest] if the environment specified doesn't exist
+    def app_request_uri(env:, owner:, name:)
+      @app_request_uri.fetch(env) do
+        raise InvalidRequest, "invalid request environment: #{env}"
+      end % {env: env, owner: owner, name: name}
+    end
+
+    attr_writer :app_request_uri
+
+    # Regular expression used to distinguish the environment from a request URI
+    # and from there distinguish the app owner and app name
+    # @see #app_request_uri
+    # @return [Hash] hash of regular expressions used to determine app from app
+    #   namespace for given environment
+    def app_request_regex
+      @app_request_regex.each_with_object({}) { |(k, v), h| h[k] = ::Regexp.new v }
+    end
+
+    attr_writer :app_request_regex
+
+    # Token used to identify a given app from the other apps
+    # @example app token for dev app owned by Bob
+    #   app_token(env: :dev, owner: 'bob', name: 'rails1')
+    #   #=> "dev/bob/rails1"
+    # @example app token for user app owned by Dan
+    #   app_request_uri(env: :dev, owner: 'dan', name: 'fillsim')
+    #   #=> "usr/dan/fillsim"
+    # @param env [Symbol] environment the app is run under
+    # @param owner [String] the owner of the app
+    # @param name [String] the name of the app
+    # @return [String] the token identifying the app
+    # @raise [InvalidRequest] if the environment specified doesn't exist
+    def app_token(env:, owner:, name:)
+      @app_token.fetch(env) do
+        raise InvalidRequest, "invalid request environment: #{env}"
+      end % {env: env, owner: owner, name: name}
+    end
+
+    attr_writer :app_token
+
+    # The passenger environment used for the given app environment
+    # @example Dev app owned by Bob
+    #   app_passenger_env(env: :dev, owner: 'bob', name: 'rails1')
+    #   #=> "development"
+    # @example User app owned by Dan
+    #   app_passenger_env(env: :usr, owner: 'dan', name: 'fillsim')
+    #   #=> "production"
+    # @param env [Symbol] environment the app is run under
+    # @param owner [String] the owner of the app
+    # @param name [String] the name of the app
+    # @return [String] the passenger environment to run app with in PUN
+    def app_passenger_env(env:, owner:, name:)
+      @app_passenger_env.fetch(env, "production")
+    end
+
+    attr_writer :app_passenger_env
+
+    #
+    # Validation configuration options
+    #
+
+    # Regular expression used to validate a given user name
+    # @return [Regexp] user name regular expression
+    def user_regex
+      /\A#{@user_regex}\z/
+    end
+
+    attr_writer :user_regex
+
+    # Minimum user id required to run the per-user NGINX as this user. This
+    # restricts running processes as special users (i.e., 'root')
+    # @return [Integer] minimum user id required to run as user
+    attr_accessor :min_uid
+
+    # Restrict starting up per-user NGINX process as user with this shell.
+    # NB: This only affects the <tt>pun</tt> command, you are still able to
+    #     start or stop the PUN using other commands (e.g., <tt>nginx</tt>,
+    #     <tt>nginx_clean</tt>, ...)
+    # @return [String] user shell that is blocked
+    attr_accessor :disabled_shell
+
+    #
+    # Configuration module
+    #
+
+    # Default configuration file
+    # @return [String] path to default yaml configuration file
+    def default_config_path
+      config = config_file
+      unless File.file?(config)
+        config = File.join root, 'config', 'nginx_stage.yml'
+        warn "[DEPRECATION] The file '#{config}' is being deprecated. Please move this file to '#{config_file}'." if File.file?(config)
+      end
+      config
+    end
+
+    # Yields the configuration object.
+    # @yieldparam [Configuration] config The library configuration
+    # @return [void]
+    def configure
+      yield self
+    end
+
+    # Sets default configuration options in any class that extends {Configuration}
+    def self.extended(base)
+      base.set_default_configuration
+    end
+
+    # Sets the default configuration options
+    # @return [void]
+    def set_default_configuration
+      self.template_root  = "#{root}/templates"
+
+      self.proxy_user       = 'apache'
+      self.nginx_bin        = '/opt/rh/nginx16/root/usr/sbin/nginx'
+      self.nginx_signals    = %i(stop quit reopen reload)
+      self.mime_types_path  = '/opt/rh/nginx16/root/etc/nginx/mime.types'
+      self.passenger_root   = '/opt/rh/rh-passenger40/root/usr/share/passenger/phusion_passenger/locations.ini'
+      self.passenger_ruby   = "#{root}/bin/ruby"
+      self.passenger_nodejs = "#{root}/bin/node"
+      self.passenger_python = "#{root}/bin/python"
+
+      self.pun_config_path     = '/var/lib/nginx/config/puns/%{user}.conf'
+      self.pun_tmp_root        = '/var/lib/nginx/tmp/%{user}'
+      self.pun_access_log_path = '/var/log/nginx/%{user}/access.log'
+      self.pun_error_log_path  = '/var/log/nginx/%{user}/error.log'
+      self.pun_pid_path        = '/var/run/nginx/%{user}/passenger.pid'
+      self.pun_socket_path     = '/var/run/nginx/%{user}/passenger.sock'
+      self.pun_sendfile_root   = '/'
+      self.pun_sendfile_uri    = '/sendfile'
+      self.pun_app_configs     = [
+        {env: :dev, owner: '%{user}', name: '*'},
+        {env: :usr, owner: '*',       name: '*'},
+        {env: :sys, owner: '',        name: '*'}
+      ]
+
+      self.app_config_path   = {
+        dev: '/var/lib/nginx/config/apps/dev/%{owner}/%{name}.conf',
+        usr: '/var/lib/nginx/config/apps/usr/%{owner}/%{name}.conf',
+        sys: '/var/lib/nginx/config/apps/sys/%{name}.conf'
+      }
+      self.app_root          = {
+        dev: '~%{owner}/ondemand/dev/%{name}',
+        usr: '/var/www/ood/apps/usr/%{owner}/gateway/%{name}',
+        sys: '/var/www/ood/apps/sys/%{name}'
+      }
+      self.app_request_uri   = {
+        dev: '/dev/%{name}',
+        usr: '/usr/%{owner}/%{name}',
+        sys: '/sys/%{name}'
+      }
+      self.app_request_regex = {
+        dev: '^/dev/(?<name>[-\w.]+)',
+        usr: '^/usr/(?<owner>[\w]+)/(?<name>[-\w.]+)',
+        sys: '^/sys/(?<name>[-\w.]+)'
+      }
+      self.app_token = {
+        dev: 'dev/%{owner}/%{name}',
+        usr: 'usr/%{owner}/%{name}',
+        sys: 'sys/%{name}'
+      }
+      self.app_passenger_env = {
+        dev: 'development',
+        usr: 'production',
+        sys: 'production'
+      }
+
+      self.user_regex     = '[\w@\.\-]+'
+      self.min_uid        = 1000
+      self.disabled_shell = '/access/denied'
+
+      read_configuration(default_config_path) if File.file?(default_config_path)
+    end
+
+    # Read in a configuration from a file
+    # @param file [String] path to the yaml configuration file
+    # @return [void]
+    def read_configuration(file)
+      config_hash = symbolize(YAML.load_file(file)) || {}
+      config_hash.each do |k,v|
+        if instance_variable_defined? "@#{k}"
+          self.send("#{k}=", v)
+        else
+          $stderr.puts %{Warning: invalid configuration option "#{k}"}
+        end
+      end
+    end
+
+    private
+      # Recursively symbolize keys in hash
+      def symbolize(obj)
+        return obj.each_with_object({}) {|(k, v), h| h[k.to_sym] =  symbolize(v)} if obj.is_a? Hash
+        return obj.each_with_object([]) {|v, a|      a           << symbolize(v)} if obj.is_a? Array
+        return obj
+      end
+  end
+end

data/lib/nginx_stage/errors.rb

@@ -0,0 +1,46 @@
+module NginxStage
+  # The root exception class that all NginxStage-specific exceptions inherit from
+  class Error < StandardError; end
+
+  # An exception raised when attempting to set an invalid configuration option
+  class InvalidConfigOption < Error; end
+
+  # An exception raised when attempting to resolve an option that doesn't exist
+  class MissingOption < Error; end
+
+  # An exception raised when attempting to resolve a command that doesn't exist
+  class MissingCommand < Error; end
+
+  # An exception raised when attempting to resolve a command that is invalid
+  class InvalidCommand < Error; end
+
+  # An exception raised when attempting to resolve a user that is invalid
+  class InvalidUser < Error; end
+
+  # An exception raised when attempting to resolve a socket that already exists
+  class InvalidSocket < Error; end
+
+  # An exception raised when attempting to resolve an invalid request option
+  class InvalidRequest < Error; end
+
+  # An exception raised when attempting to resolve an invalid sub-uri option
+  class InvalidSubUri < Error; end
+
+  # An exception raised when attempting to resolve an invalid app-init-url option
+  class InvalidAppInitUrl < Error; end
+
+  # An exception raised when attempting to read a pid file that doesn't exist
+  class MissingPidFile < Error; end
+
+  # An exception raised when attempting to read an invalid pid file
+  class InvalidPidFile < Error; end
+
+  # An exception raised when a Pid file has a process id that isn't running
+  class StalePidFile < Error; end
+
+  # An exception raised when attempting to access a socket file that doesn't exist
+  class MissingSocketFile < Error; end
+
+  # An exception raised when attempting to access an invalid socket file
+  class InvalidSocketFile < Error; end
+end

data/lib/nginx_stage/generator.rb

@@ -0,0 +1,139 @@
+require 'erb'
+require 'fileutils'
+require 'open3'
+
+require_relative "generator_helpers"
+
+module NginxStage
+  # Base class for objects that add new sub-commands to NginxStage. {Generator}
+  # is basically a class with helper methods and the ability to invoke all
+  # callback methods in a sequence.
+  class Generator
+    extend GeneratorHelpers
+
+    # Adds a new hook method that is invoked in the order it is defined
+    # @param name [Symbol] unique key defining callback method
+    # @yield The body of the generator's callback
+    # @return [void]
+    def self.add_hook(name, &block)
+      self.hooks[name] = block
+    end
+
+    # Removes a hook method from the callback chain
+    # @param name [Symbol] unique key defining callback method
+    # @return [void]
+    def self.rem_hook(name)
+      self.hooks.delete(name)
+    end
+
+    # Returns a hash of callback methods in the order they will be invoked
+    # @return [Hash] the callback methods
+    def self.hooks
+      @hooks ||= from_superclass(:hooks, {})
+    end
+
+    # Adds a new option expected from CLI and treats it as an attribute
+    # @param name [Symbol] unique key defining option
+    # @yield The body of the option's callback which should return a hash
+    # @return [void]
+    def self.add_option(name, &block)
+      attr_reader name
+      self._options[name] = block
+    end
+
+    # Removes an option expected from the CLI and removes attribute method
+    # @param name [Symbol] unique key defining option
+    # @return [void]
+    def self.rem_option(name)
+      undef name
+      self._options.delete(name)
+    end
+
+    # Returns a hash of options with callbacks that return a hash of their
+    # attributes
+    # @return [Hash] a hash of options with the corresponding callback
+    def self._options
+      @options ||= from_superclass(:_options, {})
+    end
+
+    # Returns a hash of options that point to a hash of their attributes
+    # @return [Hash] a hash of options with the corresponding hash of attributes
+    def self.options
+      Hash[self._options.map { |k,v| [k, v.call] }]
+    end
+
+    # Returns the description of generator
+    # @return [String] description of generator
+    def self.desc(desc = nil)
+      @desc ||= desc
+    end
+
+    # Returns the footer description of generator
+    # @return [String] footer description of generator
+    def self.footer(footer = nil)
+      @footer ||= footer
+    end
+
+    # @param opts [Hash] various options for controlling the behavior of the generator
+    def initialize(opts = {})
+      self.class.options.each do |k,v|
+        value = opts.fetch(k) do
+          raise MissingOption, "missing option: #{k}" if v[:required]
+          v[:default]
+        end
+        value = v[:before_init].call(value) if v[:before_init]
+        instance_variable_set("@#{k}", value)
+      end
+    end
+
+    # Invokes all the callbacks in the order they are defined in the {hooks}
+    # hash
+    # @return [void]
+    def invoke
+      self.class.hooks.each {|k,v| self.instance_eval(&v)}
+    end
+
+    # Gets an ERB template at the relative source, executes it and makes a copy
+    # at the relative destination
+    # @param source [String] the relative path to the source file
+    # @param destination [String] the relative path to the destination file
+    # @return [void]
+    def template(source, destination)
+      data = File.read File.join(NginxStage.template_root, source)
+      create_file destination, render(data)
+    end
+
+    # Create a new file at the destination path with the given data
+    # @param destination [String] the relative path to the destination file
+    # @param data [String] the given data
+    # @return [void]
+    def create_file(destination, data = "")
+      empty_directory File.dirname(destination)
+      File.open(destination, "wb", 0644) { |f| f.write data }
+    end
+
+    # Create an empty directory if it doesn't already exist
+    # @param destination [String] the directory path
+    # @param mode [Fixnum] the mode to set the directory as
+    # @return [void]
+    def empty_directory(destination, mode: 0755)
+      FileUtils.mkdir_p destination, mode: mode
+    end
+
+    private
+      # Retrieves a value from superclass. If it reaches the baseclass,
+      # returns default
+      def self.from_superclass(method, default = nil)
+        if self == NginxStage::Generator || !superclass.respond_to?(method, true)
+          default
+        else
+          superclass.send(method).dup
+        end
+      end
+
+      # Use ERB to render templates
+      def render(data)
+        ERB.new(data, nil, '-').result(binding)
+      end
+  end
+end

data/lib/nginx_stage/generator_helpers.rb

@@ -0,0 +1,68 @@
+module NginxStage
+  # Module that adds common options to generators.
+  module GeneratorHelpers
+    # Add support for accepting USER as an option
+    # @param required [Boolean] whether user option is required
+    # @return [void]
+    def add_user_support(required: true)
+      # @!method user
+      #   The user that the per-user NGINX will run as
+      #   @return [User] the user of the nginx process
+      #   @raise [MissingOption] if user isn't supplied
+      self.add_option :user do
+        {
+          opt_args: ["-u", "--user=USER", "# The USER of the per-user nginx process"],
+          required: required,
+          before_init: -> (user) do
+            raise InvalidUser, "invalid user name syntax: #{user}" unless user =~ NginxStage.user_regex
+            user ? User.new(user) : nil
+          end
+        }
+      end
+
+      if required
+        # Validate that the user isn't a special user (i.e., `root`)
+        self.add_hook :validate_user_not_special do
+          min_uid = NginxStage.min_uid
+          if user.uid < min_uid
+            raise InvalidUser, "user is special: #{user} (#{user.uid} < #{min_uid})"
+          end
+        end
+      end
+    end
+
+    # Add support for accepting SKIP_NGINX as an option
+    # @return [void]
+    def add_skip_nginx_support
+      # @!method skip_nginx
+      #   Whether we skip calling the NGINX process
+      #   @return [Boolean] if true, skip calling the nginx binary
+      add_option :skip_nginx do
+        {
+          opt_args: ["-N", "--[no-]skip-nginx", "# Skip execution of the per-user nginx process", "# Default: false"],
+          default: false
+        }
+      end
+    end
+
+    # Add support for accepting SUB_URI as an option
+    # @return [void]
+    def add_sub_uri_support
+      # @!method sub_uri
+      #   The sub-uri that distinguishes the per-user NGINX process
+      #   @example An app is requested through '/pun/usr/user/appname/...'
+      #     sub_uri #=> "/pun"
+      #   @return [String] the sub-uri for nginx
+      add_option :sub_uri do
+        {
+          opt_args: ["-i", "--sub-uri=SUB_URI", "# The SUB_URI that requests the per-user nginx", "# Default: ''"],
+          default: '',
+          before_init: -> (sub_uri) do
+            raise InvalidSubUri, "invalid sub-uri syntax: #{sub_uri}" if sub_uri =~ /[^-\w\/]/
+            sub_uri
+          end
+        }
+      end
+    end
+  end
+end