gdDocumentation0.8.0

API reference

GD.http

Entry for HTTP requests plus URL, query, and media-type handling. fetch suspends only its caller; fetch_async returns a Signal for composition.

Methods

fetch

fetch(url: String, opts: Dictionary = {  }) -> GDHTTPResponse, Err

Send an HTTP request and return its response. The default method is GET. A non-success HTTP status is still a response: distinguish transport failure from the server status, then inspect the buffered response body.

Parameters

NameTypeDefaultDescription
urlStringRequiredAbsolute HTTP or HTTPS URL.
optsDictionary{ }Request options such as method, headers, body and timeout. Timeout is in seconds.

Return value

GDHTTPResponse, Err

GDHTTPResponse exposes status, headers and body readers.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Connection, TLS, timeout and request failures are returned as Err. Status codes such as 404 are inspected on the response.

max_body accepts 0..9223372036854775807 bytes; 0 is unlimited. Response headers are limited to 10 MiB.

See also

fetch_async

fetch_async(url: String, opts: Dictionary = {  }) -> await GDHTTPResponse, Err

Send an HTTP request and return its response. The default method is GET. A non-success HTTP status is still a response: distinguish transport failure from the server status, then inspect the buffered response body.

Parameters

NameTypeDefaultDescription
urlStringRequiredAbsolute HTTP or HTTPS URL.
optsDictionary{ }Request options such as method, headers, body and timeout. Timeout is in seconds.

Return value

await GDHTTPResponse, Err

GDHTTPResponse exposes status, headers and body readers.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Connection, TLS, timeout and request failures are returned as Err. Status codes such as 404 are inspected on the response.

max_body accepts 0..9223372036854775807 bytes; 0 is unlimited. Response headers are limited to 10 MiB.

See also

parse_url

parse_url(raw: String) -> Dictionary, Err

Parse URL text into a component dictionary.

Parse URL structure, retaining the original raw_query and valid entries in query. Use decode_query to inspect query errors.

Parameters

NameTypeDefaultDescription
rawStringRequiredURL or query text to parse.

Return value

Dictionary, Err

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

parse_url_async

parse_url_async(raw: String) -> await Dictionary, Err

Dispatch URL parsing to a CPU worker.

Parameters

NameTypeDefaultDescription
rawStringRequiredURL or query text to parse.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

build_url

build_url(url: Dictionary) -> String

Format URL components as text.

Build a URL, preferring raw_query when present. Remove raw_query after editing query to regenerate its encoded representation.

Parameters

NameTypeDefaultDescription
urlDictionaryRequiredHTTP URL text or a parsed URL component dictionary, as indicated by the type.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

build_url_async

build_url_async(url: Dictionary) -> await String

Dispatch URL formatting to a CPU worker.

Parameters

NameTypeDefaultDescription
urlDictionaryRequiredHTTP URL text or a parsed URL component dictionary, as indicated by the type.

Return value

await String

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

request_target

request_target(url: Dictionary) -> String

Build an HTTP request target from URL components.

Parameters

NameTypeDefaultDescription
urlDictionaryRequiredHTTP URL text or a parsed URL component dictionary, as indicated by the type.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

request_target_async

request_target_async(url: Dictionary) -> await String

Dispatch request-target construction to a CPU worker.

Parameters

NameTypeDefaultDescription
urlDictionaryRequiredHTTP URL text or a parsed URL component dictionary, as indicated by the type.

Return value

await String

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

default_port

default_port(scheme: String) -> int

Return a scheme's default port.

Parameters

NameTypeDefaultDescription
schemeStringRequiredURL scheme name, such as http or https.

Return value

int

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

decode_query

decode_query(raw: String) -> Dictionary, Err

Parse query text into a dictionary.

Return all values per key as Arrays and the first Err, retaining valid pairs. Non-UTF-8 or NUL-containing keys and values remain PackedByteArray.

Parameters

NameTypeDefaultDescription
rawStringRequiredURL or query text to parse.

Return value

Dictionary, Err

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

A bare semicolon and a broken percent escape are reported as failures.

decode_query_async

decode_query_async(raw: String) -> await Dictionary, Err

Parse query text into a dictionary.

Return all values per key as Arrays and the first Err, retaining valid pairs. Non-UTF-8 or NUL-containing keys and values remain PackedByteArray.

Parameters

NameTypeDefaultDescription
rawStringRequiredURL or query text to parse.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

A bare semicolon and a broken percent escape are reported as failures.

encode_query

encode_query(query: Dictionary) -> String

Encode a query dictionary as text.

Encode scalar or Array values, repeating keys in byte-sorted order. PackedByteArray preserves arbitrary bytes; spaces become +.

Parameters

NameTypeDefaultDescription
queryDictionaryRequiredQuery parameter names and values to encode.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

encode_query_async

encode_query_async(query: Dictionary) -> await String

Dispatch query encoding to a CPU worker.

Parameters

NameTypeDefaultDescription
queryDictionaryRequiredQuery parameter names and values to encode.

Return value

await String

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

media_type

media_type(path: String) -> String

Select a media type from a filename.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

media_type_for_extension

media_type_for_extension(ext: String) -> String

Select a media type from an extension.

Parameters

NameTypeDefaultDescription
extStringRequiredFilename extension used for media-type lookup.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

is_textual

is_textual(kind: String) -> bool

Check whether a media type is textual.

Parameters

NameTypeDefaultDescription
kindStringRequiredMedia type to inspect, including any supplied parameters.

Return value

bool

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

extension_for_media_type

extension_for_media_type(kind: String) -> String

Return the extension corresponding to a media type.

Parameters

NameTypeDefaultDescription
kindStringRequiredMedia type to inspect, including any supplied parameters.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.