mat_views 0.1.2 → 0.3.0

data/app/jobs/mat_views/create_view_job.rb

@@ -9,7 +9,7 @@
 # Top-level namespace for the mat_views engine.
 module MatViews
   ##
-  # ActiveJob that handles *creation* of PostgreSQL materialized views for a
+  # ActiveJob that handles *creation* of PostgreSQL materialised views for a
   # given {MatViews::MatViewDefinition}.
   #
   # The job:
@@ -17,7 +17,7 @@ module MatViews
   # 2. Looks up the target {MatViews::MatViewDefinition}.
   # 3. Starts a {MatViews::MatViewRun} row to track lifecycle/timing, with `operation: :create`.
   # 4. Executes {MatViews::Services::CreateView}.
-  # 5. Finalizes the run with success/failure, duration, and payload meta.
+  # 5. Finalizes the run with success/failure, duration, and meta.
   #
   # @see MatViews::Services::CreateView
   # @see MatViews::MatViewDefinition
@@ -29,7 +29,7 @@ module MatViews
   # @example Inline run (test/dev)
   #   MatViews::CreateViewJob.new.perform(definition.id, false)
   #
-  class CreateViewJob < ::ActiveJob::Base
+  class CreateViewJob < ApplicationJob
     ##
     # Queue name for the job.
     #
@@ -40,37 +40,30 @@ module MatViews
     queue_as { MatViews.configuration.job_queue || :default }
 
     ##
-    # Perform the job for the given materialized view definition.
+    # Perform the create job for the given materialised view definition.
     #
     # @api public
     #
-    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param mat_view_definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
     # @param force_arg [Boolean, Hash, nil] Optional flag or hash (`{ force: true }`)
-    #   to force creation (drop/recreate) when supported by the service.
+    # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
-    # @return [Hash] A serialized {MatViews::ServiceResponse#to_h}:
-    #   - `:status` [Symbol] one of `:ok, :created, :updated, :noop, :error`
-    #   - `:payload` [Hash] service-specific payload (also stored in run.meta)
-    #   - `:error` [String, nil] error message if any
-    #   - `:duration_ms` [Integer, nil]
+    # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
+    #   - `:status` [Symbol]
+    #   - `:error` [String, nil]
+    #   - `:duration_ms` [Integer]
     #   - `:meta` [Hash]
     #
     # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
     #
-    # @see MatViews::Services::CreateView
-    #
-    def perform(definition_id, force_arg = nil)
-      force = normalize_force(force_arg)
-
-      definition = MatViews::MatViewDefinition.find(definition_id)
-      run        = start_run(definition)
+    def perform(mat_view_definition_id, force_arg = nil, row_count_strategy_arg = nil)
+      definition = MatViews::MatViewDefinition.find(mat_view_definition_id)
 
