smriti 0.5.0

data/app/controllers/smriti/admin/application_controller.rb

@@ -0,0 +1,135 @@
+# 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 Smriti
+  module Admin
+    # Smriti::Admin::ApplicationController
+    # --------------------------------------
+    # Base controller for the Smriti admin interface.
+    #
+    # Responsibilities:
+    # - Provides authentication and authorization via Smriti::Admin::AuthBridge.
+    # - Applies the `smriti/admin` layout and includes UI helpers.
+    # - Manages locale (`I18n.locale`) and enforces language parameter consistency.
+    # - Sets the browser time zone around each request when provided via cookies.
+    # - Exposes `smriti_data_theme` (light/dark) for theming via cookies.
+    # - Provides frame helpers (`render_frame`, `ensure_frame`) to support Turbo-driven
+    #   admin UI navigation.
+    #
+    # Filters:
+    # - `before_action`: sets locale and redirects to enforce `lang` consistency.
+    # - `around_action`: wraps requests in the browser’s time zone if valid.
+    #
+    # Methods:
+    # - {#default_url_options} ensures `lang` param is included in generated URLs.
+    # - {#set_time_zone} runs the request in the cookie-provided time zone if valid.
+    # - {#render_frame} renders a UI frame partial given `frame_id`.
+    # - {#ensure_frame} requires a `frame_id` param for frame-only actions.
+    # - {#redirect_to_lang} redirects when the URL `lang` param differs from `I18n.locale`.
+    # - {#set_smriti_locale} sets the session-defined or default locale.
+    # - {#smriti_data_theme} returns `light`, `dark`, or `nil` for theming.
+    #
+    class ApplicationController < ActionController::Base
+      include Smriti::Admin::AuthBridge
+
+      helper Smriti::Admin::UiHelper
+      helper Smriti::Admin::LocalizedDigitHelper
+      helper Smriti::Admin::DatatableHelper
+      helper Smriti::Helpers::UiTestIds
+      layout 'smriti/admin'
+
+      before_action :set_smriti_locale, :redirect_to_lang
+      helper_method :smriti_data_theme
+      around_action :set_time_zone
+
+      private
+
+      # Default URL options, ensuring `lang` is always included.
+      #
+      # @api private
+      #
+      # @return [Hash{Symbol => String}]
+      def default_url_options
+        { lang: params[:lang].presence || I18n.locale }
+      end
+
+      # Wraps the request in the browser’s time zone if one is set in cookies.
+      #
+      # @api private
+      #
+      # @yield the block representing the request lifecycle
+      # @return [void]
+      def set_time_zone(&)
+        browser_tz = cookies[:browser_tz]
+        if browser_tz.present? && ActiveSupport::TimeZone[browser_tz]
+          Time.use_zone(browser_tz, &)
+        else
+          yield
+        end
+      end
+
+      # Ensures a `frame_id` param is present.
+      # If missing, redirects to the admin root with an alert.
+      #
+      # @api private
+      #
+      # @return [void]
+      def ensure_frame
+        @frame_id = params[:frame_id]
+        return if @frame_id.present?
+
+        redirect_to admin_root_path, alert: I18n.t('smriti.errors.frame_only')
+      end
+
+      # Redirects to enforce that the `lang` param matches `I18n.locale`.
+      #
+      # @api private
+      #
+      # @return [void]
+      def redirect_to_lang
+        locale_str = locale.to_s
+        return if params[:lang] == locale_str
+
+        lang = locale_str
+        redirect_to url_for(params.permit!.to_h.merge(lang: lang)), status: :see_other
+      end
+
+      # Sets the locale for Smriti admin requests.
+      # Falls back to default locale if session value is invalid.
+      #
+      # @api private
+      #
+      # @return [void]
+      def set_smriti_locale
+        I18n.locale = if (loc = session[:smriti_locale]).present? && Smriti::Engine.available_locales.map(&:to_s).include?(loc)
+                        loc
+                      else
+                        Smriti::Engine.default_locale
+                      end
+      end
+
+      # Returns the current theme for the admin UI.
+      #
+      # @api private
+      #
+      # @return ["light", "dark", nil] the theme stored in cookies, or `nil` if invalid
+      def smriti_data_theme
+        theme = cookies[:theme].to_s
+        %w[light dark].include?(theme) ? theme : nil
+      end
+
+      # Returns the current locale.
+      #
+      # @api private
+      #
+      # @return [Symbol] the current I18n locale
+      def locale
+        I18n.locale
+      end
+    end
+  end
+end

