gemstack 0.2.5 → 0.3.0

data/lib/gemstack/mail.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "mail"
+require "erubi"
+require "uri"
+require "gemstack/core"
+
+module GemStack
+  # Email.
+  #
+  #   class AccountMailer < GemStack::Mailer
+  #     default from: "Shop <hello@shop.test>"
+  #
+  #     def welcome(user_id)
+  #       @user = User.find(user_id)
+  #       mail to: @user.email, subject: "Welcome!" # templates/account_mailer/welcome.{text,html}.erb
+  #     end
+  #   end
+  #
+  #   AccountMailer.welcome(user.id).deliver_later   # through GemStack::Jobs (pass ids)
+  #   AccountMailer.welcome(user.id).deliver_now
+  module Mail
+    class Config < Settings
+      # :smtp (production), :log (development: logged and saved to tmp/mail),
+      # :test (captured in GemStack::Mail.deliveries), or an object with #deliver(message).
+      setting :delivery, default: lambda {
+        if GemStack.env.test? then :test
+        elsif GemStack.env.development? then :log
+        else :smtp
+        end
+      }
+      # smtp://user:password@smtp.example.com:587 (STARTTLS) or smtps://…:465
+      setting :smtp_url, default: -> { ENV.fetch("SMTP_URL", nil) }
+      setting :default_from, default: -> { ENV.fetch("MAIL_FROM", "#{GemStack.config.name} <no-reply@localhost>") }
+      setting :templates_path, default: "app/mailers/templates"
+      setting :preview_dir, default: "tmp/mail"
+      # Queue used by deliver_later.
+      setting :queue, default: "mailers"
+    end
+
+    class DeliveryError < Error; end
+
+    # Loaded on first use, also by a jobs worker resolving the queued class name.
+    autoload :DeliveryJob, "gemstack/mail/delivery_job"
+
+    @deliveries = []
+    @mutex = Mutex.new
+
+    class << self
+      def config = GemStack.config.mail
+
+      # Messages delivered with the :test method.
+      attr_reader :deliveries
+
+      def deliver(message)
+        method = config.delivery
+        case method
+        when :test, "test" then @mutex.synchronize { @deliveries << message }
+        when :log, "log" then deliver_to_log(message)
+        when :smtp, "smtp" then deliver_smtp(message)
+        else
+          unless method.respond_to?(:deliver)
+            raise ConfigurationError,
+                  "a mail delivery method must respond to #deliver"
+          end
+
+          method.deliver(message)
+        end
+        GemStack.logger.info("mail.delivered", to: Array(message.to).join(","), subject: message.subject,
+                                               via: method.is_a?(Symbol) ? method : method.class.name)
+        message
+      end
+
+      def smtp_settings(url = config.smtp_url)
+        if url.to_s.empty?
+          raise ConfigurationError,
+                "set SMTP_URL (e.g. smtp://user:pass@smtp.example.com:587) to send mail"
+        end
+
+        uri = URI.parse(url)
+        {
+          address: uri.host, port: uri.port || (uri.scheme == "smtps" ? 465 : 587),
+          user_name: uri.user && URI.decode_www_form_component(uri.user),
+          password: uri.password && URI.decode_www_form_component(uri.password),
+          authentication: uri.user ? :plain : nil, tls: uri.scheme == "smtps",
+          enable_starttls_auto: uri.scheme != "smtps", open_timeout: 5, read_timeout: 10
+        }.compact
+      end
+
+      private
+
+      def deliver_smtp(message)
+        message.delivery_method(:smtp, smtp_settings)
+        message.deliver
+      rescue Net::SMTPError, SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        raise DeliveryError, "SMTP delivery failed: #{e.class}: #{e.message}"
+      end
+
+      # Development: a log line plus a copy on disk (.eml, and .html to open in a browser).
+      def deliver_to_log(message)
+        dir = File.expand_path(config.preview_dir, GemStack.config.root)
+        FileUtils.mkdir_p(dir)
+        slug = message.subject.to_s.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-")[0, 40]
+        base = File.join(dir, "#{Time.now.strftime("%Y%m%d-%H%M%S-%L")}-#{slug}")
+        File.write("#{base}.eml", message.to_s)
+        html = message.html_part&.decoded
+        File.write("#{base}.html", html) if html
+        GemStack.logger.info("mail saved", to: Array(message.to).join(","), subject: message.subject,
+                                           file: "#{base}#{".html" if html}")
+      end
+    end
+  end
+
+  # Base class for mailers. Public instance methods are mail "actions";
+  # calling one on the class returns a Delivery. An action that returns
+  # without calling `mail` sends nothing (e.g. the user was deleted since).
+  class Mailer
+    # Rendered as the value of @variables set in the action.
+    class TemplateContext
+      def initialize(mailer)
+        mailer.instance_variables.each { |ivar| instance_variable_set(ivar, mailer.instance_variable_get(ivar)) }
+      end
+
+      def render(source, escape:) = instance_eval(Erubi::Engine.new(source, escape: escape).src)
+    end
+
+    # A message waiting to be delivered.
+    class Delivery
+      attr_reader :mailer_class, :action, :args
+
+      def initialize(mailer_class, action, args)
+        @mailer_class = mailer_class
+        @action = action
+        @args = args
+      end
+
+      def message
+        return @message if defined?(@message)
+
+        @message = mailer_class.new.build(action, args)
+      end
+
+      # nil when the action decided not to send (it returned without calling mail).
+      def deliver_now
+        msg = message
+        msg && Mail.deliver(msg)
+      end
+
+      # Delivers from a background job (arguments must be JSON values — pass ids).
+      def deliver_later(wait: nil)
+        require "gemstack/jobs" # part of the gemstack gem; loaded here if config/app.rb doesn't
+        job = wait ? Mail::DeliveryJob.set(wait: wait) : Mail::DeliveryJob
+        job.perform_later(mailer_class.name, action.to_s, args)
+      end
+    end
+
+    class << self
+      def default(**headers) = defaults.merge!(headers.transform_keys(&:to_sym))
+      def defaults = @defaults ||= superclass.respond_to?(:defaults) ? superclass.defaults.dup : {}
+
+      def actions
+        (public_instance_methods(true) - Mailer.public_instance_methods(true)).map(&:to_s)
+      end
+
+      def respond_to_missing?(name, include_private = false) = actions.include?(name.to_s) || super
+
+      def method_missing(name, *args)
+        return super unless actions.include?(name.to_s)
+
+        Delivery.new(self, name.to_s, args)
+      end
+    end
+
+    def build(action, args)
+      @action = action
+      public_send(action, *args)
+      GemStack.logger.debug("mail skipped", mailer: self.class.name, action: action) unless @message
+      @message
+    end
+
+    # Builds the message. Bodies come from text:/html: or, when omitted, from
+    # templates: <templates_path>/<mailer>/<action>.text.erb and .html.erb
+    # (HTML templates escape <%= %> output; use <%== %> for trusted markup).
+    def mail(to:, subject:, text: nil, html: nil, from: nil, cc: nil, bcc: nil, reply_to: nil, template: @action)
+      headers = self.class.defaults
+      text ||= render_template(template, "text", escape: false)
+      html ||= render_template(template, "html", escape: true)
+      raise Error, "#{self.class.name}##{@action}: no body (give text:/html: or add a template)" unless text || html
+
+      @message = build_message(to: to, subject: subject, text: text, html: html,
+                               from: from || headers[:from] || Mail.config.default_from, cc: cc, bcc: bcc,
+                               reply_to: reply_to || headers[:reply_to])
+    end
+
+    private
+
+    def render_template(name, format, escape:)
+      path = File.join(GemStack.config.root, Mail.config.templates_path, Inflector.underscore(self.class.name),
+                       "#{name}.#{format}.erb")
+      return nil unless File.file?(path)
+
+      TemplateContext.new(self).render(File.read(path), escape: escape)
+    end
+
+    def build_message(to:, subject:, text:, html:, from:, cc:, bcc:, reply_to:)
+      message = ::Mail.new
+      message.from = from
+      message.to = to
+      message.cc = cc if cc
+      message.bcc = bcc if bcc
+      message.reply_to = reply_to if reply_to
+      message.subject = subject
+      if text
+        message.text_part = ::Mail::Part.new do
+          body text
+          content_type "text/plain; charset=UTF-8"
+        end
+      end
+      if html
+        message.html_part = ::Mail::Part.new do
+          body html
+          content_type "text/html; charset=UTF-8"
+        end
+      end
+      message
+    end
+  end
+end
+
+GemStack::Config.namespace(:mail, GemStack::Mail::Config)

