server.js

#!/usr/bin/env node

/**
 * lambda-edge-server
 * AWS CloudFront Lambda@Edge handler function emulator.
 *
 * Copyright 2023-2025, Marc S. Brooks (https://mbrooks.info)
 * Licensed under the MIT license:
 * http://www.opensource.org/licenses/mit-license.php
 */

'use strict';

const {Command} = require('commander');
const fs = require('fs');
const http = require('http');
const url = require('url');

const SERVER_PORT = 3000;

// Process CLI options.
const program = new Command();

program
 .usage('[options]')

 .option('--handler <path>', 'Lambda@Edge handler script.')
 .option('--port <number>', 'HTTP server port number.', SERVER_PORT)
 .option('--silent', 'Disable logging Router events to STDOUT', false)

 .action(function(opts) {
 const errors = [];

 try {
 const script = process.cwd() + '/' + opts.handler;

 // Validate option values.
 if (opts.handler && !fs.existsSync(script) || !opts.handler) {
 errors.push(" option '--handler <path>' allows path Lambda@Edge handler script");
 }

 if (opts.port && !/^[0-9]{2,5}$/.test(opts.port)) {
 errors.push(" option '--port <number>' allows up to 5 numeric characters");
 }

 if (errors.length) {
 console.error('error: Invalid script arguments');

 throw new Error(errors.join('\n'));
 }

 const {handler} = require(script);

 if (isValidFunc(handler)) {
 return initServer(handler, opts.port, !opts.silent);
 }

 throw new Error('error: Invalid handler method');

 } catch (err) {
 if (err instanceof Error) {
 console.error(`${err.message}\n`);
 }

 this.outputHelp();
 }
 });

// Skip Commander options during testing.
if (process.env.NODE_ENV === 'test') {
 const {handler} = require(process.env.TEST_HANDLER);

 module.exports = initServer(handler, SERVER_PORT);
} else {
 program.parse();
}

/**
 * Init Lambda@Edge emulator environment.
 *
 * @param {Function} handler
 * Lambda function method.
 *
 * @param {Function} port
 * HTTP server port number.
 *
 * @param {Boolean} logRouterEvents
 * Log Router events to STDOUT (default: true).
 *
 * @return {Object}
 *
 * @see https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html
 */
function initServer(handler, port, logRouterEvents = true) {
 const server = http.createServer(function(req, res) {
 let body = '';

 req.on('data', function(data) {
 body += data;
 });

 req.on('end', function() {
 const path = url.parse(req.url).pathname;
 const query = url.parse(req.url).query;

 if (body) {
 body = encodeBody(body);
 }

 // Simulate AWS origin-request event.
 const event = {
 Records: [
 {
 cf: {
 request: {
 clientIp: res.socket?.remoteAddress,
 headers: formatHeaders(req.headers).toEdge(),
 method: req.method,
 querystring: query,
 uri: path,
 body: {
 data: body
 }
 }
 }
 }
 ]
 };

 // .. and callback() application handler.
 const callback = function(request, response) {
 let {body, bodyEncoding, headers, status} = response;

 if (headers) {
 headers = formatHeaders(response.headers).toNode();
 headers.map(header => res.setHeader(header.key, header.value));
 }

 // Override Edge required media encoding.
 if (bodyEncoding === 'base64') {
 body = Buffer.from(body, 'base64');
 }

 if (status) {
 res.statusCode = status;
 }

 res.end(body);
 };

 try {

 // Run lambda-lambda-lambda
 if (isAsyncFunc(handler) || isPromise(handler)) {

 // Asynchronous handling.
 handler(event)
 .then(function(response) {
 callback(null, response);
 });
 } else {

 // Synchronous handling.
 handler(event, null, callback);
 }

 logRouterEvents && console.log(Date.now(), req.method, path, JSON.stringify(event));

 } catch (err) {
 logRouterEvents && this.emit('error', err);
 }
 });
 });

 // Start HTTP server; increment port if used.
 return server
 .listen(port, () => {
 console.info(`HTTP server started. Listening on port ${port}`);
 })
 .on('error', function(err) {
 if (err.code === 'EADDRINUSE') {
 this.close();

 console.error(`Port ${port} in use. Trying another port.`);

 initServer(handler, port + 1);
 }
 });
}

/**
 * Return base64 encoded body as string.
 *
 * @param {String} str
 * Body data as string.
 *
 * @return {String}
 */
function encodeBody(str) {
 return Buffer.from(str).toString('base64');
}

/**
 * Return converted headers (lambda/node).
 *
 * @param {Object} obj
 * Node request headers object.
 *
 * @return {Object}
 */
function formatHeaders(obj) {
 return {

 // Request format.
 toEdge: function() {
 Object.keys(obj).forEach(function(key) {
 obj[key] = [{
 key,
 value: obj[key]
 }];
 });
 return obj;
 },

 // Response format.
 toNode: function() {
 return Object.keys(obj).map(function(key) {
 return {
 key,
 value: obj[key][0].value
 };
 });
 }
 };
}

/**
 * Check if value is an async function.
 *
 * @param {AsyncFunction} func
 * Async function.
 *
 * @return {Boolean}
 */
function isAsyncFunc(value) {
 return (value && (value[Symbol.toStringTag] === 'AsyncFunction'));
}

/**
 * Check if object is Promise.
 *
 * @param {Object} obj
 * Promise object.
 *
 * @return {Boolean}
 */
function isPromise(obj) {
 return (obj && (obj[Symbol.toStringTag] === 'Promise' || typeof obj.then === 'function'));
}

/**
 * Check if valid handler function.
 *
 * @param {Function} value
 * Handler function.
 *
 * @return {Boolean}
 */
function isValidFunc(value) {
 return (typeof value === 'function' && value.length >= 1 && value.length <= 3);
}