Description

The Net namespace contains static functions for working with network requests.

Functions
Promise< Response >	fetch (< string\|URL > url, object options={})

Response	request (< string\|URL > url, object options={})

Promise< string\|ArrayBuffer >	wsGet (< string\|URL > url, any message=null, object options={})

Promise< number >	wsSend (< string\|URL > url, any message=null, object options={})

Function Documentation

◆ fetch()

Promise< Response > fetch	(	< string\|URL >	url,
		object	options = `{}`
	)

The Net.fetch() method starts the process of fetching a resource from the network, returning a Promise object which is fulfilled once a result is available.

The fetch() method itself works the same as the standard (see, eg. MDN fetch() for details), as it is simply a wrapper around other API objects. The returned Promise is resolved on a successful request/response, or rejected on failure.

Specifically:

In case of success (XMLHttpRequest.onload()), the promise is resolved with a Response object as the argument.
- Note: the non-standard option rejectOnError can be set to true, in which case fetch() will reject the promise if the returned HTTP status code is not in the 200-299 range, in the same way as if a network error occurred (see below).
In case of errors in options values or during configuration of the underlying XMLHttpRequest object the promise is rejected with TypeError or ReferenceError.
In case of any network error (XMLHttpRequest.onerror()), or if rejectOnError was set to true and the result status was not in the 200-299 range, the promise is rejected with a DOMException type named NetworkError (legacy ID DOMException.NETWORK_ERR).
The exception object has a custom property named response, which contains a Response object which holds whatever results could be retrieved, if any. If the request failed altogether (eg. server not found), the response.status will be 0.
In case of a network timeout (XMLHttpRequest.ontimeout()) the promise is rejected with a DOMException type named TimeoutError (legacy ID DOMException.TIMEOUT_ERR). This exception object also has a custom property named response, as described above (it may contain some actual response, for example in case of a redirect where the new URL timed out, the original response data may be available).
Note that the promise is rejected with the timeout exception first, before the general error rejection described above.
In case the request was aborted (XMLHttpRequest.onabort()) the promise is rejected with a DOMException type named AbortError (legacy ID DOMException.ABORT_ERR). This exception object also has a custom property named response, as described above (it may contain some actual response, for example if the request was aborted after the headers were already loaded).
Note that the promise is rejected with the abort exception first, before the general error rejection described above.

The few other differences of this implementation are in the Request and Response objects which are used to initialize the request and return the results, respectively. These are documented on their own pages.

The optional options argument passed to fetch() can, as in the standard, be either a basic object of option/value keys (eg. { method: "GET", timeout: 5000 }) or a Request object set up with the desired options. The available options are all the Request properties, which are documented there.

Basic example of sending an image to Touch Portal for use as an icon:

Net.fetch("https://mpaperno.github.io/DSEP4TP/images/logo/icon_64.png")
.then(response => response.base64())
.then((b64data) => {
    TP.stateUpdate(b64data);
})
.catch((e) => { console.error(e); })

See Fetch and Notify for a more complete example using JSON a data request.

◆ request()

Response request	(	< string\|URL >	url,
		object	options = `{}`
	)

This is a fully synchronous version of Net.fetch().

Instead of returning a Promise, Net.request() returns a Request object type. The returned Request can then be used to invoke its methods which actually send the request: Request.get(), Request.head(), Request.post(), and Request.put(). These are all shorthand for the respective HTTP methods. See the linked documentation for details.

The optional options argument passed to request() can, as with fetch(), be either a basic object of option/value keys (eg. ‘{ timeout: 5000, redirect: 'error’ }) or aRequestobject set up with the desired options. The available options are all theRequest` properties, which are documented there.

Unless the Request.noThrow option is set to true, synchronous requests may throw one of the DOMException types mentioned in the fetch() documentation, or a TypeError or ReferenceError if invalid options are passed or an exception is caught during configuration of the underlying XMLHttpRequest object.

Here is a synchronous version of the fetch() example above:

try {
  const b64data = Net.request("https://mpaperno.github.io/DSEP4TP/images/logo/icon_64.png").get().base64();
  TP.stateUpdate(b64data);
}
catch (e) { console.error(e); }

If error trapping isn't important, the image data could be returned directly from a single-line expression.

Note: This method blocks until the request completes or the timeout specified in options expires. An AbortSignal may be passed in the options object's signal property in order to terminate the request from another process (eg. a timer).

◆ wsGet()

Promise< string\|ArrayBuffer > wsGet	(	< string\|URL >	url,
		any	message = `null`,
		object	options = `{}`
	)

The Net.wsGet() function initiates a WebSocket request to the given URL, optionally sends a message after connection is established, and resolves the returned Promise with the contents of the first message received from the server.

In case of errors, the Promise is rejected with an Error or DOMException.

This is a convenience wrapper around the full WebSocket functionality for easily retrieving a single message asynchronously. Note that if you only need to send a message, w/out needing a reply, use the Net.wsSend() function instead.

Parameters

url	URL of the web socket server to connect to. Must use `ws:` or `wss:` scheme. If no scheme is in the given URL, the default is `ws:`.
message	A message to send to the server once connected. `null` (default) or `undefined` to not send any message.
options	Options to pass to the `WebSocket` constructor. The options object properties may consist of: Any of the options specified in the `WebSocket::Options` documention. If you need to specify sub-protocol(s), specify it/them using the `protocols` property (string or array of strings). `receiveTimeout` {number} - Number of milliseconds to wait for a message from the server before giving up. Set this to `<= 0` to wait indefinitely. Default: 30,000 (30 seconds). If the timeout expires before a message is received, the returned `Promise` is rejected with a `DOMException` named `TimeoutError` (error code constant `DOMException.TIMEOUT_ERR`). Note that this timer starts after a successful connection to the server. The initial connection timeout is controlled via the `handshakeTimeout` options property. `binary` {boolean} - Send the given message as binary data if `true`. Passed to `WebSocket::send()`. Default is to auto-detect the type. `signal` {AbortSignal} - Sets an `AbortSignal` which was obtained from an `AbortController` to use for aborting the network request.

Returns: A Promise which resolves with the contents of the first message received from the server, or rejects with an Error or DOMException in case of WebSocket error or message receive timeout, respectively.

See also: WebSocket, Net.wsSend()

◆ wsSend()

Promise< number > wsSend	(	< string\|URL >	url,
		any	message = `null`,
		object	options = `{}`
	)

The Net.wsSend() function initiates a WebSocket request to the given URL and, optionally, sends a message after connection is established.

If a message is sent, it resolves the returned Promise with the number of bytes sent, otherwise the Promise is resolved when the socket closes, with a value of 0. In case of errors, the Promise is rejected with an Error object.

This is a convenience wrapper around the full WebSocket functionality for easily retrieving a single message asynchronously. Note that if you need to receive a message, use the Net.wsGet() function instead.