data/app/controllers/smriti/admin/dashboard_controller.rb

@@ -0,0 +1,32 @@
+# 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 Smriti
+  module Admin
+    # Smriti::Admin::DashboardController
+    # ------------------------------------
+    # Controller for the Smriti admin dashboard.
+    #
+    # Responsibilities:
+    # - Provides the landing page (`index`) for the admin interface.
+    # - Authorizes access via {ApplicationController#authorize_smriti!}.
+    # - Prepares placeholder metrics content (future: aggregated refresh metrics).
+    #
+    class DashboardController < ApplicationController
+      # GET /:lang/admin
+      #
+      # Renders the admin dashboard. Currently sets a placeholder message
+      # until metric aggregation is implemented.
+      #
+      # @return [void]
+      def index
+        authorize_smriti!(:view, :smriti_dashboard)
+        @metrics_note = 'Metrics coming soon (see: Aggregate refresh metrics for reporting).'
+      end
+    end
+  end
+end

data/app/controllers/smriti/admin/mat_view_definitions_controller.rb

@@ -0,0 +1,372 @@
+# 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 Smriti
+  module Admin
+    # Smriti::Admin::MatViewDefinitionsController
+    # ---------------------------------------------
+    # Admin CRUD controller for {Smriti::MatViewDefinition} records.
+    #
+    # Responsibilities:
+    # - Full CRUD lifecycle: index, show, new, create, edit, update, destroy.
+    # - Admin-only actions to trigger materialised view operations:
+    #   - {#create_now} → enqueues {Smriti::CreateViewJob}
+    #   - {#refresh} → enqueues {Smriti::RefreshViewJob}
+    #   - {#delete_now} → enqueues {Smriti::DeleteViewJob}
+    # - Integrates with Turbo Frames (uses frame-aware redirects/responses).
+    # - Normalizes array fields (`unique_index_columns`, `dependencies`) from
+    #   comma-separated params into arrays.
+    #
+    # Filters:
+    # - `before_action :set_definition` for member actions.
+    # - `before_action :normalize_array_fields` for create/update.
+    # - `before_action :ensure_frame` to enforce frame context.
+    #
+    class MatViewDefinitionsController < ApplicationController
+      include Smriti::Admin::DatatableHelper
+
+      before_action :set_definition, only: %i[show edit update destroy create_now refresh delete_now]
+      before_action :normalize_array_fields, only: %i[create update]
+      before_action :parse_headers_to_params, :ensure_frame
+
+      # GET /:lang/admin/definitions
+      #
+      # Two part rendering:
+      # - Full page load when no `stream` param: renders index with datatable frame. This is
+      #   essentially shell of the datatable for initial load.
+      # - When shell is loaded, it requests the `stream` version which renders just the datatable rows
+      #   and pagination controls. This allows for dynamic updates via Turbo Streams.
+      #
+      # @return [void]
+      def index
+        authorize_smriti!(:read, :smriti_definitions)
+
+        assign_index_state
+
+        if params[:stream].present?
+          render_dt_turbo_streams
+          return
+        end
+        render 'index', formats: :html, layout: 'smriti/turbo_frame', locals: { row_meta: @row_meta }
+      end
+
+      # GET /:lang/admin/definitions/:id
+      #
+      # Shows a single definition, including run history.
+      #
+      # @return [void]
+      def show
+        authorize_smriti!(:read, :smriti_definition, @definition)
+        @mv_exists = Smriti::Services::CheckMatviewExists.new(@definition).call.response[:exists]
+        @runs = @definition.mat_view_runs.order(created_at: :desc).to_a
+        render 'show', formats: :html, layout: 'smriti/turbo_frame'
+      end
+
+      # GET /:lang/admin/definitions/new
+      #
+      # Renders the new definition form.
+      #
+      # @return [void]
+      def new
+        authorize_smriti!(:create, :smriti_definition)
+        @definition = Smriti::MatViewDefinition.new
+        render 'form', formats: :html, layout: 'smriti/turbo_frame'
+      end
+
+      # POST /:lang/admin/definitions
+      #
+      # Creates a new definition from params.
+      #
+      # @return [void]
+      def create
+        authorize_smriti!(:create, :smriti_definition)
+        @definition = Smriti::MatViewDefinition.new(definition_params)
+        if @definition.save
+          handle_frame_response(status: 298)
+        else
+          render 'form', formats: :html, layout: 'smriti/turbo_frame', status: :unprocessable_content
+        end
+      end
+
+      # GET /:lang/admin/definitions/:id/edit
+      #
+      # Renders the edit form for an existing definition.
+      #
+      # @return [void]
+      def edit
+        authorize_smriti!(:update, :smriti_definition, @definition)
+        render 'form', formats: :html, layout: 'smriti/turbo_frame'
+      end
+
+      # PATCH/PUT /:lang/admin/definitions/:id
+      #
+      # Updates an existing definition.
+      #
+      # @return [void]
+      def update
+        authorize_smriti!(:update, :smriti_definition, @definition)
+        if @definition.update(definition_params)
+          handle_frame_response(status: 298)
+        else
+          render 'form', formats: :html, layout: 'smriti/turbo_frame', status: :unprocessable_content
+        end
+      end
+
+      # DELETE /:lang/admin/definitions/:id
+      #
+      # Destroys the definition. Frame-specific redirect/empty response.
+      #
+      # @return [void]
+      def destroy
+        authorize_smriti!(:destroy, :smriti_definition, @definition)
+        @definition.destroy!
+        if @frame_id == 'dash-definitions'
+          redirect_to admin_mat_view_definitions_path(frame_id: @frame_id), status: :see_other
+        else
+          render 'empty', formats: :html, layout: 'smriti/turbo_frame', status: 298
+        end
+      end
+
+      # POST /:lang/admin/definitions/:id/create_now
+      #
+      # Immediately enqueues a background job to create the materialised view.
+      #
+      # @return [void]
+      def create_now
+        authorize_smriti!(:create, :smriti_definition_view, @definition)
+
+        force = params[:force].to_s.downcase == 'true'
+        Smriti::Jobs::Adapter.enqueue(
+          Smriti::CreateViewJob,
+          queue: Smriti.configuration.job_queue,
+          args: [@definition.id, force, row_count_strategy]
+        )
+        handle_frame_response
+      end
+
+      # POST /:lang/admin/definitions/:id/refresh
+      #
+      # Immediately enqueues a background job to refresh the materialised view.
+      #
+      # @return [void]
+      def refresh
+        authorize_smriti!(:update, :smriti_definition_view, @definition)
+        Smriti::Jobs::Adapter.enqueue(
+          Smriti::RefreshViewJob,
+          queue: Smriti.configuration.job_queue,
+          args: [@definition.id, row_count_strategy]
+        )
+        handle_frame_response
+      end
+
+      # POST /:lang/admin/definitions/:id/delete_now
+      #
+      # Immediately enqueues a background job to delete the materialised view.
+      #
+      # @return [void]
+      def delete_now
+        authorize_smriti!(:destroy, :smriti_definition_view, @definition)
+
+        cascade = params[:cascade].to_s.downcase == 'true'
+        Smriti::Jobs::Adapter.enqueue(
+          Smriti::DeleteViewJob,
+          queue: Smriti.configuration.job_queue,
+          args: [@definition.id, cascade, row_count_strategy]
+        )
+        handle_frame_response
+      end
+
+      private
+
+      # Returns the configured row count strategy for admin UI operations.
+      #
+      # @api private
+      #
+      # @return [Symbol, nil] row count strategy (e.g., :estimated, :exact, :none)
+      def row_count_strategy
+        Smriti.configuration.admin_ui[:row_count_strategy] || :none
+      end
+
+      # Handles redirect/response after a frame-based action.
+      #
+      # @api private
+      #
+      # @param status [Symbol,Integer] the HTTP status for redirect
+      # @return [void]
+      def handle_frame_response(status: :see_other)
+        if @frame_id == 'dash-definitions'
+          dtsort = params[:dtsort]
+          dtfilter = params[:dtfilter]
+          dtsearch = params[:dtsearch]
+          redirect_to admin_mat_view_definitions_path(frame_id: @frame_id, stream: true, dtsort:, dtfilter:, dtsearch:), status: status
+        else
+          redirect_to admin_mat_view_definition_path(@definition, frame_id: @frame_id), status: status
+        end
+      end
+
+      # Loads a definition by `params[:id]`.
+      #
+      # @api private
+      #
+      # @return [void]
+      def set_definition
+        @definition = Smriti::MatViewDefinition.find(params[:id])
+      end
+
+      # Normalizes array fields (unique_index_columns, dependencies) from
+      # comma-separated strings into arrays.
+      #
+      # @api private
+      #
+      # @return [void]
+      def normalize_array_fields
+        normalize_array_field(:mat_view_definition, :unique_index_columns)
+        normalize_array_field(:mat_view_definition, :dependencies)
+      end
+
+      # Normalizes a specific array field from a comma-separated string into an array.
+      #
+      # @api private
+      #
+      # @param object_key [Symbol] the params object key (e.g., :mat_view_definition)
+      # @param array_key [Symbol] the specific array field key (e.g., :unique_index_columns)
+      #
+      # @return [void]
+      def normalize_array_field(object_key, array_key)
+        object = params[object_key]
+
+        values = object[array_key]
+        return if values.nil?
+
+        object[array_key] = values.split(',').map(&:strip).reject(&:blank?)
+      end
+
+      # Strong params for mat view definitions.
+      #
+      # @api private
+      #
+      # @return [ActionController::Parameters]
+      def definition_params
+        params.require(:mat_view_definition).permit(
+          :name, :sql, :refresh_strategy, :schedule_cron,
+          unique_index_columns: [], dependencies: []
+        )
+      end
+
+      # Loads data for the index datatable with filtering, searching, sorting, and pagination.
+      # sets @data.
+      #
+      # @api private
+      #
+      # @return [void]
+      def index_dt_load_data
+        rel = Smriti::MatViewDefinition
+        rel = dt_apply_filter(rel, index_dt_columns)
+        rel = dt_apply_search(rel, index_dt_columns)
+        rel = dt_apply_sort(rel, index_dt_columns)
+        @data = dt_apply_pagination(rel, @dt_config[:pagination][:per_page_default])
+      end
+
+      # Configuration for the index datatable.
+      #
+      # @api private
+      #
+      # @return [Hash] datatable configuration
+      def index_dt_config
+        columns = index_dt_columns
+        {
+          id: 'mv-definitions-table',
+          index_url: admin_mat_view_definitions_path(frame_id: @frame_id),
+          frame_id: 'mv-definitions-datatable',
+          columns: columns,
+          dt_humanize_ref: 'Smriti::MatViewDefinition',
+          empty_row_partial_name: 'dt-index-empty-row',
+          row_partial_name: 'dt-index-row',
+          search_enabled: columns.any? { |_, col| col[:search].present? },
+          filter_enabled: columns.any? { |_, col| col[:filter].present? },
+          pagination: { per_page_default: 10, per_page_options: [10, 25, 50, 100] }
+        }
+      end
+
+      # Column definitions for the index datatable.
+      #
+      # @api private
+      #
+      # @return [Hash] column definitions
+      def index_dt_columns
+        {
+          name: {
+            label_ref: 'name',
+            label_type: 'humanize_attr',
+            sort: 'name',
+            filter: 'name',
+            search: 'name'
+          },
+          refresh_strategy: {
+            label_ref: 'refresh_strategy',
+            label_type: 'humanize_attr',
+            sort: 'refresh_strategy',
+            filter: 'refresh_strategy',
+            search: 'refresh_strategy'
+          },
+          schedule_cron: {
+            label_ref: 'schedule_cron',
+            label_type: 'humanize_attr',
+            sort: 'schedule_cron',
+            filter: 'schedule_cron',
+            search: 'schedule_cron'
+          },
+          last_run_at: {
+            label_ref: 'last_run_at',
+            label_type: 'humanize_attr',
+            sort: 'last_run_at',
+            filter: nil,
+            search: 'last_run_at'
+          },
+          actions: {
+            label_ref: 'actions',
+            label_type: 'i18n',
+            th_style: 'justify-content: end;',
+            filter: nil,
+            sort: nil,
+            search: nil
+          }
+        }
+      end
+
+      # Builds a map of definition names to their existence status in the database.
+      # If definitions is nil or empty, returns an empty hash.
+      #
+      # @api private
+      #
+      # @param definitions [Array<Smriti::MatViewDefinition>] the definitions to check
+      # @return [Hash{String => Boolean}] map of definition names to existence status
+      # e.g., { "my_view" => true, "other_view" => false }
+      def build_matview_exists_map(definitions)
+        return {} if definitions.blank?
+
+        definitions.to_h do |definition|
+          exists = Smriti::Services::CheckMatviewExists.new(definition).call.response[:exists]
+          [definition.name, exists]
+        end
+      end
+
+      # Assigns instance variables for the index action.
+      #
+      # @api private
+      #
+      # @return [void]
+      def assign_index_state
+        @dt_config = index_dt_config
+        @data = []
+
+        index_dt_load_data
+        @row_meta = { mv_exists_map: build_matview_exists_map(@data) }
+      end
+    end
+  end
+end