aws_lambda_ric 3.1.3 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e8bc181a3186101100b6f17135c0db2e9a1b46e7df20fdd83c026fde47acc2f
-  data.tar.gz: a16d3aaaab5fb3f0c5fcda6b3ca762cc38440f15b2ae2b0a07071d79a7bf2227
+  metadata.gz: aebcc51bb69e0146bf4fe0c2361e55967d773569e9a75b5edfee8e59926dca71
+  data.tar.gz: ee94ca25bd713f8dca2a08a876b6b8e9512a02953ade9d14cfa79c38b3eaee4b
 SHA512:
-  metadata.gz: 4e1ab797c6dfbde6f84de8cae8de0dc3fcdeef5912218b5a3d45467ca8d2416e0be7e56d1a9755803cd2913e6380153796b918a63ea658a50c5418946083de44
-  data.tar.gz: 3933a5ed56c6a6ac1e06e4fe5b3af87bef8f7d999a2054f3787f7ed0332c600ae12a9f76435b3dd14a9c52752d8c6999c59f84acacc9b896d25e8094810213a5
+  metadata.gz: 29f94ab802c88332d74581db2303c2b64b9864a3a5a2abdef0bdc7e1c4df810ed4248790d371d0dd55d934765928972a27a0b11976c66c86f468465b2bf62bb5
+  data.tar.gz: 82dada5e5cab9d9e85e0d0d44f65e8ccfbada3a633a491ccf25fb32b8ed0e812355be7c8fe6fa973c38e6cd0e6efeca81bf9b4a914f9a7d42b453fac50c35a57

data/README.md

@@ -11,6 +11,17 @@ You can include this package in your preferred base image to make that base imag
 
 ## Requirements
 The Ruby Runtime Interface Client package currently supports ruby 3.0 and above.
