rest_framework 0.6.13 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcc66a1bc2a8c965fcaf04106db51a08c98623a642803634fc96d5eccce9283f
-  data.tar.gz: 06c49e1eb116813833c01810379a7f377023bb37a0bb57429c254224f8b260d9
+  metadata.gz: bcc4c1783a1d0dc42b862d9daf32c6d9ef2ae029483f61ac7c2e971c6c0558db
+  data.tar.gz: '091682390838dd5f5c5db8ea2e216f336863f06b77488c88dbc68b5c59b68e22'
 SHA512:
-  metadata.gz: 6398f494b9c920a0e9765733c6be871d0cdee94fc12a2863fa7bf0bfc1bba41f601713a53b61ba3d57fcd1b3b45001eadbe6ac26b77b4bd69595ad1ae84e2f06
-  data.tar.gz: 2610d28a5d5b98fd6be70105d04a292d2acb4c3efc9d5ece74ba1a00b90e4968a55ccefc824773c2609015298221c5315ea929440e29923bba9500ce495c8c78
+  metadata.gz: 441f74ad60ade750e7483364b9e5a73fb58cb9452dc8a5e11988e154758fba345391b44bf87143a6c3e1f9ff1ec6fb773c51af30990776fedeac7c5d96461676
+  data.tar.gz: 0acb74c34c862ba9fd74e9b76ea4c1b9b413aac4989250aab3ee0b6a1cf0a1643f8095ad552d4f8e2c53cc2b2bbdf60c4efbd87d8a48605cab6d051c0082da2d

data/VERSION

@@ -1 +1 @@
-0.6.13
+0.7.0

data/app/views/layouts/rest_framework.html.erb

@@ -57,6 +57,9 @@
               <% end %>
               <button type="button" class="btn btn-primary" onclick="rrfRefresh(this)">GET</button>
             </div>
+            <% if @description.present? %>
+              <br><br><p style="display: inline-block; margin-bottom: 0"><%= @description %></p>
+            <% end %>
           </div>
         </div>
         <hr/>

data/lib/rest_framework/controller_mixins/base.rb

@@ -6,12 +6,59 @@ require_relative "../utils"
 # the ability to route arbitrary actions with `extra_actions`. This is also where `api_response`
 # is defined.
 module RESTFramework::BaseControllerMixin
+  RRF_BASE_CONTROLLER_CONFIG = {
+    filter_pk_from_request_body: true,
+    exclude_body_fields: [:created_at, :created_by, :updated_at, :updated_by],
+    accept_generic_params_as_body_params: false,
+    show_backtrace: false,
+    extra_actions: nil,
+    extra_member_actions: nil,
+    filter_backends: nil,
+    singleton_controller: nil,
+
+    # Metadata and display options.
+    title: nil,
+    description: nil,
+    inflect_acronyms: ["ID", "REST", "API"],
+
+    # Options related to serialization.
+    rescue_unknown_format_with: :json,
+    serializer_class: nil,
+    serialize_to_json: true,
+    serialize_to_xml: true,
+
+    # Options related to pagination.
+    paginator_class: nil,
+    page_size: 20,
+    page_query_param: "page",
+    page_size_query_param: "page_size",
+    max_page_size: nil,
+
+    # Option to disable serializer adapters by default, mainly introduced because Active Model
+    # Serializers will do things like serialize `[]` into `{"":[]}`.
+    disable_adapters_by_default: true,
+  }
+
   # Default action for API root.
   def root
-    api_response({message: "This is the root of your awesome API!"})
+    api_response({message: "This is the API root."})
   end
 
   module ClassMethods
