Tomahawk HTTP Server

Common errors

• Error: Cannot find module 'tomahawk'

  cause The 'tomahawk' package is not installed or the Node.js runtime cannot locate it.
  fix Run `npm install tomahawk` or `npm install -g tomahawk` if using it as a global CLI tool.

• TypeError: app.get is not a function

  cause Attempting to call an HTTP method (like `get`) on the `tomahawk` module directly instead of on the server instance returned by `tomahawk.create().`
  fix Ensure you call HTTP methods on the `app` instance created by `tomahawk.create()`. Example: `const app = require('tomahawk').create({port:8080, routes: [...]}).start(); app.get(...)`.

• Error: listen EADDRINUSE :::8080

  cause The specified port (e.g., 8080) is already in use by another application on your system.
  fix Stop the application currently using the port, or configure Tomahawk to listen on a different port using the `--port` CLI option or the `port` option in the programmatic `create` method (e.g., `port: 3000`).

• ReferenceError: require is not defined (when using import syntax in a .mjs file or with 'type: module' in package.json)

  cause Attempting to use CommonJS `require()` syntax in an ES Module context.
  fix Tomahawk is a CommonJS module and cannot be directly imported into an ES Module. You must use a Node.js environment configured for CommonJS (e.g., a `.js` file without `"type": "module"` in `package.json`). Or, preferably, switch to a modern server library that supports ESM.

Warnings

• breaking Tomahawk explicitly requires Node.js versions `>= 0.8.0 < 0.11.0`. Modern Node.js versions (e.g., v12+) are incompatible, leading to runtime errors, module resolution issues, or unexpected behavior due to significant API changes over the past decade.
  Fix: Do not use Tomahawk in any modern Node.js project. It is effectively abandoned. Consider modern alternatives like `http-server`, Express.js, Fastify, or Koa.js for static file serving or API development.
• breaking The package is unmaintained, with the last publish being over 11 years ago (December 2014) and targeting Node.js versions from 2012-2013. This means it contains numerous unpatched security vulnerabilities, is not compatible with current web standards, and should not be used in any production environment or publicly accessible service.
  Fix: Replace Tomahawk with a actively maintained and secure HTTP server library or framework. There are no security fixes or updates available for this package.
• gotcha Tomahawk uses CommonJS `require()` for module imports. It does not support ES Modules (`import`). Attempting to use `import` syntax will result in a runtime error.
  Fix: Ensure all imports for Tomahawk use the CommonJS `require()` syntax (e.g., `const tomahawk = require('tomahawk');`).
• gotcha CGI functionality relies on external shell commands and configurations. Incorrectly configured CGI routes, especially those accepting user input, can lead to severe command injection vulnerabilities if not properly sanitized.
  Fix: Thoroughly validate and sanitize all user inputs passed to CGI scripts. If using CGI, prefer dedicated, secure solutions rather than an unmaintained package. Better yet, avoid CGI entirely and use a modern API framework.

Install

• npm install tomahawk npm
• yarn add tomahawk yarn
• pnpm add tomahawk pnpm

Imports

• create
  wrong:

  import { create } from 'tomahawk';

  correct:

  const tomahawk = require('tomahawk');
  const app = tomahawk.create({port: 8080}).start();

  Tomahawk is a CommonJS module and does not support ES Modules ('import'). The `create` method is accessed from the default export.
• app.get
  wrong:

  tomahawk.get('/api/v1/resource', ...);

  correct:

  app.get('/api/v1/resource', function (req, res) { /* ... */ });

  HTTP methods like `get`, `post`, `put` are exposed on the `app` instance returned by `tomahawk.create()`, not directly on the `tomahawk` module.

Quickstart

This quickstart demonstrates how to use Tomahawk programmatically to set up a basic HTTP server, serve static files, and define REST API routes (GET, PUT) for a simple in-memory database. It includes an example of routing with path parameters and query parameters.

const tomahawk = require('tomahawk');
const path = require('path');

// A simple database for demonstration
const database = {
  captains : {
    "jim"    : "James Tiberius Kirk",
    "picard" : "Jean-Luc Picard"
  },
  starShips : {
    "jim": "NCC1701-A",
    "picard": "NCC1701-D"
  }
};

// Define routes dynamically
const routesModule = function () {
  function routes(app, config, io) {
    // GET all captains or a specific one
    app.get('/api/v1/captain/:id?', function (req, res) {
      const withStarship = req.query.starship === 'true';
      if (req.params.id) {
        const captainData = database.captains[req.params.id];
        if (captainData) {
          res.json(withStarship ?
            {id: req.params.id, name: captainData, starship: database.starShips[req.params.id]} :
            {id: req.params.id, name: captainData});
        } else {
          res.writeHead(404, {'Content-Type': 'application/json'});
          res.end(JSON.stringify({ error: 'Captain not found' }));
        }
      } else {
        res.json(database.captains);
      }
      res.end();
    });

    // PUT (create/update) a captain
    app.put('/api/v1/captain/:id', function (req, res) {
      // In a real app, req.body would be parsed by middleware
      // For this example, assuming req.body is already a string/object
      const newCaptainName = req.body || req.params.id; // Simplified for demo
      database.captains[req.params.id] = newCaptainName;
      res.json({ status: 'success', id: req.params.id, name: newCaptainName });
      // io.sockets.emit('new:captain', { id: req.params.id, name: newCaptainName }); // Example from original, 'io' is undefined here
      res.end();
    });

    console.log('REST routes registered.');
  }
  return routes;
};

// Create and start the server
const app = tomahawk.create({
  port: process.env.PORT || 8080,
  www: path.join(__dirname, 'public'), // Serve static files from a 'public' directory
  routes: [routesModule()] // Pass the route definitions
}).start();

console.log(`Tomahawk server running on http://localhost:${app.config.port}`);
console.log('Try visiting /api/v1/captain/jim or /api/v1/captain?starship=true');
console.log('To test PUT: curl -X PUT -H "Content-Type: application/json" -d "Arthur Dent" http://localhost:8080/api/v1/captain/arthur');