the-active-rpc 1.0.1

data/lib/active_rpc/rpc/concerns/request_processor.rb

@@ -0,0 +1,191 @@
+module ActiveRpc
+  module Rpc
+    module Concerns
+      # The RequestProcessor concern provides methods for processing gRPC requests
+      # with standardized error handling and parameter validation.
+      #
+      # @example
+      #   def get_user
+      #     process_request do
+      #       validate_required_params!(request.message, :id)
+      #       user = find_record(User, request.message.id)
+      #       user.to_rpc_response
+      #     end
+      #   end
+      module RequestProcessor
+        extend ActiveSupport::Concern
+
+        # Process a request with a block, handling common errors
+        def process_request
+          ActiveRecord::Base.transaction do
+            yield
+          end
+        rescue ActiveRecord::RecordNotFound => e
+          fail!(:not_found, :record_not_found, e.message)
+        rescue ActiveRecord::RecordInvalid => e
+          # For validation errors, we now return structured responses instead of failing
+          # This should be handled by the individual controller methods
+          raise e
+        rescue ArgumentError => e
+          fail!(:invalid_argument, :invalid_request, e.message)
+        rescue UncaughtThrowError => e
+          # Handle throw(:abort) from callbacks
+          if e.tag == :abort
+            fail!(:aborted, :operation_aborted, "Operation aborted")
+          else
+            # Re-raise if it's not an :abort throw
+            raise e
+          end
+        rescue StandardError => e
+          Rails.logger.error("Error processing request: #{e.message}\n#{e.backtrace.join("\n")}")
+          fail!(:internal, :unexpected_error, "An unexpected error occurred")
+        end
+
+        # Extract parameters from a request payload
+        def extract_params(payload, *param_names)
+          # Step 1: Determine which fields to extract and get _fields metadata
+          if payload.respond_to?(:_fields) && !payload._fields.empty?
+            # Use _fields metadata (only top-level fields)
+            fields_to_extract = payload._fields
+              .reject { |path| path.include?('.') || path.include?('[') }
+            # Pass the full _fields metadata for nested conversion
+            fields_metadata = payload._fields
+          elsif param_names.empty?
+            # Extract all available fields from protobuf descriptor
+            if payload.class.respond_to?(:descriptor)
+              fields_to_extract = payload.class.descriptor.map(&:name)
+            else
+              fields_to_extract = []
+            end
+            fields_metadata = nil
+          else
+            # Extract only requested fields
+            fields_to_extract = param_names.map(&:to_s)
+            fields_metadata = nil
+          end
+
+          # Step 2: Extract the fields
+          result = {}
+          fields_to_extract.each do |field_name|
+            field_sym = field_name.to_sym
+            if payload.respond_to?(field_sym)
+              field_value = payload.send(field_sym)
+              # Pass the field path and metadata for nested conversion
+              field_path = field_name
+              result[field_sym] = convert_protobuf_to_ruby(field_value, field_path, fields_metadata)
+            end
+          end
+
+          result
+        end
+
+        private
+
+        # Convert protobuf objects to Ruby hashes/arrays recursively
+        # WITHOUT using to_h to preserve empty arrays and explicit default values
+        # Respects _fields metadata to only extract fields that were originally sent
+        def convert_protobuf_to_ruby(value, current_path = '', fields_metadata = nil)
+          case value
+          when Google::Protobuf::MessageExts
+            # Convert protobuf message to hash by extracting only tracked fields
+            result = {}
+
+            if fields_metadata
+              # Only extract fields that are in the _fields metadata
+              value.class.descriptor.each do |field|
+                field_name = field.name
+                field_path = current_path.empty? ? field_name : "#{current_path}.#{field_name}"
+
+                # Check if this field path exists in _fields metadata
+                # Match exact path or any child path (but not parent paths)
+                if fields_metadata.any? { |path| path == field_path || path.start_with?("#{field_path}.") || path.start_with?("#{field_path}[") }
+                  field_value = value.send(field_name)
+                  result[field_name] = convert_protobuf_to_ruby(field_value, field_path, fields_metadata)
+                end
+              end
+            else
+              # Fallback: extract all fields when no metadata available
+              value.class.descriptor.each do |field|
+                field_name = field.name
+                field_value = value.send(field_name)
+                field_path = current_path.empty? ? field_name : "#{current_path}.#{field_name}"
+                result[field_name] = convert_protobuf_to_ruby(field_value, field_path, fields_metadata)
+              end
+            end
+
+            result
+          when Google::Protobuf::Map
+            # Convert map fields while respecting _fields metadata for individual keys
+            allowed_entry_paths = if fields_metadata
+                                    fields_metadata.select { |path| path.start_with?("#{current_path}[") }
+            end
+
+            value.each_with_object({}) do |(map_key, map_value), acc|
+              entry_path = "#{current_path}[#{map_key}]"
+
+              if allowed_entry_paths.present?
+                next unless allowed_entry_paths.any? { |path| path == entry_path || path.start_with?("#{entry_path}.") }
+              end
+
+              acc[map_key] = convert_protobuf_to_ruby(map_value, entry_path, fields_metadata)
+            end
+          when Google::Protobuf::RepeatedField
+            # Convert repeated field to array and recursively convert elements
+            value.map.with_index do |item, index|
+              item_path = "#{current_path}[#{index}]"
+              convert_protobuf_to_ruby(item, item_path, fields_metadata)
+            end
+          when Array
+            # Convert array elements recursively
+            value.map.with_index do |item, index|
+              item_path = "#{current_path}[#{index}]"
+              convert_protobuf_to_ruby(item, item_path, fields_metadata)
+            end
+          when Hash
+            # Convert hash values recursively
+            value.transform_values { |v| convert_protobuf_to_ruby(v, current_path, fields_metadata) }
+          else
+            # Return primitive values as-is
+            value
+          end
+        end
+
+        # Validate required parameters
+        def validate_required_params!(payload, *param_names)
+          missing = param_names.select { |name| !payload.respond_to?(name) || payload.send(name).nil? }
+          if missing.any?
+            raise ArgumentError, "Missing required parameters: #{missing.join(', ')}"
+          end
+        end
+
+        # Find a record or fail with not found
+        def find_record(model_class, id)
+          record = model_class.find_by(id: id)
+          unless record
+            fail!(:not_found, :record_not_found, "#{model_class.name} with ID #{id} not found")
+          end
+          record
+        end
+
+        # Create structured response metadata for validation errors
+        def create_validation_error_metadata(record)
+          # Share the Rails errors object directly - no conversion needed!
+          errors_map = {}
+          record.errors.to_hash.each do |field, messages|
+            errors_map[field.to_s] = Core::ErrorMessages.new(messages: messages)
+          end
+
+          Core::ResponseMetadata.new(
+            success: false,
+            errors: errors_map
+          )
+        end
+
+        # Create successful response metadata
+        def create_success_metadata
+          Core::ResponseMetadata.new(success: true)
+        end
+      end
+    end
+  end
+end

