Common HTTP/HTTPS/SPDY Server API

Common errors

• Error: listen EADDRINUSE: address already in use :::3000

  cause The specified port (e.g., 3000) is already being used by another process on the system.
  fix Change the `port` configuration to an available port number, or terminate the process currently using that port.

• Error: Cannot find module 'spdy'

  cause The `spdy` option was set to `true` to create an SPDY server, but the `spdy` package itself was not installed as a dependency.
  fix Install the `spdy` package: `npm install spdy` or remove the `spdy: true` option if SPDY is not intended.

• Error: ENOENT: no such file or directory, open '/path/to/server.key'

  cause The server failed to locate or read one of the specified certificate or key files (e.g., `key`, `cert`, `ca`, `pfx`, `crl`). This often happens with incorrect `root` paths or file permissions.
  fix Verify that the `root` option points to the correct base directory and that all certificate/key file paths (relative or absolute) are accurate. Ensure the Node.js process has read permissions for these files.

Warnings

• breaking The SPDY protocol, a key feature of this library, has been largely deprecated in favor of HTTP/2 and HTTP/3. Relying on SPDY functionality will result in compatibility issues with modern clients and proxies.
  Fix: Migrate to servers supporting HTTP/2 or HTTP/3, such as Node.js's built-in `http2` module or newer web frameworks, rather than relying on SPDY.
• gotcha The 'sane defaults' for secure server configuration mentioned in the README address older vulnerabilities like POODLE and Heartbleed. These defaults may be outdated and insufficient to protect against modern security threats. Custom cipher lists (`cypher`), `secureProtocol`, and `secureOptions` should be thoroughly reviewed.
  Fix: Manually audit and update TLS cipher suites, protocols, and options to align with current best practices for server security (e.g., using TLS 1.3, strong ciphers).
• gotcha The package uses CommonJS `require()` syntax exclusively in its documentation and examples. It is unlikely to have native ES module (ESM) support, which can cause issues in modern Node.js projects configured for ESM.
  Fix: Ensure your project is configured for CommonJS, or use dynamic `import()` if absolutely necessary within an ESM context, understanding the interoperability limitations.
• gotcha When configuring HTTPS or SPDY servers, certificate paths (`key`, `cert`, `ca`, `pfx`, `crl`) are specified relative to the `root` option. Incorrect `root` paths or malformed relative paths can lead to server startup failures.
  Fix: Always provide absolute paths for certificate files or carefully verify the `root` directory and relative paths. Ensure files are readable by the Node.js process.

Install

• npm install create-server npm
• yarn add create-server yarn
• pnpm add create-server pnpm

Imports

• create
  wrong:

  import create from 'create-server';

  correct:

  const create = require('create-server');

  This package primarily uses CommonJS `require()`. While Node.js might attempt to load it with `import`, it is not designed for native ESM use.
• createServer
  wrong:

  import { createServer } from 'create-server';

  correct:

  const create = require('create-server');
  // Then use `create` function

  The module exports a single function as its default, not named exports. The variable name `create` is a convention used in the documentation.

Quickstart

Demonstrates creating a basic HTTP server using `create-server` on port 3000, handling incoming requests, and logging server events. Includes graceful shutdown.

const create = require('create-server');
const http = require('http'); // Node.js built-in HTTP module

const server = create({
    port: process.env.PORT || 3000,
    hostname: '127.0.0.1',
    // Optional: redirect HTTP to HTTPS
    // redirect: 80,
    // For HTTPS/SPDY, you'd add 'key', 'cert', 'ca', 'spdy: true' options
}, {
    request: function (req, res) {
        console.log(`Received request for: ${req.url}`);
        res.writeHead(200, { 'Content-Type': 'text/plain' });
        res.end('Hello from create-server!\n');
    },
    listening: function (err) {
        if (err) {
            console.error('Server failed to start:', err);
            return;
        }
        console.log(`Server listening on http://${server.hostname}:${server.port}`);
    },
    error: function (err) {
        console.error('Server error:', err);
    }
});

// To stop the server gracefully
process.on('SIGINT', () => {
    console.log('Stopping server...');
    server.close(() => {
        console.log('Server stopped.');
        process.exit(0);
    });
});