API reference
GDWebApp
Web application that listens with routes, static files, and middleware together.
Methods
route(method: String, pattern: String, handler: Callable, middleware: Array = []) -> voidpre(middleware: Variant) -> voiduse(middleware: Variant) -> voidafter(handler: Callable) -> voidon_error(handler: Callable) -> voidshow_errors(on: bool) -> voidbody_limit(bytes: int) -> voidlimits(opts: Dictionary) -> voiddropped_headers() -> intgroup(prefix: String, middleware: Array = []) -> GDWebRouteGroupstatic(prefix: String, dir: String) -> voidfallback(handler: Callable) -> voidfile_at(path: String) -> GDWebResponse, Errfile_at_async(path: String) -> await GDWebResponse, Errlisten(port: int, host: String = "127.0.0.1") -> Variant, Errlisten_tls(port: int, cert: String, key: String, host: String = "127.0.0.1", opts: Dictionary = { }) -> Variant, Errlisten_tls_async(port: int, cert: String, key: String, host: String = "127.0.0.1", opts: Dictionary = { }) -> await Variant, Errport() -> intshutdown(context: GDAsyncContext) -> Variant, Errshutdown_async(context: GDAsyncContext) -> await Variant, Errstop() -> voidis_listening() -> boolserve_error() -> Errpoll() -> void
route
route(method: String, pattern: String, handler: Callable, middleware: Array = []) -> voidRegister 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
| Name | Type | Default | Description |
|---|---|---|---|
method | String | Required | HTTP method name, such as GET or POST. |
pattern | String | Required | Pattern interpreted by this operation; see the method description for its syntax. |
handler | Callable | Required | Callable invoked at the registered request-processing stage. |
middleware | Array | [] | 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) -> voidRegister middleware before route selection.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
middleware | Variant | Required | 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.
use
use(middleware: Variant) -> voidRegister middleware for every route.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
middleware | Variant | Required | 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.
after
after(handler: Callable) -> voidRegister response postprocessing.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
handler | Callable | Required | Callable 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) -> voidSet 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
| Name | Type | Default | Description |
|---|---|---|---|
handler | Callable | Required | Callable 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) -> voidExpose failure details in response bodies only during local development.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
on | bool | Required | True 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) -> voidSet the per-request body limit.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
bytes | int | Required | Byte 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) -> voidConfigure pending-input counts and deadlines before listening.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | Required | Named 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.
| Setting | Accepted range |
|---|---|
jobs | 0..2147483647. 0 is unlimited |
header_values | 1..2147483647 |
job_timeout, header_timeout, body_timeout | Finite 0..9223372036.854776 seconds. 0 has no deadline |
header_bytes | 1..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() -> intExpose 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 = []) -> GDWebRouteGroupCreate a prefix group whose middleware applies only to its member routes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
prefix | String | Required | Prefix applied when constructing the resulting names, paths or output. |
middleware | Array | [] | 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) -> voidMap a URL prefix to a static-file directory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
prefix | String | Required | Prefix applied when constructing the resulting names, paths or output. |
dir | String | Required | Directory 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) -> voidRegister the unmatched-route handler.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
handler | Callable | Required | Callable 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, ErrRead a static file into a response or preserve its failure.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a static file into a response or preserve its failure.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrStart 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
| Name | Type | Default | Description |
|---|---|---|---|
port | int | Required | Local port; zero requests an available port. |
host | String | "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, ErrLoad 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
| Name | Type | Default | Description |
|---|---|---|---|
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
cert | String | Required | Path to the PEM-encoded server certificate chain. |
key | String | Required | Path to an unencrypted PEM private key matching the certificate. |
host | String | "127.0.0.1" | Hostname or IP address used for connecting or binding. |
opts | Dictionary | { } | 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, ErrLoad credentials and client-auth policy off-loop and return the listen result.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
cert | String | Required | Path to the PEM-encoded server certificate chain. |
key | String | Required | Path to an unencrypted PEM private key matching the certificate. |
host | String | "127.0.0.1" | Hostname or IP address used for connecting or binding. |
opts | Dictionary | { } | 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() -> intReturn 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, ErrStop accepting and wait for active requests to finish.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
context | GDAsyncContext | Required | Cancellation 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, ErrStop accepting and wait for active requests to finish.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
context | GDAsyncContext | Required | Cancellation 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() -> voidStop 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() -> boolReport 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() -> ErrReturn 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() -> voidAdvance 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.