belt 0.3.37 → 0.3.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0308512f255c22a7fbc31ff42a20947ee8c155c4c9ceaea3a4824a1e5a50c618'
-  data.tar.gz: e071128ae46f66256e4f52c5a0b3eb096e49faf2a0cde9e6c3d962c6ed54af93
+  metadata.gz: e529a712ad25eb12761d155d77b9a62f4342858c9b2272713edd0eef36ce7b6c
+  data.tar.gz: e1e38c997a9bcfc0f454315915412cc4911cd832771cb389e8733b64d082fac9
 SHA512:
-  metadata.gz: ec4a7be24ec7cb6961ed6c06cbc7690eb05a92406cf10cedf8760ef5cde8d464bd062652524ca74e41fdd6045f495b77e1c252823d1d18e14090ed986073f1ac
-  data.tar.gz: '08f0980d98b9c868c7e53c23236acc3c72be619f3b361dea0a1520a3d5e71549ad95758d7cc8cdbdd21186dfcbd7f6e7d7acff822b1b12d00225d2c35711f6e3'
+  metadata.gz: 4f2dbd95f0dfe51d250baeed09aa65d0704fbe783b67054b61f8eb6d46519c1fc0ebad6c641db6a5bd76fe75acd2f7a74a60abca16589b4e89da1dcb1d796bc2
+  data.tar.gz: 462ba513dc663920b9cdd8af7fe12632d541c99f14234e8b43c4dd6e706de16995852a72781f38a572e3aa92f78111e304a924e92e8e03eb791a80209163df2b

data/CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog
 
+## 0.3.39
+
+### Enhancement
+
+- **Auto-load `application_controller.rb` per gateway**: `Belt::LambdaHandler`
+  now requires each gateway's `application_controller.rb` before its sibling
+  controllers, mirroring the existing model convention (`application_record.rb`
+  loads first). Controllers can inherit from `ApplicationController` without an
+  explicit `require_relative 'application_controller'` — Belt handles ordering,
+  matching Rails. The `belt generate controller` template no longer emits the
+  redundant `require_relative`, keeping loading a single framework concern.
+
+## 0.3.38
+
+### Enhancement
+
+- **Rails-like `namespace` inside nested resources**: The `NestedResourceBuilder`
+  now supports `namespace` blocks that add both a path prefix AND a controller
+  module prefix, just like Rails. This provides 99% Rails compatibility for
+  nested route organization.
+
+  ```ruby
+  resources :projects do
+    namespace :admin do
+      resources :users   # → /projects/:project_id/admin/users → admin/users controller
+    end
+  end
+  ```
+
+  Namespaces can be nested and inherit auth/tables options:
+
+  ```ruby
+  resources :projects do
+    namespace :admin, auth: :iam, tables: [:audit_log] do
+      namespace :v2 do
+        resources :settings, only: [:index]  # → admin/v2/settings controller
+      end
+    end
+  end
+  ```
+
+- **`scope module:` option inside nested resources**: The existing `scope` method
+  now supports the `module:` option for Rails-like controller module prefixing
+  without adding a path prefix.
+
+  ```ruby
+  resources :projects do
+    scope module: 'v2' do
+      resources :users   # → /projects/:project_id/users → v2/users controller
+    end
+  end
+  ```
+
+## 0.3.37
+
+### Enhancement
+
+- **DRYer routing DSL with Rails-like `scope` inside nested resources**: The
+  `NestedResourceBuilder` now supports `scope` blocks for grouping routes with
+  shared options (path prefix, controller, tables, auth). This enables much
+  cleaner route definitions when multiple routes share the same controller or
+  tables.
+
+  **Before:**
+  ```ruby
+  resources :projects do
+    get 'billing', controller: :billing, action: :show, tables: [:memberships]
+    post 'billing/checkout', controller: :billing, action: :checkout, tables: [:memberships]
+    post 'billing/subscribe', controller: :billing, action: :subscribe, tables: [:memberships]
+  end
+  ```
+
+  **After:**
+  ```ruby
+  resources :projects do
+    scope path: 'billing', controller: :billing, tables: [:memberships] do
+      get '/', action: :show
+      post :checkout
+      post :subscribe
+    end
+  end
+  ```
+
+- **Singular `resource` inside nested resources**: You can now use `resource`
+  (singular) inside a `resources` block for nested singular resources like
+  `:billing`, `:token_usage`, or `:profile`.
+
+  ```ruby
+  resources :projects do
+    resource :billing, only: [:show], tables: [:memberships]
+    resource :token_usage, only: [:show]
+  end
+  ```
+
+- **Action inference from path**: When using symbol arguments or simple string
+  paths, the action is now inferred automatically. This works in `member`,
+  `collection`, and direct route definitions within resources.
+
+  ```ruby
+  resources :webhooks do
+    member do
+      post :test      # action: :test inferred
+    end
+  end
+
+  resources :surfaces do
+    collection do
+      get :teams      # action: :teams inferred
+    end
+  end
+
+  resources :projects do
+    post 'mark-complete'  # action: :mark_complete inferred (hyphens → underscores)
+  end
+  ```
+
+- **Controller inheritance in member/collection blocks**: Routes defined in
+  `member` and `collection` blocks now properly inherit the parent resource's
+  controller. This was inconsistent before and sometimes returned `nil`.
+
+  ```ruby
+  resources :webhooks do
+    member do
+      post :test     # controller: 'webhooks' inherited
+    end
+  end
+  ```
+
 ## 0.3.32
 
 ### Enhancement