+
+## Migration from 2.x to 3.x
+
+**Important**: Version 2.x is deprecated. Please upgrade to version 3.x. For more information about Lambda runtime support, see the [AWS Lambda runtimes documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
+
+**Breaking Change**: Version 3.0.0 introduced a change in how the handler is specified:
+
+- **Version 2.x**: Handler was passed as a command line argument
+- **Version 3.x+**: Handler must be specified via the `_HANDLER` environment variable
+
+If you're upgrading from 2.x, update your Dockerfile to use the `_HANDLER` environment variable instead of relying on `CMD` arguments.
  
 ## Usage
 
@@ -39,7 +50,9 @@ Or install it manually as:
 
 The next step would be to copy your Lambda function code into the image's working directory.
 You will need to set the `ENTRYPOINT` property of the Docker image to invoke the Runtime Interface Client and
-then set the `CMD` argument to specify the desired handler.
+set the `_HANDLER` environment variable to specify the desired handler.
+
+**Important**: The Runtime Interface Client requires the handler to be specified via the `_HANDLER` environment variable.
 
 Example Dockerfile:
 ```dockerfile
@@ -57,23 +70,16 @@ RUN gem install bundler
 # Install the Runtime Interface Client
 RUN gem install aws_lambda_ric
 
-# If you want to install Runtime Interface Client From Source, you can uncomment the following `ADD` and `RUN` layers. 
-# Do not forget to comment/remove the above `RUN gem install aws_lambda_ric` command.
-# ADD https://github.com/aws/aws-lambda-ruby-runtime-interface-client.git /aws_lambda_ric
-# RUN cd /aws_lambda_ric && \
-#     make init && \
-#     make build && \
-#     gem install --local /aws_lambda_ric/pkg/aws_lambda_ric-3.0.0.gem && \
-#     rm -rf /aws_lambda_ric
-
 # Copy function code
 RUN mkdir -p ${FUNCTION_DIR}
 COPY app.rb ${FUNCTION_DIR}
 
 WORKDIR ${FUNCTION_DIR}
 
+# Set the handler via environment variable
+ENV _HANDLER="app.App::Handler.process"
+
 ENTRYPOINT ["/usr/local/bin/aws_lambda_ric"]
-CMD ["app.App::Handler.process"]
 ```
 
 Note that the `ENTRYPOINT` may differ based on the base image used. You can find the correct path by running an
@@ -119,9 +125,10 @@ mkdir -p ~/.aws-lambda-rie && \
 
 ```shell script
 docker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \
+    -e _HANDLER="app.App::Handler.process" \
     --entrypoint /aws-lambda/aws-lambda-rie \
     myfunction:latest \
-        /usr/local/bin/aws_lambda_ric app.App::Handler.process
+        /usr/local/bin/aws_lambda_ric
 ```
 
 This runs the image as a container and starts up an endpoint locally at `http://localhost:9000/2015-03-31/functions/function/invocations`. 
@@ -136,6 +143,28 @@ This command invokes the function running in the container image and returns a r
 
 *Alternately, you can also include RIE as a part of your base image. See the AWS documentation on how to [Build RIE into your base image](https://docs.aws.amazon.com/lambda/latest/dg/images-test.html#images-test-alternative).*
 
+### Automated Local Testing
+
+For a simple approach to run your local RIC changes, use the one-command setup:
+
+```shell script
+make run-local-ric
+```
+
+This command will:
+1. Build a Docker image with your local RIC code
+2. Compile the gem inside the Linux container (avoiding OS compatibility issues)
+3. Start the Lambda Runtime Interface Emulator on port 9000
+4. Run a test Lambda function using your RIC
+
+Once running, invoke the function from another terminal:
+
+```shell script
+curl -X POST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
+```
+
+Modify the test handler in `test/integration/test-handlers/echo/app.rb` to test different scenarios.
+
 ## Development
 
 ### Building the package
@@ -157,6 +186,16 @@ Then,
 * to run integration tests: `make test-integ`
 * to run smoke tests: `make test-smoke`
 
+### Running Dockerized Harness Tests
+
+To run the containerized test harness locally, use:
+
+```shell script
+make test-dockerized RUBY_VERSION=3.4
+```
+
+This command builds your Lambda function in a Docker container using the specified Ruby version, sets up the containerized test runner, and executes the test suites defined in `test/dockerized/suites/`.
+
 ### Troubleshooting
 While running integration tests, you might encounter the Docker Hub rate limit error with the following body:
 ```

data/aws_lambda_ric.gemspec

@@ -31,6 +31,7 @@ Gem::Specification.new do |spec|
   spec.executables           = 'aws_lambda_ric'
   spec.require_paths         = ['lib']
 
+  spec.add_runtime_dependency "logger", ">= 1.4", "< 2.0"
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'rake', '~> 13.0'

data/lib/aws_lambda_ric/lambda_log_formatter.rb

@@ -1,12 +1,69 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'logger'
 
 class LogFormatter < Logger::Formatter
   FORMAT = '%<sev>s, [%<datetime>s #%<process>d] %<severity>5s %<request_id>s -- %<progname>s: %<msg>s'
 
   def call(severity, time, progname, msg)
-    (FORMAT % {sev: severity[0..0], datetime: format_datetime(time), process: $$, severity: severity,
-               request_id: $_global_aws_request_id, progname: progname, msg: msg2str(msg)}).encode!('UTF-8')
+    formatted = FORMAT % {
+      sev: severity[0..0],
+      datetime: format_datetime(time),
+      process: $$,
+      severity: severity,
+      request_id: $_global_aws_request_id,
+      progname: progname,
+      msg: msg2str(msg)
+    }
+    "#{formatted.encode('UTF-8', invalid: :replace, undef: :replace, replace: '�')}\n"
+  end
+end
+
+class JsonLogFormatter < Logger::Formatter
+  DATETIME_FORMAT = '%Y-%m-%dT%H:%M:%S.%6NZ'
+
+  def call(severity, time, progname, msg)
+    payload = {
+      timestamp: time.utc.strftime(DATETIME_FORMAT),
+      level: severity,
+      message: message_for(msg),
+      requestId: $_global_aws_request_id
+    }
+
+    logger_name = sanitize_utf8(progname) unless progname.nil?
+    payload[:logger] = logger_name unless logger_name.nil? || logger_name.empty?
+
+    if msg.is_a?(Exception)
+      payload[:errorType] = msg.class.to_s
+      payload[:errorMessage] = sanitize_utf8(msg.message)
+      payload[:stackTrace] = Array(msg.backtrace).map { |line| sanitize_utf8(line) }
+      location = location_for(msg)
+      payload[:location] = location unless location.nil?
+    end
+
+    "#{JSON.generate(payload.compact)}\n"
+  end
+
+  private
+
+  def message_for(msg)
+    result = msg.is_a?(Exception) ? msg.message : msg2str(msg)
+    sanitize_utf8(result)
+  end
+
+  def location_for(exception)
+    first_backtrace_line = exception.backtrace&.first
+    return nil if first_backtrace_line.nil?
+
+    sanitized_line = sanitize_utf8(first_backtrace_line)
+    matched = sanitized_line.match(/\A(?<file>.+):(?<line>\d+):in [`'](?<method>.+)'\z/)
+    return "#{matched[:file]}:#{matched[:method]}:#{matched[:line]}" if matched
+
+    sanitized_line
+  end
+
+  def sanitize_utf8(value)
+    value.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '�')
   end
 end

