mat_views 0.1.2 → 0.3.0

data/lib/generators/mat_views/install/templates/create_mat_view_runs.rb

@@ -5,8 +5,8 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-# This migration creates the mat_view_runs table, which tracks the mutation runs(create,refresh,drop) of materialized views.
-# It includes references to the materialized view definition, status, operation type, timestamps,
+# This migration creates the mat_view_runs table, which tracks the mutation runs(create,refresh,drop) of materialised views.
+# It includes references to the materialised view definition, status, operation type, timestamps,
 # duration, error messages, and additional metadata.
 class CreateMatViewRuns < ActiveRecord::Migration[7.1]
   def change
@@ -14,17 +14,17 @@ class CreateMatViewRuns < ActiveRecord::Migration[7.1]
       t.references :mat_view_definition,
                    null: false,
                    foreign_key: true,
-                   comment: 'Reference to the materialized view definition'
+                   comment: 'Reference to the materialised view definition'
 
-      # 0=pending, 1=running, 2=success, 3=failed
-      t.integer  :status, null: false, default: 0, comment: '0=pending,1=running,2=success,3=failed'
+      # 0=running, 1=success, 2=failed
+      t.integer  :status, null: false, default: 0, comment: '0=running,1=success,2=failed'
       # 0=create, 1=refresh, 2=drop
       t.integer  :operation, null: false, default: 0, comment: '0=create,1=refresh,2=drop'
       t.datetime :started_at, comment: 'Timestamp when the operation started'
       t.datetime :finished_at, comment: 'Timestamp when the operation finished'
       t.integer  :duration_ms, comment: 'Duration of the operation in milliseconds'
-      t.text     :error, comment: 'Error message if the operation failed'
-      t.jsonb    :meta, null: false, default: {}, comment: 'Additional metadata about the run, such as job ID, row count or parameters'
+      t.jsonb :error, comment: 'Error details if the operation failed. :message, :class, :backtrace'
+      t.jsonb :meta, null: false, default: {}, comment: 'Additional metadata about the run, such as job ID, row count or parameters'
 
       t.timestamps
     end