data/README.md

@@ -209,6 +209,53 @@ end
 
 **Key point:** `namespace` and `scope` are purely organizational — they affect URL paths and controller module resolution but never change which Lambda handles the request. Use `function` when you need routes to go to a different Lambda.
 
+### Nested Resource DSL
+
+Inside a `resources` block, you can use Rails-like `member`, `collection`, `scope`, and singular `resource` for DRYer route definitions:
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api do
+    resources :projects do
+      # Singular nested resource
+      resource :billing, only: [:show], tables: [:memberships]
+      resource :token_usage, only: [:show]
+
+      # Member routes (include /:id/)
+      resources :webhooks do
+        member do
+          post :test                    # → POST /projects/:project_id/webhooks/:webhook_id/test
+        end
+      end
+
+      # Collection routes (no /:id/)
+      resources :surfaces do
+        collection do
+          get :teams                    # → GET /projects/:project_id/surfaces/teams
+        end
+        member do
+          put :assign                   # → PUT /projects/:project_id/surfaces/:surface_id/assign
+        end
+      end
+
+      # Scope groups routes with shared options
+      scope path: 'billing', controller: :billing, tables: [:memberships] do
+        get '/', action: :show          # → GET /projects/:project_id/billing
+        post :checkout                  # → POST /projects/:project_id/billing/checkout
+        post :subscribe
+        post :cancel
+      end
+    end
+  end
+end
+```
+
+**Key features:**
+- **Action inference**: `:checkout` means both path segment and action name
+- **Controller inheritance**: `member` and `collection` inherit parent resource's controller
+- **Scope in nested context**: Group routes with shared path prefix, controller, tables, or auth
+- **Singular `resource`**: For nested resources without an `:id` (billing, profile, etc.)
+
 ## BeltController Features
 
 ### Callbacks

data/lib/belt/docs/routing.md

@@ -57,6 +57,111 @@ resources :comments, except: [:destroy]
 | POST | /profile | create |
 | DELETE | /profile | destroy |
 
+## Nested Resource DSL
+
+Inside a `resources` block, you can use Rails-like `member`, `collection`, `scope`,
+`namespace`, and singular `resource` for DRYer route definitions:
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api do
+    resources :projects do
+      # Singular nested resource (no :id in path)
+      resource :billing, only: [:show], tables: [:memberships]
+      resource :token_usage, only: [:show]
+
+      # Member routes (include /:id/)
+      resources :webhooks do
+        member do
+          post :test            # → POST /projects/:project_id/webhooks/:webhook_id/test
+        end
+      end
+
+      # Collection routes (no /:id/)
+      resources :surfaces do
+        collection do
+          get :teams            # → GET /projects/:project_id/surfaces/teams
+        end
+        member do
+          put :assign           # → PUT /projects/:project_id/surfaces/:surface_id/assign
+        end
+      end
+
+      # Scope: groups routes with shared options
+      scope path: 'billing', controller: :billing, tables: [:memberships] do
+        get '/', action: :show  # → GET /projects/:project_id/billing
+        post :checkout          # → POST /projects/:project_id/billing/checkout
+        post :subscribe
+        post :cancel
+      end
+
+      # Namespace: adds path prefix AND controller module
+      namespace :admin do
+        resources :users        # → /projects/:project_id/admin/users → admin/users controller
+      end
+    end
+  end
+end
+```
+
+### Action Inference
+
+Symbol paths automatically become the action name:
+
+```ruby
+member do
+  post :test                    # path: /test, action: :test
+end
+post 'mark-complete'            # path: /mark-complete, action: :mark_complete
+```
+
+Hyphens in path segments convert to underscores in action names.
+
+### Controller Inheritance
+
+Routes inside `member` and `collection` blocks inherit the parent resource's controller:
+
+```ruby
+resources :surfaces do
+  member do
+    put :assign                 # controller: surfaces, action: assign
+  end
+end
+```
+
+Override with the `controller:` option:
+
+```ruby
+member do
+  get :billing, controller: :project_billing
+end
+```
+
+### Namespace vs Scope
+
+| Feature | `namespace` | `scope` |
+|---------|-------------|---------|
+| Path prefix | ✓ | Optional (`path:`) |
+| Controller module | ✓ | Optional (`module:`) |
+| Use case | Rails-like module nesting | Flexible grouping |
+
+```ruby
+# Namespace: path + controller module
+namespace :admin do
+  resources :users              # → /admin/users → admin/users controller
+end
+
+# Scope with path only (no controller change)
+scope path: 'v2' do
+  resources :users              # → /v2/users → users controller
+end
+
+# Scope with module only (no path change)
+scope module: 'legacy' do
+  resources :users              # → /users → legacy/users controller
+end
+```
+
 ## Namespace and Scope
 
 ```ruby

data/lib/belt/lambda_handler.rb

@@ -39,7 +39,14 @@ module Belt
       Belt.controller_paths << controllers_dir
       Dir.children(controllers_dir).each do |child|
         subdir = File.join(controllers_dir, child)
-        Belt.controller_paths << subdir if File.directory?(subdir)
+        next unless File.directory?(subdir)
+
+        Belt.controller_paths << subdir
+
+        # Auto-require application_controller.rb first (like application_record for models)
+        # so other controllers can inherit from it without explicit require_relative
+        app_controller = File.join(subdir, 'application_controller.rb')
+        require app_controller if File.exist?(app_controller)
       end
 
       # Auto-load all models (application_record first, then the rest)

data/lib/belt/route_dsl.rb

@@ -52,7 +52,7 @@ module Belt
 
   class NestedResourceBuilder
     def initialize(gateway, prefix, collection_prefix, inherited_tables: [], inherited_auth: nil, # rubocop:disable Metrics/ParameterLists
-                   inherited_controller: nil, inherited_lambda: nil)
+                   inherited_controller: nil, inherited_lambda: nil, scope_module: nil)
       @gateway = gateway
       @prefix = prefix
       @collection_prefix = collection_prefix
@@ -60,6 +60,7 @@ module Belt
       @inherited_auth = inherited_auth
       @inherited_controller = inherited_controller
       @inherited_lambda = inherited_lambda
+      @scope_module = scope_module
     end
 
     def resources(name, options = {}, &block)
@@ -67,7 +68,10 @@ module Belt
       singular = @gateway.send(:singularize, resource_name)
       param_name = options[:param] || "#{singular}_id"
       options = options.merge(tables: [resource_name.to_sym]) unless options.key?(:tables)
-      options = merge_inherited_options(options)
+      # Compute controller FIRST: explicit > scope_module/resource > resource_name
+      # Don't inherit controller from parent resource — nested resources get their own controller
+      controller_name = options[:controller] || compute_controller_name(resource_name)
+      options = merge_inherited_options(options.merge(controller: controller_name))
       resource_options = options.merge(route_type: :resources)
       actions = @gateway.send(:determine_actions, options)
 
@@ -76,14 +80,107 @@ module Belt
 
       nested_member_prefix = "#{@prefix}/#{resource_name}/{#{param_name}}"
       nested_collection_prefix = "#{@prefix}/#{resource_name}"
+      # Pass scope_module to nested builder so nested resources inherit it
       nested_builder = NestedResourceBuilder.new(@gateway, nested_member_prefix, nested_collection_prefix,
                                                  inherited_tables: Array(options[:tables] || []),
                                                  inherited_auth: options[:auth] || @inherited_auth,
-                                                 inherited_controller: @inherited_controller,
-                                                 inherited_lambda: @inherited_lambda)
+                                                 inherited_controller: controller_name,
+                                                 inherited_lambda: @inherited_lambda,
+                                                 scope_module: @scope_module)
       nested_builder.instance_eval(&block)
     end
 
+    # Singular resource inside nested context (e.g. resource :billing inside resources :projects)
+    def resource(name, options = {})
+      resource_name = name.to_s
+      # Compute controller FIRST: explicit > scope_module/resource > resource_name
+      # Don't inherit controller from parent resource — singular resources get their own controller
+      controller_name = options[:controller] || compute_controller_name(resource_name)
+      options = merge_inherited_options(options.merge(controller: controller_name))
+      resource_options = options.merge(route_type: :resource)
+      actions = determine_actions(options, default: %i[show update destroy create])
+
+      if actions.include?(:show)
+        @gateway.send(:add_route, :get, join_path(@prefix, resource_name),
+                      resolve_request_model_for(resource_options, :show))
+      end
+      if actions.include?(:update)
+        @gateway.send(:add_route, :put, join_path(@prefix, resource_name),
+                      resolve_request_model_for(resource_options, :update))
+      end
+      if actions.include?(:destroy)
+        @gateway.send(:add_route, :delete, join_path(@prefix, resource_name),
+                      resolve_request_model_for(resource_options, :destroy))
+      end
+      return unless actions.include?(:create)
+
+      @gateway.send(:add_route, :post, join_path(@prefix, resource_name),
+                    resolve_request_model_for(resource_options, :create))
+    end
+
+    # Rails-like `namespace` inside nested resource context — adds both a path prefix
+    # AND sets the controller module. Resources inside inherit the namespace module.
+    #
+    # Example:
+    #   resources :projects do
+    #     namespace :admin do
+    #       resources :users   # → /projects/:project_id/admin/users → admin/users controller
+    #     end
+    #   end
+    def namespace(name, options = {}, &)
+      segment = name.to_s
+      # namespace sets path AND module (controller prefix)
+      merged = { path: segment, module: segment }.merge(options)
+      scope(merged, &)
+    end
+
+    # Scope inside nested resource context - groups routes with shared options
+    # Example:
+    #   resources :projects do
+    #     scope path: 'billing', controller: :billing, tables: [:memberships] do
+    #       get '/', action: :show
+    #       post :checkout
+    #     end
+    #   end
+    #
+    # With module option (like Rails):
+    #   resources :projects do
+    #     scope module: 'v2' do
+    #       resources :users   # → /projects/:project_id/users → v2/users controller
+    #     end
+    #   end
+    def scope(options = {}, &)
+      previous_prefix = @prefix
+      previous_collection_prefix = @collection_prefix
+      previous_tables = @inherited_tables
+      previous_auth = @inherited_auth
+      previous_controller = @inherited_controller
+      previous_module = @scope_module
+
+      if options.key?(:path)
+        segment = options[:path].to_s.gsub(%r{^/|/$}, '')
+        @prefix = join_path(@prefix, segment)
+        @collection_prefix = join_path(@collection_prefix, segment)
+      end
+      # Module sets the controller prefix for nested resources (like Rails)
+      if options.key?(:module)
+        mod_segment = options[:module].to_s
+        @scope_module = @scope_module.to_s.empty? ? mod_segment : "#{@scope_module}/#{mod_segment}"
+      end
+      @inherited_auth = options[:auth] || @inherited_auth
+      @inherited_tables = (@inherited_tables + Array(options[:tables] || [])).uniq
+      @inherited_controller = options[:controller]&.to_s || @inherited_controller
+
+      instance_eval(&) if block_given?
+
+      @prefix = previous_prefix
+      @collection_prefix = previous_collection_prefix
+      @inherited_tables = previous_tables
+      @inherited_auth = previous_auth
+      @inherited_controller = previous_controller
+      @scope_module = previous_module
+    end
+
     def member(&)
       MemberCollectionBuilder.new(@gateway, @prefix, @inherited_tables, @inherited_auth,
                                   @inherited_controller, @inherited_lambda).instance_eval(&)
@@ -95,26 +192,65 @@ module Belt
     end
 
     %i[get post put delete patch].each do |method|
-      define_method(method) do |path, options = {}|
+      define_method(method) do |path_or_action, options = {}|
+        # Support both symbol (action name = path) and string (explicit path)
+        path, action = normalize_path_and_action(path_or_action, options)
         base = options[:on] == :collection ? @collection_prefix : @prefix
         full_path = join_path(base, path)
         options = merge_inherited_options(options)
         route_options = options.except(:on)
+        route_options[:action] ||= action if action
         @gateway.send(:add_route, method, full_path, route_options)
       end
     end
 
     private
 
+    # Normalize path/action: symbol means path=action, string means infer action from path
+    def normalize_path_and_action(path_or_action, options)
+      return [options[:path] || '', options[:action]] if path_or_action.nil?
+
+      if path_or_action.is_a?(Symbol)
+        # Symbol: use as both path segment and action name (e.g. :checkout → path: 'checkout', action: :checkout)
+        [path_or_action.to_s, options[:action] || path_or_action]
+      else
+        path = path_or_action.to_s
+        # Infer action from last non-param segment of path (e.g. 'checkout' → :checkout, '/' → nil)
+        inferred_action = options[:action] || infer_action_from_path(path)
+        [path, inferred_action]
+      end
+    end
+
+    # Infer action name from path: 'checkout' → :checkout, 'billing/checkout' → :checkout
+    def infer_action_from_path(path)
+      return nil if path.nil? || path.empty? || path == '/'
+
+      segments = path.gsub(%r{^/|/$}, '').split('/')
+      # Find last segment that's not a parameter (doesn't contain {})
+      last_segment = segments.reverse.find { |s| !s.include?('{') }
+      last_segment&.tr('-', '_')&.to_sym
+    end
+
     # Join a base path with a relative path, ensuring exactly one `/` separator.
+    # Handles "/" path by returning just the base (no trailing slash).
     def join_path(base, path)
       path = path.to_s
-      return base if path.empty?
-      return "#{base}#{path}" if path.start_with?('/')
+      return base if path.empty? || path == '/'
+      return "#{base}#{path}".chomp('/') if path.start_with?('/')
 
       "#{base}/#{path}"
     end
 
+    def determine_actions(options, default: %i[index create show update destroy])
+      if options[:only]
+        Array(options[:only])
+      elsif options[:except]
+        default - Array(options[:except])
+      else
+        default
+      end
+    end
+
     def add_nested_resource_routes(resource_name, param_name, resource_options, actions)
       if actions.include?(:index)
         @gateway.send(:add_route, :get, "#{@prefix}/#{resource_name}",
@@ -160,6 +296,17 @@ module Belt
       result[:lambda] ||= @inherited_lambda if @inherited_lambda
       result
     end
+
+    # Compute controller name from scope_module and resource name
+    # If scope_module is set, returns "module/resource_name" (Rails-like)
+    # Otherwise returns just resource_name
+    def compute_controller_name(resource_name)
+      if @scope_module && !@scope_module.empty?
+        "#{@scope_module}/#{resource_name}"
+      else
+        resource_name
+      end
+    end
   end
 
   class MemberCollectionBuilder
@@ -174,20 +321,49 @@ module Belt
     end
 
     %i[get post put delete patch].each do |method|
-      define_method(method) do |path, options = {}|
+      define_method(method) do |path_or_action, options = {}|
+        # Support both symbol (action name = path) and string (explicit path)
+        path, action = normalize_path_and_action(path_or_action, options)
         full_path = join_path(@prefix, path)
         options = merge_inherited_options(options)
+        options[:action] ||= action if action
         @gateway.send(:add_route, method, full_path, options)
       end
     end
 
     private
 
+    # Normalize path/action: symbol means path=action, string means infer action from path
+    def normalize_path_and_action(path_or_action, options)
+      return ['', options[:action]] if path_or_action.nil?
+
+      if path_or_action.is_a?(Symbol)
+        # Symbol: use as both path segment and action name (e.g. :test → path: 'test', action: :test)
+        [path_or_action.to_s, options[:action] || path_or_action]
+      else
+        path = path_or_action.to_s
+        # Infer action from last non-param segment of path (e.g. 'test' → :test)
+        inferred_action = options[:action] || infer_action_from_path(path)
+        [path, inferred_action]
+      end
+    end
+
+    # Infer action name from path: 'test' → :test, 'deep/nested' → :nested
+    def infer_action_from_path(path)
+      return nil if path.nil? || path.empty? || path == '/'
+
+      segments = path.gsub(%r{^/|/$}, '').split('/')
+      # Find last segment that's not a parameter (doesn't contain {})
+      last_segment = segments.reverse.find { |s| !s.include?('{') && !s.start_with?(':') }
+      last_segment&.tr('-', '_')&.to_sym
+    end
+
     # Join a base path with a relative path, ensuring exactly one `/` separator.
+    # Handles "/" path by returning just the base (no trailing slash).
     def join_path(base, path)
       path = path.to_s
-      return base if path.empty?
-      return "#{base}#{path}" if path.start_with?('/')
+      return base if path.empty? || path == '/'
+      return "#{base}#{path}".chomp('/') if path.start_with?('/')
 
       "#{base}/#{path}"
     end
@@ -249,9 +425,11 @@ module Belt
       inherited_tables = (@default_tables + resource_tables).uniq
       inherited_auth = options[:auth] || @default_auth
       inherited_lambda = options[:lambda]
+      inherited_controller = resource_name
       nested_builder = NestedResourceBuilder.new(self, member_prefix, collection_prefix,
                                                  inherited_tables: inherited_tables,
                                                  inherited_auth: inherited_auth,
+                                                 inherited_controller: inherited_controller,
                                                  inherited_lambda: inherited_lambda)
       nested_builder.instance_eval(&)
     end

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.3.37'
+  VERSION = '0.3.39'
 end

data/lib/templates/generate/controller.rb.erb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'application_controller'
-
 module <%= @module_name %>Controllers
   class <%= @class_name %>sController < ApplicationController
 <% if @references.any? -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.3.37
+  version: 0.3.39
 platform: ruby
 authors:
 - Stowzilla