data/lib/active_rpc/rpc/concerns/resource_controller.rb

@@ -0,0 +1,281 @@
+module ActiveRpc
+  module Rpc
+    module Concerns
+      # The ResourceController concern provides high-level methods for common CRUD operations
+      # in gRPC controllers.
+      #
+      # @example
+      #   def get_user
+      #     get_resource(User, request.message, transformer: :to_rpc_response)
+      #   end
+      #
+      #   def list_users
+      #     list_resources(User, request.message,
+      #       response_class: ::Core::UserListResponse,
+      #       transformer: :to_rpc_response
+      #     )
+      #   end
+      module ResourceController
+        extend ActiveSupport::Concern
+
+        include ActiveRpc::Rpc::Concerns::RequestProcessor
+        include ActiveRpc::Rpc::Concerns::QueryBuilder
+
+        # Get a single resource
+        def get_resource(model_class, request_payload, options = {})
+          process_request do
+            # Validate required parameters
+            validate_required_params!(request_payload, :id)
+
+            # Find the resource with includes if provided
+            includes = options[:includes] || []
+            resource = model_class.includes(includes).find(request_payload.id)
+
+            # Transform the resource
+            if options[:transformer].is_a?(Proc)
+              options[:transformer].call(resource)
+            elsif options[:transformer] == :to_rpc_response
+              resource.to_rpc_response
+            else
+              resource
+            end
+          end
+        end
+
+        # List resources
+        def list_resources(model_class, request_payload, options = {})
+          process_request do
+            execute_query(model_class, request_payload, options)
+          end
+        end
+
+        # Create a resource
+        def create_resource(model_class, request_payload, options = {})
+          process_request do
+            # Validate required parameters
+            if options[:required_params].is_a?(Array)
+              validate_required_params!(request_payload, *options[:required_params])
+            end
+
+            # Extract parameters
+            params = if options[:param_extractor].is_a?(Proc)
+                       options[:param_extractor].call(request_payload)
+            else
+                       extract_params(request_payload, *options[:param_names])
+            end
+
+            # Coerce JSONB columns from JSON string to Hash (schema-aware, generic)
+            params = coerce_jsonb_params(model_class, params)
+
+            # Create the resource
+            resource = model_class.new(params.to_h.with_indifferent_access)
+
+            # Apply before save hook if provided
+            if options[:before_save].is_a?(Proc)
+              hook_result = options[:before_save].call(resource, request_payload)
+              # Check if the hook returned an error response
+              return hook_result if hook_result.respond_to?(:success) && hook_result.success == false
+            end
+
+            # Save the resource
+            if resource.save
+              # Apply after save hook if provided
+              if options[:after_save].is_a?(Proc)
+                hook_result = options[:after_save].call(resource, request_payload)
+                # Check if the hook returned an error response
+                return hook_result if hook_result.respond_to?(:success) && hook_result.success == false
+              end
+
+              # Transform the resource with success metadata
+              result = if options[:transformer].is_a?(Proc)
+                         options[:transformer].call(resource)
+              elsif options[:transformer] == :to_rpc_response
+                         resource.reload.to_rpc_response
+              else
+                         resource.reload
+              end
+
+              # Ensure string fields in protobuf receive strings (stringify Hash/Array)
+              coerce_string_fields_in_response!(result)
+
+              # Add success metadata to the response
+              result._metadata = create_success_metadata if result.respond_to?(:_metadata=)
+
+              result
+            else
+              # Create response with validation error metadata
+              result = if options[:transformer].is_a?(Proc)
+                         options[:transformer].call(resource)
+              elsif options[:transformer] == :to_rpc_response
+                         resource.to_rpc_response
+              else
+                         # Create a basic response object for the resource type
+                         resource_class_name = resource.class.name
+                         response_class = "Core::#{resource_class_name}Response".constantize
+                         response_class.new
+              end
+
+              # Add validation error metadata to the response
+              result._metadata = create_validation_error_metadata(resource) if result.respond_to?(:_metadata=)
+
+              # Ensure string fields in protobuf receive strings (stringify Hash/Array)
+              coerce_string_fields_in_response!(result)
+
+              result
+            end
+          end
+        end
+
+        # Update a resource
+        def update_resource(model_class, request_payload, options = {})
+          process_request do
+            # Validate required parameters
+            validate_required_params!(request_payload, :id)
+
+            # Find the resource
+            resource = find_record(model_class, request_payload.id)
+
+            # Extract parameters
+            params = if options[:param_extractor].is_a?(Proc)
+                       options[:param_extractor].call(request_payload)
+            else
+                       extract_params(request_payload, *options[:param_names])
+            end
+
+            # Coerce JSONB columns from JSON string to Hash (schema-aware, generic)
+            params = coerce_jsonb_params(model_class, params)
+
+            # Apply before save hook if provided
+            if options[:before_save].is_a?(Proc)
+              hook_result = options[:before_save].call(resource, request_payload)
+              # Check if the hook returned an error response
+              return hook_result if hook_result.respond_to?(:success) && hook_result.success == false
+            end
+
+            # Update the resource
+            resource.assign_attributes(params.with_indifferent_access)
+            if resource.save
+              # Apply after save hook if provided
+              if options[:after_save].is_a?(Proc)
+                hook_result = options[:after_save].call(resource, request_payload)
+                # Check if the hook returned an error response
+                return hook_result if hook_result.respond_to?(:success) && hook_result.success == false
+              end
+
+              # Transform the resource with success metadata
+              result = if options[:transformer].is_a?(Proc)
+                         options[:transformer].call(resource)
+              elsif options[:transformer] == :to_rpc_response
+                         resource.reload.to_rpc_response
+              else
+                         resource.reload
+              end
+
+              # Ensure string fields in protobuf receive strings (stringify Hash/Array)
+              coerce_string_fields_in_response!(result)
+
+              # Add success metadata to the response
+              result._metadata = create_success_metadata if result.respond_to?(:_metadata=)
+
+              result
+            else
+              # Create response with validation error metadata
+              result = if options[:transformer].is_a?(Proc)
+                         options[:transformer].call(resource)
+              elsif options[:transformer] == :to_rpc_response
+                         resource.to_rpc_response
+              else
+                         # Create a basic response object for the resource type
+                         resource_class_name = resource.class.name
+                         response_class = "Core::#{resource_class_name}Response".constantize
+                         response_class.new
+              end
+
+              # Add validation error metadata to the response
+              result._metadata = create_validation_error_metadata(resource) if result.respond_to?(:_metadata=)
+
+              # Ensure string fields in protobuf receive strings (stringify Hash/Array)
+              coerce_string_fields_in_response!(result)
+
+              result
+            end
+          end
+        end
+
+        # Delete a resource
+        def delete_resource(model_class, request_payload, options = {})
+          process_request do
+            # Validate required parameters
+            validate_required_params!(request_payload, :id)
+
+            # Find the resource
+            resource = find_record(model_class, request_payload.id)
+
+            # Apply before destroy hook if provided
+            options[:before_destroy].call(resource, request_payload) if options[:before_destroy].is_a?(Proc)
+
+            # Destroy the resource
+            resource.destroy!
+
+            # Apply after destroy hook if provided
+            options[:after_destroy].call(resource, request_payload) if options[:after_destroy].is_a?(Proc)
+
+            # Return success response
+            options[:success_response] || { success: true }
+          end
+        end
+
+        private
+
+        # Convert jsonb column params from JSON string to Hash, generically
+        def coerce_jsonb_params(model_class, params)
+          return params unless params.is_a?(Hash)
+
+          jsonb_columns = model_class.columns.select { |c| c.type == :jsonb }.map(&:name)
+          return params if jsonb_columns.empty?
+
+          params.transform_keys(&:to_sym).tap do |h|
+            jsonb_columns.each do |col|
+              key = col.to_sym
+              next unless h.key?(key) && h[key].is_a?(String)
+
+              begin
+                parsed = JSON.parse(h[key])
+                h[key] = parsed if parsed.is_a?(Hash) || parsed.is_a?(Array)
+              rescue JSON::ParserError
+                # leave as-is
+              end
+            end
+          end
+        end
+
+        # Ensure any protobuf string fields receive strings, not Hash/Array (stringify if needed)
+        def coerce_string_fields_in_response!(message)
+          return message unless message.respond_to?(:class) && message.class.respond_to?(:descriptor)
+
+          message.class.descriptor.each do |field|
+            name = field.name
+            value = message.send(name) if message.respond_to?(name)
+
+            case field.type
+            when :string
+              message.send("#{name}=", value.to_json) if value.is_a?(Hash) || value.is_a?(Array)
+            when :message
+              if value.respond_to?(:class) && value.class.respond_to?(:descriptor)
+                coerce_string_fields_in_response!(value)
+              end
+            when :repeated
+              if value.is_a?(Array)
+                value.each do |v|
+                  coerce_string_fields_in_response!(v) if v.respond_to?(:class) && v.class.respond_to?(:descriptor)
+                end
+              end
+            end
+          end
+
+          message
+        end
+      end
+    end
+  end
+end

