common/http

Provides a simple, synchronous HTTP request interface for legacy JavaScript environments such as RingoJS or Rhino.

The http module exposes a convenient wrapper function TCHttpRequest for performing basic REST API calls and page retrievals.
It simplifies network communication by returning a structured response object containing headers, content, cookies, encoding,
and other HTTP metadata, while handling connection setup, timeouts, and errors internally.

Core Features:

  • Lightweight, synchronous HTTP client built on ringo/httpclient.
  • Supports standard HTTP methods: GET, POST, PUT, and DELETE.
  • Customizable headers, request body, and connection timeout.
  • Returns a detailed response object with connection info, status, headers, and content.
  • Simple error handling with null return and lastError() reporting.

Usage Overview:

  1. Import with const { TCHttpRequest } = require("sigma/common/http");
  2. Call TCHttpRequest(url, method, headers, data, timeout) to perform a request.
  3. Inspect response fields such as status, headers, content, or cookies.

API Highlights:

  • TCHttpRequest(url, method, headers, data, timeout)
    • url {string}: Target URL, e.g. "https://example.com/".
    • method {string}: HTTP method (GET, POST, etc.), defaults to GET.
    • headers {Object|string}: Optional request headers.
    • data {string}: Optional request body (e.g., JSON or form data).
    • timeout {number}: Connection timeout in milliseconds (default 6000).
    • returns {Object|null}: Response object or null on failure.

Response Object Fields:

  • connection: Native HTTP connection instance.
  • content: Response body as text.
  • contentBytes: Raw response bytes.
  • contentLength: Length of response body.
  • contentType: MIME type of response, e.g. "text/html; charset=utf-8".
  • cookies: Cookies returned by the server.
  • encoding: Response character encoding.
  • headers: All HTTP headers as a key-value object.
  • message: HTTP status message, e.g. "OK", "Not Found".
  • status: HTTP status code, e.g. 200, 404.
  • url: Final URL (after redirect, if applicable).

Example:

const { TCHttpRequest } = require("sigma/common/http");

const res = TCHttpRequest("http://ringojs.org/", "GET", "", "", 2000);
if (res !== null) {
    print("Status: " + res.status + " " + res.message);
    print("Content-Type: " + res.contentType);
    print("Headers: " + JSON.stringify(res.headers, null, 2));
    print("Body:\n" + res.content);
} else {
    print("Request failed: " + lastError());
}

(inner) TCHttpRequest(url, method, headersopt, dataopt, timeoutopt) → {Object|null}

Sends an HTTP request and returns a detailed response object containing headers, content, status, and metadata.
This is a synchronous request function suitable for lightweight REST API calls or page content retrieval.

Example
const res = TCHttpRequest("http://ringojs.org/", "GET", "", "", 2000);
if (res !== null) {
    print("connection:\n" + res.connection);       // Raw connection object
    print("content:\n" + res.content);             // Response text (string)
    print("contentBytes:\n" + res.contentBytes);   // Response as byte array
    print("contentLength:\n" + res.contentLength); // Length of response body
    print("contentType:\n" + res.contentType);     // e.g., text/html; charset=utf-8
    print("cookies:\n" + res.cookies);             // Cookies set by the server
    print("headers:\n" + res.headers);             // All response headers
    print("encoding:\n" + res.encoding);           // Response character encoding
    print("message:\n" + res.message);             // Status message (e.g., OK, Not Found)
    print("status:\n" + res.status);               // HTTP status code (e.g., 200, 301)
    print("url:\n" + res.url);                     // Final URL (after redirect, if any)
} else {
    print("Request failed: " + lastError());
}

// Sample Output:
connection:
sun.net.www.protocol.http.HttpURLConnection:http://ringojs.org/

content:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">...

status: 301
message: Moved Permanently
headers: { Date: [...], Location: [...] }
Parameters:
string url

The website link string, for example: "http://ringojs.org/".
string method

Request method, the default is GET, the four commonly used request methods are: GET, DELETE, PUT and POST.
Object | string headers <optional>

Request headers, the default is {}.
string data <optional>

The request body, the default is null.
number timeout <optional>
 6000

Timeout. The default is 6000.
Returns:
Object | null

If the network object is successfully returned, it returns null if it fails.
The returned network object contains attributes:

  • connection
  • content
  • contentBytes
  • contentLength
  • contentType
  • cookies
  • encoding
  • headers
  • message
  • status
  • url