smriti 0.5.0

data/lib/smriti/service_response.rb

@@ -0,0 +1,75 @@
+# 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
+  ##
+  # Encapsulates the result of a service operation within Smriti.
+  #
+  # Provides a consistent contract for all services by standardizing:
+  # - `status`: Symbol representing outcome (`:ok`, `:created`, `:updated`,
+  #   `:skipped`, `:deleted`, `:error`)
+  # - `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
+  #   Smriti::ServiceResponse.new(
+  #     status: :updated,
+  #     response: { ... }
+  #   )
+  #
+  # @example Error response
+  #   Smriti::ServiceResponse.new(
+  #     status: :error,
+  #     error: StandardError.new("Something went wrong")
+  #   )
+  #
+  class ServiceResponse
+    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 request [Hash] request details
+    # @param response [Hash] response details
+    # @param error [Exception, String, nil] error details if applicable
+    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
+      @request = request
+      @response = response
+      @error = error&.mv_serialize_error
+    end
+
+    # @return [Boolean] whether the response represents a success
+    def success?
+      OK_STATES.include?(status)
+    end
+
+    # @return [Boolean] whether the response represents an error
+    def error?
+      ERROR_STATES.include?(status)
+    end
+
+    # @return [Hash] hash representation of the response
+    def to_h
+      { status:, request:, response:, error: }.compact
+    end
+  end
+end

data/lib/smriti/services/base_service.rb