data/lib/active_rpc/rpc/concerns/scopable.rb

@@ -0,0 +1,92 @@
+module ActiveRpc
+  module Rpc
+    module Concerns
+      # The Scopable concern provides methods for applying named scopes
+      # to ActiveRecord queries in gRPC controllers.
+      #
+      # @example
+      #   def list_users
+      #     process_request do
+      #       base_query = User.all
+      #       query = apply_scopes(base_query, request.message)
+      #       # ...
+      #     end
+      #   end
+      module Scopable
+        extend ActiveSupport::Concern
+
+        # Apply scopes to a query
+        def apply_scopes(query, params)
+          return query unless params.respond_to?(:scope) && params.scope.present?
+
+          # Handle both new JSON format and old individual parameters for backward compatibility
+          scope_hash = params.scope.to_h
+          scope_params = if scope_hash.key?('args')
+                           # New format: JSON-serialized scope arguments
+                           begin
+                             JSON.parse(scope_hash['args'])
+                           rescue JSON::ParserError => e
+                             Rails.logger.error("[Scopable] Failed to parse scope args: #{e.message}")
+                             {}
+                           end
+          else
+                           # Old format: individual string parameters (backward compatibility)
+                           scope_hash
+          end
+
+          # Get available scopes
+          available_scopes = get_available_scopes(query.model)
+
+          # Apply each scope
+          scope_params.each do |scope_name, scope_value|
+            # Skip if the scope is not available and we have defined scopes
+            scope_available = available_scopes.empty? ||
+                             available_scopes.key?(scope_name.to_sym) ||
+                             available_scopes.key?(scope_name.to_s)
+
+            unless scope_available
+              Rails.logger.debug("[Scopable] Skipping scope #{scope_name} - not in available_scopes")
+              next
+            end
+
+            unless query.respond_to?(scope_name)
+              Rails.logger.debug("[Scopable] Skipping scope #{scope_name} - query doesn't respond to it")
+              next
+            end
+
+            begin
+              # Handle regular scopes
+              method = query.method(scope_name)
+              if method.arity.abs <= 1
+                Rails.logger.debug("[Scopable] Applying scope: #{scope_name}(#{scope_value.class})")
+                query = scope_value.present? ? query.public_send(scope_name, scope_value) : query.public_send(scope_name)
+              else
+                Rails.logger.debug("[Scopable] Skipping scope #{scope_name} - arity too high: #{method.arity}")
+              end
+            rescue => e
+              Rails.logger.error("[Scopable] Error applying scope '#{scope_name}': #{e.message}")
+              # Continue with other scopes even if one fails
+            end
+          end
+
+          query
+        end
+
+        private
+
+        # Get available scopes for a model
+        def get_available_scopes(model_class)
+          if model_class.respond_to?(:active_rpc_config) && model_class.active_rpc_config
+            resource = model_class.active_rpc_config[:resource].to_s.underscore
+            scopes_method = "#{resource}_scopes"
+
+            return model_class.send(scopes_method) if model_class.respond_to?(scopes_method)
+          end
+
+          # Default empty scopes if none are defined
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/active_rpc/rpc/concerns/serializable.rb

