gdDocumentation0.8.0

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 : GDAsyncContext

Context passing the first cancellation reason and deadline from parent to child.

method : String
path : String
ip : String
query : Dictionary
query_all : Dictionary
params : Dictionary
target : String

Methods

headers

headers() -> Dictionary

Return 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, Err

Read up to bytes from the stream; an empty success value denotes EOF.

Parameters

NameTypeDefaultDescription
bytesint32768Byte 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, Err

Read 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() -> int

Return 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) -> Err

Set a byte-reader limit for this request only.

Parameters

NameTypeDefaultDescription
bytesintRequiredByte 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, Err

Save the remaining body inside a mount without expanding it in memory.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem 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, Err

Read 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, Err

Read 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, Err

Always defer completion for explicit awaiting.

Parameters

NameTypeDefaultDescription
bytesint32768Byte 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, Err

Read 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, Err

Save the remaining body inside a mount without expanding it in memory.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem 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, Err

Read 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, Err

Read 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) -> void

Share request-local values between middleware and later processing.

Parameters

NameTypeDefaultDescription
nameStringRequiredName used to register or look up the corresponding entry.
valueVariantRequiredValue 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) -> Variant

Return a request-local stored value.

Parameters

NameTypeDefaultDescription
nameStringRequiredName used to register or look up the corresponding entry.
fallbackVariantnullValue 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) -> Variant

Return a validated request value.

Parameters

NameTypeDefaultDescription
nameStringRequiredName used to register or look up the corresponding entry.
fallbackVariantnullValue 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.