mat_views 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed05279bf4f2812ebeb8cb882f38772636f28c273b0992a878e13fb06b95d17f
-  data.tar.gz: 8fa0d71481c042d1b763e012b91dfe397373161decf8a68ef13c27bd3349fb33
+  metadata.gz: b7120f5d0821cb752001586381ab084a7366aeaa9616b86ef6e648be2b52d152
+  data.tar.gz: ab541f3705c974e8272cc07db3c9612add6311cb159467e04055eb980fa648b6
 SHA512:
-  metadata.gz: 3233a39ea2a44171bc95d15be3bfccf53f507f49efb946787888f3aeae95b94273126331ac607a83e3d9e23c1f8770a4b0362ee2825b6c7ae1c60aab6f9aff92
-  data.tar.gz: 05566cd4d75f7ef05465387a39794ca1cae6351375e8b298b7deec0f1503e517d09429f5d1b605042dd6f739c0fa6f868fc839ce600bf201228f206c01dbaec9
+  metadata.gz: e3d260f3fcaf3029af874c943ae72b8786e2e86232dbc352a955ae9c4e1add587a0df88507cb86fe5463b308df1ff354b64ebfed00ebe2bcd124924984121797
+  data.tar.gz: 235208e771305d1085eeea02f5bd762bfb91942901e2b9d7d127281d8e7d04da878fcbf5eb8df4cdec9434c1e5db243fb90b20c79d77ede4136006449cbe2df8

data/README.md

@@ -96,9 +96,9 @@ MatViews::Jobs::Adapter.enqueue(job_class, queue: :default, args: [...])
 
 ```bash
 # Create
-bundle exec rake mat_views:create_by_name\[VIEW_NAME,force,--yes]
-bundle exec rake mat_views:create_by_id\[ID,force,--yes]
-bundle exec rake mat_views:create_all\[force,--yes]
+bundle exec rake mat_views:create_by_name\[VIEW_NAME,force,row_count_strategy,--yes]
+bundle exec rake mat_views:create_by_id\[ID,force,row_count_strategy,--yes]
+bundle exec rake mat_views:create_all\[force,row_count_strategy,--yes]
 
 # Refresh
 bundle exec rake mat_views:refresh_by_name\[VIEW_NAME,row_count_strategy,--yes]
@@ -106,9 +106,9 @@ bundle exec rake mat_views:refresh_by_id\[ID,row_count_strategy,--yes]
 bundle exec rake mat_views:refresh_all\[row_count_strategy,--yes]
 
 # Delete
-bundle exec rake mat_views:delete_by_name\[VIEW_NAME,cascade,--yes]
-bundle exec rake mat_views:delete_by_id\[ID,cascade,--yes]
-bundle exec rake mat_views:delete_all\[cascade,--yes]
+bundle exec rake mat_views:delete_by_name\[VIEW_NAME,cascade,row_count_strategy,--yes]
+bundle exec rake mat_views:delete_by_id\[ID,cascade,row_count_strategy,--yes]
+bundle exec rake mat_views:delete_all\[cascade,row_count_strategy,--yes]
 ```
 
 ---

data/app/jobs/mat_views/application_job.rb

@@ -35,5 +35,110 @@ module MatViews
   #   end
   #
   class ApplicationJob < ActiveJob::Base