+    # Get the title of this controller. By default, this is the name of the controller class,
+    # titleized and with any custom inflection acronyms applied.
+    def get_title
+      return self.title || RESTFramework::Utils.inflect(
+        self.name.demodulize.chomp("Controller").titleize(keep_id_suffix: true),
+        self.inflect_acronyms,
+      )
+    end
+
+    # Get a label from a field/column name, titleized and inflected.
+    def get_label(s)
+      return RESTFramework::Utils.inflect(s.titleize(keep_id_suffix: true), self.inflect_acronyms)
+    end
+
     # Collect actions (including extra actions) metadata for this controller.
     def get_actions_metadata
       actions = {}
@@ -20,12 +67,14 @@ module RESTFramework::BaseControllerMixin
       RESTFramework::BUILTIN_ACTIONS.merge(
         RESTFramework::RRF_BUILTIN_ACTIONS,
       ).each do |action, methods|
-        actions[action] = {path: "", methods: methods} if self.method_defined?(action)
+        if self.method_defined?(action)
+          actions[action] = {path: "", methods: methods, type: :builtin}
+        end
       end
 
       # Add extra actions.
       if extra_actions = self.try(:extra_actions)
-        actions.merge!(RESTFramework::Utils.parse_extra_actions(extra_actions))
+        actions.merge!(RESTFramework::Utils.parse_extra_actions(extra_actions, controller: self))
       end
 
       return actions
@@ -37,12 +86,14 @@ module RESTFramework::BaseControllerMixin
 
       # Start with builtin actions.
       RESTFramework::BUILTIN_MEMBER_ACTIONS.each do |action, methods|
-        actions[action] = {path: "", methods: methods} if self.method_defined?(action)
+        if self.method_defined?(action)
+          actions[action] = {path: "", methods: methods, type: :builtin}
+        end
       end
 
       # Add extra actions.
       if extra_actions = self.try(:extra_member_actions)
-        actions.merge!(RESTFramework::Utils.parse_extra_actions(extra_actions))
+        actions.merge!(RESTFramework::Utils.parse_extra_actions(extra_actions, controller: self))
       end
 
       return actions
@@ -51,8 +102,8 @@ module RESTFramework::BaseControllerMixin
     # Get a hash of metadata to be rendered in the `OPTIONS` response. Cache the result.
     def get_options_metadata
       return @_base_options_metadata ||= {
-        name: self.metadata&.name || self.controller_name.titleize,
-        description: self.metadata&.description,
+        title: self.get_title,
+        description: self.description,
         renders: [
           "text/html",
           self.serialize_to_json ? "application/json" : nil,
@@ -62,6 +113,16 @@ module RESTFramework::BaseControllerMixin
         member_actions: self.get_member_actions_metadata,
       }.compact
     end
+
+    # Define any behavior to execute at the end of controller definition.
+    def rrf_finalize
+      if RESTFramework.config.freeze_config
+        self::RRF_BASE_CONTROLLER_CONFIG.keys.each { |k|
+          v = self.send(k)
+          v.freeze if v.is_a?(Hash) || v.is_a?(Array)
+        }
+      end
+    end
   end
 
   def self.included(base)
@@ -70,34 +131,7 @@ module RESTFramework::BaseControllerMixin
     base.extend(ClassMethods)
 
     # Add class attributes (with defaults) unless they already exist.
-    {
-      filter_pk_from_request_body: true,
-      exclude_body_fields: [:created_at, :created_by, :updated_at, :updated_by],
-      accept_generic_params_as_body_params: false,
-      show_backtrace: false,
-      extra_actions: nil,
-      extra_member_actions: nil,
-      filter_backends: nil,
-      singleton_controller: nil,
-      metadata: nil,
-
-      # Options related to serialization.
-      rescue_unknown_format_with: :json,
-      serializer_class: nil,
-      serialize_to_json: true,
-      serialize_to_xml: true,
-
-      # Options related to pagination.
-      paginator_class: nil,
-      page_size: 20,
-      page_query_param: "page",
-      page_size_query_param: "page_size",
-      max_page_size: nil,
-
-      # Option to disable serializer adapters by default, mainly introduced because Active Model
-      # Serializers will do things like serialize `[]` into `{"":[]}`.
-      disable_adapters_by_default: true,
-    }.each do |a, default|
+    RRF_BASE_CONTROLLER_CONFIG.each do |a, default|
       next if base.respond_to?(a)
 
       base.class_attribute(a)
@@ -126,6 +160,19 @@ module RESTFramework::BaseControllerMixin
     base.rescue_from(ActiveRecord::RecordNotSaved, with: :record_not_saved)
     base.rescue_from(ActiveRecord::RecordNotDestroyed, with: :record_not_destroyed)
     base.rescue_from(ActiveModel::UnknownAttributeError, with: :unknown_attribute_error)
+
+    # Use `TracePoint` hook to automatically call `rrf_finalize`.
+    unless RESTFramework.config.disable_auto_finalize
+      TracePoint.trace(:end) do |t|
+        next if base != t.self
+
+        base.rrf_finalize
+
+        # It's important to disable the trace once we've found the end of the base class definition,
+        # for performance.
+        t.disable
+      end
+    end
   end
 
   # Get the configured serializer class.
@@ -269,7 +316,8 @@ module RESTFramework::BaseControllerMixin
             @xml_payload = payload.to_xml if self.class.serialize_to_xml
           end
           @template_logo_text ||= "Rails REST Framework"
-          @title ||= self.controller_name.titleize
+          @title ||= self.class.get_title
+          @description ||= self.class.description
           @route_props, @route_groups = RESTFramework::Utils.get_routes(
             Rails.application.routes, request
           )

data/lib/rest_framework/controller_mixins/models.rb

@@ -5,6 +5,44 @@ require_relative "../filters"
 module RESTFramework::BaseModelControllerMixin
   include RESTFramework::BaseControllerMixin
 
+  RRF_BASE_MODEL_CONTROLLER_CONFIG = {
+    # Core attributes related to models.
+    model: nil,
+    recordset: nil,
+
+    # Attributes for configuring record fields.
+    fields: nil,
+    action_fields: nil,
+
+    # Attributes for finding records.
+    find_by_fields: nil,
+    find_by_query_param: "find_by",
+
+    # Attributes for create/update parameters.
+    allowed_parameters: nil,
+    allowed_action_parameters: nil,
+
+    # Attributes for the default native serializer.
+    native_serializer_config: nil,
+    native_serializer_singular_config: nil,
+    native_serializer_plural_config: nil,
+    native_serializer_only_query_param: "only",
+    native_serializer_except_query_param: "except",
+
+    # Attributes for default model filtering, ordering, and searching.
+    filterset_fields: nil,
+    ordering_fields: nil,
+    ordering_query_param: "ordering",
+    ordering_no_reorder: false,
+    search_fields: nil,
+    search_query_param: "search",
+    search_ilike: false,
+
+    # Other misc attributes.
+    create_from_recordset: true,  # Option for `recordset.create` vs `Model.create` behavior.
+    filter_recordset_before_find: true,  # Control if filtering is done before find.
+  }
+
   module ClassMethods
     IGNORE_VALIDATORS_WITH_KEYS = [:if, :unless]
 
@@ -19,8 +57,8 @@ module RESTFramework::BaseModelControllerMixin
       rescue NameError
       end
 
-      # Delegate to the recordset's model, if it's defined.
-      unless from_get_recordset  # Prevent infinite recursion.
+      # Delegate to the recordset's model, if it's defined. This option prevents infinite recursion.
+      unless from_get_recordset
         # Instantiate a new controller to get the recordset.
         controller = self.new
         controller.request = ActionController::TestRequest.new
@@ -34,24 +72,34 @@ module RESTFramework::BaseModelControllerMixin
       return nil
     end
 
+    # Override `get_label` to include ActiveRecord i18n-translated column names.
+    def get_label(s)
+      return self.get_model.human_attribute_name(s, default: super)
+    end
+
     # Get metadata about the resource's fields.
     def get_fields_metadata(fields: nil)
       # Get metadata sources.
       model = self.get_model
-      fields ||= self.fields || model&.column_names || []
+      fields ||= self.fields || model.column_names || []
       fields = fields.map(&:to_s)
-      columns = model&.columns_hash
-      column_defaults = model&.column_defaults
-      attributes = model&._default_attributes
+      columns = model.columns_hash
+      column_defaults = model.column_defaults
+      attributes = model._default_attributes
 
       return fields.map { |f|
         # Initialize metadata to make the order consistent.
         metadata = {
-          type: nil, kind: nil, label: nil, primary_key: nil, required: nil, read_only: nil
+          type: nil,
+          kind: nil,
+          label: self.get_label(f),
+          primary_key: nil,
+          required: nil,
+          read_only: nil,
         }
 
         # Determine `primary_key` based on model.
-        if model&.primary_key == f
+        if model.primary_key == f
           metadata[:primary_key] = true
         end
 
@@ -59,7 +107,6 @@ module RESTFramework::BaseModelControllerMixin
         if column = columns[f]
           metadata[:type] = column.type
           metadata[:required] = true unless column.null
-          metadata[:label] = column.human_name.instance_eval { |n| n == "Id" ? "ID" : n }
           metadata[:kind] = "column"
         end
 
@@ -121,73 +168,15 @@ module RESTFramework::BaseModelControllerMixin
         },
       )
     end