data/lib/mat_views/admin/auth_bridge.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module MatViews
+  module Admin
+    #
+    # MatViews::Admin::AuthBridge
+    # ---------------------------
+    # Bridge module that wires the MatViews admin engine to a **host-provided**
+    # authentication/authorization layer, while providing safe defaults.
+    #
+    # ### How it works
+    # - Includes {MatViews::Admin::DefaultAuth} first (fallback, no-op/hostable).
+    # - Then includes the **host auth module** returned by {.host_auth_module}.
+    #   Because Ruby searches the most recently included module first, the host
+    #   module cleanly **overrides** any defaults from `DefaultAuth`.
+    # - Registers a before_action `authenticate_mat_views!`.
+    # - Exposes helpers: `mat_views_current_user` and its alias {#user}.
+    #
+    # ### Host integration options (define one of these):
+    # 1) A top-level module:
+    #    ```ruby
+    #    # app/lib/mat_views_admin.rb (or any autoloaded path)
+    #    module MatViewsAdmin
+    #      def authenticate_mat_views!;  end
+    #      def authorize_mat_views!(*); end
+    #      def mat_views_current_user;  end
+    #    end
+    #    ```
+    # 2) A namespaced module:
+    #    ```ruby
+    #    # app/lib/mat_views/admin/host_auth.rb
+    #    module MatViews
+    #      module Admin
+    #        module HostAuth
+    #          def authenticate_mat_views!;  end
+    #          def authorize_mat_views!(*); end
+    #          def mat_views_current_user;  end
+    #        end
+    #      end
+    #    end
+    #    ```
+    #
+    # If neither module is present, a blank `Module.new` is included and the
+    # defaults in {MatViews::Admin::DefaultAuth} remain in effect.
+    #
+    # @see MatViews::Admin::DefaultAuth
+    #
+    module AuthBridge
+      extend ActiveSupport::Concern
+
+      included do
+        # Include defaults first, so the host module (included below) can override.
+        include MatViews::Admin::DefaultAuth
+        include host_auth_module
+
+        before_action :authenticate_mat_views!
+        helper_method :mat_views_current_user, :user
+      end
+
+      # Convenience alias for `mat_views_current_user` exposed to views.
+      #
+      # @return [Object, nil] the current user object as defined by host auth
+      def user = mat_views_current_user
+
+      class_methods do
+        # Resolves the host's auth module, if any.
+        #
+        # Lookup order:
+        # 1. `::MatViewsAdmin`
+        # 2. `::MatViews::Admin::HostAuth`
+        # 3. Fallback: a blank Module (no overrides)
+        #
+        # @return [Module] the module to include for host auth overrides
+        def host_auth_module
+          if Object.const_defined?('MatViewsAdmin')
+            ::MatViewsAdmin
+          elsif Object.const_defined?('MatViews') &&
+                MatViews.const_defined?('Admin') &&
+                MatViews::Admin.const_defined?('HostAuth')
+            ::MatViews::Admin::HostAuth
+          else
+            Module.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mat_views/admin/default_auth.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module MatViews
+  module Admin
+    # MatViews::Admin::DefaultAuth
+    # ----------------------------
+    # Development-friendly **fallback** authentication/authorization for the MatViews
+    # admin UI. It is included first by {MatViews::Admin::AuthBridge}, and is meant
+    # to be overridden by a host-provided module (`MatViewsAdmin` or
+    # `MatViews::Admin::HostAuth`).
+    #
+    # ❗ **Not for production**: this module allows all access and returns a dummy user.
+    #
+    # @see MatViews::Admin::AuthBridge
+    #
+    module DefaultAuth
+      # Minimal stand-in user object used by the default auth.
+      #
+      # @!attribute [rw] email
+      #   @return [String] the email address of the sample user
+      class SampleUser
+        attr_accessor :email
+
+        # @param email [String]
+        def initialize(email) = @email = email
+
+        # @return [String] the user's email
+        def to_s = email
+      end
+
+      # Authenticates the current request.
+      # Always returns true in the default implementation.
+      #
+      # @return [Boolean] true
+      # rubocop:disable Naming/PredicateMethod
+      def authenticate_mat_views! = true
+      # rubocop:enable Naming/PredicateMethod
+
+      # Returns the current user object.
+      # In the default implementation this is a {SampleUser}.
+      #
+      # @return [SampleUser]
+      def mat_views_current_user = SampleUser.new('sample-user@example.com')
+
+      # Authorizes an action on a record.
+      # Always returns true in the default implementation.
+      #
+      # @param _action [Symbol, String] the attempted action (ignored)
+      # @param _record [Object] the target record or symbol (ignored)
+      # @return [Boolean] true
+      # rubocop:disable Naming/PredicateMethod
+      def authorize_mat_views!(_action, _record) = true
+      # rubocop:enable Naming/PredicateMethod
+    end
+  end
+end

data/lib/mat_views/configuration.rb

@@ -17,6 +17,7 @@ module MatViews
   #   MatViews.configure do |config|
   #     config.job_adapter = :sidekiq
   #     config.job_queue   = :low_priority
+  #     config.admin_ui   = { row_count_strategy: :estimated }
   #   end
   #
   # Supported job adapters:
@@ -37,6 +38,11 @@ module MatViews
     # @return [Symbol, String]
     attr_accessor :job_queue
 
+    ##
+    # admin_ui configuration
+    # @return [Hash]
+    attr_accessor :admin_ui
+
     ##
     # Initialize with defaults.
     #
@@ -44,6 +50,9 @@ module MatViews
     def initialize
       @job_adapter = :active_job
       @job_queue   = :default
+      @admin_ui    = {
+        row_count_strategy: :none
+      }
     end
   end
 end

data/lib/mat_views/engine.rb

@@ -5,13 +5,19 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
+##
+# MatViews is a Rails engine that provides first-class support for
+# PostgreSQL materialised views in Rails applications.
 module MatViews
+  class << self
+    attr_accessor :importmap
+  end
   ##
   # Rails Engine for MatViews.
   #
   # This engine encapsulates all functionality related to
