lcp 0.1.0

data/lib/lcp_ruby/authorized_controller.rb

@@ -0,0 +1,44 @@
+module LcpRuby
+  # Enables Pundit's `after_action :verify_authorized` framework guarantee
+  # on LCP controllers — every action must call `authorize` (or
+  # `skip_authorization` explicitly) or the request raises
+  # `Pundit::AuthorizationNotPerformedError` in dev/test, surfacing
+  # gateless paths the boot validator can't reach.
+  #
+  # Composes with `LcpRuby::Controller::Authorization` (which provides
+  # the dynamic-policy `authorize` override and the tracker primitives
+  # — `verify_authorized`, `skip_authorization`, etc.). This concern
+  # only adds the `after_action` hook plus a Devise opt-out predicate.
+  #
+  # See docs/design/authorization_hardening.md § "Layer 4 —
+  # Controller-level verify_authorized" and § "AuthorizedController
+  # concern shape and skip-list taxonomy".
+  module AuthorizedController
+    extend ActiveSupport::Concern
+
+    included do
+      after_action :verify_authorized, unless: :lcp_skip_verify_authorized?
+    end
+
+    private
+
+    # `verify_authorized` enforces *success-path* coverage — every action
+    # that actually serves resource data must invoke `authorize`. Skip for:
+    #
+    # - Devise session/registration controllers (outside the LCP resource
+    #   pipeline). The `respond_to?` guard means LCP works whether or not
+    #   Devise is mounted in the host app.
+    # - 4xx and 5xx responses, which are framework-level error handling
+    #   (record not found, model is not a tree, target_model param missing,
+    #   raw .json on a composite page returning 406, etc.). These exit
+    #   before any policy lookup makes sense; demanding authorize there
+    #   would force `skip_authorization` markers in a dozen `head :not_found`
+    #   one-liners and obscure the success-path guarantee.
+    def lcp_skip_verify_authorized?
+      return true if respond_to?(:devise_controller?) && devise_controller?
+      return true if response.status >= 400
+
+      false
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/base_handler.rb

@@ -0,0 +1,113 @@
+module LcpRuby
+  module BackgroundJobs
+    class BaseHandler
+      attr_reader :execution, :definition
+
+      def initialize(execution, definition)
+        @execution = execution
+        @definition = definition
+        @last_progress_at = nil
+        @last_log_flush_at = nil
+      end
+
+      def perform
+        raise NotImplementedError, "#{self.class}#perform must be implemented"
+      end
+
+      def params
+        @params ||= begin
+          raw = execution.respond_to?(:params) ? execution.params : nil
+          case raw
+          when Hash then raw
+          when String
+            JSON.parse(raw)
+          else
+            {}
+          end
+        rescue JSON::ParserError
+          {}
+        end
+      end
+
+      def triggered_by
+        @triggered_by ||= begin
+          snapshot = execution.respond_to?(:triggered_by_snapshot) ? execution.triggered_by_snapshot : nil
+          case snapshot
+          when Hash then snapshot
+          when String then JSON.parse(snapshot)
+          else {}
+          end
+        rescue JSON::ParserError
+          {}
+        end
+      end
+
+      def target_record
+        @target_record ||= begin
+          model_name = execution.respond_to?(:target_model) ? execution.target_model : nil
+          record_id = execution.respond_to?(:target_id) ? execution.target_id : nil
+          return nil unless model_name.present? && record_id.present?
+
+          model_class = LcpRuby.registry.model_for(model_name)
+          model_class.find_by(id: record_id)
+        rescue LcpRuby::MetadataError
+          nil
+        end
+      end
+
+      def check_cancellation!
+        execution.reload
+        if execution.respond_to?(:cancellation_requested?) && execution.cancellation_requested?
+          raise CancellationError, "Job cancelled by user"
+        end
+      end
+
+      def update_progress!(percentage)
+        return if @last_progress_at && Time.current - @last_progress_at < 1.second
+
+        now = Time.current
+        execution.update_columns(progress: percentage.to_i.clamp(0, 100), updated_at: now)
+        @last_progress_at = now
+      end
+
+      def log!(message, level: :info)
+        entry = { "at" => Time.current.iso8601, "level" => level.to_s, "message" => message.to_s }
+        entry["attempt"] = execution.attempt if level.to_s == "error" && execution.respond_to?(:attempt)
+
+        current_log = execution.log || []
+        current_log << entry
+        execution.log = current_log
+
+        flush_log! if should_flush_log?
+      end
+
+      def flush_log!
+        execution.update_columns(log: execution.log, updated_at: Time.current)
+        @last_log_flush_at = Time.current
+      end
+
+      def attach_result!(data, filename:, content_type:)
+        unless execution.respond_to?(:result_file) && execution.respond_to?(:result_file=)
+          raise JobError, "JobExecution model does not have a result_file attachment"
+        end
+
+        io = data.is_a?(StringIO) ? data : StringIO.new(data.to_s)
+        execution.result_file.attach(
+          io: io,
+          filename: filename,
+          content_type: content_type
+        )
+      end
+
+      def set_result_url!(url)
+        execution.update_columns(result_url: url, updated_at: Time.current)
+      end
+
+      private
+
+      def should_flush_log?
+        @last_log_flush_at.nil? || Time.current - @last_log_flush_at >= 2.seconds
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/change_handler.rb