-  end
-
-  def self.included(base)
-    return unless base.is_a?(Class)
-
-    RESTFramework::BaseControllerMixin.included(base)
-    base.extend(ClassMethods)
-
-    # Add class attributes (with defaults) unless they already exist.
-    {
-      # Core attributes related to models.
-      model: nil,
-      recordset: nil,
-
-      # Attributes for configuring record fields.
-      fields: nil,
-      action_fields: nil,
-      metadata_fields: nil,
-
-      # Attributes for finding records.
-      find_by_fields: nil,
-      find_by_query_param: "find_by",
-
-      # Attributes for create/update parameters.
-      allowed_parameters: nil,
-      allowed_action_parameters: nil,
-
-      # Attributes for the default native serializer.
-      native_serializer_config: nil,
-      native_serializer_singular_config: nil,
-      native_serializer_plural_config: nil,
-      native_serializer_only_query_param: "only",
-      native_serializer_except_query_param: "except",
-
-      # Attributes for default model filtering, ordering, and searching.
-      filterset_fields: nil,
-      ordering_fields: nil,
-      ordering_query_param: "ordering",
-      ordering_no_reorder: false,
-      search_fields: nil,
-      search_query_param: "search",
-      search_ilike: false,
-
-      # Other misc attributes.
-      create_from_recordset: true,  # Option for `recordset.create` vs `Model.create` behavior.
-      filter_recordset_before_find: true,  # Control if filtering is done before find.
-    }.each do |a, default|
-      next if base.respond_to?(a)
-
-      base.class_attribute(a)
-
-      # Set default manually so we can still support Rails 4. Maybe later we can use the default
-      # parameter on `class_attribute`.
-      base.send(:"#{a}=", default)
-    end
-
-    # Actions to run at the end of the class definition.
-    TracePoint.trace(:end) do |t|
-      next if base != t.self
 
+    def setup_delegation
       # Delegate extra actions.
-      base.extra_actions&.each do |action, config|
+      self.extra_actions&.each do |action, config|
         next unless config.is_a?(Hash) && config[:delegate]
+        next unless self.get_model.respond_to?(action)
 
-        base.define_method(action) do
+        self.define_method(action) do
           model = self.class.get_model
-          next unless model.respond_to?(action)
 
           if model.method(action).parameters.last&.first == :keyrest
             return api_response(model.send(action, **params))
