node cgi core

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-core

Then, start a CGI server:

npx cgi-server --filePath ./cgi-bin

Basic 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-binconst 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: `                404: File not found              `,contentType: "text/html"
  },
  500: {content: `                500: Internal server error              `,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-bin

Available arguments

  -h, --help                    Display help
  --urlPath            Set base url path for routing
  --filePath          Set file path where the CGI scripts are located
  --indexExtension   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              Set the port to listen on

Supported 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_URI

License

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.