{"id":13527349,"url":"https://github.com/aws/aws-lambda-nodejs-runtime-interface-client","last_synced_at":"2025-05-15T03:08:13.655Z","repository":{"id":41474263,"uuid":"291796346","full_name":"aws/aws-lambda-nodejs-runtime-interface-client","owner":"aws","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-01T11:54:04.000Z","size":38734,"stargazers_count":208,"open_issues_count":39,"forks_count":60,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-08T00:07:58.343Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-31T18:41:31.000Z","updated_at":"2025-05-01T11:29:54.000Z","dependencies_parsed_at":"2023-09-27T14:59:35.482Z","dependency_job_id":"b7cb0bb4-9a36-4afa-90b6-9f58ef8143ec","html_url":"https://github.com/aws/aws-lambda-nodejs-runtime-interface-client","commit_stats":{"total_commits":49,"total_committers":19,"mean_commits":"2.5789473684210527","dds":0.5918367346938775,"last_synced_commit":"db6a30da32934bcde91da248db30b60b17b891c4"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-lambda-nodejs-runtime-interface-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-lambda-nodejs-runtime-interface-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-lambda-nodejs-runtime-interface-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-lambda-nodejs-runtime-interface-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/aws-lambda-nodejs-runtime-interface-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254150659,"owners_count":22023009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:46.243Z","updated_at":"2025-05-15T03:08:08.636Z","avatar_url":"https://github.com/aws.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","TypeScript"],"sub_categories":[],"readme":"## AWS Lambda NodeJS Runtime Interface Client\n\nWe have open-sourced a set of software packages, Runtime Interface Clients (RIC), that implement the Lambda\n [Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html), allowing you to seamlessly extend your preferred\n  base images to be Lambda compatible.\nThe Lambda Runtime Interface Client is a lightweight interface that allows your runtime to receive requests from and send requests to the Lambda service.\n\nThe Lambda NodeJS Runtime Interface Client is vended through [npm](https://www.npmjs.com/package/aws-lambda-ric). \nYou can include this package in your preferred base image to make that base image Lambda compatible.\n\n## Requirements\nThe NodeJS Runtime Interface Client package currently supports NodeJS versions:\n - 16.x\n - 18.x\n - 20.x\n\n## Usage\n\n### Creating a Docker Image for Lambda with the Runtime Interface Client\nFirst step is to choose the base image to be used. The supported Linux OS distributions are:\n\n - Amazon Linux (2 and 2023)\n - Alpine\n - CentOS\n - Debian\n - Ubuntu\n\nThe Runtime Interface Client can be installed outside of the Dockerfile as a dependency of the function we want to run in Lambda (run the below command in your function directory to add the dependency to `package.json`):\n```shell script\nnpm install aws-lambda-ric --save\n```\nor inside the Dockerfile:\n```dockerfile\nRUN npm install aws-lambda-ric\n```\n\nNext step would be to copy your Lambda function code into the image's working directory.\n```dockerfile\n# Copy function code\nRUN mkdir -p ${FUNCTION_DIR}\nCOPY myFunction/* ${FUNCTION_DIR}\n\nWORKDIR ${FUNCTION_DIR}\n\n# If the dependency is not in package.json uncomment the following line\n# RUN npm install aws-lambda-ric\n\nRUN npm install\n```\n\nThe next step would be 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.\n\nExample Dockerfile (to keep the image light we used a multi-stage build):\n```dockerfile\n# Define custom function directory\nARG FUNCTION_DIR=\"/function\"\n\nFROM node:18-buster as build-image\n\n# Include global arg in this stage of the build\nARG FUNCTION_DIR\n\n# Install aws-lambda-cpp build dependencies\nRUN apt-get update \u0026\u0026 \\\n    apt-get install -y \\\n    g++ \\\n    make \\\n    cmake \\\n    unzip \\\n    libcurl4-openssl-dev\n\n# Copy function code\nRUN mkdir -p ${FUNCTION_DIR}\nCOPY myFunction/* ${FUNCTION_DIR}\n\nWORKDIR ${FUNCTION_DIR}\n\nRUN npm install\n\n# If the dependency is not in package.json uncomment the following line\n# RUN npm install aws-lambda-ric\n\n# Grab a fresh slim copy of the image to reduce the final size\nFROM node:18-buster-slim\n\n# Required for Node runtimes which use npm@8.6.0+ because\n# by default npm writes logs under /home/.npm and Lambda fs is read-only\nENV NPM_CONFIG_CACHE=/tmp/.npm\n\n# Include global arg in this stage of the build\nARG FUNCTION_DIR\n\n# Set working directory to function root directory\nWORKDIR ${FUNCTION_DIR}\n\n# Copy in the built dependencies\nCOPY --from=build-image ${FUNCTION_DIR} ${FUNCTION_DIR}\n\nENTRYPOINT [\"/usr/local/bin/npx\", \"aws-lambda-ric\"]\nCMD [\"app.handler\"]\n```\n\nExample NodeJS handler `app.js`:\n```js\n\"use strict\";\n\nexports.handler = async (event, context) =\u003e {\n    return 'Hello World!';\n}\n```\n\n### Local Testing\n\nTo make it easy to locally test Lambda functions packaged as container images we open-sourced a lightweight web-server, Lambda Runtime Interface Emulator (RIE), which allows your function packaged as a container image to accept HTTP requests. You can install the [AWS Lambda Runtime Interface Emulator](https://github.com/aws/aws-lambda-runtime-interface-emulator) on your local machine to test your function. Then when you run the image function, you set the entrypoint to be the emulator. \n\n*To install the emulator and test your Lambda function*\n\n1) From your project directory, run the following command to download the RIE from GitHub and install it on your local machine. \n\n```shell script\nmkdir -p ~/.aws-lambda-rie \u0026\u0026 \\\n    curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie \u0026\u0026 \\\n    chmod +x ~/.aws-lambda-rie/aws-lambda-rie\n```\n2) Run your Lambda image function using the docker run command. \n\n```shell script\ndocker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \\\n    --entrypoint /aws-lambda/aws-lambda-rie \\\n    myfunction:latest \\\n        /usr/local/bin/npx aws-lambda-ric app.handler\n```\n\nThis runs the image as a container and starts up an endpoint locally at `http://localhost:9000/2015-03-31/functions/function/invocations`. \n\n3) Post an event to the following endpoint using a curl command: \n\n```shell script\ncurl -XPOST \"http://localhost:9000/2015-03-31/functions/function/invocations\" -d '{}'\n```\n\nThis command invokes the function running in the container image and returns a response.\n\n*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).*\n\n\n## Development\n\n### Building the package\nClone this repository and run:\n\n```shell script\nmake init\nmake build\n```\n\n### Running tests\n\nMake sure the project is built:\n```shell script\nmake init build\n```\nThen,\n* to run unit tests: `make test`\n* to run integration tests: `make test-integ`\n* to run smoke tests: `make test-smoke`\n\n### Raising a PR\nWhen modifying dependencies (`package.json`), make sure to:\n1. Run `npm install` to generate an updated `package-lock.json`\n2. Commit both `package.json` and `package-lock.json` together\n\nWe require package-lock.json to be checked in to ensure consistent installations across development environments.\n\n### Troubleshooting\n\nWhile running integration tests, you might encounter the Docker Hub rate limit error with the following body:\n```\nYou have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits\n```\nTo fix the above issue, consider authenticating to a Docker Hub account by setting the Docker Hub credentials as below CodeBuild environment variables.\n```shell script\nDOCKERHUB_USERNAME=\u003cdockerhub username\u003e\nDOCKERHUB_PASSWORD=\u003cdockerhub password\u003e\n```\nRecommended way is to set the Docker Hub credentials in CodeBuild job by retrieving them from AWS Secrets Manager.\n## Security\n\nIf you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-lambda-nodejs-runtime-interface-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Faws-lambda-nodejs-runtime-interface-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-lambda-nodejs-runtime-interface-client/lists"}