API reference
GDWebRequest
The HTTP request received by a route handler, with strict JSON, a per-request context, and streaming of large bodies.
path is decoded once per segment; target keeps percent escapes and the query. %2F does not become a separator. A path whose decoded segments are not valid UTF-8 or contain control characters gets a 400.
Query values that are not valid text are kept as PackedByteArray. query omits malformed pairs; GD.http.decode_query() returns both the valid pairs and an Err.
The body has no default size limit. The handler starts right after the header, and the body is read from the connection only as the handler reads it. An empty successful read() is the end of the body. text() is limited to what fits in a String.
Properties
context: GDAsyncContextContext passing the first cancellation reason and deadline from parent to child.
method: Stringpath: Stringip: Stringquery: Dictionaryquery_all: Dictionaryparams: Dictionarytarget: String
Methods
header(name: String) -> Stringheaders() -> Dictionaryread(bytes: int = 32768) -> PackedByteArray, Errbytes() -> PackedByteArray, Errbody_size() -> intlimit(bytes: int) -> Errsave(path: String) -> int, Errtext() -> String, Errjson() -> Variant, Errread_async(bytes: int = 32768) -> await PackedByteArray, Errbytes_async() -> await PackedByteArray, Errsave_async(path: String) -> await int, Errtext_async() -> await String, Errjson_async() -> await Variant, Errkeep(name: String, value: Variant) -> voidkept(name: String, fallback: Variant = null) -> Variantvalid(name: String, fallback: Variant = null) -> Variant
header
header(name: String) -> StringReturn the named HTTP header.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
name | String | Required | Name used to register or look up the corresponding entry. |
Return value
String
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
headers
headers() -> DictionaryReturn HTTP headers as a dictionary.
Parameters
No parameters.
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
read
read(bytes: int = 32768) -> PackedByteArray, ErrRead up to bytes from the stream; an empty success value denotes EOF.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
bytes | int | 32768 | Byte count; it counts encoded bytes rather than text characters. |
Return value
PackedByteArray, Err
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.
bytes
bytes() -> PackedByteArray, ErrRead the complete request body as bytes. Body reads are consuming operations; avoid reading the same streaming body through multiple independent readers.
Parameters
No parameters.
Return value
PackedByteArray, Err
Body bytes without text decoding.
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.
Body transport, cancellation and configured size-limit failures propagate through Err; decoding can also fail.
See also
body_size
body_size() -> intReturn the body length without reading a large body into memory.
Parameters
No parameters.
Return value
int
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
limit
limit(bytes: int) -> ErrSet a byte-reader limit for this request only.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
bytes | int | Required | Byte count; it counts encoded bytes rather than text characters. |
Return value
Err
Errors
Returns an Err object directly, not a value-and-error pair. An absent error is null; inspect the method description to distinguish creation, lookup, and stored failure.
Accepts 0..9223372036854775807 bytes. Going over the limit is returned as a failure to the operation that read the body.
save
save(path: String) -> int, ErrSave the remaining body inside a mount without expanding it in memory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
Return value
int, Err
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.
text
text() -> String, ErrRead the request body and decode it as UTF-8 text. Body reads are consuming operations; avoid reading the same streaming body through multiple independent readers.
Parameters
No parameters.
Return value
String, Err
Decoded body text.
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.
Body transport, cancellation and configured size-limit failures propagate through Err; decoding can also fail.
See also
json
json() -> Variant, ErrRead and decode the request body as strict JSON. Body reads are consuming operations; avoid reading the same streaming body through multiple independent readers.
Parameters
No parameters.
Return value
Variant, Err
Decoded JSON value, which may be an object, array, scalar or null.
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.
Body transport, cancellation and configured size-limit failures propagate through Err; decoding can also fail.
See also
read_async
read_async(bytes: int = 32768) -> await PackedByteArray, ErrAlways defer completion for explicit awaiting.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
bytes | int | 32768 | Byte count; it counts encoded bytes rather than text characters. |
Return value
await PackedByteArray, 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.
bytes_async
bytes_async() -> await PackedByteArray, ErrRead the complete request body as bytes. Body reads are consuming operations; avoid reading the same streaming body through multiple independent readers.
Parameters
No parameters.
Return value
await PackedByteArray, Err
Body bytes without text decoding.
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.
Body transport, cancellation and configured size-limit failures propagate through Err; decoding can also fail.
See also
save_async
save_async(path: String) -> await int, ErrSave the remaining body inside a mount without expanding it in memory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
Return value
await int, 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.
text_async
text_async() -> await String, ErrRead the request body and decode it as UTF-8 text. Body reads are consuming operations; avoid reading the same streaming body through multiple independent readers.
Parameters
No parameters.
Return value
await String, Err
Decoded body text.
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.
Body transport, cancellation and configured size-limit failures propagate through Err; decoding can also fail.
See also
json_async
json_async() -> await Variant, ErrRead and decode the request body as strict JSON. Body reads are consuming operations; avoid reading the same streaming body through multiple independent readers.
Parameters
No parameters.
Return value
await Variant, Err
Decoded JSON value, which may be an object, array, scalar or null.
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.
Body transport, cancellation and configured size-limit failures propagate through Err; decoding can also fail.
See also
keep
keep(name: String, value: Variant) -> voidShare request-local values between middleware and later processing.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
name | String | Required | Name used to register or look up the corresponding entry. |
value | Variant | Required | Value to store, serialize, validate or pass to the operation described above. |
Return value
void
No value is returned.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
kept
kept(name: String, fallback: Variant = null) -> VariantReturn a request-local stored value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
name | String | Required | Name used to register or look up the corresponding entry. |
fallback | Variant | null | Value returned when the requested value is unavailable or omitted. |
Return value
Variant
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
valid
valid(name: String, fallback: Variant = null) -> VariantReturn a validated request value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
name | String | Required | Name used to register or look up the corresponding entry. |
fallback | Variant | null | Value returned when the requested value is unavailable or omitted. |
Return value
Variant
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.