mat_views 0.2.0 → 0.3.0

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/services/base_service.rb

@@ -8,7 +8,7 @@
 module MatViews
   module Services
     ##
-    # Base class for service objects that operate on PostgreSQL materialized
+    # Base class for service objects that operate on PostgreSQL materialised
     # views (create/refresh/delete, schema discovery, quoting, and common
     # response helpers).
     #
@@ -19,12 +19,17 @@ module MatViews
     #
     # @example Subclassing BaseService
     #   class MyService < MatViews::Services::BaseService
-    #     def run
-    #       return err("missing view") unless view_exists?
-    #       # perform work...
-    #       ok(:updated, payload: { view: "#{schema}.#{rel}" })
-    #     rescue => e
-    #       error_response(e, meta: { op: "my_service" })
+    #     private
+    #     def assign_request
+    #     # assign @request hash keys
+    #     end
+    #
+    #     def prepare
+    #     # perform pre-flight checks, raise StandardError on failure
+    #     end
+    #
+    #     def _run
+    #     # perform the operation, return a MatViews::ServiceResponse
     #     end
     #   end
     #
@@ -42,7 +47,7 @@ module MatViews
       DEFAULT_NIL_STRATEGY = :none
 
       ##
-      # @return [MatViews::MatViewDefinition] The target materialized view definition.
+      # @return [MatViews::MatViewDefinition] The target materialised view definition.
       attr_reader :definition
 
       ##
@@ -61,6 +66,11 @@ module MatViews
       # @return [Hash]
       attr_accessor :response
 
+      ##
+      # wrap in transaction
+      # @return [Boolean]
+      attr_accessor :use_transaction
+
       ##
       # @param definition [MatViews::MatViewDefinition]
       # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
@@ -70,6 +80,7 @@ module MatViews
         @row_count_strategy = extract_row_strategy(row_count_strategy)
         @request = {}
         @response = {}
+        @use_transaction = true
       end
 
       ##
@@ -81,19 +92,35 @@ module MatViews
       #
       # @return [MatViews::ServiceResponse]
       # @raise [NotImplementedError] if not implemented in subclass
-      def run
-        assign_request
-        prepare
-        _run
+      def call
+        if use_transaction
+          ActiveRecord::Base.transaction { run_core }
+        else
+          run_core
+        end
       rescue StandardError => e
+        # finish pending transaction if any
+        # eg: current transaction is aborted, commands ignored until end of transaction block
         error_response(e)
       end
 
       private
 
+      ##
+      # Core run logic without transaction wrapper.
+      # Called by {#call}.
+      #
+      # @api private
+      # @return [MatViews::ServiceResponse]
+      def run_core
+        assign_request
+        prepare
+        _run
+      end
+
       ##
       # Assign the request parameters.
-      # Called by {#run} before {#prepare}.
+      # Called by {#call} before {#prepare}.
       #
       # Must be implemented in concrete subclasses.
       #
@@ -107,7 +134,7 @@ module MatViews
 
       ##
       # Perform pre-flight checks.
-      # Called by {#run} after {#assign_request}.
+      # Called by {#call} after {#assign_request}.
       #
       # Must be implemented in concrete subclasses.
       #
@@ -122,7 +149,7 @@ module MatViews
 
       ##
       # Execute the service operation.
-      # Called by {#run} after {#prepare}.
+      # Called by {#call} after {#prepare}.
       #
       # Must be implemented in concrete subclasses.
       #
@@ -197,7 +224,7 @@ module MatViews
       # ────────────────────────────────────────────────────────────────
 
       ##
-      # Whether the materialized view exists for the resolved `schema` and `rel`.
+      # Whether the materialised view exists for the resolved `schema` and `rel`.
       #
       # @api private
       # @return [Boolean]
@@ -222,7 +249,7 @@ module MatViews
       end
 
       ##
-      # Drop the materialized view if it exists (idempotent).
+      # Drop the materialised view if it exists (idempotent).
       #
       # @api private
       # @return [void]
@@ -376,26 +403,7 @@ module MatViews
       end
 
       ##
