_HANDLER gets overwritten by blank string on execution by Lambda

[waynerobinson]

Issue

When using aws_lambda_ric with cdk initialization fails because the _HANDLER environment variable appears to be reserved by Lambda and it's being overwritten by a blank string (not set to nil, so not failing on that check).

I've created an example project demonstrating this at https://github.com/waynerobinson/lambda-ric-cdk-handler-issue-example

Our current project patches aws_lambda_ric to rename _HANDLER to _RIC_HANDLER in aws_lambda_ric.rb, which appears to be working OK, but unsure as to whether that's the best way to fix this in this core library.

Environment

Ruby: 3.2.9
Node: 24.11.1
CDK: 2.1031.2

Reproduction Steps

git checkout https://github.com/waynerobinson/lambda-ric-cdk-handler-issue-example
cd lambda-ric-cdk-handler-issue-example
npm install
cdk deploy
aws lambda invoke --function-name lambda-ric-cdk-issue-test /dev/stdout

Backtrace

{
  "errorMessage": "Invalid handler [], must be of form FILENAME.METHOD or FILENAME.CLASS.METHOD where FILENAME corresponds with an existing Ruby source file FILENAME.rb, CLASS is an optional module/class namespace and METHOD is a callable method. If using CLASS, METHOD must be a class-level method.",
  "errorType": "Init<ArgumentError>",
  "stackTrace": [
    "/usr/local/share/ruby3.2-gems/gems/aws_lambda_ric-3.1.3/lib/aws_lambda_ric/lambda_handler.rb:16:in `initialize'",
    "/usr/local/share/ruby3.2-gems/gems/aws_lambda_ric-3.1.3/lib/aws_lambda_ric.rb:45:in `new'",
    "/usr/local/share/ruby3.2-gems/gems/aws_lambda_ric-3.1.3/lib/aws_lambda_ric.rb:45:in `run'",
    "/usr/local/share/ruby3.2-gems/gems/aws_lambda_ric-3.1.3/lib/aws_lambda_ric.rb:219:in `bootstrap_handler'",
    "/usr/local/share/ruby3.2-gems/gems/aws_lambda_ric-3.1.3/lib/aws_lambda_ric.rb:201:in `start'",
    "/usr/local/share/ruby3.2-gems/gems/aws_lambda_ric-3.1.3/bin/aws_lambda_ric:9:in `<top (required)>'",
    "/usr/local/bin/aws_lambda_ric:25:in `load'",
    "/usr/local/bin/aws_lambda_ric:25:in `<main>'"
  ]
}

[waynerobinson]

I just did a quick code search of this project too and it appears there are no tests for the using the _HANDLER environment variable. Any integration tests use the older argument-passed option for the handler in the CMD portion of the various Dockerfiles.

f606a7b introduces the _HANDLER environment variable but does nothing to test it.

Also, none of the tests actually seem to test this with Lambda itself (which I suspect is what's overwriting the _HANDLER environment variable as per Defined Runtime Environment Variables.

[waynerobinson]

On further investigation, it appears the correct way to use this library is to actually put the handler in the CMD like the below.

The real Lambda environment will take that CMD value and inject it into the _HANDLER environment variable. You can't specify this ENV directly in the Dockerfile as Lambda will overwrite it with a blank string.

Dockerfile

FROM amazonlinux:latest

# Define custom function directory
ARG FUNCTION_DIR="/function"

# Install ruby
RUN dnf install -y ruby3.2 make

# Install bundler
RUN gem install bundler

# Install the Runtime Interface Client
RUN gem install aws_lambda_ric

# Copy function code
RUN mkdir -p ${FUNCTION_DIR}
COPY app.rb ${FUNCTION_DIR}

WORKDIR ${FUNCTION_DIR}

ENTRYPOINT ["/usr/local/bin/aws_lambda_ric"]

# Attempt to pass handler via command-line
CMD ["app.App::Handler.process"]