@@ -0,0 +1,30 @@
+module ActiveRpc
+  module Rpc
+    module Concerns
+      # The Serializable concern provides methods for transforming ActiveRecord models
+      # into gRPC response objects.
+      #
+      # @example
+      #   def get_user
+      #     process_request do
+      #       user = find_record(User, request.message.id)
+      #       serialize_record(user, serializer: UserSerializer)
+      #     end
+      #   end
+      module Serializable
+        extend ActiveSupport::Concern
+
+        # Transform a record using a serializer
+        def serialize_record(record, options = {})
+          serializer_class = options[:serializer] || "#{record.class.name}Serializer".constantize
+          serializer_class.new(record).to_h
+        end
+
+        # Transform a collection using a serializer
+        def serialize_collection(collection, options = {})
+          collection.map { |record| serialize_record(record, options) }
+        end
+      end
+    end
+  end
+end

data/lib/active_rpc/rpc/concerns/sortable.rb

@@ -0,0 +1,71 @@
+module ActiveRpc
+  module Rpc
+    module Concerns
+      # The Sortable concern provides methods for applying sorting
+      # to ActiveRecord queries in gRPC controllers.
+      #
+      # @example
+      #   def list_users
+      #     process_request do
+      #       base_query = User.all
+      #       query = apply_sorting(base_query, request.message)
+      #       # ...
+      #     end
+      #   end
+      module Sortable
+        extend ActiveSupport::Concern
+
+        # Apply sorting to a query
+        def apply_sorting(query, params)
+          return query unless params.respond_to?(:sort) && params.sort.present?
+
+          begin
+            # Parse the sort parameter
+            field, direction = params.sort.split(' ')
+            direction ||= 'asc'
+
+            # Sanitize the direction
+            direction = %w[asc desc].include?(direction.downcase) ? direction.downcase : 'asc'
+
+            # Get query configuration
+            query_config = get_query_config(query.model)
+            sortable_attrs = query_config[:sortable] || []
+
+            # Check if the field is sortable or if we have no defined sortable attributes
+            if sortable_attrs.empty? || sortable_attrs.include?(field.to_sym) || sortable_attrs.include?(field.to_s)
+              # Apply sorting
+              query.order("#{field} #{direction}")
+            else
+              Rails.logger.error("Invalid sort field: #{field}")
+              query
+            end
+          rescue => e
+            Rails.logger.error("Error applying sorting: #{e.message}")
+            # Return original query if sorting fails
+            query
+          end
+        end
+
+        # Get query configuration for a model
+        def get_query_config(model_class)
+          if model_class.respond_to?(:active_rpc_config) && model_class.active_rpc_config
+            resource = model_class.active_rpc_config[:resource].to_s.underscore
+            query_config_method = "#{resource}_query_config"
+
+            if model_class.respond_to?(query_config_method)
+              return model_class.send(query_config_method)
+            end
+          end
+
+          # Default configuration if none is defined
+          {
+            searchable: model_class.column_names,
+            filterable: model_class.column_names,
+            sortable: model_class.column_names,
+            includable: model_class.reflect_on_all_associations.map(&:name)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/active_rpc/rpc/configuration.rb

@@ -0,0 +1,7 @@
+module ActiveRpc
+  module Rpc
+    class Configuration
+      # Server-side gRPC configuration placeholder
+    end
+  end
+end