-      # Validate SQL starts with SELECT.
-      #
-      # @api private
-      # @return [Boolean]
-      #
-      def valid_sql?
-        definition.sql.to_s.strip.upcase.start_with?('SELECT')
-      end
-
-      ##
-      # Validate that the view name is a sane PostgreSQL identifier.
-      #
-      # @api private
-      # @return [Boolean]
-      def valid_name?
-        /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(definition.name.to_s)
-      end
-
-      ##
-      # Check for any UNIQUE index on the materialized view, required by CONCURRENTLY.
+      # Check for any UNIQUE index on the materialised view, required by CONCURRENTLY.
       #
       # @api private
       # @return [Boolean]
@@ -450,7 +458,7 @@ module MatViews
       end
 
       ##
-      # Accurate row count using `COUNT(*)` on the materialized view.
+      # Accurate row count using `COUNT(*)` on the materialised view.
       #
       # @api private
       # @return [Integer]

data/lib/mat_views/services/check_matview_exists.rb

@@ -0,0 +1,76 @@
+# 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 Services
+    # MatViews::Services::CheckMatviewExists
+    # --------------------------------------
+    # Service object that checks whether the underlying PostgreSQL **materialised view**
+    # for a given {MatViews::MatViewDefinition} currently exists.
+    #
+    # ### Contract
+    # - Inherits from {MatViews::Services::BaseService}.
+    # - Uses BaseService helpers such as `definition`, `view_exists?`,
+    #   `ok`, `raise_err`, and the `request`/`response` accessors.
+    # - The public entrypoint is `#call` (defined in BaseService), which will call the
+    #   private lifecycle hooks here: {#prepare}, {#assign_request}, and {#_run}.
+    #
+    # ### Result
+    # - On success: status `:ok`, with `response: { exists: true|false }`.
+    # - On validation failure (bad view name): raises via {BaseService#raise_err}.
+    #
+    # @example Check if a materialised view exists
+    #   defn = MatViews::MatViewDefinition.find(1)
+    #   res  = MatViews::Services::CheckMatviewExists.new(defn).call
+    #   if res.success?
+    #     puts res.response[:exists] ? "Exists" : "Missing"
+    #   else
+    #     warn res.error
+    #   end
+    #
+    # @see MatViews::Services::BaseService
+    # @see MatViews::MatViewDefinition
+    #
+    class CheckMatviewExists < BaseService
+      private
+
+      # Core execution step (invoked by BaseService#call).
+      #
+      # @api private
+      #
+      # Sets {#response} to `{ exists: Boolean }` and marks the service as ok.
+      #
+      # @return [void]
+      def _run
+        self.response = { exists: view_exists? }
+        ok(:ok)
+      end
+
+      # Validation step (invoked by BaseService#call before execution).
+      #
+      # @api private
+      #
+      # Empty for this service as no other preparation is needed.
+      #
+      # @return [void]
+      def prepare; end
+
+      # Request initialization (invoked by BaseService#call).
+      #
+      # @api private
+      #
+      # Establishes a canonical, immutable snapshot of the input request
+      # for logging/inspection purposes. This service does not require inputs,
+      # so it assigns an empty Hash.
+      #
+      # @return [void]
+      def assign_request
+        self.request = {}
+      end
+    end
+  end
+end

data/lib/mat_views/services/concurrent_refresh.rb

@@ -13,7 +13,7 @@ module MatViews
     #   `REFRESH MATERIALIZED VIEW CONCURRENTLY <schema>.<rel>`
     #
     # It keeps the view readable during refresh, but **requires at least one
-    # UNIQUE index** on the materialized view (a PostgreSQL constraint).
+    # UNIQUE index** on the materialised view (a PostgreSQL constraint).
     #
     # Options:
     # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
@@ -25,7 +25,7 @@ module MatViews
     #
     # @example Direct usage
     #   svc = MatViews::Services::ConcurrentRefresh.new(definition, **options)
-    #   response = svc.run
+    #   response = svc.call
     #   response.success? # => true/false
     #
     # @example via job, this is the typical usage and will create a run record in the DB
