pakyow-core 0.11.3 → 1.0.0.rc1

data/lib/pakyow/environment.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require "async"
+
+require "console"
+require "console/split"
+
+require "pakyow/support/core_refinements/array/ensurable"
+
+require "pakyow/support/hookable"
+require "pakyow/support/configurable"
+require "pakyow/support/class_state"
+require "pakyow/support/deep_dup"
+require "pakyow/support/deep_freeze"
+require "pakyow/support/logging"
+require "pakyow/support/pipeline"
+require "pakyow/support/inflector"
+
+require "pakyow/environment/behavior/config"
+require "pakyow/environment/behavior/initializers"
+require "pakyow/environment/behavior/input_parsing"
+require "pakyow/environment/behavior/plugins"
+require "pakyow/environment/behavior/silencing"
+require "pakyow/environment/behavior/timezone"
+require "pakyow/environment/behavior/running"
+require "pakyow/environment/behavior/watching"
+require "pakyow/environment/behavior/restarting"
+
+require "pakyow/environment/actions/dispatch"
+require "pakyow/environment/actions/input_parser"
+require "pakyow/environment/actions/logger"
+require "pakyow/environment/actions/normalizer"
+
+require "pakyow/app"
+
+require "pakyow/logger/destination"
+require "pakyow/logger/multiplexed"
+require "pakyow/logger/thread_local"
+
+# Pakyow environment for running one or more rack apps. Multiple apps can be
+# mounted in the environment, each one handling requests at some path.
+#
+#   Pakyow.configure do
+#     mount Pakyow::App, at: "/"
+#   end
+#
+# = Configuration
+#
+# The environment can be configured
+#
+#   Pakyow.configure do
+#     config.server.port = 2001
+#   end
+#
+# It's possible to configure environments differently.
+#
+#   Pakyow.configure :development do
+#     config.server.host = "pakyow.dev"
+#   end
+#
+# @see Support::Configurable
+#
+# = Hooks
+#
+# Hooks can be defined for the following events:
+#
+#   - load
+#   - configure
+#   - setup
+#   - boot
+#   - shutdown
+#   - run
+#
+# Here's how to log a message after boot:
+#
+#   Pakyow.after "boot" do
+#     logger.info "booted"
+#   end
+#
+# @see Support::Hookable
+#
+# = Logging
+#
+# The environment contains a global general-purpose logger. It also provides
+# a {RequestLogger} instance to each app for logging during a request.
+#
+# = Setup & Running
+#
+# The environment can be setup and then run.
+#
+#   Pakyow.setup(env: :development).run
+#
+module Pakyow
+  using Support::DeepDup
+  using Support::DeepFreeze
+  using Support::Refinements::Array::Ensurable
+
+  extend Support::DeepFreeze
+  unfreezable :global_logger, :app
+
+  include Support::Hookable
+  events :load, :configure, :setup, :boot, :shutdown, :run
+
+  include Support::Configurable
+
+  include Environment::Behavior::Config
+  include Environment::Behavior::Initializers
+  include Environment::Behavior::InputParsing
+  include Environment::Behavior::Plugins
+  include Environment::Behavior::Silencing
+  include Environment::Behavior::Timezone
+  include Environment::Behavior::Running
+  include Environment::Behavior::Watching
+  include Environment::Behavior::Restarting
+
+  include Support::Pipeline
+  action Actions::Logger
+  action Actions::Normalizer
+  action Actions::InputParser
+  action Actions::Dispatch
+
+  extend Support::ClassState
+  class_state :apps,        default: []
+  class_state :tasks,       default: []
+  class_state :mounts,      default: []
+  class_state :frameworks,  default: {}
+  class_state :booted,      default: false, getter: false
+  class_state :server,      default: nil, getter: false
+  class_state :env,         default: nil, getter: false
+  class_state :setup_error, default: nil
+
+  class << self
+    # Name of the environment
+    #
+    attr_reader :env
+
+    # Logger instance for the environment
+    #
+    attr_reader :logger
+
+    # Global logger instance
+    #
+    attr_reader :global_logger
+
+    # Any error encountered during the boot process
+    #
+    attr_reader :error
+
+    # Mounts an app at a path.
+    #
+    # The app can be any rack endpoint, but must implement an
+    # initializer like {App#initialize}.
+    #
+    # @param app the rack endpoint to mount
+    # @param at [String] where the endpoint should be mounted
+    #
+    def mount(app, at:, &block)
+      mounts << { app: app, block: block, path: at }
+    end
+
+    # Loads the Pakyow environment for the current project.
+    #
+    def load
+      performing :load do
+        if File.exist?(config.loader_path + ".rb")
+          require config.loader_path
+        else
+          require "pakyow/integrations/bundler/setup"
+          require "pakyow/integrations/bootsnap"
+
+          require "pakyow/integrations/bundler/require"
+          require "pakyow/integrations/dotenv"
+
+          require config.environment_path
+
+          load_apps
+        end
+      end
+    end
+
+    # Loads apps located in the current project.
+    #
+    def load_apps
+      require "./config/application"
+    end
+
+    # Prepares the environment for booting.
+    #
+    # @param env [Symbol] the environment to prepare for
+    #
+    def setup(env: nil)
+      @env = (env ||= config.default_env).to_sym
+
+      load
+
+      performing :configure do
+        configure!(env)
+        $LOAD_PATH.unshift(config.lib)
+      end
+
+      performing :setup do
+        init_global_logger
+      end
+
+      self
+    rescue => error
+      begin
+        # Try again to initialize the logger, since we may have failed before that point.
+        #
+        unless Pakyow.logger
+          init_global_logger
+        end
+      rescue
+      end
+
+      @setup_error = error; self
+    end
+
+    # Returns true if the environment has booted.
+    #
+    def booted?
+      @booted == true
+    end
+
+    # Boots the environment without running it.
+    #
+    def boot(unsafe: false)
+      ensure_setup_succeeded
+
+      performing :boot do
+        # Tasks should only be available before boot.
+        #
+        @tasks = [] unless unsafe
+
+        # Mount each app.
+        #
+        @apps = mounts.map { |mount|
+          initialize_app_for_mount(mount)
+        }
+
+        # Create the callable pipeline.
+        #
+        @pipeline = Pakyow.__pipeline.callable(self)
+
+        # Set the environment as booted ahead of telling each app that it is booted. This allows an
+        # app's after boot hook to access the booted app through `Pakyow.app`.
+        #
+        @booted = true
+
+        # Now tell each app that it has been booted.
+        #
+        @apps.select { |app| app.respond_to?(:booted) }.each(&:booted)
+      end
+
+      if config.freeze_on_boot
+        deep_freeze unless unsafe
+      end
+
+      self
+    rescue StandardError => error
+      handle_boot_failure(error)
+    end
+
+    def register_framework(framework_name, framework_module)
+      @frameworks[framework_name] = framework_module
+    end
+
+    def app(app_name, path: "/", without: [], only: nil, mount: true, &block)
+      app_name = app_name.to_sym
+
+      if booted?
+        @apps.find { |app|
+          app.config.name == app_name
+        }
+      else
+        local_frameworks = (only || frameworks.keys) - Array.ensure(without)
+
+        Pakyow::App.make(Support::ObjectName.namespace(app_name, "app")) {
+          config.name = app_name
+          include_frameworks(*local_frameworks)
+        }.tap do |app|
+          app.define(&block) if block_given?
+          mount(app, at: path) if mount
+        end
+      end
+    end
+
+    def env?(name)
+      env == name.to_sym
+    end
+
+    def call(input)
+      config.connection_class.new(input).yield_self { |connection|
+        Async(logger: connection.logger) {
+          # Set the request logger as a thread-local variable for when there's no other way to access
+          # it. This originated when looking for a way to log queries with the request logger. By
+          # setting the request logger for the current connection as thread-local we can create a
+          # connection pointing to `Pakyow.logger`, an instance of `Pakyow::Logger::ThreadLocal`. The
+          # thread local logger decides at the time of logging which logger to use based on an
+          # available context, falling back to `Pakyow.global_logger`. This gets us around needing to
+          # configure a connection per request, altering Sequel's internals, and other oddities.
+          #
+          # Pakyow is designed so that the connection object and its logger should always be available
+          # anywhere you need it. If it isn't, reconsider the design before using the thread local.
+          #
+          Thread.current[:pakyow_logger] = connection.logger
+
+          catch :halt do
+            @pipeline.call(connection)
+          end
+        }.wait
+      }.finalize
+    rescue StandardError => error
+      Pakyow.logger.houston(error)
+
+      Async::HTTP::Protocol::Response.new(
+        nil, 500, {}, Async::HTTP::Body::Buffered.wrap(
+          StringIO.new("500 Low-Level Server Error")
+        )
+      )
+    end
+
+    # @api private
+    def load_tasks
+      require "rake"
+      require "pakyow/task"
+
+      @tasks = config.tasks.paths.uniq.each_with_object([]) do |tasks_path, tasks|
+        Dir.glob(File.join(File.expand_path(tasks_path), "**/*.rake")).each do |task_path|
+          tasks.concat(Pakyow::Task::Loader.new(task_path).__tasks)
+        end
+      end
+    end
+
+    # @api private
+    def initialize_app_for_mount(mount)
+      if mount[:app].ancestors.include?(Pakyow::App)
+        mount[:app].new(env, mount_path: mount[:path], &mount[:block])
+      else
+        mount[:app].new
+      end
+    end
+
+    private
+
+    def init_global_logger
+      destinations = Logger::Multiplexed.new(
+        *config.logger.destinations.map { |destination, io|
+          io.sync = config.logger.sync
+          Logger::Destination.new(destination, io)
+        }
+      )
+
+      @global_logger = config.logger.formatter.new(destinations)
+
+      @logger = Logger::ThreadLocal.new(
+        Logger.new("pkyw", output: @global_logger, level: config.logger.level)
+      )
+
+      Console.logger = Logger.new("asnc", output: @global_logger, level: :warn)
+    end
+
+    def ensure_setup_succeeded
+      if @setup_error
+        handle_boot_failure(@setup_error)
+      end
+    end
+
+    def handle_boot_failure(error)
+      @error = error
+
+      Support::Logging.safe do |logger|
+        logger.houston(error)
+      end
+
+      if config.exit_on_boot_failure
+        exit(false)
+      end
+    end
+  end
+end