-  # materialized views, including:
-  # - Defining materialized view definitions
+  # materialised views, including:
+  # - Defining materialised view definitions
   # - Creating and refreshing views
   # - Managing background jobs for refresh/create/delete
   #
@@ -30,5 +36,47 @@ module MatViews
     initializer 'mat_views.load_config' do
       MatViews.configuration ||= MatViews::Configuration.new
     end
+
+    initializer 'mat_views.javascript' do |app|
+      app.config.assets.paths << root.join('app/javascript')
+    end
+
+    initializer 'mat_views.importmap', before: 'importmap' do |_app|
+      next unless defined?(Importmap)
+
+      MatViews.importmap = Importmap::Map.new
+      MatViews.importmap.draw(root.join('config/importmap.rb'))
+      MatViews.importmap.cache_sweeper(watches: root.join('app/javascript'))
+
+      ActiveSupport.on_load(:action_controller_base) do
+        before_action { MatViews.importmap.cache_sweeper.execute_if_updated }
+      end
+    end
+
+    def self.locale_code_mapping
+      @locale_code_mapping ||= begin
+        mappings = Dir[root.join('config', 'locales', '*.yml')].map.to_h do |file|
+          code = File.basename(file, '.yml').to_sym
+          name = I18n.t('i18n.name', locale: code)
+          [code, name]
+        end
+        mappings.sort_by { |code, _name| code.to_s }.to_h
+      end
+    end
+
+    def self.available_locales
+      @available_locales ||= locale_code_mapping.keys.freeze
+    end
+
+    def self.default_locale = :en
+    def self.loaded_spec = Gem.loaded_specs['mat_views']
+    def self.project_name = loaded_spec&.name
+    def self.project_version = MatViews::VERSION
+    def self.project_homepage = loaded_spec&.homepage
+    def self.company_name = 'Codevedas Inc.'
+    def self.documentation_uri = loaded_spec&.metadata&.[]('documentation_uri')
+    def self.bug_tracker_uri = loaded_spec&.metadata&.[]('bug_tracker_uri')
+    def self.support_uri = loaded_spec&.metadata&.[]('support_uri')
+    def self.rubygems_uri = loaded_spec&.metadata&.[]('rubygems_uri')
   end
 end

data/lib/mat_views/helpers/ui_test_ids.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module MatViews
+  module Helpers
+    module UiTestIds
+      GEM_LINK = 'gem_link'
+      PROJECT_HOMEPAGE_LINK = 'project_homepage_link'
+      OPEN_ISSUE_LINK = 'open_issue_link'
+      DOCUMENTATION_LINK = 'documentation_link'
+      SUPPORT_LINK = 'support_link'
+
+      DRAWER_REFRESH_LINK = 'drawer_refresh_link'
+      DRAWER_CLOSE_LINK = 'drawer_close_link'
+
+      HEADER_LINK = 'header_link'
+      PREFERENCES_LINK = 'preferences_link'
+
+      DEFINITIONS_TAB_LINK = 'definitions_tab_link'
+      RUNS_TAB_LINK = 'runs_tab_link'
+
+      NEW_DEFINITION_LINK = 'new_definition_link'
+      SUBMIT_BUTTON = 'submit_button'
+      CANCEL_BUTTON = 'cancel_button'
+      VIEW_HISTORY_LINK = 'view_history_link'
+      VIEW_LINK = 'view_link'
+      EDIT_LINK = 'edit_link'
+      DELETE_LINK = 'delete_link'
+      REFRESH_LINK = 'refresh_link'
+      DROP_LINK = 'drop_link'
+      DROP_CASCADE_LINK = 'drop_cascade_link'
+      CREATE_MV_LINK = 'create_mv_link'
+      RESET_FILTERS_LINK = 'reset_filters_link'
+
+      PREFERENCES_SAVE_BUTTON = 'preferences_save_button'
+      PREFERENCES_CANCEL_BUTTON = 'preferences_cancel_button'
+    end
+  end
+end

data/lib/mat_views/jobs/adapter.rb

