APIリファレンス
GDWebApp
URLごとの処理、静的ファイル、ミドルウェアを登録して、リクエストを待ち受けるWebアプリケーションです。
メソッド
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 = []) -> voidHTTPメソッドとURLのパターンに対応する処理関数(ハンドラー)を登録します。この関数はリクエストを受け取り、レスポンスを返します。レスポンスとErrの組や、自動でレスポンスに変換できる文字列・辞書なども返せます。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
method | String | 省略不可 | GETやPOSTなどのHTTPメソッド名。 |
pattern | String | 省略不可 | この操作が解釈するパターン。構文はメソッドの説明を参照。 |
handler | Callable | 省略不可 | リクエストを処理する関数(Callable)。 |
middleware | Array | [] | 対応するリクエストハンドラーの前に適用するミドルウェア。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
HEAD専用のルートがあればそれを選び、無ければGETルートのヘッダーを返します。fallbackが無い場合、パスは合うのにメソッドが合わない要求には405とAllowを返します。
ハンドラーとミドルウェアは、awaitの後も含めてSignalを返せます。完了時の引数が0個ならnull、1個ならその値、複数ならArrayとして処理を再開します。利用できないSignalはエラーハンドラーへ渡します。要求が終わったときとappが停止したときは、待機中のSignalとの接続を解除します。
GD.web.json()やview()へ渡した値は、返事を送り終えるまで変更しないでください。
関連文書
pre
pre(middleware: Variant) -> void英語原文Register middleware before route selection.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
middleware | Variant | 省略不可 | 対応するリクエストハンドラーの前に適用するミドルウェア。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
use
use(middleware: Variant) -> void英語原文Register middleware for every route.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
middleware | Variant | 省略不可 | 対応するリクエストハンドラーの前に適用するミドルウェア。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
after
after(handler: Callable) -> void英語原文Register response postprocessing.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
handler | Callable | 省略不可 | リクエストを処理する関数(Callable)。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
on_error
on_error(handler: Callable) -> voidリクエストの処理に失敗したときの関数を登録します。登録した関数には、リクエストと元のErrが渡されます。この関数自体が失敗した場合は、再び呼び出さずに500を返します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
handler | Callable | 省略不可 | リクエストを処理する関数(Callable)。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
テンプレートの読み込みと描画、JSON変換、ミドルウェア、after、自動JSON変換の失敗は、どれも元のErrを保ったままここへ届きます。ストリームの送信が始まった後はステータスコードを変えられないため、writerが返すErrを処理してください。
関連文書
show_errors
show_errors(on: bool) -> void英語原文Expose failure details in response bodies only during local development.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
on | bool | 省略不可 | trueで設定を有効にし、falseで無効にします。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
body_limit
body_limit(bytes: int) -> void英語原文Set the per-request body limit.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
bytes | int | 省略不可 | 文字数ではなく、バイト数で指定します。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
limits
limits(opts: Dictionary) -> void待ち受けを始める前に、保持する処理の数と各種の期限を設定します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
opts | Dictionary | 省略不可 | 処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
| 設定 | 受け付ける範囲 |
|---|---|
jobs | 0..2147483647。0は無制限 |
header_values | 1..2147483647 |
job_timeout、header_timeout、body_timeout | 有限の0..9223372036.854776秒。0は無期限 |
header_bytes | 1..2147479551バイト。本文とは別 |
受け付けるのはこの6つの名前だけで、綴り違いやbody_limitは誤りとして拒否します。ヘッダーの行数はheader_valuesを指定した場合だけ制限します。trailerは4096バイトまでです。header_timeoutは完了していないTLSの初期通信にも適用されます。返事の追加ヘッダーには件数と全体量の固定上限がなく、不正な名前と値だけを落とします。
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.
引数
引数はありません。
戻り値
int
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
group
group(prefix: String, middleware: Array = []) -> GDWebRouteGroup英語原文Create a prefix group whose middleware applies only to its member routes.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
prefix | String | 省略不可 | 名前やパスなどの先頭に付ける文字列。 |
middleware | Array | [] | 対応するリクエストハンドラーの前に適用するミドルウェア。 |
戻り値
GDWebRouteGroup
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
static
static(prefix: String, dir: String) -> void英語原文Map a URL prefix to a static-file directory.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
prefix | String | 省略不可 | 名前やパスなどの先頭に付ける文字列。 |
dir | String | 省略不可 | 操作の基点となるディレクトリ。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
fallback
fallback(handler: Callable) -> void英語原文Register the unmatched-route handler.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
handler | Callable | 省略不可 | リクエストを処理する関数(Callable)。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
file_at
file_at(path: String) -> GDWebResponse, Err英語原文Read a static file into a response or preserve its failure.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
path | String | 省略不可 | ファイルシステム上のパス。相対パスは実行ディレクトリ基準で、アクセス権限の設定に従います。 |
戻り値
GDWebResponse, Err
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
file_at_async
file_at_async(path: String) -> await GDWebResponse, Err英語原文Read a static file into a response or preserve its failure.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
path | String | 省略不可 | ファイルシステム上のパス。相対パスは実行ディレクトリ基準で、アクセス権限の設定に従います。 |
戻り値
await GDWebResponse, Err
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
listen
listen(port: int, host: String = "127.0.0.1") -> Variant, Err指定ホストとポートで待ち受けを開始します。起動の失敗は呼び出し結果で確認できます。ポート0はOSが空きポートを選び、起動後のport()で取得します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
port | int | 省略不可 | ローカルポート。0は空きポートを取得。 |
host | String | "127.0.0.1" | 待ち受けアドレス。127.0.0.1はローカル接続だけを受け付けます。 |
戻り値
Variant, Err
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
指定したアドレスやポートを使用できない場合など、接続の待ち受けを始められなければErrを返します。
関連文書
listen_tls
listen_tls(port: int, cert: String, key: String, host: String = "127.0.0.1", opts: Dictionary = { }) -> Variant, ErrPEM形式の証明書チェーンと暗号化されていない秘密鍵を使い、HTTPSの待ち受けを開始します。TLS 1.2/1.3に対応し、ALPNでHTTP/2またはHTTP/1.1を選びます。起動結果は値とErrで返します。optsのclient_authはnone/request/require/verify_if_given/require_and_verifyから選び、client_caにはクライアント証明書の検証に使うCAを指定します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
port | int | 省略不可 | ネットワークのポート番号。待ち受け時の0はOSがポートを選びます。 |
cert | String | 省略不可 | PEM形式のサーバー証明書チェーンへのパス。 |
key | String | 省略不可 | 証明書に対応する、暗号化されていないPEM秘密鍵のパス。 |
host | String | "127.0.0.1" | 接続または待ち受けに使うホスト名・IPアドレス。 |
opts | Dictionary | { } | 処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。 |
戻り値
Variant, Err
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
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.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
port | int | 省略不可 | ネットワークのポート番号。待ち受け時の0はOSがポートを選びます。 |
cert | String | 省略不可 | PEM形式のサーバー証明書チェーンへのパス。 |
key | String | 省略不可 | 証明書に対応する、暗号化されていないPEM秘密鍵のパス。 |
host | String | "127.0.0.1" | 接続または待ち受けに使うホスト名・IPアドレス。 |
opts | Dictionary | { } | 処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。 |
戻り値
await Variant, Err
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
port
port() -> int英語原文Return the actual listen port, including kernel-selected ports.
引数
引数はありません。
戻り値
int
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
shutdown
shutdown(context: GDAsyncContext) -> Variant, Err英語原文Stop accepting and wait for active requests to finish.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
context | GDAsyncContext | 省略不可 | キャンセルや制限時間を管理するコンテキスト。 |
戻り値
Variant, Err
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
shutdown_async
shutdown_async(context: GDAsyncContext) -> await Variant, Err英語原文Stop accepting and wait for active requests to finish.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
context | GDAsyncContext | 省略不可 | キャンセルや制限時間を管理するコンテキスト。 |
戻り値
await Variant, Err
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
stop
stop() -> void英語原文Stop processing and listening, then release resources.
引数
引数はありません。
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
is_listening
is_listening() -> bool英語原文Report whether the application is listening.
引数
引数はありません。
戻り値
bool
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
serve_error
serve_error() -> Err起動後に待受けが継続できなくなった場合、その原因を返します。失敗していなければnullです。
引数
引数はありません。
戻り値
Err
待受けのErr。継続不能な失敗がなければnull。
エラー
Errオブジェクトを直接返します。処理結果とErrの2つを返す形式ではありません。エラーが見つからない場合などはnullを返します。詳しい条件は、この関数の説明を参照してください。
関連文書
poll
poll() -> void英語原文Advance only requests that received readiness notifications.
引数
引数はありません。
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。