API reference
GD.web
Entry for building websites and Web APIs, with routes, static files, gdhtml templates, sessions, CSRF, JWT, rate limiting, and input validation.
Methods
app() -> GDWebAppserver() -> GDWebServertext(body: String, status: int = 200) -> GDWebResponsehtml(body: String, status: int = 200) -> GDWebResponsejson(data: Variant, status: int = 200) -> GDWebResponse, Errbytes(body: PackedByteArray, type: String = "application/octet-stream", status: int = 200) -> GDWebResponsestream(producer: Callable, length: int = -1, type: String = "application/octet-stream", status: int = 200) -> GDWebResponseredirect(to: String, status: int = 302, away: bool = false) -> GDWebResponseguard(reply: GDWebResponse) -> GDWebResponsenot_found(msg: String = "Not Found") -> GDWebResponseheader(reply: GDWebResponse, name: String, value: Variant) -> GDWebResponseadd_header(reply: GDWebResponse, name: String, value: Variant) -> GDWebResponseview(path: String, data: Dictionary = { }, status: int = 200, renderer: Callable = null) -> GDWebResponse, Errview_async(path: String, data: Dictionary = { }, status: int = 200, renderer: Callable = null) -> await GDWebResponse, Errjson_async(data: Variant, status: int = 200) -> await GDWebResponse, Errerror_status(error: Err) -> intjwt(key: Variant, opts: Dictionary = { }) -> GDWebMiddlewarejwt_sign(claims: Dictionary, key: Variant, opts: Dictionary = { }) -> String, Errjwt_verify(token: String, key: Variant, opts: Dictionary = { }) -> Dictionary, Errjwt_sign_async(claims: Dictionary, key: Variant, opts: Dictionary = { }) -> await String, Errjwt_verify_async(token: String, key: Variant, opts: Dictionary = { }) -> await Dictionary, Errcsrf(opts: Dictionary = { }) -> GDWebMiddlewaresessions(opts: Dictionary = { }) -> GDWebSessionStorerate(opts: Dictionary = { }) -> GDWebMiddlewaretext_rule(opts: Dictionary = { }) -> Dictionaryint_rule(opts: Dictionary = { }) -> Dictionarynumber_rule(opts: Dictionary = { }) -> Dictionarybool_rule() -> Dictionarylist_rule(item: Dictionary = { }, opts: Dictionary = { }) -> Dictionaryobject_rule(fields: Dictionary, opts: Dictionary = { }) -> Dictionaryoptional(rule: Dictionary, fallback: Variant = null) -> Dictionaryone_of(values: Array) -> Dictionaryvalidate(value: Variant, rule: Dictionary) -> Variant, Errvalidate_async(value: Variant, rule: Dictionary) -> await Variant, Errjson_body(rule: Dictionary, name: String = "body") -> GDWebMiddlewarequery(rule: Dictionary, name: String = "query") -> GDWebMiddlewareparams(rule: Dictionary, name: String = "params") -> GDWebMiddleware
app
app() -> GDWebAppCreate a routed web application.
Parameters
No parameters.
Return value
GDWebApp
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
server
server() -> GDWebServerCreate a raw HTTP server.
Parameters
No parameters.
Return value
GDWebServer
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
text
text(body: String, status: int = 200) -> GDWebResponseCreate a plain-text HTTP response. Use it for text output that should not be interpreted as HTML.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
body | String | Required | Response text. |
status | int | 200 | HTTP status code. |
Return value
GDWebResponse
A GDWebResponse with a plain-text content type.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
See also
html
html(body: String, status: int = 200) -> GDWebResponseCreate a response from HTML that has already been rendered. This helper does not parse a template or escape arbitrary text: escape untrusted values or use a template before calling it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
body | String | Required | Complete HTML response text. |
status | int | 200 | HTTP status code. |
Return value
GDWebResponse
A GDWebResponse with an HTML content type.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
See also
json
json(data: Variant, status: int = 200) -> GDWebResponse, ErrEncode a value into a JSON HTTP response. This operation can fail during serialization; return its result directly from a handler to let the application error boundary handle the failure.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
data | Variant | Required | Value to serialize as JSON. |
status | int | 200 | HTTP response status, default 200. |
Return value
GDWebResponse, Err
A GDWebResponse on success.
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.
Unsupported values or invalid JSON values produce Err. Do not discard the error and use the response alone.
Examples
func hello(_req):
return GD.web.json({"message": "Hello, world!"})See also
bytes
bytes(body: PackedByteArray, type: String = "application/octet-stream", status: int = 200) -> GDWebResponseCreate a binary response.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
body | PackedByteArray | Required | Content to write or include in the response. |
type | String | "application/octet-stream" | Media type of the response body. |
status | int | 200 | HTTP response status code. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
stream
stream(producer: Callable, length: int = -1, type: String = "application/octet-stream", status: int = 200) -> GDWebResponseCreate a lazy response from a producer writing bytes into its response Writer.
Create a lazy response producer called once with a GDWebWriter. Write PackedByteArray chunks and return void or a value and Err when finished. length=-1 selects unknown-length framing. The producer may await and should observe request-context cancellation; HEAD and bodyless statuses do not invoke it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
producer | Callable | Required | Callable receiving the response Writer and producing body chunks. |
length | int | -1 | Declared body length in bytes; -1 means the length is not known in advance. |
type | String | "application/octet-stream" | Media type of the response body. |
status | int | 200 | HTTP response status code. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
redirect
redirect(to: String, status: int = 302, away: bool = false) -> GDWebResponseCreate a redirect response.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
to | String | Required | Destination selected by the operation. |
status | int | 302 | HTTP response status code. |
away | bool | false | Whether an external redirect destination is permitted. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
guard
guard(reply: GDWebResponse) -> GDWebResponseAdd basic security headers to a response.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
reply | GDWebResponse | Required | Response value to extend or return. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
not_found
not_found(msg: String = "Not Found") -> GDWebResponseCreate a 404 response.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
msg | String | "Not Found" | Message text associated with this operation. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
header
header(reply: GDWebResponse, name: String, value: Variant) -> GDWebResponseReplace a response header.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
reply | GDWebResponse | Required | Response value to extend or return. |
name | String | Required | Header name or the name used to store a validated value on the request. |
value | Variant | Required | Value to store, serialize, validate or pass to the operation described above. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
add_header
add_header(reply: GDWebResponse, name: String, value: Variant) -> GDWebResponseAppend another response header with the same name.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
reply | GDWebResponse | Required | Response value to extend or return. |
name | String | Required | Header name or the name used to store a validated value on the request. |
value | Variant | Required | Value to store, serialize, validate or pass to the operation described above. |
Return value
GDWebResponse
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
view
view(path: String, data: Dictionary = { }, status: int = 200, renderer: Callable = null) -> GDWebResponse, ErrLoad an HTML template, render it with the supplied data, and create an HTTP response. Template expressions escape inserted data according to their output context.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Template file path. |
data | Dictionary | { } | Values made available to template expressions. |
status | int | 200 | HTTP status for a successful rendering. |
renderer | Callable | null | Optional custom rendering callable; null selects the built-in renderer. |
Return value
GDWebResponse, Err
A rendered GDWebResponse.
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 access, template parsing and rendering errors are preserved as Err.
Examples
func page(_req):
return GD.web.view("index.html", {"name": "world"})See also
view_async
view_async(path: String, data: Dictionary = { }, status: int = 200, renderer: Callable = null) -> await GDWebResponse, ErrLoad an HTML template, render it with the supplied data, and create an HTTP response. Template expressions escape inserted data according to their output context.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Template file path. |
data | Dictionary | { } | Values made available to template expressions. |
status | int | 200 | HTTP status for a successful rendering. |
renderer | Callable | null | Optional custom rendering callable; null selects the built-in renderer. |
Return value
await GDWebResponse, Err
A rendered GDWebResponse.
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.
File access, template parsing and rendering errors are preserved as Err.
Examples
func page(_req):
return GD.web.view("index.html", {"name": "world"})See also
json_async
json_async(data: Variant, status: int = 200) -> await GDWebResponse, ErrEncode a value into a JSON HTTP response. This operation can fail during serialization; return its result directly from a handler to let the application error boundary handle the failure.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
data | Variant | Required | Value to serialize as JSON. |
status | int | 200 | HTTP response status, default 200. |
Return value
await GDWebResponse, Err
A GDWebResponse on success.
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.
Unsupported values or invalid JSON values produce Err. Do not discard the error and use the response alone.
Examples
func hello(_req):
return GD.web.json({"message": "Hello, world!"})See also
error_status
error_status(error: Err) -> intReturn the HTTP status corresponding to an Err.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
error | Err | Required | Error value to classify when choosing an HTTP status. |
Return value
int
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
jwt
jwt(key: Variant, opts: Dictionary = { }) -> GDWebMiddlewareCreate middleware that verifies bearer JWTs.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
key | Variant | Required | Signing or verification key accepted by the configured JWT algorithm. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
GDWebMiddleware
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
An HS256 key is at least 32 bytes. The JSON and the signature are both validated. leeway is finite and 0 or more.
jwt_sign
jwt_sign(claims: Dictionary, key: Variant, opts: Dictionary = { }) -> String, ErrSign claims into a JWT.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
claims | Dictionary | Required | JWT claims to sign, including any configured validity timestamps. |
key | Variant | Required | Signing or verification key accepted by the configured JWT algorithm. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
String, 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.
ttl is 0 or more.
jwt_verify
jwt_verify(token: String, key: Variant, opts: Dictionary = { }) -> Dictionary, ErrVerify a JWT and return its claims.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
token | String | Required | Encoded JWT to verify before using its claims. |
key | Variant | Required | Signing or verification key accepted by the configured JWT algorithm. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
Dictionary, 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.
jwt_sign_async
jwt_sign_async(claims: Dictionary, key: Variant, opts: Dictionary = { }) -> await String, ErrSign claims into a JWT.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
claims | Dictionary | Required | JWT claims to sign, including any configured validity timestamps. |
key | Variant | Required | Signing or verification key accepted by the configured JWT algorithm. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
await String, 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.
ttl is 0 or more.
jwt_verify_async
jwt_verify_async(token: String, key: Variant, opts: Dictionary = { }) -> await Dictionary, ErrVerify a JWT on a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
token | String | Required | Encoded JWT to verify before using its claims. |
key | Variant | Required | Signing or verification key accepted by the configured JWT algorithm. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
await Dictionary, 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.
csrf
csrf(opts: Dictionary = { }) -> GDWebMiddlewareCreate CSRF middleware that permits only same-origin writes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
GDWebMiddleware
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sessions
sessions(opts: Dictionary = { }) -> GDWebSessionStoreCreate a cookie-session store and middleware.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
GDWebSessionStore
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
total and per_user accept 1..2147483647; idle and life accept 1..9223372036 seconds. Session values are string and integer identifiers. Sessions live in the process and are not shared across --workers.
rate
rate(opts: Dictionary = { }) -> GDWebMiddlewareCreate a per-key fixed-window rate limiter.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
GDWebMiddleware
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
limit and an explicit keys accept 1..2147483647. Keys live in the process and are not shared across --workers.
text_rule
text_rule(opts: Dictionary = { }) -> DictionaryCreate a text-length validation rule.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
int_rule
int_rule(opts: Dictionary = { }) -> DictionaryCreate an integer-range validation rule.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
number_rule
number_rule(opts: Dictionary = { }) -> DictionaryCreate a numeric-range validation rule.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
bool_rule
bool_rule() -> DictionaryCreate a boolean validation rule.
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.
list_rule
list_rule(item: Dictionary = { }, opts: Dictionary = { }) -> DictionaryCreate an array item and length validation rule.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
item | Dictionary | { } | Item to inspect or the item rule applied to collection elements. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
object_rule
object_rule(fields: Dictionary, opts: Dictionary = { }) -> DictionaryCreate an object-field validation rule.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
fields | Dictionary | Required | Object field names mapped to their validation rules. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
optional
optional(rule: Dictionary, fallback: Variant = null) -> DictionaryAdd a default value for missing input to a rule.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
rule | Dictionary | Required | Validation rule describing the accepted input. |
fallback | Variant | null | Value returned when the requested value is unavailable or omitted. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
one_of
one_of(values: Array) -> DictionaryCreate a rule from an allowed-value list.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
values | Array | Required | Values to inspect or accept as the allowed alternatives. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
validate
validate(value: Variant, rule: Dictionary) -> Variant, ErrValidate a value with a rule and return the safe value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
value | Variant | Required | Value to store, serialize, validate or pass to the operation described above. |
rule | Dictionary | Required | Validation rule describing the accepted input. |
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.
validate_async
validate_async(value: Variant, rule: Dictionary) -> await Variant, ErrDispatch nested input validation to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
value | Variant | Required | Value to store, serialize, validate or pass to the operation described above. |
rule | Dictionary | Required | Validation rule describing the accepted input. |
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.
json_body
json_body(rule: Dictionary, name: String = "body") -> GDWebMiddlewareCreate JSON-body validation middleware.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
rule | Dictionary | Required | Validation rule describing the accepted input. |
name | String | "body" | Header name or the name used to store a validated value on the request. |
Return value
GDWebMiddleware
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
query
query(rule: Dictionary, name: String = "query") -> GDWebMiddlewareCreate query validation middleware.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
rule | Dictionary | Required | Validation rule describing the accepted input. |
name | String | "query" | Header name or the name used to store a validated value on the request. |
Return value
GDWebMiddleware
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
params
params(rule: Dictionary, name: String = "params") -> GDWebMiddlewareCreate route-parameter validation middleware.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
rule | Dictionary | Required | Validation rule describing the accepted input. |
name | String | "params" | Header name or the name used to store a validated value on the request. |
Return value
GDWebMiddleware
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.