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(url: String, opts: Dictionary = { }) -> GDHTTPResponse, Errfetch_async(url: String, opts: Dictionary = { }) -> await GDHTTPResponse, Errparse_url(raw: String) -> Dictionary, Errparse_url_async(raw: String) -> await Dictionary, Errbuild_url(url: Dictionary) -> Stringbuild_url_async(url: Dictionary) -> await Stringrequest_target(url: Dictionary) -> Stringrequest_target_async(url: Dictionary) -> await Stringdefault_port(scheme: String) -> intdecode_query(raw: String) -> Dictionary, Errdecode_query_async(raw: String) -> await Dictionary, Errencode_query(query: Dictionary) -> Stringencode_query_async(query: Dictionary) -> await Stringmedia_type(path: String) -> Stringmedia_type_for_extension(ext: String) -> Stringis_textual(kind: String) -> boolextension_for_media_type(kind: String) -> String
fetch
fetch(url: String, opts: Dictionary = { }) -> GDHTTPResponse, ErrSend 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
| Name | Type | Default | Description |
|---|---|---|---|
url | String | Required | Absolute HTTP or HTTPS URL. |
opts | Dictionary | { } | 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, ErrSend 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
| Name | Type | Default | Description |
|---|---|---|---|
url | String | Required | Absolute HTTP or HTTPS URL. |
opts | Dictionary | { } | 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, ErrParse 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
| Name | Type | Default | Description |
|---|---|---|---|
raw | String | Required | URL 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, ErrDispatch URL parsing to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
raw | String | Required | URL 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) -> StringFormat URL components as text.
Build a URL, preferring raw_query when present. Remove raw_query after editing query to regenerate its encoded representation.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
url | Dictionary | Required | HTTP 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 StringDispatch URL formatting to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
url | Dictionary | Required | HTTP 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) -> StringBuild an HTTP request target from URL components.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
url | Dictionary | Required | HTTP 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 StringDispatch request-target construction to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
url | Dictionary | Required | HTTP 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) -> intReturn a scheme's default port.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
scheme | String | Required | URL 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, ErrParse 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
| Name | Type | Default | Description |
|---|---|---|---|
raw | String | Required | URL 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, ErrParse 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
| Name | Type | Default | Description |
|---|---|---|---|
raw | String | Required | URL 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) -> StringEncode a query dictionary as text.
Encode scalar or Array values, repeating keys in byte-sorted order. PackedByteArray preserves arbitrary bytes; spaces become +.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
query | Dictionary | Required | Query 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 StringDispatch query encoding to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
query | Dictionary | Required | Query 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) -> StringSelect a media type from a filename.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> StringSelect a media type from an extension.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
ext | String | Required | Filename 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) -> boolCheck whether a media type is textual.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
kind | String | Required | Media 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) -> StringReturn the extension corresponding to a media type.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
kind | String | Required | Media 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.