@@ -0,0 +1,17 @@
+module LcpRuby
+  module BackgroundJobs
+    class ChangeHandler
+      def self.install!(model_class)
+        model_class.after_commit do |_record|
+          Registry.reload!
+
+          adapter = LcpRuby.configuration.schedule_adapter
+          if adapter&.respond_to?(:sync_schedules!)
+            definitions = Registry.all_definitions
+            adapter.sync_schedules!(definitions)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/contract.rb

@@ -0,0 +1,16 @@
+module LcpRuby
+  module BackgroundJobs
+    module Contract
+      # @return [Hash<String, Definition>] all job definitions keyed by name
+      def job_definitions
+        raise NotImplementedError, "#{self.class}#job_definitions must be implemented"
+      end
+
+      # @param name [String]
+      # @return [Definition, nil]
+      def job_definition_by_name(name)
+        raise NotImplementedError, "#{self.class}#job_definition_by_name must be implemented"
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/contract_validator.rb

@@ -0,0 +1,112 @@
+module LcpRuby
+  module BackgroundJobs
+    class ContractValidator
+      REQUIRED_FIELDS = {
+        "job_type" => "string",
+        "status" => "enum",
+        "progress" => "integer"
+      }.freeze
+
+      RECOMMENDED_FIELDS = {
+        "error_message" => "text",
+        "log" => %w[json jsonb],
+        "params" => %w[json jsonb],
+        "target_model" => "string",
+        "target_id" => "integer",
+        "started_at" => "datetime",
+        "last_attempt_at" => "datetime",
+        "completed_at" => "datetime",
+        "scheduled_at" => "datetime",
+        "cancellation_requested" => "boolean",
+        "triggered_by_id" => "integer",
+        "triggered_by_snapshot" => %w[json jsonb],
+        "unique_key" => "string",
+        "active_job_id" => "string",
+        "attempt" => "integer"
+      }.freeze
+
+      def self.validate(model_def, field_mapping = nil)
+        new(model_def, field_mapping).validate
+      end
+
+      def initialize(model_def, field_mapping = nil)
+        @model_def = model_def
+        @field_mapping = (field_mapping || default_field_mapping).transform_keys(&:to_s)
+        @errors = []
+        @warnings = []
+      end
+
+      def validate
+        validate_required_fields
+        validate_recommended_fields
+
+        Metadata::ContractResult.new(errors: @errors, warnings: @warnings)
+      end
+
+      private
+
+      def validate_required_fields
+        REQUIRED_FIELDS.each do |logical_name, expected_type|
+          mapped_name = @field_mapping[logical_name] || logical_name
+          field = find_field(mapped_name)
+
+          if field.nil?
+            @errors << "JobExecution model '#{@model_def.name}' must have a '#{mapped_name}' field (mapped as #{logical_name})"
+            next
+          end
+
+          expected_types = expected_type.is_a?(Array) ? expected_type : [ expected_type ]
+          unless expected_types.include?(field.type)
+            @errors << "JobExecution model '#{@model_def.name}': '#{mapped_name}' field must be type " \
+                       "'#{expected_type}' (got '#{field.type}')"
+          end
+        end
+      end
+
+      def validate_recommended_fields
+        RECOMMENDED_FIELDS.each do |logical_name, expected_type|
+          mapped_name = @field_mapping[logical_name] || logical_name
+          field = find_field(mapped_name)
+
+          if field.nil?
+            @warnings << "JobExecution model '#{@model_def.name}': '#{mapped_name}' field is recommended (mapped as #{logical_name})"
+            next
+          end
+
+          expected_types = expected_type.is_a?(Array) ? expected_type : [ expected_type ]
+          unless expected_types.include?(field.type)
+            @errors << "JobExecution model '#{@model_def.name}': '#{mapped_name}' field must be type " \
+                       "'#{expected_type}' (got '#{field.type}')"
+          end
+        end
+      end
+
+      def find_field(name)
+        @model_def.fields.find { |f| f.name == name.to_s }
+      end
+
+      def default_field_mapping
+        {
+          "job_type" => "job_type",
+          "status" => "status",
+          "progress" => "progress",
+          "error_message" => "error_message",
+          "log" => "log",
+          "params" => "params",
+          "target_model" => "target_model",
+          "target_id" => "target_id",
+          "started_at" => "started_at",
+          "last_attempt_at" => "last_attempt_at",
+          "completed_at" => "completed_at",
+          "scheduled_at" => "scheduled_at",
+          "cancellation_requested" => "cancellation_requested",
+          "triggered_by_id" => "triggered_by_id",
+          "triggered_by_snapshot" => "triggered_by_snapshot",
+          "unique_key" => "unique_key",
+          "active_job_id" => "active_job_id",
+          "attempt" => "attempt"
+        }
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/declarative/base_action.rb