@@ -0,0 +1,471 @@
+# 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 Services
+    ##
+    # Base class for service objects that operate on PostgreSQL materialised
+    # views (create/refresh/delete, schema discovery, quoting, and common
+    # response helpers).
+    #
+    # Concrete services (e.g., {Smriti::Services::CreateView},
+    # {Smriti::Services::RegularRefresh}) should inherit from this class.
+    #
+    # @abstract
+    #
+    # @example Subclassing BaseService
+    #   class MyService < Smriti::Services::BaseService
+    #     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 Smriti::ServiceResponse
+    #     end
+    #   end
+    #
+    class BaseService
+      # Constant indicating unknown row count
+      UNKNOWN_ROW_COUNT = -1
+
+      # Allowed row count strategies
+      ALLOWED_ROW_STRATEGIES = %i[none estimated exact].freeze
+
+      # Default row count strategy
+      DEFAULT_ROW_STRATEGY = :estimated
+
+      # Default strategy when nil or unrecognized value is given
+      DEFAULT_NIL_STRATEGY = :none
+
+      ##
+      # @return [Smriti::MatViewDefinition] The target materialised view definition.
+      attr_reader :definition
+
+      ##
+      # Row count strategy (`:estimated`, `:exact`, `nil`).
+      #
+      # @return [Symbol, nil]
+      attr_reader :row_count_strategy
+
+      ##
+      # request hash to be returned in service response
+      # @return [Hash]
+      attr_accessor :request
+
+      ##
+      # response hash to be returned in service response
+      # @return [Hash]
+      attr_accessor :response
+
+      ##
+      # wrap in transaction
+      # @return [Boolean]
+      attr_accessor :use_transaction
+
+      ##
+      # @param definition [Smriti::MatViewDefinition]
+      # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
+      #
+      def initialize(definition, row_count_strategy: DEFAULT_ROW_STRATEGY)
+        @definition = definition
+        @row_count_strategy = extract_row_strategy(row_count_strategy)
+        @request = {}
+        @response = {}
+        @use_transaction = true
+      end
+
+      ##
+      # Execute the service operation.
+      #
+      # Calls {#assign_request}, {#prepare} and {#_run} in order.
+      #
+      # Concrete subclasses must implement these methods.
+      #
+      # @return [Smriti::ServiceResponse]
+      # @raise [NotImplementedError] if not implemented in subclass
+      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 [Smriti::ServiceResponse]
+      def run_core
+        assign_request
+        prepare
+        _run
+      end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      #
+      # Must be implemented in concrete subclasses.
+      #
+      # @api private
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented in subclass
+      #
+      def assign_request
+        raise NotImplementedError, "Must implement #{self.class}##{__method__}"
+      end
+
+      ##
+      # Perform pre-flight checks.
+      # Called by {#call} after {#assign_request}.
+      #
+      # Must be implemented in concrete subclasses.
+      #
+      # @api private
+      # @return [nil] on success
+      # @raise [StandardError] on failure
+      # @raise [NotImplementedError] if not implemented in subclass
+      #
+      def prepare
+        raise NotImplementedError, "Must implement #{self.class}##{__method__}"
+      end
+
+      ##
+      # Execute the service operation.
+      # Called by {#call} after {#prepare}.
+      #
+      # Must be implemented in concrete subclasses.
+      #
+      # @api private
+      # @return [Smriti::ServiceResponse]
+      # @raise [NotImplementedError] if not implemented in subclass
+      #
+      def _run
+        raise NotImplementedError, "Must implement #{self.class}##{__method__}"
+      end
+
+      def extract_row_strategy(value)
+        ALLOWED_ROW_STRATEGIES.include?(value) ? value : DEFAULT_NIL_STRATEGY
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # Schema / resolution helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Resolve the first existing schema from `schema_search_path`,
+      # falling back to `"public"` if none are valid.
+      #
+      # Supports `$user`, quoted tokens, and ignores non-existent schemas.
+      #
+      # @api private
+      # @return [String] a valid schema name
+      #
+      def first_existing_schema
+        raw_path   = conn.schema_search_path.presence || 'public'
+        candidates = raw_path.split(',').filter_map { |token| resolve_schema_token(token.strip) }
+        candidates << 'public' unless candidates.include?('public')
+        candidates.find { |schema_str| schema_exists?(schema_str) } || 'public'
+      end
+
+      ##
+      # Normalize a schema token:
+      # - strip surrounding quotes
+      # - expand `$user` to the current database user
+      #
+      # @api private
+      # @param token [String]
+      # @return [String]
+      #
+      def resolve_schema_token(token)
+        cleaned = token.delete_prefix('"').delete_suffix('"')
+        return current_user if cleaned == '$user'
+
+        cleaned
+      end
+
+      ##
+      # @api private
+      # @return [String] current PostgreSQL user
+      def current_user
+        @current_user ||= conn.select_value('SELECT current_user')
+      end
+
+      ##
+      # Check whether a schema exists.
+      #
+      # @api private
+      # @param name [String] schema name
+      # @return [Boolean]
+      #
+      def schema_exists?(name)
+        conn.select_value("SELECT to_regnamespace(#{conn.quote(name)}) IS NOT NULL")
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # View / relation helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Whether the materialised view exists for the resolved `schema` and `rel`.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def view_exists?
+        conn.select_value(<<~SQL).to_i.positive?
+          SELECT COUNT(*)
+          FROM pg_matviews
+          WHERE schemaname = #{conn.quote(schema)}
+            AND matviewname = #{conn.quote(rel)}
+        SQL
+      end
+
+      ##
+      # Fully-qualified, safely-quoted relation name, e.g. `"public"."mv_users"`.
+      #
+      # @api private
+      # @return [String]
+      #
+      def qualified_rel
+        %(#{quote_table_name(schema)}.#{quote_table_name(rel)})
+      end
+
+      ##
+      # Drop the materialised view if it exists (idempotent).
+      #
+      # @api private
+      # @return [void]
+      #
+      def drop_view
+        conn.execute(<<~SQL)
+          DROP MATERIALIZED VIEW IF EXISTS #{qualified_rel}
+        SQL
+      end
+
+      ##
+      # Refresh strategy from the definition (stringified).
+      #
+      # @api private
+      # @return [String] one of `"regular"`, `"concurrent"`, `"swap"` (or custom)
+      #
+      def strategy
+        @strategy ||= definition.refresh_strategy.to_s
+      end
+
+      ##
+      # Unqualified relation (matview) name from the definition.
+      #
+      # @api private
+      # @return [String]
+      #
+      def rel
+        @rel ||= definition.name.to_s
+      end
+
+      ##
+      # SQL `SELECT …` for the materialization.
+      #
+      # @api private
+      # @return [String]
+      #
+      def sql
+        @sql ||= definition.sql.to_s
+      end
+
+      ##
+      # Unique index column list (normalized to strings, unique).
+      #
+      # @api private
+      # @return [Array<String>]
+      #
+      def cols
+        @cols ||= Array(definition.unique_index_columns).map(&:to_s).uniq
+      end
+
+      ##
+      # ActiveRecord connection.
+      #
+      # @api private
+      # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      #
+      def conn
+        @conn ||= ActiveRecord::Base.connection
+      end
+
+      ##
+      # Resolved, existing schema for this operation.
+      #
+      # @api private
+      # @return [String]
+      #
+      def schema
+        @schema ||= first_existing_schema
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # Response helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Build a success response.
+      #
+      # @api private
+      # @param status [Symbol] e.g., `:ok`, `:created`, `:updated`, `:skipped`, `:deleted`
+      # @return [Smriti::ServiceResponse]
+      #
+      def ok(status)
+        Smriti::ServiceResponse.new(status:, request:, response:)
+      end
+
+      ##
+      # Raise a StandardError with the given message.
+      #
+      # @api private
+      # @param msg [String]
+      # @return [void]
+      # @raise [StandardError] with `msg`
+      #
+      def raise_err(msg)
+        raise StandardError, msg
+      end
+
+      ##
+      # Build an error response from an exception, including backtrace.
+      #
+      # @api private
+      # @param error [Exception]
+      # @return [Smriti::ServiceResponse]
+      #
+      def error_response(error)
+        Smriti::ServiceResponse.new(status: :error, error:, request:, response:)
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # Quoting / environment helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Quote a column name for SQL.
+      #
+      # @api private
+      # @param name [String, Symbol]
+      # @return [String] quoted column name
+      #
+      def quote_column_name(name)
+        conn.quote_column_name(name)
+      end
+
+      ##
+      # Quote a table/relation name for SQL.
+      #
+      # @api private
+      # @param name [String, Symbol]
+      # @return [String] quoted relation name
+      #
+      def quote_table_name(name)
+        conn.quote_table_name(name)
+      end
+
+      ##
+      # Whether the underlying PG connection is idle (no active tx/savepoint).
+      #
+      # Used to guard `CONCURRENTLY` operations which must run outside a txn.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def pg_idle?
+        rc = conn.raw_connection
+        return true unless rc.respond_to?(:transaction_status)
+
+        # Only use CONCURRENTLY outside any tx/savepoint.
+        rc.transaction_status == PG::PQTRANS_IDLE
+      rescue StandardError
+        false
+      end
+
+      ##
+      # Check for any UNIQUE index on the materialised view, required by CONCURRENTLY.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def unique_index_exists?
+        conn.select_value(<<~SQL).to_i.positive?
+          SELECT COUNT(*)
+          FROM pg_index i
+          JOIN pg_class c ON c.oid = i.indrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = #{conn.quote(schema)}
+            AND c.relname = #{conn.quote(rel)}
+            AND i.indisunique = TRUE
+        SQL
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # rows counting
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Compute row count based on the configured strategy.
+      #
+      # @api private
+      # @return [Integer, nil]
+      #
+      def fetch_rows_count
+        case row_count_strategy
+        when :estimated then estimated_rows_count
+        when :exact     then exact_rows_count
+        else
+          UNKNOWN_ROW_COUNT
+        end
+      end
+
+      ##
+      # Fast, approximate row count via `pg_class.reltuples`.
+      #
+      # @api private
+      # @return [Integer]
+      #
+      def estimated_rows_count
+        conn.select_value(<<~SQL).to_i
+          SELECT COALESCE(c.reltuples::bigint, 0)
+          FROM pg_class c
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relkind IN ('m','r','p')
+            AND n.nspname = #{conn.quote(schema)}
+            AND c.relname = #{conn.quote(rel)}
+          LIMIT 1
+        SQL
+      end
+
+      ##
+      # Accurate row count using `COUNT(*)` on the materialised view.
+      #
+      # @api private
+      # @return [Integer]
+      #
+      def exact_rows_count
+        conn.select_value("SELECT COUNT(*) FROM #{qualified_rel}").to_i
+      end
+    end
+  end
+end

data/lib/smriti/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 Smriti
+  module Services
+    # Smriti::Services::CheckMatviewExists
+    # --------------------------------------
+    # Service object that checks whether the underlying PostgreSQL **materialised view**
+    # for a given {Smriti::MatViewDefinition} currently exists.
+    #
+    # ### Contract
+    # - Inherits from {Smriti::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 = Smriti::MatViewDefinition.find(1)
+    #   res  = Smriti::Services::CheckMatviewExists.new(defn).call
+    #   if res.success?
+    #     puts res.response[:exists] ? "Exists" : "Missing"
+    #   else
+    #     warn res.error
+    #   end
+    #
+    # @see Smriti::Services::BaseService
+    # @see Smriti::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/smriti/services/concurrent_refresh.rb

@@ -0,0 +1,94 @@
+# 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 Services
+    ##
+    # Refresh service that runs:
+    #
+    #   `REFRESH MATERIALIZED VIEW CONCURRENTLY <schema>.<rel>`
+    #
+    # It keeps the view readable during refresh, but **requires at least one
+    # 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
+    #
+    # Returns a {Smriti::ServiceResponse}
+    #
+    # @see Smriti::Services::RegularRefresh
+    # @see Smriti::Services::SwapRefresh
+    #
+    # @example Direct usage
+    #   svc = Smriti::Services::ConcurrentRefresh.new(definition, **options)
+    #   response = svc.call
+    #   response.success? # => true/false
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   When definition.refresh_strategy == "concurrent"
+    #   Smriti::Jobs::Adapter.enqueue(Smriti::Services::RefreshViewJob, definition.id, **options)
+    #
+    class ConcurrentRefresh < BaseService
+      def initialize(definition, row_count_strategy: :estimated)
+        super
+        @use_transaction = false
+      end
+
+      private
+
+      ##
+      # Execute the concurrent refresh.
+      #
+      # Validates name format, existence of the matview, and presence of a UNIQUE index.
+      # If validation fails, returns an error {Smriti::ServiceResponse}.
+      #
+      # @return [Smriti::ServiceResponse]
+      #   - `status: :updated` on success, with `response` containing:
+      #     - `view` - the qualified view name
+      #     - `row_count_before` - if requested and available
+      #     - `row_count_after` - if requested and available
+      #   - `status: :error` with `error` on failure, with `error` containing:
+      #     - serlialized exception class, message, and backtrace in a hash
+      def _run
+        sql = "REFRESH MATERIALIZED VIEW CONCURRENTLY #{qualified_rel}"
+        self.response = { view: "#{schema}.#{rel}", sql: [sql] }
+
+        response[:row_count_before] = fetch_rows_count
+        conn.execute(sql)
+        response[:row_count_after] = fetch_rows_count
+
+        ok(:updated)
+      end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      # Sets `concurrent: true` in the request hash.
+      #
+      # @api private
+      # @return [void]
+      #
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, concurrent: true }
+      end
+
+      ##
+      # Validation step (invoked by BaseService#call before execution).
+      #
+      # @api private
+      # @return [nil] on success
+      # @raise [StandardError] on failure
+      #
+      def prepare
+        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?
+
+        nil
+      end
+    end
+  end
+end