sync-request-curl

sync-request-curl

   

   

     

Make synchronous web requests similar to sync-request, but 20 times more quickly.

Leverages node-libcurl for performance instead of spawning child processes like sync-request.

This library was designed to run on NodeJS. It will not work in a browser.

• 1. Installation
• 2. Usage
  • 2.1. Method
  • 2.2. URL
  • 2.3. Options
  • 2.4. Response
• 3. License
• 4. Windows/MacOS
  • 4.1. Windows
  • 4.2. MacOS
• 5. Caveats

1. Installation

npm install sync-request-curl

Please also refer to the Windows/MacOS section for known issues and workarounds.

2. Usage

request(method, url, options);

Examples (click to view)

GET request without options

import request from 'sync-request-curl';

const response = request('GET', 'https://comp1531namesages.alwaysdata.net');
console.log('Status Code:', response.statusCode);
const jsonBody = JSON.parse(response.body.toString());
console.log('Returned JSON object:', jsonBody);

GET request with query string parameters

import request from 'sync-request-curl';

const response = request(
  'GET',
  'https://comp1531forum.alwaysdata.net/echo/echo',
  {
    qs: { message: 'Hello, world!' },
  }
);
console.log('Status Code:', response.statusCode);
const jsonBody = JSON.parse(response.body.toString());
console.log('Returned JSON object:', jsonBody);

POST request with headers and JSON payload

import request from 'sync-request-curl';

const response = request(
  'POST',
  'https://comp1531quiz.alwaysdata.net/quiz/create',
  {
    headers: { lab08quizsecret: "bruno's fight club" },
    json: {
      quizTitle: 'New Quiz',
      quizSynopsis: 'Sync request curl example'
    },
  }
);
console.log('Status Code:', response.statusCode);
const jsonBody = JSON.parse(response.body.toString());
console.log('Returned JSON Object:', jsonBody);

See sync-request for the original documentation. All Libcurl Errors will contain a non-zero integer code that can be looked up here.

Please note that this library only supports a subset of the original features which are summarised below.

2.1. Method

HTTP method (of type HttpVerb)

• e.g. PUT/POST/GET/DELETE.

2.2. URL

URL as a string

• e.g. https://toohak.fly.dev

2.3. Options

Only the following options from sync-request are supported for the time being:

Option	Description	Example	Default
qs	An object containing query string parameters which will be appended to the URL.	{ message: 'Hi!' }	undefined
headers	HTTP headers for the request.	{ token: 'abcde' }	undefined
json	Sets the body as a JSON representation of the value and automatically adds Content-type: application/json to the header.	{ name: 'Tam', course: 1531 }	undefined
body	Body for POST and PUT requests. We recommended using json instead for JSON payloads, otherwise the Content-Type will need to be set manually.	JSON.stringify({ name: 'Tam', course: 1531 })	undefined
timeout	Times out if no response is returned within the given number of milliseconds	2000	0 (no timeout)
followRedirects	Sets whether redirects (status code 302) should be followed automatically	false	true
maxRedirects	Sets the maximum number of redirects to follow before throwing an Error.	3	-1 (no limit)

Below are some additional options available from node-libcurl:

Option	Description	Example	Default
insecure	Set to false to send insecure requests. This can be useful on Windows which can sometimes have SSL issues (Curlcode 60).	true	false
setEasyOptions	Optional callback to set additional curl options for the Easy Interface. This has priority over existing options.	(curl, opt) => { curl.setOpt( opt.MAXREDIRS, 3 ); };	undefined

In src/types.ts, the Options interface following is defined as:

export interface Options {
  /*
   * sync-request options
   */
  headers?: IncomingHttpHeaders;
  qs?: { [key: string]: any };
  json?: any;
  body?: string | Buffer;

  timeout?: number;
  followRedirects?: boolean;
  maxRedirects?: number;

  /*
   * node-libcurl options
   */
  insecure?: boolean;
  setEasyOptions?: SetEasyOptionCallback;
}

2.4. Response

• statusCode - a number representing the HTTP status code (e.g. 200, 400, 401, 403)
• headers - HTTP response headers
• body - a string or buffer - use body.toString() for common use cases in combination with JSON.parse()
• getBody - a function with an optional encoding argument that returns the body if encoding is undefined, otherwise body.toString(encoding). If statusCode >= 300, an Error is thrown instead.
• url - the final URL used in the request after all redirections and with the query string parameters appended.

In src/types.ts, the Response interface is defined as:

export interface Response {
  statusCode: number;
  headers: IncomingHttpHeaders;
  body: string | Buffer;
  getBody: (encoding?: BufferEncoding) => string | Buffer; // simplified
  url: string;
}

3. License

MIT

4. Windows/MacOS

4.1. Windows

Your requests may unexpectedly fail with a Libcurl Error (code 60, CURLE_PEER_FAILED_VERIFICATION) when using NodeJS natively on Windows.

The reason is covered in the below resources:

• https://github.com/JCMais/node-libcurl/issues/301
• https://stackoverflow.com/a/34883260/22324694

One quick workaround is to set the insecure option to true when sending your requests. This is the same as setting the Libcurl Easy's equivalent SSL_VERIFYPEER to 0, or using curl in the command line with the -k or --insecure option.

Alternatively, consider using Windows Subsystem for Linux (WSL).

4.2. MacOS

The build for MacOS may fail during the installation process.

In most cases, this can be fixed by following these Github issues:

• https://github.com/JCMais/node-libcurl/issues/296
• https://github.com/JCMais/node-libcurl/issues/382

Otherwise, we recommend uninstalling this library and using sync-request instead.

5. Caveats

This library was developed mainly to improve performance with sending synchronous requests in NodeJS.

It was designed to work with UNIX-like systems for UNSW students enrolled in COMP1531 Software Engineering Fundamentals.

It has been tested to be working on Arch & Debian Linux and is compatible with Windows/MacOS