@@ -0,0 +1,11 @@
+module LcpRuby
+  module BackgroundJobs
+    module Declarative
+      class BaseAction < BaseHandler
+        def config
+          definition.handler_config
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/declarative/call_webhook_action.rb

@@ -0,0 +1,174 @@
+require "net/http"
+require "json"
+
+module LcpRuby
+  module BackgroundJobs
+    module Declarative
+      class CallWebhookAction < BaseAction
+        RETRYABLE_STATUS_CODES = [ 408, 429, 500, 502, 503, 504 ].freeze
+        PERMANENT_FAILURE_RANGE = (400..499).freeze
+
+        def perform
+          url = resolve_url(config["url"])
+          uri = validate_webhook_uri!(url)
+          method = (config["method"] || "POST").upcase
+          headers = resolve_headers(config["headers"] || {})
+          body = resolve_body(config["body"])
+          http_timeout = (config["timeout"] || 30).to_i
+          expect_status = config["expect_status"]
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = http_timeout
+          http.read_timeout = http_timeout
+
+          request = build_request(method, uri, headers, body)
+
+          response = http.request(request)
+          handle_response(response, expect_status)
+        rescue UrlSafety::UnsafeUrlError => e
+          log!("Blocked webhook URL: #{e.message}", level: :error)
+          raise JobError, "Webhook URL is not allowed: #{e.message}"
+        rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
+               SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+          log!("Network error: #{e.class}: #{e.message}", level: :error)
+          raise JobError, "Webhook network error: #{e.message}"
+        end
+
+        private
+
+        # Validates the webhook URL. Scheme is always checked (even static sources).
+        # For DB-sourced jobs, additionally checks webhook_allowed_hosts allowlist
+        # or blocks private/loopback IPs via UrlSafety.
+        def validate_webhook_uri!(url)
+          uri = URI.parse(url)
+
+          unless %w[http https].include?(uri.scheme&.downcase)
+            raise JobError, "Webhook URL must use http or https (got '#{uri.scheme}' in job '#{definition.name}')"
+          end
+
+          # Static sources are trusted (deployed with code) — skip host/IP checks
+          return uri if definition.source_type != "model"
+
+          # Strict allowlist if configured
+          allowed = LcpRuby.configuration.webhook_allowed_hosts
+          if allowed.is_a?(Array)
+            unless allowed.any? { |h| uri.host&.downcase == h.downcase }
+              raise JobError, "Webhook host '#{uri.host}' not in allowed hosts (job '#{definition.name}')"
+            end
+            return uri
+          end
+
+          # Default: block private/loopback IPs for DB-sourced jobs via shared UrlSafety
+          UrlSafety.reject_host!(uri.host)
+          uri
+        rescue URI::InvalidURIError => e
+          raise JobError, "Invalid webhook URL: #{e.message} (job '#{definition.name}')"
+        end
+
+        def resolve_url(url)
+          return url unless url.is_a?(String)
+          interpolate_env_vars(url)
+        end
+
+        def resolve_headers(headers)
+          return {} unless headers.is_a?(Hash)
+          headers.transform_values { |v| v.is_a?(String) ? interpolate_env_vars(v) : v.to_s }
+        end
+
+        def resolve_body(body)
+          return nil unless body.is_a?(Hash)
+
+          resolved = {}
+          body.each do |key, value|
+            resolved[key] = resolve_body_value(value)
+          end
+          resolved
+        end
+
+        def resolve_body_value(value)
+          case value
+          when Hash
+            if value.key?("field_ref") || value.key?(:field_ref)
+              field_name = value["field_ref"] || value[:field_ref]
+              record = target_record
+              record&.respond_to?(field_name) ? record.send(field_name) : nil
+            else
+              value.transform_values { |v| resolve_body_value(v) }
+            end
+          else
+            value
+          end
+        end
+
+        def interpolate_env_vars(text)
+          return text unless text.include?("${env:")
+
+          if definition.source_type == "model"
+            raise JobError,
+              "Environment variable interpolation (${env:...}) is not allowed in DB-sourced job definitions " \
+              "(job '#{definition.name}'). Use literal values instead."
+          end
+
+          text.gsub(/\$\{env:([^}]+)\}/) do |_match|
+            var_name = $1
+            value = ENV[var_name]
+            unless value
+              raise EnvVariableNotFoundError,
+                "Environment variable '#{var_name}' not found (referenced in job '#{definition.name}')"
+            end
+            value
+          end
+        end
+
+        def build_request(method, uri, headers, body)
+          request_class = case method
+          when "GET" then Net::HTTP::Get
+          when "POST" then Net::HTTP::Post
+          when "PUT" then Net::HTTP::Put
+          when "PATCH" then Net::HTTP::Patch
+          when "DELETE" then Net::HTTP::Delete
+          else
+                           raise JobError, "Unsupported HTTP method: #{method}"
+          end
+
+          request = request_class.new(uri)
+          headers.each { |k, v| request[k] = v }
+
+          if body
+            request["Content-Type"] ||= "application/json"
+            request.body = JSON.generate(body)
+          end
+
+          request
+        end
+
+        def handle_response(response, expect_status)
+          status = response.code.to_i
+          body_preview = response.body.to_s[0, 1024]
+
+          if success_status?(status, expect_status)
+            log!("Webhook response: #{status} — #{body_preview}", level: :info)
+          elsif RETRYABLE_STATUS_CODES.include?(status)
+            log!("Webhook retryable error: #{status} — #{body_preview}", level: :error)
+            raise JobError, "Webhook returned retryable status #{status}"
+          elsif PERMANENT_FAILURE_RANGE.include?(status)
+            log!("Webhook permanent failure: #{status} — #{body_preview}", level: :error)
+            raise JobError, "Webhook returned permanent failure status #{status}"
+          else
+            log!("Webhook error: #{status} — #{body_preview}", level: :error)
+            raise JobError, "Webhook returned unexpected status #{status}"
+          end
+        end
+
+        def success_status?(status, expect_status)
+          if expect_status.is_a?(Array)
+            expect_status.any? { |s| s.is_a?(Range) ? s.include?(status) : s.to_i == status }
+          else
+            (200..299).include?(status)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/declarative/fire_event_action.rb

