belt 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fde6517c1c9ccbd2cac44b59f692934fe4f2faf614d64ebafad7ee30f6e562a1
-  data.tar.gz: f368621167b1266f21cb8205a3eb31dd92fefb6856876696130ff023f5c953ad
+  metadata.gz: 9445afac3a832595238e015620913022c6cdfa6fb8f45e4d37b59f7215a34f25
+  data.tar.gz: 88b09d9faf70b253c2ac50429a3e4c54bd2cc3ebd4c9e59f2e7887e833d8d543
 SHA512:
-  metadata.gz: e2128c5df77f839ffb2997d4f634b149a28140187f57fec829b4109e687e958bf1513276e7963a679577c069b4404208178adb62142ebd6f791ccafc56cebc0e
-  data.tar.gz: cf0b2faf98684b8ad6d53eb6505a3543c62a09c143f2c8a07de8eb2601a076b007134609cdc0f9fa3f4536aa84df35702cc3c595018e2e348c14e55b519c0bc6
+  metadata.gz: 186ffe088baefe51b1535a0be897053d61d5ae717d06720afd6f1862decd7b0074f85b47de5ec27d6e8e3e7104d35ed390b64e8e20a4a270efd1ed14c00e73ea
+  data.tar.gz: c43ac53938a4642699bda126b97b703b72bd5f98470333e6cb889ac9fef21528bc5da791a9bb20bd50f7908442e2bb93c967cdb75fb2ee725e7f5bd3c8de9a58

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.0.5
+
+- Eliminated regex from `Belt::ActionRouter` — uses pure segment-by-segment string comparison (resolves CodeQL alerts)
+
+## 0.0.4
+
+- Added `Belt::Holster` — Belt's equivalent of Rails Engines. Gems subclass `Belt::Holster` to provide controllers, models, routes, and schema via convention.
+- Added `Belt.all_controller_paths`, `Belt.all_models_paths`, `Belt.all_routes_paths`, `Belt.all_schema_paths` aggregation methods
+- `Belt::ActionRouter` now searches holster controller paths automatically
+
+## 0.0.3
+
+- Added `Belt::LambdaHandler` — module for Lambda entry points with observability, CORS preflight, JSON parsing, and error wrapping
+- Added `Belt::ActionRouter` — request routing to controllers based on route manifests
+- Added `Belt::Observability` — global Logger and Metrics facades for access from anywhere in the codebase
+
+## 0.0.2
+
+- Renamed base class to `BeltController::Base` (mirrors `ActionController::Base`)
+- Added `BeltController::Base` with callbacks, strong params, CORS, error handling
+- Added `ActionController::Parameters` (strong params without Rails)
+- Added response helpers and CORS origin resolution
+- Bundled dependencies: activeitem, lambda_loadout, s3arch

data/README.md

@@ -1,19 +1,281 @@
 # Belt
 
-A utility toolkit for Ruby applications.
+A Rails-inspired framework for building serverless Ruby applications on AWS Lambda.
+
+Belt bundles everything you need to go from zero to production:
+
+- **BeltController** — callbacks, strong parameters, error handling, CORS
+- **Belt::LambdaHandler** — Lambda entry point with observability, CORS preflight, error wrapping
+- **Belt::ActionRouter** — request routing to controllers from route manifests
+- **ActiveItem** — DynamoDB ORM (queries, validations, associations, transactions)
+- **Lambda Loadout** — structured logging, CloudWatch metrics (EMF), error alerting
+- **S3arch** — full-text search via SQLite FTS5, stored on S3, queried from Lambda
 
 ## Installation
 
+Add to your Gemfile:
+
+```ruby
+gem "belt"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Project structure
+
+```
+my-app/
+├── infrastructure/
+│   ├── routes.tf.rb        # Belt provider route definitions
+│   └── schema.tf.rb        # DynamoDB table schemas
+├── lambda/
+│   ├── controllers/
+│   │   └── posts_controller.rb
+│   ├── models/
+│   │   └── post.rb
+│   ├── lib/
+│   │   └── routes.rb
+│   └── api.rb              # Lambda entry point
+├── Gemfile
+└── Gemfile.lock
+```
+
+### 2. Define a model
+
+```ruby
+require "activeitem"
+
+class Post < ActiveItem::Base
+  self.primary_key = :id
+
+  attr_accessor :id, :user_id, :title, :body, :created_at
+
+  validates :title, presence: true
+  before_create { self.id ||= SecureRandom.uuid }
+end
+```
+
+### 3. Write a controller
+
+```ruby
+require "belt"
+
+class PostsController < BeltController::Base
+  before_action :authenticate!
+
+  def index
+    posts = Post.where(user_id: current_user_id, index: "UserIndex")
+    success_response(posts.map(&:attributes))
+  end
+
+  def show
+    post = Post.find(params["id"])
+    success_response(post.attributes)
+  end
+
+  def create
+    attrs = params.require(:post).permit(:title, :body).to_h
+    post = Post.create!(attrs.merge(user_id: current_user_id))
+    success_response(post.attributes, 201)
+  end
+end
+```
+
+### 4. Lambda entry point
+
+Use `Belt::LambdaHandler` to get automatic observability, CORS preflight handling, and error wrapping:
+
+```ruby
+require "belt"
+
+include Belt::LambdaHandler
+
+ROUTER = Belt::ActionRouter.new(routes: Routes::API, namespace: "api")
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end
+```
+
+That's it. `lambda_handler` is automatically your Lambda function handler. It:
+- Initializes structured logging and CloudWatch metrics
+- Handles OPTIONS preflight requests
+- Parses JSON request bodies
+- Catches unhandled errors and returns proper CORS-enabled error responses
+- Calls your `execute` method for routing
+
+### 5. Configure the Belt Terraform provider
+
+The Belt Terraform provider (formerly Dispatcher) handles Lambda packaging, API Gateway routing, and IAM permissions.
+
+Add the provider to your Terraform config:
+
+```hcl
+terraform {
+  required_providers {
+    belt = {
+      source = "stowzilla/belt"
+    }
+  }
+}
+```
+
+Define routes in `infrastructure/routes.tf.rb`:
+
 ```ruby
-gem 'belt'
+TerraDispatch.routes.draw do
+  namespace :api do
+    resources :posts, only: [:index, :show, :create]
+  end
+end
 ```
 
-## Usage
+Define tables in `infrastructure/schema.tf.rb`:
 
 ```ruby
-require 'belt'
+TerraDispatch.schema.define do
+  model :post do
+    partition_key :id, :string
+    global_secondary_index :UserIndex, partition_key: :user_id
+  end
+end
+```
+
+Then deploy:
+
+```bash
+terraform init
+terraform apply
 ```
 
+The provider will:
+- Package your Ruby code into Lambda functions
+- Create API Gateway routes matching your DSL
+- Generate IAM policies for DynamoDB table access
+- Set up CloudWatch log groups
+
+## BeltController Features
+
+### Callbacks
+
+```ruby
+class AdminController < BeltController::Base
+  before_action :authenticate!
+  before_action :require_admin!, except: [:health]
+  skip_before_action :authenticate!, only: [:health]
+end
+```
+
+### Strong Parameters
+
+```ruby
+params.require(:user).permit(:name, :email, address: [:street, :city])
+```
+
+### Error Handling
+
+```ruby
+class ApiController < BeltController::Base
+  rescue_from MyCustomError, with: :handle_custom
+
+  private
+
+  def handle_custom(exception, _context = {})
+    error_response(exception.message, 422)
+  end
+end
+```
+
+### Response Helpers
+
+```ruby
+success_response({ id: "123", name: "Example" })       # 200 JSON with CORS
+success_response({ id: "123" }, 201)                    # 201 Created
+error_response("Not found", 404)                        # 404 JSON error
+html_response("<h1>Hello</h1>")                         # 200 HTML with CORS
+```
+
+## Holsters (Belt's Engines)
+
+Holsters are Belt's equivalent of Rails Engines. A holster lets a gem provide its own controllers, models, routes, and schema — all discovered automatically via convention.
+
+### Creating a Holster
+
+In your gem, subclass `Belt::Holster`:
+
+```ruby
+# lib/s3arch/holster.rb
+module S3arch
+  class Holster < Belt::Holster
+  end
+end
+```
+
+That's it. Belt discovers all `Holster` subclasses at boot. By convention, it expects:
+
+```
+your-gem/
+├── infrastructure/
+│   ├── routes.tf.rb      # Holster's route definitions
+│   └── schema.tf.rb      # Holster's DynamoDB tables
+└── lambda/
+    ├── controllers/      # Holster's controllers
+    └── models/           # Holster's models
+```
+
+No configuration needed if you follow the convention. Belt resolves paths relative to your gem's root (two directories up from the holster file).
+
+### Customizing Paths
+
+If your gem uses a different layout, override any path:
+
+```ruby
+module MyGem
+  class Holster < Belt::Holster
+    self.gem_root = File.expand_path("..", __dir__)
+    self.controllers_path = File.join(gem_root, "app", "controllers")
+  end
+end
+```
+
+### How Belt Uses Holsters
+
+- **Controllers**: `Belt::ActionRouter` searches holster controller paths automatically
+- **Routes**: `Belt.all_routes_paths` collects all holster `routes.tf.rb` files for the Terraform provider
+- **Schema**: `Belt.all_schema_paths` collects all holster `schema.tf.rb` files for the Terraform provider
+- **Models**: `Belt.all_models_paths` collects all holster model directories
+
+## Controller Discovery
+
+Belt discovers controllers from the app's namespace module first, then searches `Belt.all_controller_paths` — which includes both app-defined paths and holster-provided paths. No registration needed.
+
+## Belt::Observability
+
+Belt provides global `Belt::Observability::Logger` and `Belt::Observability::Metrics` facades that are set automatically by `Belt::LambdaHandler`. Access them from anywhere:
+
+```ruby
+Belt::Observability::Logger.info("Something happened", user_id: "123")
+Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ENVIRONMENT` | Controls verbose error responses (`dev*`, `local`, `test`) |
+| `BELT_METRICS_NAMESPACE` | CloudWatch metrics namespace (default: `Belt`) |
+| `ACTION` | Service name for logging (falls back to function name) |
+| `ERROR_NOTIFICATION_TOPIC_ARN` | SNS topic for error alerts |
+| `CORS_ALLOWED_ORIGINS` | Comma-separated origins (overrides domain vars) |
+| `CUSTOMER_APP_DOMAIN` | Primary app domain for CORS |
+| `OPS_APP_DOMAIN` | Internal tools domain for CORS |
+
 ## License
 
 MIT

data/certs/stowzilla.pem

@@ -0,0 +1,26 @@
+-----BEGIN CERTIFICATE-----
+MIIEdDCCAtygAwIBAgIBATANBgkqhkiG9w0BAQsFADBAMQ4wDAYDVQQDDAVhZ2Vu
+dDEZMBcGCgmSJomT8ixkARkWCXN0b3d6aWxsYTETMBEGCgmSJomT8ixkARkWA2Nv
+bTAeFw0yNjA2MDgxOTExNTlaFw0yNzA2MDgxOTExNTlaMEAxDjAMBgNVBAMMBWFn
+ZW50MRkwFwYKCZImiZPyLGQBGRYJc3Rvd3ppbGxhMRMwEQYKCZImiZPyLGQBGRYD
+Y29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAupBquKI/4WvXOgND
+pXyqH2GllZs1wG4TWWdn/DoMg45UoCwD+AWEuGrIdInBCpPN8vEJNJWPoM/RrU+b
+xRBZT4uUk00bnZRW2SYh5GJSqBoBR+rWc2DGkXyGfdRU2sQvkB0+is6ChgQ61WMM
+33LE9+loBlVsZ6EVtrc18Uh2OW0mJpe0hN2nmBrxZqqOZigxC4DKRMFHvpRkxSb6
+mD4kit1AcwX9NEWJsXxrPaetL/SB/VbXaEZX93XAvp6USaXvCWt4slkDS2mIvqtn
+9DtGC43LFC7SDGbnsG9PVenQgVCi8UWFPUAab0PqZSlmi3Qlbhw8qTGPp5Cbv4vz
+qjC2UGPOQigA/7lbbGRhCohMrjOVHMAQwkcgiIqtolUoYlnvPMIy+m3pdvgDv/PH
+bsZGvXQ7i0458xsmp1vaKthZocVAR+GboHbuIiYPUnO45ccXUQ00x6365tTe7mZi
+NvmUYdAGbQmVvFqyxF7IYA6sF74L2Lstu0knSfss557bAe1HAgMBAAGjeTB3MAkG
+A1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBSnxTL/lNBCeLqpeVIX6AUY
+kel4zjAeBgNVHREEFzAVgRNhZ2VudEBzdG93emlsbGEuY29tMB4GA1UdEgQXMBWB
+E2FnZW50QHN0b3d6aWxsYS5jb20wDQYJKoZIhvcNAQELBQADggGBACm9Fjit/UCv
+FxlKqeiCTIG94cIx+QrWAOJSx9knKydwUec1u04D/DbfZjTn3C2Bj227QgxeUn+6
+if3e2v7zAk1896hLmGYzML0+nxQPb0vmtdLR7HETUlSKTVabcv1fbwLyjsuGrBvk
+y51vOEzUEZ508a9yepLYqrQu1kOju4d57c9oA5l3H0mMKWz7av9tFj0B+STvuaWk
+HRYDWc5HgOEVTyV+w0uFt2Kw4OCb8C42uSvC5RfYYtw78MSP+5Ru+LXJ7XOtmuN0
+E6GVmofQ17ig9O3rgfFbMendSInrRmvPIGswvM1yivq9NOllFbdck2OJKPx6FCJF
+7SJIkXQfc9P4B5iASIV1d1FsE0YX+g3jHXPJK/4mGL5bAyBKzpMfQB/mg6vQBzkh
+aOKPwcreFj7TznBl89R5tNS9wZQfPVR98zgPyocddWhK18eQNMSBUnv4eeJ8PPbk
+DovL+G8ajHDZ9fjH/+GVYHEMuiVdLarXrKJpHC1VfGTTUAp4NSEpUQ==
+-----END CERTIFICATE-----

data/lib/belt/action_router.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'helpers/cors_origin'
+
+module Belt
+  # Routes incoming requests to controllers based on a route manifest.
+  #
+  # Usage:
+  #   ROUTER = Belt::ActionRouter.new(routes: MY_ROUTES, namespace: "api")
+  #   response = ROUTER.route(event: event, body: body)
+  #
+  class ActionRouter
+    class RouteNotFound < StandardError; end
+
+    def initialize(routes:, namespace:)
+      @namespace = namespace.to_s
+      @namespace_module_name = "#{@namespace.split('_').map(&:capitalize).join}Controllers"
+      @routes = build_route_table(routes)
+    end
+
+    def route(event:, body:)
+      method = event['httpMethod']
+      full_path = event['path']
+      match_path = strip_namespace_prefix(full_path)
+
+      route_info = find_route(method, match_path)
+
+      unless route_info
+        Belt::Observability::Logger.instance&.warn('Route not found', method: method, path: full_path)
+        return error_response('Not found', 404, event)
+      end
+
+      path_params = extract_path_params(route_info[:pattern], match_path)
+      event['pathParameters'] = (event['pathParameters'] || {}).merge(path_params)
+
+      dispatch_to_controller(route_info, event, body)
+    end
+
+    def find_route(method, path)
+      path_segments = path.split('/')
+      @routes.find { |r| r[:verb] == method && segments_match?(r[:segments], path_segments) }
+    end
+
+    def extract_path_params(pattern, actual_path)
+      pattern_segments = pattern.split('/')
+      path_segments = actual_path.split('/')
+      params = {}
+
+      pattern_segments.each_with_index do |seg, i|
+        params[seg[1..-2]] = path_segments[i] if seg.start_with?('{') && seg.end_with?('}')
+      end
+
+      params
+    end
+
+    private
+
+    def strip_namespace_prefix(path)
+      return '/' if path.nil?
+
+      prefix = "/#{@namespace}"
+      if path.start_with?(prefix)
+        stripped = path.sub(prefix, '')
+        stripped.empty? ? '/' : stripped
+      else
+        path
+      end
+    end
+
+    def build_route_table(routes)
+      routes.map { |r| build_route_entry(r) }
+            .sort_by { |r| route_specificity(r[:pattern]) }
+    end
+
+    def route_specificity(pattern)
+      segments = pattern.split('/').reject(&:empty?)
+      param_count = segments.count { |s| s.start_with?('{') }
+      [param_count, -segments.length, pattern]
+    end
+
+    def build_route_entry(route)
+      pattern = route[:path] || route['path']
+      {
+        verb: route[:verb] || route['verb'],
+        pattern: pattern,
+        segments: pattern.split('/'),
+        controller: route[:controller] || route['controller'],
+        action: route[:action] || route['action']
+      }
+    end
+
+    def segments_match?(pattern_segments, path_segments)
+      return false unless pattern_segments.length == path_segments.length
+
+      pattern_segments.each_with_index do |seg, i|
+        next if seg.start_with?('{') && seg.end_with?('}')
+        return false unless seg == path_segments[i]
+      end
+
+      true
+    end
+
+    def dispatch_to_controller(route_info, event, body)
+      controller_class = resolve_controller(route_info[:controller])
+      controller = controller_class.new(event: event, body: body)
+
+      controller_name = controller_class.name.split('::').last.gsub('Controller', '')
+      Belt::Observability::Logger.instance&.info("Processing by #{controller_name}##{route_info[:action]}")
+
+      controller.dispatch(route_info[:action].to_sym)
+    end
+
+    def resolve_controller(controller_name)
+      # Try namespace module first (app's own controllers)
+      begin
+        namespace_module = Object.const_get(@namespace_module_name)
+        return resolve_from_module(namespace_module, controller_name)
+      rescue NameError
+        # Fall through to controller_paths lookup
+      end
+
+      # Scan controller_paths (gem-provided controllers via convention)
+      resolve_from_paths(controller_name)
+    end
+
+    def resolve_from_module(namespace_module, controller_name)
+      if controller_name.include?('/')
+        parts = controller_name.split('/')
+        parent = namespace_module.const_get(parts[0].split('_').map(&:capitalize).join)
+        parent.const_get("#{parts[1].split('_').map(&:capitalize).join}Controller")
+      else
+        namespace_module.const_get("#{controller_name.split('_').map(&:capitalize).join}Controller")
+      end
+    end
+
+    def resolve_from_paths(controller_name)
+      if controller_name.include?('/')
+      end
+      file_name = "#{controller_name}_controller.rb"
+
+      Belt.all_controller_paths.each do |path|
+        full_path = File.join(path, file_name)
+        next unless File.exist?(full_path)
+
+        require full_path
+        # After requiring, try to find the constant
+        class_name = "#{controller_name.split(%r{[_/]}).map(&:capitalize).join}Controller"
+        return Object.const_get(class_name) if Object.const_defined?(class_name)
+      end
+
+      raise Belt::ActionNotFound, "Controller not found: #{controller_name}"
+    end
+
+    def error_response(message, status_code, event = nil)
+      origin = Belt::Helpers::CorsOrigin.resolve_origin(Belt::Helpers::CorsOrigin.origin_from_event(event))
+      headers = {
+        'Access-Control-Allow-Headers' => 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token',
+        'Access-Control-Allow-Methods' => 'GET,POST,PUT,DELETE,PATCH,OPTIONS',
+        'Content-Type' => 'application/json'
+      }
+      headers['Access-Control-Allow-Origin'] = origin if origin
+      { statusCode: status_code, headers: headers, body: JSON.generate(error: message) }
+    end
+  end
+end

data/lib/belt/helpers/cors_origin.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Belt
+  module Helpers
+    module CorsOrigin
+      def self.resolve_origin(request_origin)
+        allowed = allowed_origins
+        return nil if allowed.empty?
+        return request_origin if request_origin && allowed.include?(request_origin)
+
+        allowed.first
+      end
+
+      def self.origin_from_event(event)
+        return nil unless event.is_a?(Hash)
+
+        headers = event['headers']
+        return nil unless headers.is_a?(Hash)
+
+        headers['Origin'] || headers['origin']
+      end
+
+      def self.allowed_origins
+        @allowed_origins ||= build_allowed_origins
+      end
+
+      def self.reset!
+        @allowed_origins = nil
+      end
+
+      private_class_method def self.build_allowed_origins
+        explicit = ENV.fetch('CORS_ALLOWED_ORIGINS', nil)
+        return explicit.split(',').map(&:strip).reject(&:empty?) if explicit && !explicit.empty?
+
+        origins = []
+        domains = %w[CUSTOMER_APP_DOMAIN OPS_APP_DOMAIN BLOG_APP_DOMAIN]
+        domains.each do |var|
+          domain = ENV.fetch(var, nil)
+          next unless domain && !domain.empty?
+
+          origins << "https://#{domain}"
+          origins << "https://www.#{domain}" if domain.count('.') == 1
+        end
+
+        env = ENV.fetch('ENVIRONMENT', nil)
+        unless %w[prod production staging].include?(env)
+          origins << 'http://localhost:3000'
+          origins << 'http://localhost:3001'
+        end
+
+        origins
+      end
+    end
+  end
+end

data/lib/belt/helpers/error_logging.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Belt
+  module Helpers
+    module ErrorLogging
+      module_function
+
+      def log_error(logger, message, error, context = {})
+        filtered_backtrace = filter_backtrace(error.backtrace || [])
+
+        if logger
+          logger.error(message,
+                       error_class: error.class.name,
+                       error_message: error.message,
+                       backtrace: filtered_backtrace,
+                       backtrace_full: error.backtrace&.first(20),
+                       **context)
+        else
+          require 'json'
+          puts JSON.generate({
+                               level: 'ERROR',
+                               message: message,
+                               error_class: error.class.name,
+                               error_message: error.message,
+                               backtrace: filtered_backtrace,
+                               timestamp: Time.now.utc.iso8601,
+                               **context
+                             })
+        end
+      end
+
+      def filter_backtrace(backtrace)
+        return [] if backtrace.nil? || backtrace.empty?
+
+        app_patterns = [%r{/var/task/}, %r{lambda/}, %r{controllers/}, %r{models/}, %r{lib/}, %r{helpers/}]
+        exclude_patterns = [%r{/var/runtime/}, %r{/opt/ruby/}, %r{/gems/}, /rubygems/, /<internal:/]
+
+        app_lines = []
+        lib_lines = []
+
+        backtrace.each do |line|
+          next if exclude_patterns.any? { |pattern| line.match?(pattern) }
+
+          if app_patterns.any? { |pattern| line.match?(pattern) }
+            app_lines << line
+          else
+            lib_lines << line
+          end
+        end
+
+        (app_lines.first(10) + lib_lines.first(3)).compact
+      end
+    end
+  end
+end