data/lib/pakyow/error.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "method_source"
+
+require "pakyow/support/class_state"
+require "pakyow/support/cli/style"
+require "pakyow/support/dependencies"
+require "pakyow/support/inflector"
+require "pakyow/support/string_builder"
+
+module Pakyow
+  # Base error object.
+  #
+  class Error < StandardError
+    class << self
+      # Wraps an error in a pakyow error instance, with additional context.
+      #
+      def build(original_error, message_type = :default, context: nil, **message_values)
+        if original_error.is_a?(self)
+          original_error
+        else
+          message = message(message_type, **message_values)
+          message = original_error.message if message.empty?
+          new(message).tap do |error|
+            error.wrapped_exception = original_error
+            error.set_backtrace(original_error.backtrace)
+            error.context = context
+          end
+        end
+      end
+
+      # Initialize an error with a particular message.
+      #
+      def new_with_message(type = :default, **values)
+        new(message(type, **values))
+      end
+
+      private
+
+      def message(type = :default, **values)
+        if @messages.include?(type)
+          Support::StringBuilder.new(
+            @messages[type]
+          ).build(**values)
+        else
+          ""
+        end
+      end
+    end
+
+    extend Support::ClassState
+    class_state :messages, default: {}, inheritable: true
+
+    attr_accessor :wrapped_exception, :context
+
+    def initialize(*)
+      @context = nil
+
+      super
+    end
+
+    def cause
+      wrapped_exception || super
+    end
+
+    def name
+      Support.inflector.humanize(
+        Support.inflector.underscore(
+          Support.inflector.demodulize(self.class.name)
+        )
+      )
+    end
+
+    def details
+      if project? && location = project_backtrace_locations[0]
+        message = "`#{(cause || self).class}' occurred on line `#{location.lineno}' of `#{path}':"
+
+        begin
+          <<~MESSAGE
+            #{message}
+
+            #{indent_as_source(MethodSource.source_helper([path, location.lineno], location.label), location.lineno)}
+          MESSAGE
+        rescue StandardError
+          <<~MESSAGE
+            #{message}
+
+                Error parsing source.
+          MESSAGE
+        end
+      elsif location = (cause || self).backtrace_locations.to_a[0]
+        library_name = Support::Dependencies.library_name(location.absolute_path)
+        library_type = Support::Dependencies.library_type(location.absolute_path)
+
+        occurred_in = if library_type == :pakyow || library_name.start_with?("pakyow-")
+          "within the `#{library_name.split("-", 2)[1]}' framework"
+        elsif library_type == :gem || library_type == :bundler
+          "within the `#{library_name}' gem"
+        else
+          "somewhere within ruby itself"
+        end
+
+        <<~MESSAGE
+          `#{(cause || self).class}' occurred outside of your project, #{occurred_in}.
+        MESSAGE
+      else
+        <<~MESSAGE
+          `#{(cause || self).class}' occurred at an unknown location.
+        MESSAGE
+      end
+    end
+
+    # If the error occurred in the project, returns the relative path to where
+    # the error occurred. Otherwise returns the absolute path to where the
+    # error occurred.
+    #
+    def path
+      @path ||= if project?
+        Pathname.new(
+          File.expand_path(project_backtrace_locations[0].absolute_path.to_s)
+        ).relative_path_from(
+          Pathname.new(Pakyow.config.root)
+        ).to_s
+      else
+        File.expand_path(project_backtrace_locations[0].absolute_path.to_s)
+      end
+    end
+
+    # Returns true if the error occurred in the project.
+    #
+    def project?
+      File.expand_path(backtrace[0].to_s).start_with?(Pakyow.config.root)
+    end
+
+    # Returns the backtrace without any of the framework locations, unless the
+    # error originated from the framework. Return value is as an array of
+    # strings rather than backtrace location objects.
+    #
+    def condensed_backtrace
+      if project?
+        project_backtrace_locations.map { |line|
+          line.to_s.gsub(/^#{Pakyow.config.root}\//, "")
+        }
+      else
+        padded_length = backtrace.map { |line|
+          Support::Dependencies.library_name(line).to_s.gsub(/^pakyow-/, "")
+        }.max_by(&:length).length + 3
+
+        backtrace.map { |line|
+          modified_line = Support::Dependencies.strip_path_prefix(line)
+          if line.start_with?(Pakyow.config.root)
+            "› ".rjust(padded_length) + modified_line
+          elsif modified_line.start_with?("ruby")
+            "ruby | ".rjust(padded_length) + modified_line.split("/", 3)[2].to_s
+          else
+            "#{Support::Dependencies.library_name(line).to_s.gsub(/^pakyow-/, "")} | ".rjust(padded_length) + modified_line.split("/", 2)[1].to_s
+          end
+        }
+      end
+    end
+
+    private
+
+    def project_backtrace_locations
+      (cause || self).backtrace_locations.to_a.select { |line|
+        File.expand_path(line.absolute_path.to_s).start_with?(Pakyow.config.root)
+      }
+    end
+
+    def indent_as_code(message)
+      message.split("\n").map { |line|
+        "    #{line}"
+      }.join("\n")
+    end
+
+    def indent_as_source(message, lineno)
+      message.split("\n").each_with_index.map { |line, i|
+        start = String.new("    #{lineno + i}|")
+        if i == 0
+          start << "›"
+        else
+          start << " "
+        end
+        "#{start} #{line}"
+      }.join("\n")
+    end
+
+    # @api private
+    class CLIFormatter
+      def initialize(error)
+        @error = error
+      end
+
+      def to_s
+        <<~MESSAGE
+          #{message}
+
+          #{Support::CLI.style.black.on_white.bold(" DETAILS                                                                        ")}
+
+          #{details}
+
+          #{Support::CLI.style.black.on_white.bold(" BACKTRACE                                                                      ")}
+
+          #{backtrace}
+        MESSAGE
+      end
+
+      def header
+        start = " #{@error.name.upcase} "
+
+        finish = if @error.project?
+          File.basename(@error.path)
+        else
+          ""
+        end
+
+        "#{start}#{" " * (80 - (start.length + finish.length + 2))} #{finish} "
+      end
+
+      def message
+        message = Support::CLI.style.white.on_red.bold(header)
+        message_lines = @error.message.split("\n")
+        if message_lines.any?
+          message << "\n\n#{self.class.indent(Support::CLI.style.red("›") + Support::CLI.style.bright_black(" #{self.class.format(message_lines.shift)}"))}\n"
+          message_lines.each do |line|
+            message << Support::CLI.style.bright_black("\n#{line}")
+          end
+        end
+
+        if @error.respond_to?(:contextual_message)
+          message = <<~MESSAGE
+            #{message}
+            #{Support::CLI.style.bright_black(self.class.indent(self.class.format(@error.contextual_message)))}
+          MESSAGE
+        end
+
+        message.rstrip
+      end
+
+      def details
+        Support::CLI.style.bright_black(self.class.indent(self.class.format(@error.details)))
+      end
+
+      def backtrace
+        @error.condensed_backtrace.map(&:to_s).join("\n")
+      end
+
+      private
+
+      class << self
+        # @api private
+        def indent(message)
+          message.split("\n").map { |line|
+            "  #{line}"
+          }.join("\n")
+        end
+
+        # @api private
+        HIGHLIGHT_REGEX = /`([^']*)'/
+
+        # @api private
+        def format(message)
+          message.dup.tap do |message_to_format|
+            message.scan(HIGHLIGHT_REGEX).each do |match|
+              message_to_format.gsub!("`#{match[0]}'", Support::CLI.style.italic.blue(match[0]))
+            end
+          end
+        end
+      end
+    end
+  end
+end