@@ -33,6 +33,11 @@ module MatViews
     #   MatViews::Jobs::Adapter.enqueue(MatViews::Services::RefreshViewJob, definition.id, **options)
     #
     class ConcurrentRefresh < BaseService
+      def initialize(definition, row_count_strategy: :estimated)
+        super
+        @use_transaction = false
+      end
+
       private
 
       ##
@@ -61,7 +66,7 @@ module MatViews
 
       ##
       # Assign the request parameters.
-      # Called by {#run} before {#prepare}.
+      # Called by {#call} before {#prepare}.
       # Sets `concurrent: true` in the request hash.
       #
       # @api private
@@ -72,15 +77,13 @@ module MatViews
       end
 
       ##
-      # Perform pre-flight checks.
-      # Called by {#run} after {#assign_request}.
+      # Validation step (invoked by BaseService#call before execution).
       #
       # @api private
       # @return [nil] on success
       # @raise [StandardError] on failure
       #
       def prepare
-        raise_err("Invalid view name format: #{definition.name.inspect}") unless valid_name?
         raise_err("Materialized view #{schema}.#{rel} does not exist") unless view_exists?
         raise_err("Materialized view #{schema}.#{rel} must have a unique index for concurrent refresh") unless unique_index_exists?
 

data/lib/mat_views/services/create_view.rb

@@ -8,7 +8,7 @@
 module MatViews
   module Services
     ##
-    # Service responsible for creating PostgreSQL materialized views.
+    # Service responsible for creating PostgreSQL materialised views.
     #
     # The service validates the view definition, handles existence checks,
     # executes `CREATE MATERIALIZED VIEW ... WITH DATA`, and, when the
@@ -25,12 +25,12 @@ module MatViews
     #
     # @example Create a new matview (no force)
     #   svc = MatViews::Services::CreateView.new(defn, **options)
-    #   response = svc.run
+    #   response = svc.call
     #   response.status # => :created or :skipped
     #
     # @example Force recreate an existing matview
     #   svc = MatViews::Services::CreateView.new(defn, force: true)
-    #   svc.run
+    #   svc.call
     #
     # @example via job, this is the typical usage and will create a run record in the DB
     #   MatViews::Jobs::Adapter.enqueue(MatViews::Services::CreateViewJob, definition.id, **options)
@@ -53,7 +53,11 @@ module MatViews
       # - `nil` → skip row count
       def initialize(definition, force: false, row_count_strategy: :estimated)
         super(definition, row_count_strategy: row_count_strategy)
-        @force = !!force
+        @force = force
+        # Transactions are disabled if unique_index_columns are present because
+        # PostgreSQL does not allow creating a UNIQUE INDEX CONCURRENTLY inside a transaction block.
+        # If a unique index is required (for concurrent refresh), we must avoid wrapping the operation in a transaction.
+        @use_transaction = definition.unique_index_columns.none?
       end
 
       private
@@ -63,7 +67,7 @@ module MatViews
       #
       # - Validates name, SQL, and concurrent-index requirements.
       # - Handles existing view: skipped (default) or drop+recreate (`force: true`).
-      # - Creates the materialized view WITH DATA.
+      # - Creates the materialised view WITH DATA.
       # - Creates a UNIQUE index if refresh strategy is concurrent.
       #
       # @api private
@@ -94,22 +98,18 @@ module MatViews
       end
 
       ##
-      # Validate name, SQL, and concurrent strategy requirements.
+      # Validation step (invoked by BaseService#call before execution).
+      # Empty for this service as no other preparation is needed.
       #
       # @api private
-      # @return [MatViews::ServiceResponse, nil] error response or nil if OK
       #
-      def prepare
-        raise_err("Invalid view name format: #{definition.name.inspect}") unless valid_name?
-        raise_err('SQL must start with SELECT') unless valid_sql?
-        raise_err('refresh_strategy=concurrent requires unique_index_columns (non-empty)') if strategy == 'concurrent' && cols.empty?
-
-        nil
-      end
+      # @return [void]
+      #
+      def prepare; end
 
       ##
       # Assign the request parameters.
-      # Called by {#run} before {#prepare}.
+      # Called by {#call} before {#prepare}.
       #
       # @api private
       # @return [void]