Node.js CGI Middleware

1.0.0 verified Thu Apr 23 auth: no javascript abandoned

gateway is a Node.js middleware designed to facilitate the execution of CGI scripts, such as PHP files, within a Node.js HTTP server environment. It was initially developed around 2012 to support development tools like Yeoman and Livestyle in serving dynamic content. The package's current stable version is 1.0.0, released over a decade ago, indicating it is no longer actively maintained. Unlike `node-cgi`, `gateway` focuses on serving individual script files rather than `cgi-bin` directories, requiring the corresponding CGI binary (e.g., `php-cgi`) to be installed and accessible in the system's PATH. This approach allows Node.js applications to integrate with existing CGI-based applications but comes with the inherent security and maintenance implications of executing external processes.

Common errors

error Error: spawn <cgi-binary-name> ENOENT ↓

cause The specified CGI executable (e.g., `php-cgi`) cannot be found in the system's PATH.

fix

Install the required CGI binary and ensure its installation directory is correctly added to your system's PATH environment variable.

error PHP script content displayed as plain text in the browser. ↓

cause `gateway` is serving the PHP file content directly instead of executing it, likely due to a misconfiguration in the file extension mapping or the `php-cgi` binary not functioning.

fix

Verify that the gateway options correctly map the file extension (e.g., '.php': 'php-cgi') and confirm that the CGI binary (e.g., php-cgi) is installed and can execute the script from the command line.

error TypeError: gateway is not a function ↓

cause Attempting to import the CommonJS `gateway` module using an ESM `import` statement in an ESM context, leading to an incorrect module resolution.

fix

Use the CommonJS require syntax: const gateway = require('gateway');.

Warnings

breaking This package is considered abandoned and has not been updated in over 10 years. It is highly susceptible to unpatched security vulnerabilities, especially when executing external CGI scripts. Use in production or with untrusted input is strongly discouraged. ↓

fix Migrate to actively maintained alternatives or use more secure methods for serving dynamic content. If absolutely necessary, thoroughly audit any external scripts executed.

gotcha `gateway` explicitly does not support `cgi-bin` directories for script execution. Its design focuses on serving individual script files based on file extension mapping. ↓

fix If `cgi-bin` functionality is required, consider using alternative packages like `node-cgi` or setting up a dedicated web server (e.g., Nginx, Apache) to handle `cgi-bin`.

gotcha The middleware requires external CGI executables (e.g., `php-cgi`) to be pre-installed on the system and accessible in the system's PATH environment variable. Failure to do so will prevent scripts from executing correctly. ↓

fix Install the necessary CGI binaries for your scripting language (e.g., `brew install php@XX` for PHP on macOS) and ensure their location is included in your system's PATH.

gotcha When a URL points to a valid directory but does not end with a trailing slash, `gateway` will issue a permanent (301) redirect to append the slash. This behavior may impact routing or caching strategies. ↓

fix Be aware of this redirect behavior in your application's routing. Ensure client requests for directories include a trailing slash if redirects are undesired.

gotcha This package is a CommonJS module and does not natively support ES Modules (ESM) `import` syntax. It also does not ship with TypeScript type definitions. ↓

fix Always use `const gateway = require('gateway');` for importing. For TypeScript projects, you may need to create a custom declaration file (`.d.ts`) if type safety is desired.

Install

npm install gateway

yarn add gateway

pnpm add gateway

Imports

gateway
wrong
```
import gateway from 'gateway';
```
correct
```
const gateway = require('gateway');
```
This package is a CommonJS module and must be imported using `require()`. It does not support native ESM `import` statements, nor does it provide TypeScript type definitions.

Quickstart

This example sets up a basic Node.js HTTP server using `gateway` to serve a dynamically created `info.php` file, demonstrating how to execute PHP scripts through `php-cgi`.

const http = require('http');
const gateway = require('gateway');
const path = require('path');
const fs = require('fs');

// Create a temporary directory and a PHP file for demonstration
const tempDir = path.join(__dirname, 'temp_gateway_test');
if (!fs.existsSync(tempDir)) {
  fs.mkdirSync(tempDir);
}
const phpFilePath = path.join(tempDir, 'info.php');
fs.writeFileSync(phpFilePath, `<?php phpinfo(); ?>`);

console.log('Created temporary PHP file at:', phpFilePath);
console.log('Ensure php-cgi is installed and in your PATH for this example to work.');

const server = http.createServer(gateway(tempDir, {
  '.php': 'php-cgi'
}));

const PORT = 3000;
server.listen(PORT, () => {
  console.log(`Gateway server listening on http://localhost:${PORT}`);
  console.log(`Try visiting http://localhost:${PORT}/info.php`);
  console.log(`Press Ctrl+C to stop the server and clean up.`);
});

// Basic cleanup on exit
process.on('SIGINT', () => {
  console.log('\nShutting down server...');
  server.close(() => {
    if (fs.existsSync(phpFilePath)) {
      fs.unlinkSync(phpFilePath);
    }
    if (fs.existsSync(tempDir)) {
      fs.rmdirSync(tempDir);
    }
    console.log('Cleaned up temporary files. Server stopped.');
    process.exit(0);
  });
});