A minimalistic, zero-dependency wrapper for hosting CGI scripts with HTTP/1.1 support.
Released under the MIT License.
Install the latest stable version of cgi-core:
npm install cgi-coreThen, start a CGI server:
npx cgi-server --filePath ./cgi-binHere’s an example of how to set up a CGI server with cgi-core:
import { createServer } from "node:http";
import { createHandler } from "cgi-core";
// create a http server that handles CGI requests under the url path /cgi-bin
const handler = createHandler({
urlPath: "/cgi-bin",
filePath: "./cgi-bin",
extensions: {
"/usr/bin/perl": ["pl", "cgi"],
"/usr/bin/python": ["py"],
"/usr/local/bin/node": ["js", "node"],
},
debugOutput: false,
});
const app = createServer(async (req, res) => {
const requestHandled = await handler(req, res);
if (!requestHandled) {
// here, handle any routing outside of urlPath === '/cgi-bin'
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("outside of urlPath");
}
});
app.listen(3000);Usage example using Express.
Base url for routing. Default: '/cgi-bin'
File path where the CGI scripts are located. It is strongly advised to set a value for filePath (example: './cgi-bin'). Default: process.cwd()
Object containing file extension values for given interpreter paths. If no interpreter path is found for a file extension, the CGI script will be called as a standalone executable. Default:
// on POSIX systems
{
"/usr/bin/perl": ["pl", "cgi"],
"/usr/bin/python": ["py"],
"/usr/local/bin/node": ["js", "node"]
}
// on Windows systems
{
"perl": ["pl", "cgi"],
"python": ["py"],
"node": ["js", "node"]
}File extension to lookup for an index CGI script in any given directory. Default: 'js'
Set true to enable debug output. Default: false
Set true to print HTTP request logs to STDOUT. Default: false
Size of the allowed HTTP request and response payloads in bytes. Default: 2 * 1024 * 1024 (2 MB)
Size of the HTTP request payload data chunks in bytes, used for internal buffering when reading request data. Default: 32 * 1024 (32 KB)
Size of the HTTP response payload data chunks in bytes, applicable when Transfer-Encoding: chunked is used. If Content-Length is set, chunking is disabled, and the response is sent as a single block. Default: 32 * 1024 (32 KB)
Timeout delay for the HTTP request in milliseconds. If the request takes longer than the specified time, the server will respond with a 504 Gateway Timeout error. Default: 30000 (30 seconds)
Object containing custom HTTP response payloads per status code. Default: {}
// Example:
{
404: {
content: `<html>
<body>404: File not found</body>
</html>`,
contentType: "text/html"
},
500: {
content: `<html>
<body>500: Internal server error</body>
</html>`,
contentType: "text/html"
}
}Object containing custom environment variables to pass to the CGI scripts. Default: {}
// Example:
{
SERVER_ADMIN: "admin@example.com",
ANOTHER_VAR: "another value"
}An updater function can also be passed to the env option to update the environment variables on each request. It gets the environment variables object and the incoming HTTP request as arguments.
// Example:
(env, req) => {
return {
SERVER_ADMIN: "admin@example.com",
ANOTHER_VAR: "another value",
VALUE_FROM_REQUEST: req.headers["x-custom-header"],
};
}The command cgi-server can be used to run an HTTP server to serve CGI scripts.
npx cgi-server --port 3001 --urlPath /cgi-bin --filePath ./cgi-bin -h, --help Display help
-v, --version Display cgi-core version string
--urlPath <urlPath> Set base url path for routing
--filePath <filePath> Set file path where the CGI scripts are located
--indexExtension <extension> Set file extension to lookup for index files
--maxBuffer <bytes> Set the allowed HTTP request and response payloads size in bytes
--requestChunkSize <bytes> Set the HTTP request payload data chunks size in bytes
--responseChunkSize <bytes> Set the HTTP response payload data chunks size in bytes
--requestTimeout <ms> Set the HTTP request timeout delay in milliseconds
-d, --debugOutput Output errors for HTTP status 500
-l, --logRequests Log HTTP requests to STDOUT
-p, --port <port> Set the port to listen on
In addition to the standard HTTP-related variables, the following CGI environment variables are supported:
CONTENT_LENGTH
CONTENT_TYPE
PATH
PATH_INFO
QUERY_STRING
REMOTE_ADDR
REQUEST_METHOD
REQUEST_URI
SCRIPT_FILENAME
SCRIPT_NAME
SERVER_PROTOCOL
SERVER_SOFTWARE
cgi-core is released under the MIT License.
100% Free: cgi-core can be used freely in both proprietary and open-source projects.
Attribution is required: You must retain the author's name and the license information in any distributed code. These items do not need to be user-facing and can remain within the codebase.