API http

http

Opt-in native HTTP client module with synchronous and callback APIs.

Script API Reference · Host BuiltInModules

Enable and Import

The module is disabled by default. The host must add BuiltInModules.HttpClient before constructing the engine:

using AuroraScript.Runtime.Package;

var options = EngineOptions.Default.WithBuiltIns(builtIns =>
    builtIns.Add(BuiltInModules.HttpClient));

import http from "http";

Only absolute http:// and https:// URLs are accepted. http is an import alias, not a global object.

Quick Reference

Synchronous methods block the current script call until the response body is fully read.

Method	Returns
request(method, url, options?)	HttpResponse
get(url, options?)	HttpResponse
post(url, body?, options?)	HttpResponse
put(url, body?, options?)	HttpResponse
patch(url, body?, options?)	HttpResponse
delete(url, options?)	HttpResponse
head(url, options?)	HttpResponse

Every method also has an asynchronous callback form. It returns true after scheduling and requires callback as the final argument.

Method	Callback call
requestAsync(method, url, options?, callback)	callback(error, response)
getAsync(url, options?, callback)	callback(error, response)
postAsync(url, body?, options?, callback)	callback(error, response)
putAsync(url, body?, options?, callback)	callback(error, response)
patchAsync(url, body?, options?, callback)	callback(error, response)
deleteAsync(url, options?, callback)	callback(error, response)
headAsync(url, options?, callback)	callback(error, response)

Generic Request

http.request(method, url, options?)

http.request(
    method: string,
    url: string,
    options?: HttpRequestOptions
): HttpResponse

method is trimmed and normalized to uppercase. The method text must be accepted by .NET's HTTP method parser.

http.requestAsync(method, url, options?, callback)

http.requestAsync(
    method: string,
    url: string,
    options?: HttpRequestOptions,
    callback: function
): boolean

Schedules the request and returns true.

Verb Helpers

Helpers without a positional body argument (an advanced caller may still set options.body):

http.get(url: string, options?: HttpRequestOptions): HttpResponse
http.delete(url: string, options?: HttpRequestOptions): HttpResponse
http.head(url: string, options?: HttpRequestOptions): HttpResponse

http.getAsync(url: string, options?: HttpRequestOptions, callback: function): boolean
http.deleteAsync(url: string, options?: HttpRequestOptions, callback: function): boolean
http.headAsync(url: string, options?: HttpRequestOptions, callback: function): boolean

Body-capable verb helpers:

http.post(url: string, options?: HttpRequestOptions): HttpResponse
http.post(url: string, body?: string|UInt8Array, options?: HttpRequestOptions): HttpResponse

http.put(url: string, options?: HttpRequestOptions): HttpResponse
http.put(url: string, body?: string|UInt8Array, options?: HttpRequestOptions): HttpResponse

http.patch(url: string, options?: HttpRequestOptions): HttpResponse
http.patch(url: string, body?: string|UInt8Array, options?: HttpRequestOptions): HttpResponse

Their callback forms accept these call shapes:

http.postAsync(url, callback)
http.postAsync(url, options, callback)
http.postAsync(url, body, callback)
http.postAsync(url, body, options, callback)

putAsync and patchAsync follow the same shapes. For a two-argument synchronous call or a three-argument callback call, a plain object in the body position is treated as options. A positional body takes precedence over options.body.

HttpRequestOptions

The optional request object supports:

Property	Type	Description
headers	object	Header names mapped to a string or non-empty string[].
body	`string	UInt8Array`
contentType	string	Non-empty Content-Type value.
timeout	number	Positive integer milliseconds, no greater than the CLR Int32 limit.

Content-Length cannot be supplied manually. It is calculated by the client. A string body defaults to text/plain; charset=utf-8; a byte body defaults to application/octet-stream. An explicit contentType or Content-Type header overrides that default.

var options = {
    headers: {
        "accept": "application/json",
        "x-tag": ["one", "two"]
    },
    contentType: "application/json; charset=utf-8",
    timeout: 5000
};

var response = http.post(
    "https://example.test/items",
    JSON.stringify({ name: "Aurora" }),
    options);

Request options, headers, and byte bodies are copied before an asynchronous send so later script mutations do not change the scheduled request.

HttpResponse

Responses are frozen objects:

Property	Type	Description
status	number	Numeric HTTP status code.
statusText	string	HTTP reason phrase, or an empty string.
ok	boolean	true for a 2xx status.
url	string	Final URL after redirects.
headers	object	Frozen response headers with lowercase keys and combined string values.
body	string	Decoded response text.
text	string	Alias containing the same decoded text as body.
bytes	UInt8Array	Complete raw response body.

The client uses a declared response charset when supported, detects byte-order marks, and otherwise decodes as UTF-8. It buffers the complete response before returning or invoking the callback.

import http from "http";

export func load(url) {
    var response = http.get(url, { timeout: 5000 });
    if (!response.ok) {
        return { status: response.status, text: response.text };
    }
    return JSON.parse(response.text);
}

Callback Contract

Callback methods use an error-first, two-argument convention:

• completed HTTP exchange: callback(null, response);
• transport, timeout, request construction, or response-reading failure: callback(error, null).

HTTP status codes such as 404 or 500 are completed exchanges, not callback errors. Inspect response.ok or response.status.

Argument and option validation happens before scheduling. Invalid URLs, option types, timeout values, or a missing final callback throw AuroraRuntimeException immediately instead of invoking the callback.

import http from "http";

export func loadLater(url) {
    return http.getAsync(url, { timeout: 5000 }, (error, response) => {
        if (error != null) {
            console.error(error.message);
            return;
        }

        console.log(response.status, response.text);
    });
}

The callback runs through a detached script context and may execute after the original exported function has returned. It does not reuse a disposed invocation context. Callback exceptions are written to the host-configured error stream rather than converted into a second callback.

Connection and Security Behavior

• A shared .NET HttpClient reuses connections.
• Redirects and supported content decompression are automatic.
• Cookies are disabled and are not retained between requests, engines, or domains.
• All response content is buffered in memory; hosts should account for response-size and latency limits.
• http is network authority under the host process identity. Enforce URL allowlists, egress controls, and process-level isolation when scripts are not fully trusted.