HTTP

A plugin talks to web services with two functions, both globals - no import line:

• useFetch - the everyday one: one call sends the request and reads the JSON of the response into your interface. It never throws: what went wrong is in the result.
• fetch - the browser's own function, for the response as it is: its status, headers and body.

A request runs in the background. The game does not wait for it: the response arrives on a later server frame, never inside the call that sent the request.

useFetch since v0.2

interface Weather {
    
temperature
: number;
    
description
: string;
}

server
.
addCommand
("/weather", async ({ 
player
 }) => {
    const { 
data
, 
error
 } = await 
useFetch
<Weather>("https://example.com/api/weather", {
        
query
: { 
city
: "Paris" },
    });
    if (
error
) return 
print
(
player
, `No weather: ${
error
.
message
}`);
    
print
(
player
, `${
data
!.
temperature
} °C, ${
data
!.
description
}`);
});

useFetch<T>(url, options) gives { data, error, status }:

• data is the response's JSON read into T - an interface of the fields the JSON has, declared beside your code. null when there is an error or the response has no body.
• error is null, or why there is no data:

  error	when
  FetchError	the server answered with a status outside 2xx; error.status, error.statusText and error.body - often what the server says went wrong
  TypeError	there is no response: no connection, a bad address, a certificate no trusted authority vouches for; or the JSON lacks a field T requires
  SyntaxError	the body is not JSON
  TimeoutError, AbortError	timeout ran out, or signal aborted

• status is the response's HTTP status, 0 when there was no response.

A field the JSON may leave out is an optional one in the interface (description?: string); a field the interface does not name is skipped.

useFetch asks for JSON (Accept: application/json). To read the body as text, give string as T: useFetch<string>(url).

Sending data

An object goes as JSON, with Content-Type: application/json. Its type is the second type argument:

interface Report {
    
map
: string;
    
players
: number;
}

interface Saved {
    
id
: number;
}

const 
report
: Report = { 
map
: 
server
.
map
, 
players
: 
server
.
players
.
length
 };
const { 
data
, 
error
 } = await 
useFetch
<Saved, Report>("https://example.com/api/reports", {
    
method
: "POST",
    
body
: 
report
,
    
retry
: 2,
});

Text is sent as it is: body: "hello", with useFetch<Saved> alone.

fetch

interface Answer {
    
accepted
: boolean;
}

const 
response
 = await 
fetch
("https://example.com/api/stats", {
    
method
: "POST",
    
headers
: { 
Authorization
: "Bearer abc", "Content-Type": "application/json" },
    
body
: 
JSON
.
stringify
(stats),
});
if (!
response
.
ok
) return 
console
.
log
(`HTTP ${
response
.
status
} ${
response
.
statusText
}`);
const 
answer
 = await 
response
.
json
<Answer>();

fetch(input, init) takes an address as text, a URL or a Request (new Request(url, init)), and gives a promise of the Response.

The response:

• response.status and response.statusText are the status and its words (404, "Not Found"); response.ok is true for 200 to 299.
• response.headers are its headers: get(name) in any case, has, forEach, entries, and getSetCookie() for every Set-Cookie.
• response.url is the address it came from after any redirects, and response.redirected says whether there were any.
• The body is read once, with await response.text(), await response.json<T>() or await response.arrayBuffer(); clone() makes a copy to read it twice.

A status such as 404 or 500 is a response, as in the browser: check response.ok. The promise is rejected when there is no response at all - with a TypeError whose message says why (fetch failed: Could not resolve host: ...) - and when a signal aborts.

Addresses and queries

URL takes an address apart, and searchParams builds its query:

const 
url
 = new 
URL
("https://example.com/api/rank");
url
.
searchParams
.
set
("steamid", 
player
.
steamId
);
url
.
searchParams
.
set
("map", 
server
.
map
);
const 
response
 = await 
fetch
(
url
);

new URL(path, base) resolves an address against another (new URL("../users", "https://example.com/api/v1/")); URL.canParse and URL.parse check one without a try. new URLSearchParams({ ... }) makes a query of its own, which ${query} writes as text:

const 
query
 = new 
URLSearchParams
({ 
steamid
: 
player
.
steamId
, 
map
: 
server
.
map
 });
await 
fetch
(`https://example.com/api/rank?${
query
}`);

Cancelling and timeouts

A signal cancels a request, and the promise is rejected with an error named AbortError - TimeoutError for AbortSignal.timeout(ms):

const 
response
 = await 
fetch
(url, { 
signal
: AbortSignal.timeout(5000) });   // give up after 5 s

useFetch has the same as its timeout option, for each try. In an async command handler or a listener of an event about a player, the player leaving cancels the request by itself (async).

HTTPS and proxies

An https:// address is checked against the certificate authorities a browser trusts; the server module carries their list, so a server needs nothing installed for it. A service with a certificate of its own making - a panel on your own machine - is trusted by giving that certificate, as PEM text, in tls.ca:

import * as 
fs
 from "@amxts/core/fs";

const 
ca
 = 
fs
.
readFileSync
(`${
server
.
configsDir
}/panel.pem`) ?? "";
const 
response
 = await 
fetch
("https://panel.example.com/api/bans", { 
tls
: { 
ca
 } });

proxy sends a request through a proxy - http://, https:// or socks5://, with a user and password in the address when it needs them:

await 
useFetch
<Status>(url, { 
proxy
: "http://user:secret@proxy.example.com:3128" });

Without proxy a request goes straight out; a server's http_proxy environment variable is not used.