cgi-core
v0.9.33
Published
Minimalistic, zero-dependency wrapper for hosting CGI scripts with HTTP/1.1 support
Downloads
980
Readme
cgi-core
A minimalistic, zero-dependency wrapper for hosting CGI scripts with HTTP/1.1 support. Released under the MIT License.
Getting Started
Install the latest stable version of cgi-core:
npm install cgi-coreThen, start a CGI server:
npx cgi-server --filePath ./cgi-binBasic Usage
Here’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.
Configuration options
urlPath
Base url for routing. Default: '/cgi-bin'
filePath
File path where the CGI scripts are located. It is strongly advised to set a value for filePath (example: './cgi-bin'). Default: process.cwd()
extensions
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"]
}indexExtension
File extension to lookup for an index CGI script in any given directory. Default: 'js'
debugOutput
Set true to enable debug output. Default: false
logRequests
Set true to print HTTP request logs to STDOUT. Default: false
maxBuffer
Size of the allowed HTTP request and response payloads in bytes. Default: 2 * 1024 * 1024 (2 MB)
requestChunkSize
Size of the HTTP request payload data chunks in bytes. Default: 16 * 1024 (16 KB)
responseChunkSize
Size of the HTTP response payload data chunks in bytes. Default: 16 * 1024 (16 KB)
statusPages
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"
}
}env
Object containing custom environment variables to pass to the CGI scripts. Default: {}
// Example:
{
SERVER_ADMIN: "[email protected]",
ANOTHER_VAR: "another value"
}Start a CGI Server from the Command Line
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-binAvailable arguments
-h, --help Display help
--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
-d, --debugOutput Output errors for HTTP status 500
-l, --logRequests Log HTTP requests to STDOUT
-p, --port <port> Set the port to listen onSupported CGI environment variables
In addition to the standard HTTP-related variables, the following CGI environment variables are supported:
CONTENT_LENGTH
CONTENT_TYPE
PATH
PATH_INFO
SCRIPT_FILENAME
SCRIPT_NAME
SERVER_PROTOCOL
SERVER_SOFTWARE
QUERY_STRING
REQUEST_METHOD
REQUEST_URILicense
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.