belt 0.0.1 → 0.0.5

data/lib/belt/helpers/response.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'error_logging'
+require_relative 'cors_origin'
+
+module Belt
+  module Helpers
+    module Response
+      def cors_headers(event = nil)
+        event = @event if event.nil? && instance_variable_defined?(:@event)
+        origin = CorsOrigin.resolve_origin(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',
+          'Access-Control-Max-Age' => '300',
+          'Content-Type' => 'application/json'
+        }
+        headers['Access-Control-Allow-Origin'] = origin if origin
+        headers
+      end
+
+      def success_response(body, status_code = 200)
+        { statusCode: status_code, headers: cors_headers, body: JSON.generate(body) }
+      end
+
+      def error_response(message, status_code = 400, error_details = nil)
+        body = { error: message }
+        if error_details
+          body[:details] = error_details.is_a?(Hash) ? error_details : { message: error_details.to_s }
+        end
+        { statusCode: status_code, headers: cors_headers, body: JSON.generate(body) }
+      end
+
+      def html_response(html, status_code = 200)
+        event = @event if instance_variable_defined?(:@event)
+        origin = CorsOrigin.resolve_origin(CorsOrigin.origin_from_event(event))
+        headers = { 'Content-Type' => 'text/html; charset=utf-8' }
+        headers['Access-Control-Allow-Origin'] = origin if origin
+        { statusCode: status_code, headers: headers, body: html }
+      end
+
+      def handle_error_and_respond(error, message, context = {}, status_code = 500)
+        log_error(message, error, context)
+        if verbose_errors_enabled?
+          error_details = {
+            type: error.class.name, message: error.message,
+            backtrace: ErrorLogging.filter_backtrace(error.backtrace || []),
+            environment: ENV.fetch('ENVIRONMENT', nil)
+          }
+          error_details[:context] = context unless context.empty?
+          error_response(message, status_code, error_details)
+        else
+          error_response(message, status_code)
+        end
+      end
+
+      private
+
+      def verbose_errors_enabled?
+        env = ENV['ENVIRONMENT']&.downcase || ''
+        env.start_with?('dev') || env == 'local' || env == 'test'
+      end
+
+      def log_error(message, error, context = {})
+        logger_instance = defined?(LOGGER) && LOGGER.respond_to?(:instance) ? LOGGER.instance : @logger
+        ErrorLogging.log_error(logger_instance, message, error, context)
+      end
+    end
+  end
+end

data/lib/belt/holster.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Belt
+  class Holster
+    class << self
+      def inherited(subclass)
+        super
+        Belt.holsters << subclass
+      end
+
+      # Convention: gem root is two levels up from the holster file
+      def gem_root
+        @gem_root ||= File.expand_path('../..', caller_locations(1, 1).first.path)
+      end
+
+      attr_writer :gem_root, :controllers_path, :models_path, :routes_path, :schema_path
+
+      # Defaults follow Belt project structure conventions
+      def controllers_path
+        @controllers_path || File.join(gem_root, 'lambda', 'controllers')
+      end
+
+      def models_path
+        @models_path || File.join(gem_root, 'lambda', 'models')
+      end
+
+      def routes_path
+        @routes_path || File.join(gem_root, 'infrastructure', 'routes.tf.rb')
+      end
+
+      def schema_path
+        @schema_path || File.join(gem_root, 'infrastructure', 'schema.tf.rb')
+      end
+
+      def holster_name
+        name&.split('::')&.first&.downcase || 'unknown'
+      end
+    end
+  end
+
+  @holsters = []
+
+  class << self
+    attr_reader :holsters
+  end
+end

data/lib/belt/lambda_handler.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'lambda_loadout'
+require_relative 'observability'
+require_relative 'helpers/response'
+
+module Belt
+  # Lambda handler module — include in your Lambda entry point to get automatic
+  # observability setup, CORS preflight handling, JSON body parsing, and error wrapping.
+  #
+  # Usage:
+  #   require "belt"
+  #
+  #   include Belt::LambdaHandler
+  #
+  #   def execute(path:, body:, event:)
+  #     ROUTER.route(event: event, body: body)
+  #   end
+  #
+  module LambdaHandler
+    include Belt::Helpers::Response
+
+    attr_accessor :logger, :metrics
+
+    def self.included(base)
+      base.instance_variable_set(:@belt_lambda_handler_included, true)
+    end
+
+    # API Gateway Lambda handler.
+    # Handles HTTP requests with automatic CORS, body parsing, observability, and error wrapping.
+    # Override `execute` to provide your own routing logic.
+    def lambda_handler(event:, context:)
+      init_observability(context: context)
+
+      LambdaLoadout.with_logging_and_metrics(
+        logger,
+        metrics,
+        context,
+        event: event,
+        error_notification_config: {
+          sns_topic_arn: ENV.fetch('ERROR_NOTIFICATION_TOPIC_ARN', nil)
+        }
+      ) do
+        logger.info('Lambda invoked',
+                    http_method: event['httpMethod'],
+                    path: event['path'],
+                    source_ip: event.dig('requestContext', 'identity', 'sourceIp'))
+
+        return { statusCode: 200, headers: cors_headers(event), body: '{}' } if event['httpMethod'] == 'OPTIONS'
+
+        begin
+          body = JSON.parse(event['body'] || '{}')
+        rescue JSON::ParserError
+          return error_response('Invalid JSON in request body')
+        end
+
+        begin
+          result = execute(path: event['path'], body: body, event: event)
+          logger.info('Request completed', status_code: result[:statusCode], path: event['path'])
+          result
+        rescue StandardError => e
+          handle_error_and_respond(e, 'Unhandled error during request processing',
+                                   { path: event['path'], method: event['httpMethod'] })
+        end
+      end
+    rescue StandardError => e
+      Belt::Helpers::ErrorLogging.log_error(@logger, 'Unhandled Lambda error', e,
+                                            { phase: 'lambda_handler', path: event&.dig('path') })
+
+      body = { error: 'Internal server error' }
+      if verbose_errors_enabled?
+        body[:message] = e.message
+        body[:type] = e.class.name
+        body[:backtrace] = Belt::Helpers::ErrorLogging.filter_backtrace(e.backtrace || [])
+      end
+
+      { statusCode: 500, headers: cors_headers, body: JSON.generate(body) }
+    end
+
+    private
+
+    def init_observability(context:)
+      service_name = ENV['ACTION'] || context.function_name.split('-').last
+
+      @logger = LambdaLoadout::Logger.new(service: service_name)
+      @metrics = LambdaLoadout::Metrics.new(
+        namespace: ENV['BELT_METRICS_NAMESPACE'] || 'Belt',
+        service: service_name
+      )
+
+      Belt::Observability::Logger.instance = @logger
+      Belt::Observability::Metrics.instance = @metrics
+    end
+  end
+end

data/lib/belt/observability.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Belt
+  # Global facades for Lambda Loadout logger and metrics.
+  # Set by Belt::LambdaHandler at the start of each request.
+  # Provides clean access to observability from anywhere in the codebase.
+  module Observability
+    # Logger facade — delegates to a LambdaLoadout::Logger instance
+    module Logger
+      class << self
+        attr_accessor :instance
+
+        def info(message, **context)
+          instance&.info(message, **context)
+        end
+
+        def error(message, exception = nil, **context)
+          if exception
+            instance&.error(message, exception, **context)
+          else
+            instance&.error(message, **context)
+          end
+        end
+
+        def warn(message, exception = nil, **context)
+          if exception
+            instance&.warn(message, exception, **context)
+          else
+            instance&.warn(message, **context)
+          end
+        end
+
+        def debug(message, **context)
+          instance&.debug(message, **context)
+        end
+      end
+    end
+
+    # Metrics facade — delegates to a LambdaLoadout::Metrics instance
+    module Metrics
+      class << self
+        attr_accessor :instance
+
+        def add_metric(name:, unit:, value:)
+          instance&.add_metric(name: name, unit: unit, value: value)
+        end
+
+        def add_dimension(name:, value:)
+          instance&.add_dimension(name: name, value: value)
+        end
+
+        def track_event(event_name, **dimensions)
+          instance&.add_metric(name: event_name, unit: 'Count', value: 1)
+          dimensions.each { |k, v| instance&.add_dimension(name: k.to_s, value: v.to_s) }
+        end
+
+        def track_value(metric_name, value, unit: 'None', **dimensions)
+          instance&.add_metric(name: metric_name, unit: unit, value: value)
+          dimensions.each { |k, v| instance&.add_dimension(name: k.to_s, value: v.to_s) }
+        end
+      end
+    end
+  end
+end

data/lib/belt/parameters.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+
+# Rails-like Strong Parameters for Lambda controllers.
+# Provides secure parameter filtering without requiring Rails.
+module ActionController
+  class ParameterMissing < StandardError
+    attr_reader :param
+
+    def initialize(param)
+      @param = param.to_s
+      super("param is missing or the value is empty: #{@param}")
+    end
+  end
+
+  class UnpermittedParameters < StandardError
+    attr_reader :params
+
+    def initialize(params)
+      @params = Array(params).map(&:to_s)
+      super("found unpermitted parameter(s): #{@params.join(', ')}")
+    end
+  end
+
+  class Parameters
+    def initialize(params = {}, permitted = false)
+      @params = normalize_keys(params)
+      @permitted = permitted
+    end
+
+    def [](key)
+      @params[key.to_s]
+    end
+
+    def fetch(key, *, &)
+      @params.fetch(key.to_s, *, &)
+    end
+
+    def key?(key)
+      @params.key?(key.to_s)
+    end
+
+    def keys
+      @params.keys
+    end
+
+    def values
+      @params.values
+    end
+
+    def each(&)
+      @params.each(&)
+    end
+
+    def empty?
+      @params.empty?
+    end
+
+    def any?
+      @params.any?
+    end
+
+    def require(key)
+      value = @params[key.to_s]
+      raise ParameterMissing, key if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      value.is_a?(Hash) ? Parameters.new(value) : value
+    end
+
+    def permit(*filters)
+      permitted_params = {}
+
+      filters.each do |filter|
+        case filter
+        when Symbol, String
+          key = filter.to_s
+          permitted_params[key] = @params[key] if @params.key?(key)
+        when Hash
+          filter.each do |key, nested_filter|
+            key = key.to_s
+            next unless @params.key?(key)
+
+            permitted_params[key] = permit_nested(@params[key], nested_filter)
+          end
+        end
+      end
+
+      Parameters.new(permitted_params, true)
+    end
+
+    def permitted?
+      @permitted
+    end
+
+    def to_h
+      raise UnpermittedParameters, @params.keys unless @permitted
+
+      deep_to_h(@params)
+    end
+
+    def to_unsafe_h
+      deep_to_h(@params)
+    end
+
+    def merge(other)
+      other_hash = other.is_a?(Parameters) ? other.to_unsafe_h : other
+      Parameters.new(@params.merge(normalize_keys(other_hash)), @permitted)
+    end
+
+    def slice(*keys)
+      Parameters.new(@params.slice(*keys.map(&:to_s)), @permitted)
+    end
+
+    def except(*keys)
+      Parameters.new(@params.except(*keys.map(&:to_s)), @permitted)
+    end
+
+    private
+
+    def normalize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.transform_keys { |key| key.to_s.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '') }
+    end
+
+    def permit_nested(value, filter)
+      case value
+      when Hash
+        if filter == {}
+          value
+        elsif filter.is_a?(Array)
+          Parameters.new(value).permit(*filter).to_unsafe_h
+        else
+          value
+        end
+      when Array
+        if filter == []
+          value.select { |v| scalar?(v) }
+        elsif filter.is_a?(Array)
+          value.map do |item|
+            next item unless item.is_a?(Hash)
+
+            Parameters.new(item).permit(*filter).to_unsafe_h
+          end
+        else
+          value
+        end
+      else
+        value
+      end
+    end
+
+    def scalar?(value)
+      case value
+      when String, Symbol, NilClass, Numeric, TrueClass, FalseClass, Date, Time, DateTime
+        true
+      else
+        false
+      end
+    end
+
+    def deep_to_h(value)
+      case value
+      when Hash
+        value.transform_values { |v| deep_to_h(v) }
+      when Array
+        value.map { |v| deep_to_h(v) }
+      when Parameters
+        value.to_unsafe_h
+      else
+        value
+      end
+    end
+  end
+end

data/lib/belt/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Belt
-  VERSION = "0.1.0"
+  VERSION = '0.0.5'
 end

data/lib/belt.rb

@@ -1,3 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'belt/version'
+require_relative 'belt/parameters'
+require_relative 'belt/observability'
+require_relative 'belt/lambda_handler'
+require_relative 'belt/action_router'
+require_relative 'belt/holster'
+
 module Belt
-  VERSION = "0.0.1"
+  class AuthenticationError < StandardError; end
+  class RecordNotFound < StandardError; end
+  class ActionNotFound < StandardError; end
+
+  @controller_paths = []
+
+  class << self
+    attr_reader :controller_paths
+
+    # Collects all controller paths: app-defined + holster-provided
+    def all_controller_paths
+      controller_paths + holsters.select { |h| File.directory?(h.controllers_path) }.map(&:controllers_path)
+    end
+
+    # Collects all model paths from holsters
+    def all_models_paths
+      holsters.select { |h| File.directory?(h.models_path) }.map(&:models_path)
+    end
+
+    # Collects all routes files from holsters
+    def all_routes_paths
+      holsters.select { |h| File.exist?(h.routes_path) }.map(&:routes_path)
+    end
+
+    # Collects all schema files from holsters
+    def all_schema_paths
+      holsters.select { |h| File.exist?(h.schema_path) }.map(&:schema_path)
+    end
+  end
 end
+
+require_relative 'belt_controller/base'