+    private
+
+    def record_run(definition, operation, &)
+      start = monotime
+      run = start_run(definition, operation)
+      response = yield
+      finalize_run(run, response, elapsed_ms(start))
+      response.to_h
+    rescue StandardError => e
+      fail_run(run, e, elapsed_ms(start))
+      raise e
+    end
+
+    ##
+    # Begin a {MatViews::MatViewRun} row for lifecycle tracking.
+    #
+    # @api private
+    #
+    # @return [MatViews::MatViewRun]
+    #
+    def start_run(definition, operation)
+      MatViews::MatViewRun.create!(
+        mat_view_definition: definition,
+        status: :running,
+        started_at: Time.current,
+        operation: operation
+      )
+    end
+
+    ##
+    # Finalize the run with success/failure, timing, and meta from the response.
+    #
+    # @api private
+    #
+    # @param run [MatViews::MatViewRun]
+    # @param response [MatViews::ServiceResponse, nil] may be nil if exception raised
+    # @param duration_ms [Integer]
+    # @return [void]
+    #
+    def finalize_run(run, response, duration_ms)
+      base_attrs = {
+        finished_at: Time.current,
+        duration_ms: duration_ms,
+        meta: { request: response.request, response: response.response }.compact
+      }
+
+      if response.success?
+        run.update!(base_attrs.merge(status: :success, error: nil))
+      else
+        run.update!(base_attrs.merge(status: :failed, error: response.error))
+      end
+    end
+
+    ##
+    # Mark the run failed due to an exception.
+    #
+    # @api private
+    #
+    # @param run [MatViews::MatViewRun]
+    # @param exception [Exception]
+    # @param duration_ms [Integer]
+    # @return [void]
+    #
+    def fail_run(run, exception, duration_ms)
+      run&.update!(
+        error: exception.mv_serialize_error,
+        finished_at: Time.current,
+        duration_ms: duration_ms,
+        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
+
+    ##
+    # Normalize the strategy argument into a symbol or default.
+    #
+    # @api private
+    #
+    # @param arg [Symbol, String, nil]
+    # @return [Symbol] One of `:estimated`, `:exact`, or `:none` by default.
+    #
+    def normalize_strategy(arg)
+      case arg
+      when String, Symbol
+        arg.to_sym
+      else
+        :none
+      end
+    end
   end
 end

data/app/jobs/mat_views/create_view_job.rb

@@ -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,29 @@ 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 materialized view definition.
     #
     # @api public
     #
     # @param 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]
+    #   - `:payload` [Hash]
+    #   - `: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)
-
+    def perform(definition_id, force_arg = nil, row_count_strategy_arg = nil)
       definition = MatViews::MatViewDefinition.find(definition_id)
-      run        = start_run(definition)
 
-      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)).run
+      end
     end
 
     private
@@ -82,107 +74,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

@@ -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.
     #
@@ -40,60 +45,35 @@ module MatViews
     #
     # @param 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]
+    #   - `: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, cascade_arg = nil)
-      cascade    = normalize_cascade?(cascade_arg)
+    def perform(definition_id, cascade_arg = nil, row_count_strategy_arg = nil)
       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
+      record_run(definition, :drop) do
+        MatViews::Services::DeleteView.new(definition, cascade: cascade?(cascade_arg),
+                                                       row_count_strategy: normalize_strategy(row_count_strategy_arg)).run
+      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

@@ -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,16 +48,12 @@ 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 materialized 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 row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
     # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
     #   - `:status` [Symbol]
@@ -68,54 +64,14 @@ module MatViews
     #
     # @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)
+    def perform(definition_id, row_count_strategy_arg = nil)
       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
+      record_run(definition, :refresh) do
+        service(definition).new(definition, row_count_strategy: normalize_strategy(row_count_strategy_arg)).run
       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 +91,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

data/app/models/mat_views/mat_view_run.rb

@@ -77,13 +77,33 @@ module MatViews
     validates :status, presence: true
 
     ##
-    # Scopes
+    # Scope create runs
+    # All runs with `operation: :create`.
+    # @return [ActiveRecord::Relation<MatViews::MatViewRun>]
     scope :create_runs, -> { where(operation: :create) }
+
+    ##
+    # Scope refresh runs
+    # All runs with `operation: :refresh`.
+    # @return [ActiveRecord::Relation<MatViews::MatViewRun>]
     scope :refresh_runs, -> { where(operation: :refresh) }
+
+    ##
+    # Scope drop runs
+    # All runs with `operation: :drop`.
+    # @return [ActiveRecord::Relation<MatViews::MatViewRun>]
     scope :drop_runs,    -> { where(operation: :drop) }
 
-    def row_count
-      meta['row_count']
+    # row count before the operation, if applicable
+    # @return [Integer, nil]
+    def row_count_before
+      meta.dig('response', 'row_count_before')
+    end
+
+    # row count after the operation, if applicable
+    # @return [Integer, nil]
+    def row_count_after
+      meta.dig('response', 'row_count_after')
     end
   end
 end