@@ -198,12 +187,12 @@ module RESTFramework::BaseModelControllerMixin
       end
 
       # Delegate extra member actions.
-      base.extra_member_actions&.each do |action, config|
+      self.extra_member_actions&.each do |action, config|
         next unless config.is_a?(Hash) && config[:delegate]
+        next unless self.get_model.method_defined?(action)
 
-        base.define_method(action) do
+        self.define_method(action) do
           record = self.get_record
-          next unless record.respond_to?(action)
 
           if record.method(action).parameters.last&.first == :keyrest
             return api_response(record.send(action, **params))
@@ -212,10 +201,38 @@ module RESTFramework::BaseModelControllerMixin
           end
         end
       end
+    end
+
+    # Define any behavior to execute at the end of controller definition.
+    def rrf_finalize
+      super
+      self.setup_delegation
+      # self.setup_channel
 
-      # It's important to disable the trace once we've found the end of the base class definition,
-      # for performance.
-      t.disable
+      if RESTFramework.config.freeze_config
+        self::RRF_BASE_MODEL_CONTROLLER_CONFIG.keys.each { |k|
+          v = self.send(k)
+          v.freeze if v.is_a?(Hash) || v.is_a?(Array)
+        }
+      end
+    end
+  end
+
+  def self.included(base)
+    return unless base.is_a?(Class)
+
+    RESTFramework::BaseControllerMixin.included(base)
+    base.extend(ClassMethods)
+
+    # Add class attributes (with defaults) unless they already exist.
+    RRF_BASE_MODEL_CONTROLLER_CONFIG.each do |a, default|
+      next if base.respond_to?(a)
+
+      base.class_attribute(a)
+
+      # Set default manually so we can still support Rails 4. Maybe later we can use the default
+      # parameter on `class_attribute`.
+      base.send(:"#{a}=", default)
     end
   end
 

data/lib/rest_framework/routers.rb

@@ -39,8 +39,10 @@ module ActionDispatch::Routing
 
     # Interal interface for routing extra actions.
     def _route_extra_actions(actions, &block)
-      actions.each do |action, config|
-        config[:methods].each do |m|
+      parsed_actions = RESTFramework::Utils.parse_extra_actions(actions)
+
+      parsed_actions.each do |action, config|
+        [config[:methods]].flatten.each do |m|
           public_send(m, config[:path], action: action, **(config[:kwargs] || {}))
         end
         yield if block_given?
@@ -84,17 +86,13 @@ module ActionDispatch::Routing
       public_send(resource_method, name, except: skip, **kwargs) do
         if controller_class.respond_to?(:extra_member_actions)
           member do
-            self._route_extra_actions(
-              RESTFramework::Utils.parse_extra_actions(controller_class.extra_member_actions),
-            )
+            self._route_extra_actions(controller_class.extra_member_actions)
           end
         end
 
         collection do
           # Route extra controller-defined actions.
-          self._route_extra_actions(
-            RESTFramework::Utils.parse_extra_actions(controller_class.extra_actions),
-          )
+          self._route_extra_actions(controller_class.extra_actions)
 
           # Route extra RRF-defined actions.
           RESTFramework::RRF_BUILTIN_ACTIONS.each do |action, methods|
@@ -155,9 +153,7 @@ module ActionDispatch::Routing
 
         collection do
           # Route extra controller-defined actions.
-          self._route_extra_actions(
-            RESTFramework::Utils.parse_extra_actions(controller_class.extra_actions),
-          )
+          self._route_extra_actions(controller_class.extra_actions)
 
           # Route extra RRF-defined actions.
           RESTFramework::RRF_BUILTIN_ACTIONS.each do |action, methods|

data/lib/rest_framework/utils.rb

@@ -1,20 +1,30 @@
 module RESTFramework::Utils
   HTTP_METHOD_ORDERING = %w(GET POST PUT PATCH DELETE OPTIONS HEAD)
 