@@ -58,19 +58,22 @@ module MatViews
       # @raise [ArgumentError] if the configured adapter is not recognized.
       #
       def self.enqueue(job_class, queue:, args: [])
-        case MatViews.configuration.job_adapter
+        queue_str = queue.to_s
+        job_adapter = MatViews.configuration.job_adapter
+
+        case job_adapter
         when :active_job
-          job_class.set(queue: queue.to_s).perform_later(*args)
+          job_class.set(queue: queue_str).perform_later(*args)
         when :sidekiq
           Sidekiq::Client.push(
             'class' => job_class.name,
-            'queue' => queue.to_s,
+            'queue' => queue_str,
             'args' => args
           )
         when :resque
-          Resque.enqueue_to(queue.to_s, job_class, *args)
+          Resque.enqueue_to(queue_str, job_class, *args)
         else
-          raise ArgumentError, "Unknown job adapter: #{MatViews.configuration.job_adapter.inspect}"
+          raise ArgumentError, "Unknown job adapter: #{job_adapter.inspect}"
         end
       end
     end

data/lib/mat_views/service_response.rb

@@ -10,16 +10,19 @@ module MatViews
   # Encapsulates the result of a service operation within MatViews.
   #
   # Provides a consistent contract for all services by standardizing:
-  # - `status`: Symbol representing outcome (`:ok`, `:created`, `:updated`, `:noop`,
+  # - `status`: Symbol representing outcome (`:ok`, `:created`, `:updated`,
   #   `:skipped`, `:deleted`, `:error`)
-  # - `payload`: Arbitrary structured data returned by the service
-  # - `error`: Exception object or message if an error occurred
-  # - `meta`: Additional metadata such as SQL statements, timing, or strategies
+  # - `request`: Request detailed that service was invoked with
+  # - `response`: Response detailed that service returned, nil with :error status
+  # - `error`: Exception or error message, with :error status
+  #    - `message`: String description of the error
+  #    - `class`: Exception class name
+  #    - `backtrace`: Array of strings
   #
   # @example Successful response
   #   MatViews::ServiceResponse.new(
   #     status: :updated,
-  #     payload: { view: "public.users_mv" }
+  #     response: { ... }
   #   )
   #
   # @example Error response
@@ -29,32 +32,44 @@ module MatViews
   #   )
   #
   class ServiceResponse
-    attr_reader :status, :payload, :error, :meta
+    attr_reader :status, :request, :error, :response
+
+    # acceptable status values
+    ACCEPTABLE_STATES = %i[ok created updated skipped deleted error].freeze
+
+    # statuses indicating success
+    OK_STATES = %i[ok created updated skipped deleted].freeze
+
+    # statuses indicating error
+    ERROR_STATES = %i[error].freeze
 
     # @param status [Symbol] the outcome status
-    # @param payload [Hash] optional data payload
+    # @param request [Hash] request details
+    # @param response [Hash] response details
     # @param error [Exception, String, nil] error details if applicable
-    # @param meta [Hash] additional metadata
-    def initialize(status:, payload: {}, error: nil, meta: {})
+    def initialize(status:, request: {}, response: {}, error: nil)
+      raise ArgumentError, 'status is required' unless ACCEPTABLE_STATES.include?(status&.to_sym)
+      raise ArgumentError, 'error must be an Exception object' if error && !error.is_a?(Exception)
+
       @status = status.to_sym
-      @payload = payload
-      @error = error
-      @meta = meta
+      @request = request
+      @response = response
+      @error = error&.mv_serialize_error
     end
 
     # @return [Boolean] whether the response represents a success
     def success?
-      !error? && %i[ok created updated noop skipped deleted].include?(status)
+      OK_STATES.include?(status)
     end
 
     # @return [Boolean] whether the response represents an error
     def error?
-      !error.nil? || status == :error
+      ERROR_STATES.include?(status)
     end
 
     # @return [Hash] hash representation of the response
     def to_h
-      { status:, payload:, error:, meta: }
+      { status:, request:, response:, error: }.compact
     end
   end
 end