Machinepack HTTP

9.0.0 verified Thu Apr 23 auth: no javascript

machinepack-http provides a simple, `jQuery.get()`-like interface for sending HTTP requests, scraping webpages, and streaming data within Node.js and Sails.js applications. Currently at version 9.0.0, this library aims for immediate productivity in common cloud API interactions. It differentiates itself by offering robust error negotiation, distinguishing between network failures (e.g., offline, server down) and deliberate server errors (non-2xx status codes), and providing low-level streaming access to responses. The package is maintained by the Sails.js core team and follows the node-machine specification, acting as a higher-level wrapper around an underlying HTTP client. Its release cadence is tied to the Sails.js ecosystem, focusing on stability and integration.

Common errors

error TypeError: Http.get is not a function ↓

cause Attempting to call a 'machine' method without first requiring the `machinepack-http` module or incorrectly accessing the method.

fix

Ensure const Http = require('machinepack-http'); is present and that you are calling methods like Http.get() on the required object.

error Error: connect ECONNREFUSED ↓

cause The target server actively refused the connection, usually because it's not running, or a firewall is blocking the connection. This error is caught by the `error` exit handler.

fix

Verify the target URL and port are correct and that the server is online and accessible. Check firewall rules on both client and server.

error Error: getaddrinfo ENOTFOUND ↓

cause The hostname in the target URL could not be resolved to an IP address (DNS lookup failed). This error is caught by the `error` exit handler.

fix

Check the hostname for typos, ensure your network has access to a DNS server, or try accessing a different, known-good URL.

error Error: Unknown machine: [machineName] ↓

cause You are trying to call a method (machine) that does not exist on the `machinepack-http` module or you have a typo in the machine name.

fix

Refer to the node-machine.org documentation for machinepack-http to see the list of available machines and their correct names. Ensure correct casing.

Warnings

breaking machinepack-http v9.0.0 explicitly depends on the `request` package, which has been deprecated and is no longer maintained since 2019. The `request` package contains known security vulnerabilities and does not receive security updates. Relying on `machinepack-http` introduces these vulnerabilities into your application. ↓

fix Consider migrating to a modern, maintained HTTP client such as `node-fetch`, `axios`, or the built-in Node.js `undici`. If `machinepack-http` is critical, monitor its updates for a transition away from `request`.

gotcha This package is built on the 'machinepack' specification, which uses a declarative, `.exec()`-based API. This differs significantly from Promise-based or callback-based HTTP clients. All 'machines' (like `get`, `post`, `send`) must be explicitly executed via a `.exec()` call, which then takes an object of exit handlers (e.g., `success`, `error`, `non2xx`). ↓

fix Familiarize yourself with the node-machine specification and the `.exec()` pattern. Always chain `.exec()` after calling a machine, providing handlers for all expected exit states.

gotcha machinepack-http distinguishes between network errors (e.g., DNS resolution failure, connection refused) caught by the `error` exit, and non-2xx HTTP responses (e.g., 404, 500) caught by the `non2xx` exit. Developers commonly conflate these, leading to incomplete error handling. ↓

fix Always provide distinct handlers for both the `error` and `non2xx` exits in your `.exec()` call to ensure robust error management.

deprecated The underlying `request` library, which `machinepack-http` relies on, has been formally deprecated. While `machinepack-http` itself is maintained by the Sails.js core team, its fundamental dependency's deprecation indicates a significant risk and lack of future-proofing for this package. ↓

fix Evaluate alternatives to `machinepack-http` or be prepared for potential future breaking changes if it undergoes a major rewrite to replace its `request` dependency.

Install

npm install machinepack-http

yarn add machinepack-http

pnpm add machinepack-http

Imports

Http
wrong
```
import Http from 'machinepack-http';
```
correct
```
const Http = require('machinepack-http');
```
Primarily designed for CommonJS `require`. While modern Node.js supports ESM, `machinepack-http`'s ecosystem typically uses CJS.

Http.send

wrong

import { send } from 'machinepack-http'; send(/* ... */);

correct

const Http = require('machinepack-http');
Http.send(/* ... */).exec(/* ... */);

Individual 'machines' are accessed as properties of the main `Http` object and must be executed with `.exec()`.

Http.get
wrong
```
require('machinepack-http').get(/* ... */);
```
correct
```
const Http = require('machinepack-http');
Http.get(/* ... */).exec(/* ... */);
```
A convenient machine for GET requests. Always call `.exec()` to run a machine, providing named exit handlers.

Quickstart

Demonstrates making a GET request to a target URL, handling both network errors and non-2xx HTTP status code responses, and parsing a successful JSON response.

const Http = require('machinepack-http');

const TARGET_URL = process.env.TARGET_URL ?? 'https://example.com/api/data';

Http.get({
  url: TARGET_URL,
  data: { userId: 123 },
  timeout: 5000,
  headers: { 'User-Agent': 'Machinepack-HTTP-Example' }
})
.exec({
  // Handle network-level errors (e.g., server down, DNS issues)
  error: function (err) {
    console.error('Network or unexpected error:', err.message);
    // console.error(err); // Uncomment for full error stack
  },
  // Handle HTTP errors (non-2xx status codes) detected by the server
  non2xx: function (response) {
    console.warn(`Server responded with non-2xx status: ${response.statusCode}`);
    console.warn('Response body:', response.body);
  },
  // Handle successful 2xx responses
  success: function (response) {
    console.log('Successfully fetched data!');
    console.log(`Status Code: ${response.statusCode}`);
    console.log('Response body:', JSON.parse(response.body));
  }
});