gdDocumentation0.8.0

API reference

GDWebApp

Web application that listens with routes, static files, and middleware together.

Methods

route

route(method: String, pattern: String, handler: Callable, middleware: Array = []) -> void

Register a handler for an HTTP method and route pattern. The handler receives a request and may return a response, a result containing a response and Err, or a value for automatic response conversion.

Parameters

NameTypeDefaultDescription
methodStringRequiredHTTP method name, such as GET or POST.
patternStringRequiredPattern interpreted by this operation; see the method description for its syntax.
handlerCallableRequiredCallable invoked at the registered request-processing stage.
middlewareArray[]Middleware applied before the associated request handler.

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.

An explicit HEAD route is chosen first; otherwise HEAD returns the GET route's headers. Without a fallback, a known path with an unsupported method returns 405 and Allow.

Handlers and middleware may return a Signal, including after await. Processing resumes when it completes: no arguments become null, one argument becomes that value, and several become an Array. An unusable Signal goes to the error handler. Pending subscriptions are removed when the request ends or the app stops.

Do not modify values passed to GD.web.json() or view() until the reply has been sent.

See also

pre

pre(middleware: Variant) -> void

Register middleware before route selection.

Parameters

NameTypeDefaultDescription
middlewareVariantRequiredMiddleware applied before the associated request handler.

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.

use

use(middleware: Variant) -> void

Register middleware for every route.

Parameters

NameTypeDefaultDescription
middlewareVariantRequiredMiddleware applied before the associated request handler.

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.

after

after(handler: Callable) -> void

Register response postprocessing.

Parameters

NameTypeDefaultDescription
handlerCallableRequiredCallable invoked at the registered request-processing stage.

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.

on_error

on_error(handler: Callable) -> void

Set the handler called with the request and an Err when request processing fails. Preserve the original error until this boundary. If the error handler also fails, the server sends a 500 response without recursively calling it.

Parameters

NameTypeDefaultDescription
handlerCallableRequiredCallable invoked at the registered request-processing stage.

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.

Failures from template loading and rendering, JSON encoding, middleware, after, and automatic JSON conversion all arrive here with the original Err. Once a stream has started sending, the status cannot change; handle the writer's Err instead.

See also

show_errors

show_errors(on: bool) -> void

Expose failure details in response bodies only during local development.

Parameters

NameTypeDefaultDescription
onboolRequiredTrue enables the setting; false disables it.

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.

body_limit

body_limit(bytes: int) -> void

Set the per-request body limit.

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.

limits

limits(opts: Dictionary) -> void

Configure pending-input counts and deadlines before listening.

Parameters

NameTypeDefaultDescription
optsDictionaryRequiredNamed options for this operation. Omitted entries use their documented defaults.

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.

SettingAccepted range
jobs0..2147483647. 0 is unlimited
header_values1..2147483647
job_timeout, header_timeout, body_timeoutFinite 0..9223372036.854776 seconds. 0 has no deadline
header_bytes1..2147479551 bytes, separate from the body

Only these six names are accepted; a misspelling or body_limit is rejected. The header line count is limited only when header_values is set. Trailers are limited to 4096 bytes. header_timeout also covers an unfinished TLS handshake. Extra reply headers have no fixed count or total size; only invalid names and values are dropped.

dropped_headers

dropped_headers() -> int

Expose the cumulative count of unsafe response headers omitted from output. Keep a counter instead of attacker-amplifiable per-header logs.

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.

group

group(prefix: String, middleware: Array = []) -> GDWebRouteGroup

Create a prefix group whose middleware applies only to its member routes.

Parameters

NameTypeDefaultDescription
prefixStringRequiredPrefix applied when constructing the resulting names, paths or output.
middlewareArray[]Middleware applied before the associated request handler.

Return value

GDWebRouteGroup

Errors

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

static

static(prefix: String, dir: String) -> void

Map a URL prefix to a static-file directory.

Parameters

NameTypeDefaultDescription
prefixStringRequiredPrefix applied when constructing the resulting names, paths or output.
dirStringRequiredDirectory used as the base of the operation.

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.

fallback

fallback(handler: Callable) -> void

Register the unmatched-route handler.

Parameters

NameTypeDefaultDescription
handlerCallableRequiredCallable invoked at the registered request-processing stage.

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.

file_at

file_at(path: String) -> GDWebResponse, Err

Read a static file into a response or preserve its failure.

Parameters

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

Return value

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

file_at_async

file_at_async(path: String) -> await GDWebResponse, Err

Read a static file into a response or preserve its failure.

Parameters

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

Return value

await GDWebResponse, 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.

listen

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

Start listening on the selected host and port. The call reports startup failure before the server is used. Port zero lets the operating system choose a free port; read port() after startup.

Parameters

NameTypeDefaultDescription
portintRequiredLocal port; zero requests an available port.
hostString"127.0.0.1"Local bind address. 127.0.0.1 accepts local connections only.

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.

Binding and socket setup errors are returned through Err.

See also

listen_tls

listen_tls(port: int, cert: String, key: String, host: String = "127.0.0.1", opts: Dictionary = {  }) -> Variant, Err

Load credentials and client-auth policy off-loop and return the listen result.

Start an HTTPS listener from a PEM certificate chain and an unencrypted private key, selecting HTTP/2 or HTTP/1.1 through ALPN. Supports TLS 1.2 and 1.3. The startup returns a value and Err. opts sets client_auth to none, request, require, verify_if_given, or require_and_verify; client_ca selects the client trust bundle.

Parameters

NameTypeDefaultDescription
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
certStringRequiredPath to the PEM-encoded server certificate chain.
keyStringRequiredPath to an unencrypted PEM private key matching the certificate.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

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

listen_tls_async

listen_tls_async(port: int, cert: String, key: String, host: String = "127.0.0.1", opts: Dictionary = {  }) -> await Variant, Err

Load credentials and client-auth policy off-loop and return the listen result.

Parameters

NameTypeDefaultDescription
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
certStringRequiredPath to the PEM-encoded server certificate chain.
keyStringRequiredPath to an unencrypted PEM private key matching the certificate.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

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

port

port() -> int

Return the actual listen port, including kernel-selected 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.

shutdown

shutdown(context: GDAsyncContext) -> Variant, Err

Stop accepting and wait for active requests to finish.

Parameters

NameTypeDefaultDescription
contextGDAsyncContextRequiredCancellation context that controls the operation lifetime.

Return value

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

shutdown_async

shutdown_async(context: GDAsyncContext) -> await Variant, Err

Stop accepting and wait for active requests to finish.

Parameters

NameTypeDefaultDescription
contextGDAsyncContextRequiredCancellation context that controls the operation lifetime.

Return value

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

stop

stop() -> void

Stop processing and listening, then release resources.

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 application is listening.

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.

serve_error

serve_error() -> Err

Return the terminal listener error, if accepting connections failed after startup. A null result means no such failure has occurred.

Parameters

No parameters.

Return value

Err

The listener Err, or null while no terminal accept failure has occurred.

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.

See also

poll

poll() -> void

Advance only requests that received readiness notifications.

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.