data/lib/aws_lambda_ric/logger_patch.rb

@@ -1,19 +1,57 @@
 # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 
+# frozen_string_literal: true
+
+require 'logger'
+require_relative 'lambda_log_formatter'
+
 module LoggerPatch
-  def initialize(logdev, shift_age = 0, shift_size = 1048576, level: 'debug',
-                 progname: nil, formatter: nil, datetime_format: nil,
-                 binmode: false, shift_period_suffix: '%Y%m%d')
-    logdev_lambda_override = logdev
-    formatter_override = formatter
-    # use unpatched constructor if logdev is a filename or an IO Object other than $stdout or $stderr
+  LOG_LEVEL_MAP = {
+    'TRACE' => Logger::DEBUG,
+    'DEBUG' => Logger::DEBUG,
+    'INFO' => Logger::INFO,
+    'WARN' => Logger::WARN,
+    'ERROR' => Logger::ERROR,
+    'FATAL' => Logger::FATAL
+  }.freeze
+
+  class << self
+    attr_reader :aws_lambda_log_format, :aws_lambda_log_level
+
+    def refresh_runtime_config!
+      @aws_lambda_log_format = ENV.fetch('AWS_LAMBDA_LOG_FORMAT', '').upcase
+      env_level = ENV.fetch('AWS_LAMBDA_LOG_LEVEL', nil)
+      @aws_lambda_log_level = LOG_LEVEL_MAP[env_level&.upcase]
+    end
+
+    def json_format?
+      @aws_lambda_log_format == 'JSON'
+    end
+  end
+
+  refresh_runtime_config!
+
+  # shift_size default to 1 megabyte, matching Ruby Logger's default log rotation size.
+  def initialize(logdev, shift_age = 0, shift_size = 1_048_576, **kwargs)
+    level_was_provided = kwargs.key?(:level)
+    kwargs = {
+      level: Logger::DEBUG,
+      progname: nil,
+      formatter: nil,
+      datetime_format: nil,
+      binmode: false,
+      shift_period_suffix: '%Y%m%d'
+    }.merge(kwargs)
+
+    logdev_override = logdev
+
     if !logdev || logdev == $stdout || logdev == $stderr
-      logdev_lambda_override = AwsLambdaRIC::TelemetryLogger.telemetry_log_sink
-      formatter_override = formatter_override || LogFormatter.new
+      telemetry_sink = AwsLambdaRIC::TelemetryLogger.telemetry_log_sink
+      logdev_override = telemetry_sink || logdev
+      kwargs[:formatter] ||= LoggerPatch.json_format? ? JsonLogFormatter.new : LogFormatter.new
+      kwargs[:level] = LoggerPatch.aws_lambda_log_level if !level_was_provided && LoggerPatch.aws_lambda_log_level
     end
 
-    super(logdev_lambda_override, shift_age, shift_size, level: level, progname: progname,
-                                    formatter: formatter_override, datetime_format: datetime_format,
-                                    binmode: binmode, shift_period_suffix: shift_period_suffix)
+    super(logdev_override, shift_age, shift_size, **kwargs)
   end
 end

data/lib/aws_lambda_ric/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AwsLambdaRIC
-  VERSION = '3.1.3'
+  VERSION = '3.2.0'
 end

data/lib/aws_lambda_ric.rb

@@ -131,10 +131,19 @@ module AwsLambdaRIC
     ENV_VAR_TELEMETRY_LOG_FD = '_LAMBDA_TELEMETRY_LOG_FD'
 
     class << self
-      attr_accessor :telemetry_log_fd_file, :telemetry_log_sink
-
+      attr_accessor :telemetry_log_fd_file, :telemetry_log_sink, :logger_patch_applied
       def close
         telemetry_log_fd_file&.close
+        self.telemetry_log_fd_file = nil
+      end
+
+      def mutate_std_logger
+        return if logger_patch_applied
+
+        Logger.class_eval do
+          prepend LoggerPatch
+        end
+        self.logger_patch_applied = true
       end
     end
 
@@ -145,28 +154,28 @@ module AwsLambdaRIC
 
       AwsLambdaRIC::TelemetryLogger.telemetry_log_sink = TelemetryLogSink.new(file: AwsLambdaRIC::TelemetryLogger.telemetry_log_fd_file)
 
-      mutate_std_logger
       mutate_kernel_puts
+
     rescue Errno::ENOENT, Errno::EBADF
-      # If File.open() fails, then the mutation won't happen and the default behaviour (print to stdout) will prevail
+      AwsLambdaRIC::TelemetryLogger.telemetry_log_fd_file = nil
+      AwsLambdaRIC::TelemetryLogger.telemetry_log_sink = nil
     end
 
     def self.from_env()
-      if ENV.key?(ENV_VAR_TELEMETRY_LOG_FD)
-        fd = ENV.fetch(AwsLambdaRIC::TelemetryLogger::ENV_VAR_TELEMETRY_LOG_FD)
-        ENV.delete(AwsLambdaRIC::TelemetryLogger::ENV_VAR_TELEMETRY_LOG_FD)
-        AwsLambdaRIC::TelemetryLogger.new(fd)
-      end
-    end
 
-    private
+      LoggerPatch.refresh_runtime_config!
+      mutate_std_logger
+      AwsLambdaRIC::TelemetryLogger.telemetry_log_sink = nil
 
-    def mutate_std_logger
-      Logger.class_eval do
-        prepend LoggerPatch
-      end
+      return unless ENV.key?(ENV_VAR_TELEMETRY_LOG_FD)
+
+      fd = ENV.fetch(AwsLambdaRIC::TelemetryLogger::ENV_VAR_TELEMETRY_LOG_FD)
+      ENV.delete(AwsLambdaRIC::TelemetryLogger::ENV_VAR_TELEMETRY_LOG_FD)
+      AwsLambdaRIC::TelemetryLogger.new(fd)
     end
 
+    private
+
     def mutate_kernel_puts
       Kernel.module_eval do
         def puts(*arg)
@@ -180,7 +189,6 @@ module AwsLambdaRIC
       end
     end
   end
-
   # Represents a single Lambda Invocation Request
   class LambdaInvocationRequest
 

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: aws_lambda_ric
 version: !ruby/object:Gem::Version
-  version: 3.1.3
+  version: 3.2.0
 platform: ruby
 authors:
 - AWS Lambda
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-03 00:00:00.000000000 Z
+date: 2026-04-15 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement