monkrb 0.19.0 → 0.21.0

data/lib/monk/auth.rb

@@ -34,13 +34,18 @@ module Monk
         freeze_rqrcode!
       end
 
+      # callback_path: is where the app's own callback route redeems a
+      # token (GET "#{callback_path}/:token"). Monk doesn't define that
+      # route, but builds links to it: login_link below, and so
+      # Monk::Auth::SendLoginLink.
       def configure(
         db_name: nil, secret: nil, login_ttl: nil, session_ttl: nil, redirect_allowlist: [], secure: true,
-        deliver: nil
+        deliver: nil, callback_path: "/auth/callback"
       )
         config = {
           db_name: db_name, secret: secret, login_ttl: login_ttl, session_ttl: session_ttl,
           redirect_allowlist: redirect_allowlist, secure: secure, deliver: deliver,
+          callback_path: checked_callback_path(callback_path),
         }
 
         REQUIRED_CONFIG_KEYS.each do |key|
@@ -81,6 +86,17 @@ module Monk
         raw
       end
 
+      # The magic link for a raw token: the app's public_url
+      # (config/settings.rb, a trusted origin -- never request headers like
+      # X-Forwarded-Host, which any direct client can spoof), then
+      # callback_path:, then the token.
+      #
+      #   Monk::Auth.login_link(token) # => "https://app.example/auth/callback/<token>"
+      def login_link(token)
+        ensure_configured!
+        "#{Monk::Settings[:public_url]}#{config[:callback_path]}/#{token}"
+      end
+
       # The single place an app's login-request handler calls to get a
       # magic link to its owner: uses the `deliver:` callable passed to
       # `configure` (e.g. wrapping a mailer or a provider's HTTP API) when
@@ -94,10 +110,8 @@ module Monk
       # that Monk::Mail exists (docs/adr/0012-minimal-built-in-mailer.md):
       # it's usually a one-line Monk::Mail.deliver, but can be any channel.
       #
-      # `link` is the app's own job to build (Monk doesn't own routing, so
-      # it can't know the callback path) -- from a trusted origin, e.g.
-      # Monk::Settings[:public_url], never from request headers like
-      # X-Forwarded-Proto/Host, which any direct client can spoof.
+      # `link` is usually login_link(token), above. An app may build its
+      # own instead, from a trusted origin, never from request headers.
       # `token` is passed through for a deliver: that wants it (an SMS
       # body instead of a link, say); most won't need it.
       def deliver_link(email:, link:, token: nil)
@@ -254,6 +268,17 @@ module Monk
           "Monk::Auth is not configured -- call Monk::Auth.configure first" unless @config
       end
 
+      # An absolute path, kept without a trailing slash so login_link
+      # adds exactly one before the token.
+      def checked_callback_path(path)
+        unless path.is_a?(String) && path.start_with?("/")
+          raise Monk::InvalidAuthConfigError,
+            "Monk::Auth.configure(callback_path:) must be an absolute path like \"/auth/callback\", got #{path.inspect}"
+        end
+
+        path.chomp("/").freeze
+      end
+
       def hash_token(raw)
         Digest::SHA256.hexdigest(raw)
       end
@@ -299,3 +324,7 @@ module Monk
     Monk.freeze_hooks << self
   end
 end
+
+# Monk::Auth::SendLoginLink, when jobs are loaded too -- either order works
+# (lib/monk/jobs.rb ends the same way, docs/adr/0017).
+require_relative "auth/send_login_link" if Monk.const_defined?(:Jobs)

data/lib/monk/base.rb

@@ -12,6 +12,11 @@ module Monk
     EMPTY_ARRAY = [].freeze
     private_constant :EMPTY_ARRAY
 