-      response, duration_ms = execute(definition, force: force)
-      finalize_run!(run, response, duration_ms)
-      response.to_h
-    rescue StandardError => e
-      fail_run!(run, e) if run
-      raise e
+      record_run(definition, :create) do
+        MatViews::Services::CreateView.new(definition,
+                                           force: force?(force_arg),
+                                           row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
+      end
     end
 
     private
@@ -82,107 +75,13 @@ module MatViews
     #
     # @api private
     #
-    # @param arg [Object] Raw argument; commonly `true/false`, `nil`, or `Hash`.
+    # @param arg [Object] Raw argument; commonly `true/false`, `nil`
     # @return [Boolean] Coerced force flag.
     #
-    def normalize_force(arg)
-      case arg
-      when Hash
-        arg[:force] || arg['force'] || false
-      else
-        !!arg
-      end
-    end
+    def force?(arg)
+      return false if arg.nil?
 
-    ##
-    # Execute the create service and measure duration.
-    #
-    # @api private
-    #
-    # @param definition [MatViews::MatViewDefinition]
-    # @param force [Boolean]
-    # @return [Array(MatViews::ServiceResponse, Integer)] response and elapsed ms.
-    #
-    def execute(definition, force:)
-      started  = monotime
-      response = MatViews::Services::CreateView.new(definition, force: force).run
-      [response, elapsed_ms(started)]
+      !!arg
     end
-
-    ##
-    # Begin a {MatViews::MatViewRun} row for lifecycle tracking.
-    #
-    # @api private
-    #
-    # @param definition [MatViews::MatViewDefinition]
-    # @return [MatViews::MatViewRun] newly created run with `status: :running`
-    #
-    def start_run(definition)
-      MatViews::MatViewRun.create!(
-        mat_view_definition: definition,
-        status: :running,
-        started_at: Time.current,
-        operation: :create
-      )
-    end
-
-    ##
-    # Finalize the run with success/failure, timing, and meta from the response payload.
-    #
-    # @api private
-    #
-    # @param run [MatViews::MatViewRun]
-    # @param response [MatViews::ServiceResponse]
-    # @param duration_ms [Integer]
-    # @return [void]
-    #
-    def finalize_run!(run, response, duration_ms)
-      base_attrs = {
-        finished_at: Time.current,
-        duration_ms: duration_ms,
-        meta: response.payload || {}
-      }
-
-      if response.success?
-        run.update!(base_attrs.merge(status: :success, error: nil))
-      else
-        run.update!(base_attrs.merge(status: :failed, error: response.error.to_s.presence))
-      end
-    end
-
-    ##
-    # Mark the run failed due to an exception.
-    #
-    # @api private
-    #
-    # @param run [MatViews::MatViewRun]
-    # @param exception [Exception]
-    # @return [void]
-    #
-    def fail_run!(run, exception)
-      run.update!(
-        finished_at: Time.current,
-        duration_ms: run.duration_ms || 0,
-        error: "#{exception.class}: #{exception.message}",
-        status: :failed
-      )
-    end
-
-    ##
-    # Monotonic clock getter (for elapsed-time measurement).
-    #
-    # @api private
-    # @return [Float] seconds from a monotonic source.
-    #
-    def monotime = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-    ##
-    # Convert a monotonic start time to elapsed milliseconds.
-    #
-    # @api private
-    # @param start [Float] monotonic seconds.
-    # @return [Integer] elapsed milliseconds.
-    #
-    def elapsed_ms(start) = ((monotime - start) * 1000).round
   end
 end

data/app/jobs/mat_views/delete_view_job.rb

@@ -9,7 +9,7 @@
 # Top-level namespace for the mat_views engine.
 module MatViews
   ##
-  # ActiveJob that handles *deletion* of PostgreSQL materialized views via
+  # ActiveJob that handles *deletion* of PostgreSQL materialised views via
   # {MatViews::Services::DeleteView}.
   #
   # This job mirrors {MatViews::CreateViewJob} and {MatViews::RefreshViewJob}:
@@ -25,7 +25,12 @@ module MatViews
   # @example Inline run (test/dev)
   #   MatViews::DeleteViewJob.new.perform(definition.id, false)
   #
-  class DeleteViewJob < ::ActiveJob::Base
+  class DeleteViewJob < ApplicationJob
+    ###
+    # cascade flag for the service call
+    # @return [Boolean]
+    attr_reader :cascade
+
     ##
     # Queue name for the job.
     #
@@ -34,66 +39,41 @@ module MatViews
     queue_as { MatViews.configuration.job_queue || :default }
 
     ##
-    # Perform the job for the given materialized view definition.
+    # Perform the job for the given materialised view definition.
     #
     # @api public
     #
-    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param mat_view_definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
     # @param cascade_arg [Boolean, String, Integer, Hash, nil] Cascade option.
-    #   Accepts:
-    #   - `true/false`
-    #   - `1` (treated as true)
-    #   - `"true"`, `"1"`, `"yes"` (case-insensitive)
-    #   - `{ cascade: true }` or `{ "cascade" => true }`
+    # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
-    # @return [Hash] A serialized {MatViews::ServiceResponse#to_h}:
-    #   - `:status` [Symbol] `:success`, `:failed`, etc.
-    #   - `:payload` [Hash] response payload (also stored in run.meta)
+    # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
+    #   - `:status` [Symbol]
     #   - `:error` [String, nil]
     #   - `:duration_ms` [Integer]
     #   - `:meta` [Hash]
     #
     # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
     #
-    def perform(definition_id, cascade_arg = nil)
-      cascade    = normalize_cascade?(cascade_arg)
-      definition = MatViews::MatViewDefinition.find(definition_id)
-      run        = start_run(definition)
-
-      response, duration_ms = execute(definition, cascade: cascade)
-      finalize_run!(run, response, duration_ms)
-      response.to_h
-    rescue StandardError => e
-      fail_run!(run, e) if run
-      raise e
+    def perform(mat_view_definition_id, cascade_arg = nil, row_count_strategy_arg = nil)
+      definition = MatViews::MatViewDefinition.find(mat_view_definition_id)
+      record_run(definition, :drop) do
+        MatViews::Services::DeleteView.new(definition,
+                                           cascade: cascade?(cascade_arg),
+                                           row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
+      end
     end
 
     private
 
     ##
-    # Normalize cascade argument into a boolean.
-    #
-    # @api private
-    # @param arg [Object] Raw cascade argument.
-    # @return [Boolean] Whether to cascade drop.
-    #
-    def normalize_cascade?(arg)
-      value = if arg.is_a?(Hash)
-                arg[:cascade] || arg['cascade']
-              else
-                arg
-              end
-      cascade_value_trueish?(value)
-    end
-
-    ##
-    # Evaluate if a value is "truthy" for cascade purposes.
+    # Evaluate if a value is "truthy" for cascade.
     #
     # @api private
-    # @param value [Object]
+    # @param value [TrueClass, FalseClass, String, Integer, nil, Object]
     # @return [Boolean]
     #
-    def cascade_value_trueish?(value)
+    def cascade?(value)
       case value
       when true
         true
@@ -105,92 +85,5 @@ module MatViews
         false
       end
     end
-
-    ##
-    # Execute the delete service and measure duration.
-    #
-    # @api private
-    # @param definition [MatViews::MatViewDefinition]
-    # @param cascade [Boolean]
-    # @return [Array(MatViews::ServiceResponse, Integer)]
-    #
-    def execute(definition, cascade:)
-      started  = monotime
-      response = MatViews::Services::DeleteView.new(definition, cascade: cascade, if_exists: true).run
-      [response, elapsed_ms(started)]
-    end
-
-    ##
-    # Begin a {MatViews::MatViewRun} row for lifecycle tracking.
-    #
-    # @api private
-    # @param definition [MatViews::MatViewDefinition]
-    # @return [MatViews::MatViewRun]
-    #
-    def start_run(definition)
-      MatViews::MatViewRun.create!(
-        mat_view_definition: definition,
-        status: :running,
-        started_at: Time.current,
-        operation: :drop
-      )
-    end
-
-    ##
-    # Finalize the run with success/failure, timing, and meta from the response.
-    #
-    # @api private
-    # @param run [MatViews::MatViewRun]
-    # @param response [MatViews::ServiceResponse]
-    # @param duration_ms [Integer]
-    # @return [void]
-    #
-    def finalize_run!(run, response, duration_ms)
-      base_attrs = {
-        finished_at: Time.current,
-        duration_ms: duration_ms,
-        meta: response.payload || {}
-      }
-
-      if response.success?
-        run.update!(base_attrs.merge(status: :success, error: nil))
-      else
-        run.update!(base_attrs.merge(status: :failed, error: response.error.to_s.presence))
-      end
-    end
-
-    ##
-    # Mark the run failed due to an exception.
-    #
-    # @api private
-    # @param run [MatViews::MatViewRun]
-    # @param exception [Exception]
-    # @return [void]
-    #
-    def fail_run!(run, exception)
-      run.update!(
-        finished_at: Time.current,
-        duration_ms: run.duration_ms || 0,
-        error: "#{exception.class}: #{exception.message}",
-        status: :failed
-      )
-    end
-
-    ##
-    # Monotonic clock getter (for elapsed-time measurement).
-    #
-    # @api private
-    # @return [Float] seconds
-    #
-    def monotime = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-    ##
-    # Convert monotonic start time to elapsed milliseconds.
-    #
-    # @api private
-    # @param start [Float]
-    # @return [Integer] elapsed ms
-    #
-    def elapsed_ms(start) = ((monotime - start) * 1000).round
   end
 end

data/app/jobs/mat_views/refresh_view_job.rb

@@ -23,9 +23,9 @@ module MatViews
   # - otherwise      → {MatViews::Services::RegularRefresh}
   #
   # Row count reporting can be controlled via `row_count_strategy`:
-  # - `:estimated` (default) — fast, approximate via reltuples
-  # - `:exact` — accurate `COUNT(*)`
-  # - `nil` — skip counting
+  # - `:estimated` (default) - fast, approximate via reltuples
+  # - `:exact` - accurate `COUNT(*)`
+  # - `nil` - skip counting
   #
   # @see MatViews::MatViewDefinition
   # @see MatViews::MatViewRun
@@ -39,7 +39,7 @@ module MatViews
   # @example Enqueue using keyword-hash form
   #   MatViews::RefreshViewJob.perform_later(definition.id, row_count_strategy: :estimated)
   #
-  class RefreshViewJob < ::ActiveJob::Base
+  class RefreshViewJob < ApplicationJob
     ##
     # Queue name for the job.
     #
@@ -48,74 +48,29 @@ module MatViews
     queue_as { MatViews.configuration.job_queue || :default }
 
     ##
-    # Perform the job for the given materialized view definition.
-    #
-    # Accepts either a symbol/string (`:estimated`, `:exact`) or a hash
-    # (`{ row_count_strategy: :exact }`) for `strategy_arg`.
+    # Perform the refresh job for the given materialised view definition.
     #
     # @api public
     #
-    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
-    # @param strategy_arg [Symbol, String, Hash, nil] Row count strategy override.
-    #   When a Hash, looks for `:row_count_strategy` / `"row_count_strategy"`.
+    # @param mat_view_definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
     # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
     #   - `:status` [Symbol]
-    #   - `:payload` [Hash]
     #   - `:error` [String, nil]
     #   - `:duration_ms` [Integer]
     #   - `:meta` [Hash]
     #
     # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
     #
-    def perform(definition_id, strategy_arg = nil)
-      row_count_strategy = normalize_strategy(strategy_arg)
-      definition = MatViews::MatViewDefinition.find(definition_id)
-      run        = start_run(definition)
-
-      response, duration_ms = execute(definition, row_count_strategy: row_count_strategy)
-      finalize_run!(run, response, duration_ms)
-      response.to_h
-    rescue StandardError => e
-      fail_run!(run, e) if run
-      raise e
-    end
-
-    private
-
-    ##
-    # Normalize the strategy argument into a symbol or default.
-    #
-    # @api private
-    #
-    # @param arg [Symbol, String, Hash, nil]
-    # @return [Symbol] One of `:estimated`, `:exact`, or `:estimated` by default.
-    #
-    def normalize_strategy(arg)
-      case arg
-      when Hash
-        (arg[:row_count_strategy] || arg['row_count_strategy'] || :estimated).to_sym
-      when String, Symbol
-        arg.to_sym
-      else
-        :estimated
+    def perform(mat_view_definition_id, row_count_strategy_arg = nil)
+      definition = MatViews::MatViewDefinition.find(mat_view_definition_id)
+      record_run(definition, :refresh) do
+        service(definition).new(definition, row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
       end
     end
 
-    ##
-    # Execute the appropriate refresh service and measure duration.
-    #
-    # @api private
-    #
-    # @param definition [MatViews::MatViewDefinition]
-    # @param row_count_strategy [Symbol, nil]
-    # @return [Array(MatViews::ServiceResponse, Integer)] response and elapsed ms.
-    #
-    def execute(definition, row_count_strategy:)
-      started  = monotime
-      response = service(definition).new(definition, row_count_strategy: row_count_strategy).run
-      [response, elapsed_ms(started)]
-    end
+    private
 
     ##
     # Select the refresh service class based on the definition's strategy.
@@ -135,81 +90,5 @@ module MatViews
         MatViews::Services::RegularRefresh
       end
     end
-
-    ##
-    # Begin a {MatViews::MatViewRun} row for lifecycle tracking.
-    #
-    # @api private
-    #
-    # @param definition [MatViews::MatViewDefinition]
-    # @return [MatViews::MatViewRun]
-    #
-    def start_run(definition)
-      MatViews::MatViewRun.create!(
-        mat_view_definition: definition,
-        status: :running,
-        started_at: Time.current,
-        operation: :refresh
-      )
-    end
-
-    ##
-    # Finalize the run with success/failure, timing, and meta from the response.
-    #
-    # @api private
-    #
-    # @param run [MatViews::MatViewRun]
-    # @param response [MatViews::ServiceResponse]
-    # @param duration_ms [Integer]
-    # @return [void]
-    #
-    def finalize_run!(run, response, duration_ms)
-      base_attrs = {
-        finished_at: Time.current,
-        duration_ms: duration_ms,
-        meta: response.payload || {}
-      }
-
-      if response.success?
-        run.update!(base_attrs.merge(status: :success, error: nil))
-      else
-        run.update!(base_attrs.merge(status: :failed, error: response.error.to_s.presence))
-      end
-    end
-
-    ##
-    # Mark the run failed due to an exception.
-    #
-    # @api private
-    #
-    # @param run [MatViews::MatViewRun]
-    # @param exception [Exception]
-    # @return [void]
-    #
-    def fail_run!(run, exception)
-      run.update!(
-        finished_at: Time.current,
-        duration_ms: run.duration_ms || 0,
-        error: "#{exception.class}: #{exception.message}",
-        status: :failed
-      )
-    end
-
-    ##
-    # Monotonic clock getter (for elapsed-time measurement).
-    #
-    # @api private
-    # @return [Float] seconds
-    #
-    def monotime = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-    ##
-    # Convert monotonic start time to elapsed milliseconds.
-    #
-    # @api private
-    # @param start [Float]
-    # @return [Integer] elapsed ms
-    #
-    def elapsed_ms(start) = ((monotime - start) * 1000).round
   end
 end