@@ -0,0 +1,24 @@
+module LcpRuby
+  module BackgroundJobs
+    module Declarative
+      class FireEventAction < BaseAction
+        def perform
+          event_name = config["event"]
+          raise JobError, "fire_event action requires an 'event' key" unless event_name.present?
+
+          record = target_record
+          if record
+            Events::Dispatcher.dispatch(
+              event_name: event_name,
+              record: record,
+              changes: {}
+            )
+            log!("Fired event '#{event_name}' for #{execution.target_model}##{execution.target_id}", level: :info)
+          else
+            log!("Fired event '#{event_name}' (no target record)", level: :info)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/declarative/registry.rb

@@ -0,0 +1,34 @@
+module LcpRuby
+  module BackgroundJobs
+    module Declarative
+      class Registry
+        @actions = {}
+
+        class << self
+          def register(name, action_class)
+            @actions[name.to_s] = action_class
+          end
+
+          def action_for(name)
+            @actions[name.to_s]
+          end
+
+          def clear!
+            @actions = {}
+          end
+
+          def registered_actions
+            @actions.keys
+          end
+
+          def register_built_ins!
+            register("run_scope", RunScopeAction)
+            register("fire_event", FireEventAction)
+            register("call_webhook", CallWebhookAction)
+            register("send_notification", SendNotificationAction)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/declarative/run_scope_action.rb