+    # How much of an unhandled exception's backtrace #log_exception
+    # writes -- the same depth Monk::Jobs keeps for a failed job.
+    BACKTRACE_LINES = 10
+    private_constant :BACKTRACE_LINES
+
     # Action name -> path suffix (appended to the resource path) and verb(s)
     # it dispatches on, for #resources. :update registers both PATCH and PUT --
     # PATCH is the canonical partial-update verb, PUT accepted too since
@@ -162,6 +167,7 @@ module Monk
             [200, context.headers, [body]]
           rescue StandardError => e
             handler = error_handlers.find { |matcher, _| matcher.is_a?(Class) && e.is_a?(matcher) }
+            log_exception(env, e, handled: !handler.nil?)
             if handler
               context.status = 500
               body = context.instance_exec(context, &handler.last)
@@ -173,6 +179,20 @@ module Monk
         end
       end
 
+      # The request line alone ("GET /x -> 500") says nothing about why.
+      # Unhandled: an error, with the first backtrace lines. Handled by an
+      # `error` block: the app chose the response, so one info line --
+      # an error(NotFound) { halt 404 } shouldn't fill the log with ERRORs.
+      def log_exception(env, error, handled:)
+        line = "#{env["REQUEST_METHOD"]} #{env["PATH_INFO"]} raised #{error.class}: #{error.message}"
+        if handled
+          Monk::Log.info("#{line} (handled)")
+        else
+          trace = Array(error.backtrace).first(BACKTRACE_LINES).map { |frame| "\n  #{frame}" }
+          Monk::Log.error("#{line}#{trace.join}")
+        end
+      end
+
       def log_request(env, status, start)
         duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
         line = "#{Monk::Log.timestamp} #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]} -> #{status} (#{duration_ms}ms)"

data/lib/monk/bin.rb