-  # Convert `extra_actions` hash to a consistent format: `{path:, methods:, kwargs:}`.
-  def self.parse_extra_actions(extra_actions)
+  # Convert `extra_actions` hash to a consistent format: `{path:, methods:, kwargs:}`, and
+  # additional metadata fields.
+  #
+  # If a controller is provided, labels will be added to any metadata fields.
+  def self.parse_extra_actions(extra_actions, controller: nil)
     return (extra_actions || {}).map { |k, v|
       path = k
 
       # Convert structure to path/methods/kwargs.
       if v.is_a?(Hash)  # Allow kwargs to be used to define path differently from the key.
+        # Symbolize keys (which also makes a copy so we don't mutate the original).
         v = v.symbolize_keys
+        methods = v.delete(:methods)
 
-        # Ensure methods is an array.
-        if v[:methods].is_a?(String) || v[:methods].is_a?(Symbol)
-          methods = [v.delete(:methods)]
-        else
-          methods = v.delete(:methods)
+        # First, remove any metadata keys.
+        delegate = v.delete(:delegate)
+        fields = v.delete(:fields)
+
+        # Add label to fields.
+        if controller && fields
+          fields = fields.map { |f| [f, {}] }.to_h if f.is_a?(Array)
+          fields&.each do |field, cfg|
+            cfg[:label] = controller.get_label(field)
+          end
         end
 
         # Override path if it's provided.
@@ -23,14 +33,24 @@ module RESTFramework::Utils
         end
 
         # Pass any further kwargs to the underlying Rails interface.
-        kwargs = v.presence&.except(:delegate)
-      elsif v.is_a?(Symbol) || v.is_a?(String)
-        methods = [v]
+        kwargs = v.presence
+      elsif v.is_a?(Array) && v.length == 1
+        methods = v[0]
       else
         methods = v
       end
 
-      [k, {path: path, methods: methods, kwargs: kwargs}.compact]
+      next [
+        k,
+        {
+          path: path,
+          methods: methods,
+          kwargs: kwargs,
+          delegate: delegate,
+          fields: fields,
+          type: :extra,
+        }.compact,
+      ]
     }.to_h
   end
 
@@ -108,4 +128,13 @@ module RESTFramework::Utils
       [request.params[:controller] == c ? 0 : 1, c.count("/"), c]
     }.to_h
   end
+
+  # Custom inflector for RESTful controllers.
+  def self.inflect(s, acronyms=nil)
+    acronyms&.each do |acronym|
+      s = s.gsub(/\b#{acronym}\b/i, acronym)
+    end
+
+    return s
+  end
 end

data/lib/rest_framework.rb

@@ -13,6 +13,31 @@ module RESTFramework
   RRF_BUILTIN_ACTIONS = {
     options: :options,
   }.freeze
+
+  # Global configuration should be kept minimal, as controller-level configurations allows multiple
+  # APIs to be defined to behave differently.
+  class Config
+    # Do not run `rrf_finalize` on controllers automatically using a `TracePoint` hook. This is a
+    # performance option and must be global because we have to determine this before any
+    # controller-specific configuration is set. If this is set to `true`, then you must manually
+    # call `rrf_finalize` after any configuration on each controller that needs to participate
+    # in:
+    #  - Model delegation, for the helper methods to be defined dynamically.
+    #  - Websockets, for `::Channel` class to be defined dynamically.
+    #  - Controller configuration finalizatino.
+    attr_accessor :disable_auto_finalize
+
+    # Freeze configuration attributes during finalization to prevent accidental mutation.
+    attr_accessor :freeze_config
+  end
+
+  def self.config
+    return @config ||= Config.new
+  end
+
+  def self.configure
+    yield(self.config)
+  end
 end
 
 require_relative "rest_framework/controller_mixins"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 0.6.13
+  version: 0.7.0
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-28 00:00:00.000000000 Z
+date: 2022-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails