gdDocumentation0.8.0

API reference

GDWebServer

Low-level server using HTTP/1.1 responses for HTTP/1 requests and independent streams for TLS-negotiated HTTP/2 requests.

Methods

body_limit

body_limit(bytes: int) -> void

Set the body-reader limit for all requests.

Parameters

NameTypeDefaultDescription
bytesintRequiredByte count; it counts encoded bytes rather than text characters.

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.

header_limits

header_limits(bytes: int, values: int) -> void

Set request-header byte and field-count limits.

Parameters

NameTypeDefaultDescription
bytesintRequiredByte count; it counts encoded bytes rather than text characters.
valuesintRequiredMaximum number of header values accepted.

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.

listen

listen(port: int, host: String = "127.0.0.1") -> Variant, Err

Start an HTTP listener on the specified host and port.

Parameters

NameTypeDefaultDescription
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.

Return value

Variant, 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.

port

port() -> int

Return the actual listen port, including kernel-assigned ports.

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.

stop

stop() -> void

Close the listener and all connections, releasing retained buffers.

Parameters

No parameters.

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.

is_listening

is_listening() -> bool

Report whether the HTTP listener is active.

Parameters

No 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.

poll

poll() -> PackedInt32Array

Advance connections and return ready request IDs, valid until the next poll.

Parameters

No parameters.

Return value

PackedInt32Array

Errors

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

get_method

get_method(id: int) -> String

Return the request method.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.

Return value

String

Errors

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

get_path

get_path(id: int) -> String

Return the path component of the request target.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.

Return value

String

Errors

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

get_query

get_query(id: int) -> String

Return the query component of the request target.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.

Return value

String

Errors

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

get_header

get_header(id: int, name: String) -> String

Return the named request-header value.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.
nameStringRequiredName 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.

get_headers

get_headers(id: int) -> Dictionary

Return request headers as a dictionary with lowercase names.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.

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_body

read_body(id: int, bytes: int = 32768) -> Dictionary

Read one body chunk through the low-level API, returning state and data.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.
bytesint32768Byte count; it counts encoded bytes rather than text characters.

Return value

Dictionary

Errors

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

respond

respond(id: int, status: int, body: PackedByteArray, content_type: String = "text/plain; charset=utf-8") -> void

Submit the common response form with just content and type.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.
statusintRequiredHTTP response status code.
bodyPackedByteArrayRequiredContent to write or include in the response.
content_typeString"text/plain; charset=utf-8"Media type sent in the HTTP Content-Type header.

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.

respond_with

respond_with(id: int, status: int, headers: Dictionary, body: PackedByteArray) -> void

Submit a response with additional headers.

Parameters

NameTypeDefaultDescription
idintRequiredIdentifier previously returned by the corresponding API.
statusintRequiredHTTP response status code.
headersDictionaryRequiredResponse header names and their values.
bodyPackedByteArrayRequiredContent to write or include in the response.

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.

connection_count

connection_count() -> int

Return the number of retained connections.

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.

dropped_headers

dropped_headers() -> int

Cumulative number of omitted headers.

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.