data/lib/gemstack/plugins.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Registry through which optional modules hook into application boot
+  # without the core (or the umbrella gem) knowing about them in advance.
+  #
+  #   # inside a module such as gemstack/jobs:
+  #   GemStack::Plugins.register(:jobs) do |app|
+  #     app.config.http.middleware.use GemStack::Jobs::Middleware
+  #     app.on_shutdown { GemStack::Jobs.stop }
+  #   end
+  #
+  # Hooks run once per boot, after configuration files are loaded and before
+  # the application is built, in registration order.
+  module Plugins
+    Plugin = Struct.new(:name, :hook)
+
+    @registry = {}
+    @mutex = Mutex.new
+
+    class << self
+      def register(name, &hook)
+        raise ArgumentError, "plugin #{name.inspect} needs a block" unless hook
+
+        @mutex.synchronize { @registry[name.to_sym] = Plugin.new(name.to_sym, hook) }
+      end
+
+      def unregister(name) = @mutex.synchronize { @registry.delete(name.to_sym) }
+      def registered?(name) = @registry.key?(name.to_sym)
+      def names = @registry.keys
+      def each(&) = @registry.values.each(&)
+
+      def run(app)
+        each { |plugin| plugin.hook.call(app) }
+      end
+    end
+  end
+end

data/lib/gemstack/schema.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "gemstack/core"
+require_relative "types"
+
+module GemStack
+  # Declarative input validation and coercion.
+  #
+  #   class ProductInput < GemStack::Schema
+  #     required :name, :string, max_length: 120
+  #     required :price, :decimal, gt: 0
+  #     optional :active, :boolean, default: true
+  #     optional :tags, [:string]
+  #     optional :dimensions do
+  #       required :width, :integer
+  #     end
+  #   end
+  #
+  #   ProductInput.call(params)   # => { name: "Lamp", price: 0.999e1, active: true }
+  #                               # or raises GemStack::ValidationError (422) with
+  #                               #    errors: { "price" => ["must be greater than 0"] }
+  #
+  # - Output has symbol keys and only declared fields (an allow-list).
+  # - Values are coerced to their type ("12" → 12 for :integer).
+  # - For non-string types an empty string counts as "not given" (HTML forms).
+  # - A required string that is blank is reported as "is required".
+  # - Error keys are paths: "dimensions.width", "tags.2".
+  class Schema
+    Field = Struct.new(:name, :type, :required, :nullable, :default, :rules, :schema, :array, keyword_init: true) do
+      def default? = !default.equal?(NO_DEFAULT)
+      def default_value = default.respond_to?(:call) ? default.call : default
+      def ts_optional? = !required && !default?
+    end
+
+    NO_DEFAULT = Object.new.freeze
+    RULES = %i[gt gte lt lte min_length max_length in format].freeze
+    STRING_TYPES = %i[string text].freeze
+
+    # rule => [passes?(value, arg), message(arg)]
+    RULE_CHECKS = {
+      gt: [->(v, a) { v > a }, ->(a) { "must be greater than #{a}" }],
+      gte: [->(v, a) { v >= a }, ->(a) { "must be greater than or equal to #{a}" }],
+      lt: [->(v, a) { v < a }, ->(a) { "must be less than #{a}" }],
+      lte: [->(v, a) { v <= a }, ->(a) { "must be less than or equal to #{a}" }],
+      min_length: [->(v, a) { v.to_s.length >= a }, ->(a) { "is too short (minimum #{a} characters)" }],
+      max_length: [->(v, a) { v.to_s.length <= a }, ->(a) { "is too long (maximum #{a} characters)" }],
+      in: [->(v, a) { a.include?(v) }, ->(a) { "must be one of: #{a.to_a.join(", ")}" }],
+      format: [->(v, a) { a.match?(v.to_s) }, ->(_) { "is invalid" }]
+    }.freeze
+
+    class << self
+      def fields
+        @fields ||= superclass.respond_to?(:fields) ? superclass.fields.dup : {}
+      end
+
+      # Name used for this schema's TypeScript/OpenAPI type.
+      attr_writer :type_name
+
+      def type_name
+        @type_name || name&.split("::")&.join
+      end
+
+      def required(name, type = nil, **options, &) = add_field(name, type, true, options, &)
+      def optional(name, type = nil, **options, &) = add_field(name, type, false, options, &)
+
+      # An anonymous schema from a block: Schema.define { required :q, :string }
+      def define(type_name = nil, &)
+        Class.new(self) do
+          self.type_name = type_name
+          class_exec(&)
+        end
+      end
+
+      # Every field optional and without defaults — for PATCH-style updates.
+      def partial(type_name = nil)
+        source = self
+        Class.new(Schema) do
+          self.type_name = type_name
+          source.fields.each_value do |field|
+            fields[field.name] = field.dup.tap do |copy|
+              copy.required = false
+              copy.default = NO_DEFAULT
+            end
+          end
+        end
+      end
+
+      # A schema derived from a model's field declarations (anything that
+      # responds to #gemstack_fields → { name => field with #type and #options }).
+      # Fields that are NOT NULL without a default become required.
+      def from_model(model, only: nil, except: nil, type_name: nil)
+        declared = model.gemstack_fields
+        names = only ? Array(only).map(&:to_sym) : declared.keys
+        names -= Array(except).map(&:to_sym)
+        define(type_name) do
+          names.each do |name|
+            field = declared.fetch(name) { raise ArgumentError, "#{model} has no field #{name.inspect}" }
+            opts = field.options
+            rules = opts.slice(*RULES)
+            rules[:max_length] ||= opts[:size] if opts[:size].is_a?(Integer)
+            required = opts[:null] == false && !opts.key?(:default) && field.type != :boolean
+            add_field(name, field.type, required, rules.merge(nullable: opts[:null] != false))
+          end
+        end
+      end
+
+      def call(input)
+        errors = {}
+        result = coerce_object(input, nil, errors)
+        raise ValidationError.new(errors: errors) unless errors.empty?
+
+        result
+      end
+
+      # Like #call but returns [result, errors] instead of raising.
+      def validate(input)
+        errors = {}
+        result = coerce_object(input, nil, errors)
+        [errors.empty? ? result : nil, errors]
+      end
+
+      def coerce_object(input, path, errors)
+        input = normalize_input(input)
+        unless input.is_a?(Hash)
+          errors[path || "base"] = ["must be an object"]
+          return nil
+        end
+
+        fields.each_value.with_object({}) do |field, output|
+          coerce_field(field, input, path, output, errors)
+        end
+      end
+
+      private
+
+      def add_field(name, type, required, options, &block)
+        options = options.dup
+        nullable = options.delete(:nullable) || false
+        default = options.key?(:default) ? options.delete(:default) : NO_DEFAULT
+        unknown = options.keys - RULES
+        raise ArgumentError, "unknown option(s) #{unknown.inspect} for #{name}" unless unknown.empty?
+
+        array = false
+        schema = nil
+        if type.is_a?(Array)
+          array = true
+          type = type.first
+        elsif type == :array
+          array = true
+          type = nil
+        end
+        if block
+          schema = Schema.define(&block)
+          type = nil
+        elsif type.is_a?(Class) && type <= Schema
+          schema = type
+          type = nil
+        elsif type.nil?
+          raise ArgumentError, "#{name}: give a type (e.g. :string) or a block"
+        else
+          Types.fetch(type) # validate early
+          type = Types::CLASS_ALIASES.fetch(type, type).to_sym
+        end
+
+        fields[name.to_sym] = Field.new(name: name.to_sym, type: type, required: required, nullable: nullable,
+                                        default: default, rules: options.freeze, schema: schema, array: array)
+      end
+
+      # absent → default or omitted; required + absent/nil/blank → "is required";
+      # explicit null → nil when nullable, otherwise "can't be null".
+      def coerce_field(field, input, path, output, errors)
+        key = field.name.to_s
+        field_path = path ? "#{path}.#{key}" : key
+        value = input[key]
+        present = input.key?(key) && !empty_form_value?(field, value)
+
+        if field.required && (!present || value.nil? || blank_string?(value))
+          missing_required(field, present, field_path, output, errors)
+        elsif !present
+          output[field.name] = field.default_value if field.default?
+        else
+          coerce_present(field, value, field_path, output, errors)
+        end
+      end
+
+      def coerce_present(field, value, path, output, errors)
+        if value.nil?
+          field.nullable ? output[field.name] = nil : (errors[path] ||= []) << "can't be null"
+        else
+          coerced = coerce_value(field, value, path, errors)
+          output[field.name] = coerced unless coerced.equal?(NO_DEFAULT)
+        end
+      end
+
+      def missing_required(field, present, path, output, errors)
+        return output[field.name] = field.default_value if field.default? && !present
+
+        (errors[path] ||= []) << "is required"
+      end
+
+      def coerce_value(field, value, path, errors)
+        return coerce_array(field, value, path, errors) if field.array
+
+        coerce_single(field, value, path, errors)
+      end
+
+      def coerce_array(field, value, path, errors)
+        value = value.values if value.is_a?(Hash) && value.keys.all? { |k| k.to_s.match?(/\A\d+\z/) } # form arrays
+        unless value.is_a?(Array)
+          (errors[path] ||= []) << "must be a list"
+          return NO_DEFAULT
+        end
+
+        value.each_with_index.map { |item, index| coerce_single(field, item, "#{path}.#{index}", errors) }
+      end
+
+      def coerce_single(field, value, path, errors)
+        return field.schema.coerce_object(value, path, errors) if field.schema
+
+        coerced = Types.fetch(field.type).coerce(value)
+        check_rules(field.rules, coerced, path, errors)
+        coerced
+      rescue Types::CoercionError => e
+        (errors[path] ||= []) << e.message
+        NO_DEFAULT
+      end
+
+      def check_rules(rules, value, path, errors)
+        messages = rules.filter_map { |rule, arg| rule_message(rule, arg, value) }
+        (errors[path] ||= []).concat(messages) unless messages.empty?
+      end
+
+      def rule_message(rule, arg, value)
+        check, message = RULE_CHECKS.fetch(rule)
+        check.call(value, arg) ? nil : message.call(arg)
+      end
+
+      def normalize_input(input)
+        input = input.to_unsafe_h if input.respond_to?(:to_unsafe_h) # GemStack::Params
+        input.is_a?(Hash) ? input.transform_keys(&:to_s) : input
+      end
+
+      def blank_string?(value) = value.is_a?(String) && value.strip.empty?
+
+      # An empty form input for a non-string field means "not given".
+      def empty_form_value?(field, value) = value == "" && !STRING_TYPES.include?(field.type)
+    end
+  end
+end
+
+require_relative "serializer"