@@ -0,0 +1,107 @@
+module Monk
+  # What a scaffolded app's bin/ scripts run their work in:
+  #
+  #   Monk::Bin.run(__FILE__) do
+  #     require_relative "../config/persistence"
+  #     ...
+  #   end
+  #
+  # An unreachable Postgres or Redis, a missing database, refused
+  # credentials or an unset setting end the script with what failed, which
+  # setting decides it, and the commands that fix it (the same as SETUP.md),
+  # on stderr, exit 1 -- not a backtrace. Anything else is re-raised as it
+  # is. Errors are recognized by class name, so this file loads neither pg
+  # nor redis (docs/adr/0017).
+  module Bin
+    class << self
+      def run(script)
+        yield
+      rescue StandardError => e
+        message = explain(e, script)
+        raise unless message
+
+        # Not warn: it prints nothing when $VERBOSE is nil (ruby -W0), and
+        # this message is the whole point of the failure.
+        $stderr.puts message # rubocop:disable Style/StderrPuts
+        exit 1
+      end
+
+      # The explanation for an error, or nil when it's not one of the above.
+      def explain(error, script)
+        context = Context.for(script)
+
+        case error.class.name
+        when "PG::ConnectionBad" then postgres(error, context)
+        when "Redis::CannotConnectError" then redis(context)
+        when "Monk::WebSocket::ListenError" then fanout(error, context)
+        when "Monk::MissingSettingError" then missing_setting(error.message[/ENV\["([^"]+)"\]/, 1], context)
+        when "KeyError" then missing_setting(error.key, context) if error.receiver.equal?(ENV)
+        end
+      end
+
+      private
+
+      def postgres(error, context)
+        host = error.message[/server at "([^"]+)"/, 1] || ENV.fetch("DB_HOST", "127.0.0.1")
+        port = error.message[/port (\d+)/, 1] || ENV.fetch("DB_PORT", "5432")
+        at = "Postgres at #{host}:#{port}"
+
+        if (database = error.message[/database "([^"]+)" does not exist/, 1])
+          context.message("database \"#{database}\" doesn't exist on #{at} (DB_NAME in .env).",
+            "Create it (it asks for DB_PASSWORD), then run #{context.name} again -- SETUP.md:",
+            "createdb -h #{host} -p #{port} -U #{ENV.fetch("DB_USER", "postgres")} #{database}",)
+        elsif (user = error.message[/authentication failed for user "([^"]+)"/, 1])
+          context.message("#{at} refused user \"#{user}\" (DB_USER/DB_PASSWORD in .env).",
+            "Check them, then run #{context.name} again.",)
+        elsif error.message.include?("Connection refused")
+          context.message("can't connect to #{at} (DB_HOST/DB_PORT in .env).",
+            "Start it, then run #{context.name} again -- SETUP.md:",
+            "docker run --rm -d -p #{port}:5432 -e POSTGRES_PASSWORD=postgres --name #{context.app}_pg postgres:16",)
+        else
+          context.message("can't connect to #{at} (DB_* in .env): #{error.message.lines.first.strip}")
+        end
+      end
+
+      # The WS process's subscriber connection, opened by listen! at boot.
+      def fanout(error, context)
+        if error.message.include?("RedisFanout")
+          redis(context)
+        elsif error.message.include?("PgFanout")
+          postgres(error, context)
+        end
+      end
+
+      def redis(context)
+        url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+        port = url[%r{//[^/]*:(\d+)}, 1] || "6379"
+        shown = url.sub(%r{//([^@/]*):[^@/]*@}, '//\1:***@') # never the password
+        context.message("can't connect to Redis at #{shown} (REDIS_URL in .env).",
+          "Start it, then run #{context.name} again -- SETUP.md:",
+          "docker run --rm -d -p #{port}:6379 --name #{context.app}_redis redis:7",)
+      end
+
+      def missing_setting(name, context)
+        return unless name
+
+        context.message("#{name} is not set.",
+          "Set it in .env (development) or the environment, then run #{context.name} again.",)
+      end
+    end
+
+    # The script being run: its name as typed from the app's root
+    # (bin/setup_db), and the app's directory name, which SETUP.md's
+    # container names use.
+    Context = Data.define(:name, :app) do
+      def self.for(script)
+        path = File.expand_path(script)
+        new(name: "bin/#{File.basename(path)}", app: File.basename(File.dirname(path, 2)))
+      end
+
+      # The first line says what failed; the next, what to do; the last,
+      # if there's one, is the command to run.
+      def message(what, todo = nil, command = nil)
+        ["#{name}: #{what}", todo, ("  #{command}" if command)].compact.join("\n")
+      end
+    end
+  end
+end

data/lib/monk/cli.rb

@@ -0,0 +1,277 @@
+require "json"
+require "fileutils"
+require_relative "generators"
+
+module Monk
+  # What exe/monk runs (docs/history/plan-scaffold.md Phase 5): `monk new`,
+  # `monk add`, `monk add --list`, `monk help`. Each answers in text, or
+  # as one JSON object with --json, and returns the exit code: 0 done,
+  # 1 usage error, 2 a missing choice, 3 a conflict on a wiring file
+  # (decision 28). It never prompts without a terminal (decision 23).
+  class CLI
+    Error = Class.new(StandardError) do
+      attr_reader :suggestion
+
+      def initialize(message, suggestion: nil)
+        @suggestion = suggestion
+        super(message)
+      end
+    end
+
+    # `monk new`'s flags before docs/adr/0017, in the order --with lists
+    # them. Each is a usage error now, showing the command to type instead.
+    OLD_FLAGS = %w[postgres auth mail jobs redis live].freeze
+
+    USAGE = <<~TEXT.freeze
+      Usage:
+        monk new NAME [--with a,b] [options]   create an app, with modules
+        monk add MODULE... [options]           add modules to the app here
+        monk add --list                        the modules, and which are installed
+        monk help [MODULE] [--file PATH]       this, a module's details, or Monk's version of one of its files
+
+      Options:
+        --transport=postgres|redis   websocket's transport (inferred when only one is installed)
+        --no-demo                    live without its demo
+        --dry-run                    say what would be written, and write nothing
+        --json                       answer as one JSON object
+    TEXT
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd, registry: Generator.registry,
+                   now: Time.now)
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @cwd = cwd
+      @registry = registry
+      @now = now
+    end
+
+    def run(argv)
+      command, *args = argv
+      @args = parse(args)
+      case command
+      when nil, "help", "--help", "-h" then help
+      when "new" then new_app
+      when "add" then @args[:list] ? list : add
+      else raise Error.new("Unknown command: #{command}.", suggestion: "monk help")
+      end
+    rescue Error => e
+      report(Generator::Result.new(status: :usage_error, written: false, message: e.message, suggestion: e.suggestion))
+    end
+
+    private
+
+    def parse(args)
+      parsed = { positional: [], options: {}, with: [], old: [] }
+      args = args.dup
+      until args.empty?
+        arg = args.shift
+        case arg
+        when "--json" then parsed[:json] = true
+        when "--dry-run" then parsed[:dry_run] = true
+        when "--list" then parsed[:list] = true
+        when "--no-demo" then parsed[:options][:demo] = "off"
+        when /\A--(with|transport|file)(?:=(.*))?\z/
+          value = Regexp.last_match(2) || args.shift || raise(Error, "--#{Regexp.last_match(1)} needs a value.")
+          key = Regexp.last_match(1).to_sym
+          case key
+          when :with then parsed[:with].concat(value.split(",").map(&:strip).reject(&:empty?).map(&:to_sym))
+          when :transport then parsed[:options][:transport] = value
+          else parsed[:file] = value
+          end
+        when /\A--(#{OLD_FLAGS.join("|")})\z/ then parsed[:old] << Regexp.last_match(1)
+        when /\A-/ then raise Error.new("Unknown option: #{arg}.", suggestion: "monk help")
+        else parsed[:positional] << arg
+        end
+      end
+      parsed
+    end
+
+    def new_app
+      name = @args[:positional].first || raise(Error.new("monk new needs a name.", suggestion: "monk new my_app"))
+      old_flags!(name)
+      dir = File.expand_path(name, @cwd)
+      raise Error.new("#{name} already exists.", suggestion: "cd #{name} && monk add <module>") if File.exist?(dir)
+
+      FileUtils.mkdir_p(dir) unless @args[:dry_run]
+      command = "monk new #{name}#{" --with #{@args[:with].join(",")}" unless @args[:with].empty?}"
+      result = run_generators(dir, [:base, *@args[:with]], command)
+      FileUtils.rm_rf(dir) if !result.ok? && !@args[:dry_run]
+      report(result, app: name)
+    end
+
+    def add
+      modules = @args[:positional].map(&:to_sym)
+      raise Error.new("monk add needs a module.", suggestion: "monk add --list") if modules.empty?
+      unless monk_app?
+        raise Error.new("This isn't a Monk app (no config/load.rb here).",
+          suggestion: "monk new my_app, or cd into your app",)
+      end
+
+      report(run_generators(@cwd, modules, "monk add #{modules.join(" ")}"))
+    end
+
+    # A choice the result says is missing is asked for, in a terminal only,
+    # then the run starts over with it.
+    def run_generators(dir, modules, command)
+      options = @args[:options].dup
+      loop do
+        result = @registry.add(dir, modules, options: options, dry_run: @args[:dry_run], now: @now, command: command)
+        return result unless result.status == :missing_choice && interactive?
+
+        value = ask(result)
+        return result unless value
+
+        options[result.choice[:option].to_sym] = value
+      end
+    end
+
+    def interactive?
+      !@args[:json] && @stdin.respond_to?(:tty?) && @stdin.tty?
+    end
+
+    def ask(result)
+      choice = result.choice
+      @stdout.puts result.message, ""
+      width = choice[:values].map(&:size).max
+      choice[:values].each_with_index do |value, index|
+        @stdout.puts "  #{index + 1}) #{value.ljust(width)}   #{choice[:describe]&.fetch(value, nil)}".rstrip
+      end
+      @stdout.print "\n#{choice[:option].capitalize} [#{(1..choice[:values].size).to_a.join("/")}]: "
+      answer = @stdin.gets&.strip.to_s
+      number = answer.match?(/\A\d+\z/) ? answer.to_i : 0
+      value = number.between?(1, choice[:values].size) ? choice[:values][number - 1] : nil
+      value ||= answer if choice[:values].include?(answer)
+      @stdout.puts "# Using --#{choice[:option]}=#{value} skips this question." if value
+      value
+    end
+
+    def old_flags!(name)
+      return if @args[:old].empty?
+
+      old = @args[:old]
+      transport = (%w[redis postgres] & old).first if old.include?("live")
+      with = (OLD_FLAGS & old) - [transport]
+      new_form = "monk new #{name} --with #{with.join(",")}#{" --transport=#{transport}" if transport}"
+      raise Error.new("monk new no longer takes module flags. The same command is now:", suggestion: new_form)
+    end
+
+    def monk_app? = File.exist?(File.join(@cwd, "config/load.rb"))
+
+    def list
+      installed = monk_app? ? @registry.definitions.select { |d| File.exist?(File.join(@cwd, d.installed_if)) } : []
+      rows = @registry.definitions.reject { |definition| definition.name == :base }.map do |definition|
+        list_row(definition, installed.include?(definition))
+      end
+      if @args[:json]
+        @stdout.puts JSON.pretty_generate(modules: rows)
+      else
+        @stdout.puts "Modules#{" (✓ installed)" if monk_app?}", ""
+        width = rows.map { |row| row[:name].size }.max
+        rows.each do |row|
+          needs = row[:needs].empty? ? row[:needs_one_of] : row[:needs]
+          needs_text = "  (needs #{needs.join(row[:needs].empty? ? " or " : ", ")})" unless needs.empty?
+          @stdout.puts "  #{row[:installed] ? "✓" : " "} #{row[:name].ljust(width)}   #{row[:summary]}#{needs_text}"
+        end
+        @stdout.puts "", "Add one: monk add <module>      Details: monk help <module>"
+      end
+      0
+    end
+
+    def list_row(definition, installed)
+      dependency_options = definition.options.select { |option| definition.dependency_options.include?(option.name) }
+      {
+        name: definition.name.to_s, summary: definition.summary, installed: installed,
+        needs: definition.dependencies.map(&:to_s), needs_one_of: dependency_options.flat_map(&:values),
+        options: definition.options.to_h { |option| [option.name, option.values] },
+      }
+    end
+
+    def help
+      name = @args[:positional].first
+      return general_help unless name
+
+      definition = @registry.names.include?(name.to_sym) ? @registry.fetch(name) : nil
+      raise Error.new("Unknown module: #{name}.", suggestion: "monk add --list") unless definition
+      return file_help(definition) if @args[:file]
+
+      module_help(definition)
+    end
+
+    def general_help
+      @stdout.puts USAGE, "Modules:"
+      @registry.definitions.reject { |definition| definition.name == :base }.each do |definition|
+        @stdout.puts "  #{definition.name.to_s.ljust(10)} #{definition.summary}"
+      end
+      0
+    end
+
+    def module_help(definition)
+      @stdout.puts "#{definition.name}: #{definition.summary}"
+      @stdout.puts "Needs: #{definition.dependencies.join(", ")}" unless definition.dependencies.empty?
+      definition.options.each do |option|
+        default = " (default #{option.default})" if option.default
+        @stdout.puts "Option --#{option.name}: #{option.values.join(", ")}#{default}"
+      end
+      @stdout.puts "", "Writes:"
+      definition.copies.each { |copy| @stdout.puts "  #{copy.path.ljust(32)} #{copy.role}" }
+      definition.migrations.each do |migration|
+        @stdout.puts "  db/migrate/<timestamp>_#{migration.name}.{up,down}.sql  wiring"
+      end
+      @stdout.puts "", "Monk's version of one of these: monk help #{definition.name} --file PATH"
+      0
+    end
+
+    # Monk's version of one of a module's files, for a file the app already
+    # had (a conflict, docs/history/plan-scaffold.md decision 26).
+    def file_help(definition)
+      path = @args[:file]
+      source = migration_template(definition, path) || copy_template(definition, path)
+      unless source
+        raise Error.new("#{definition.name} doesn't write #{path}.", suggestion: "monk help #{definition.name}")
+      end
+
+      @stdout.print File.read(source)
+      0
+    end
+
+    def migration_template(definition, path)
+      migration = definition.migrations.find { |m| path.match?(/_#{Regexp.escape(m.name)}\.(up|down)\.sql\z/) }
+      return unless migration
+
+      pattern = "db/migrate/*_#{migration.name}.#{path[/\.(up|down)\.sql\z/, 1]}.sql"
+      Dir[File.join(@registry.templates_dir, definition.name.to_s, pattern)].first
+    end
+
+    def copy_template(definition, path)
+      copy = definition.copies.find { |candidate| candidate.path == path }
+      File.join(@registry.templates_dir, template_for_copy(definition, copy)) if copy
+    end
+
+    def template_for_copy(definition, copy)
+      return "#{definition.name}/#{copy.path}" unless copy.from
+      return copy.from unless copy.from.respond_to?(:call)
+
+      options = definition.options.to_h { |option| [option.name, @args[:options][option.name] || option.default] }
+      missing = definition.options.find { |option| options[option.name].nil? }
+      if missing
+        raise Error.new("#{copy.path} depends on --#{missing.name}.",
+          suggestion: "monk help #{definition.name} --file #{copy.path} --#{missing.name}=#{missing.values.first}",)
+      end
+      copy.from.call(options)
+    end
+
+    def report(result, app: nil)
+      if @args&.fetch(:json, false)
+        hash = result.to_h
+        hash["app"] = app if app
+        @stdout.puts JSON.pretty_generate(hash)
+      elsif result.ok?
+        @stdout.print app ? result.new_text(app) : result.to_text
+      else
+        @stderr.print result.to_text
+      end
+      result.exit_code
+    end
+  end
+end

data/lib/monk/context.rb

@@ -4,8 +4,18 @@ require_relative "views"
 require_relative "assets"
 
 module Monk
+  # The base of Context#head_tags: no tags. A module's helpers, included
+  # into Context after this, add theirs with `def head_tags = super + [...]`
+  # (Monk::Live::Helpers does), so a layout's <%= monk_head %> renders
+  # every loaded module's tags and adding a module never edits the layout
+  # (docs/adr/0017).
+  module HeadTags
+    def head_tags = []
+  end
+
   class Context
     include Monk::Views::Compiled
+    include Monk::HeadTags
 
     attr_reader :params, :env, :headers
     attr_accessor :status
@@ -68,6 +78,13 @@ module Monk
       Monk::Assets.path_for(path)
     end
 
+    # Every loaded module's <head> tags, one per line, for the layout:
+    #   <head> ... <%= monk_head %> </head>
+    # Each tag is built by Monk, which escapes what it interpolates.
+    def monk_head
+      raw(head_tags.join("\n"))
+    end
+
     # Same frozen values Monk::Settings[] reads, e.g. `settings[:api_key]`
     # -- returns the module itself rather than duplicating its #[] here,
     # so an undeclared key raises the exact same way through either path.

data/lib/monk/errors.rb

@@ -31,10 +31,4 @@ module Monk
 
   class TemplateSyntaxError < StandardError
   end
-
-  class ScaffoldExistsError < StandardError
-  end
-
-  class AmbiguousLiveTransportError < StandardError
-  end
 end