@@ -0,0 +1,98 @@
+module LcpRuby
+  module BackgroundJobs
+    module Declarative
+      class RunScopeAction < BaseAction
+        ALLOWED_OPERATIONS = %w[destroy_all delete_all update_all count].freeze
+
+        def perform
+          model_name = config["model"]
+          scope_name = config["scope"]
+          operation = config["operation"] || "count"
+          batch_size = (config["batch_size"] || 1000).to_i
+
+          unless ALLOWED_OPERATIONS.include?(operation)
+            raise JobError, "Invalid operation '#{operation}'. Allowed: #{ALLOWED_OPERATIONS.join(', ')}"
+          end
+
+          model_class = LcpRuby.registry.model_for(model_name)
+
+          scope = if scope_name.present?
+                    scope_params = config["scope_params"] || {}
+                    scope_params = scope_params.transform_keys(&:to_sym) if scope_params.is_a?(Hash)
+                    if scope_params.any?
+                      model_class.send(scope_name, **scope_params)
+                    else
+                      model_class.send(scope_name)
+                    end
+          else
+                    model_class.all
+          end
+
+          case operation
+          when "destroy_all"
+            perform_destroy_all(scope, batch_size)
+          when "delete_all"
+            perform_delete_all(scope, batch_size)
+          when "update_all"
+            perform_update_all(scope, batch_size)
+          when "count"
+            perform_count(scope)
+          end
+        end
+
+        private
+
+        def perform_destroy_all(scope, batch_size)
+          total = scope.count
+          destroyed = 0
+
+          scope.find_each(batch_size: batch_size) do |record|
+            check_cancellation!
+            record.destroy!
+            destroyed += 1
+            update_progress!((destroyed * 100) / total) if total > 0
+          end
+
+          log!("Destroyed #{destroyed} records", level: :info)
+        end
+
+        def perform_delete_all(scope, batch_size)
+          deleted = 0
+
+          loop do
+            check_cancellation!
+            count = scope.limit(batch_size).delete_all
+            break if count == 0
+
+            deleted += count
+          end
+
+          log!("Deleted #{deleted} records", level: :info)
+        end
+
+        def perform_update_all(scope, batch_size)
+          update_params = config["update_params"]
+          raise JobError, "update_all operation requires update_params" unless update_params
+
+          updated = 0
+
+          loop do
+            check_cancellation!
+            batch_ids = scope.limit(batch_size).pluck(:id)
+            break if batch_ids.empty?
+
+            count = scope.model.where(id: batch_ids).update_all(update_params)
+            updated += count
+          end
+
+          log!("Updated #{updated} records", level: :info)
+        end
+
+        def perform_count(scope)
+          count = scope.count
+          log!("Count result: #{count} records", level: :info)
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/declarative/send_notification_action.rb

@@ -0,0 +1,13 @@
+module LcpRuby
+  module BackgroundJobs
+    module Declarative
+      class SendNotificationAction < BaseAction
+        def perform
+          raise NotImplementedError,
+            "send_notification action depends on the notifications module which is not yet implemented. " \
+            "Configure a custom handler class instead."
+        end
+      end
+    end
+  end
+end