gdドキュメント0.8.0

APIリファレンス

GDWebApp

URLごとの処理、静的ファイル、ミドルウェアを登録して、リクエストを待ち受けるWebアプリケーションです。

メソッド

route

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

HTTPメソッドとURLのパターンに対応する処理関数(ハンドラー)を登録します。この関数はリクエストを受け取り、レスポンスを返します。レスポンスとErrの組や、自動でレスポンスに変換できる文字列・辞書なども返せます。

引数

名前型省略時の値説明
methodString省略不可GETやPOSTなどのHTTPメソッド名。
patternString省略不可この操作が解釈するパターン。構文はメソッドの説明を参照。
handlerCallable省略不可リクエストを処理する関数(Callable)。
middlewareArray[]対応するリクエストハンドラーの前に適用するミドルウェア。

戻り値

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.

引数

名前型省略時の値説明
middlewareVariant省略不可対応するリクエストハンドラーの前に適用するミドルウェア。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

use

use(middleware: Variant) -> void
英語原文

Register middleware for every route.

引数

名前型省略時の値説明
middlewareVariant省略不可対応するリクエストハンドラーの前に適用するミドルウェア。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

after

after(handler: Callable) -> void
英語原文

Register response postprocessing.

引数

名前型省略時の値説明
handlerCallable省略不可リクエストを処理する関数(Callable)。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

on_error

on_error(handler: Callable) -> void

リクエストの処理に失敗したときの関数を登録します。登録した関数には、リクエストと元のErrが渡されます。この関数自体が失敗した場合は、再び呼び出さずに500を返します。

引数

名前型省略時の値説明
handlerCallable省略不可リクエストを処理する関数(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.

引数

名前型省略時の値説明
onbool省略不可trueで設定を有効にし、falseで無効にします。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

body_limit

body_limit(bytes: int) -> void
英語原文

Set the per-request body limit.

引数

名前型省略時の値説明
bytesint省略不可文字数ではなく、バイト数で指定します。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

limits

limits(opts: Dictionary) -> void

待ち受けを始める前に、保持する処理の数と各種の期限を設定します。

引数

名前型省略時の値説明
optsDictionary省略不可処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

設定受け付ける範囲
jobs0..2147483647。0は無制限
header_values1..2147483647
job_timeout、header_timeout、body_timeout有限の0..9223372036.854776秒。0は無期限
header_bytes1..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.

引数

名前型省略時の値説明
prefixString省略不可名前やパスなどの先頭に付ける文字列。
middlewareArray[]対応するリクエストハンドラーの前に適用するミドルウェア。

戻り値

GDWebRouteGroup

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

static

static(prefix: String, dir: String) -> void
英語原文

Map a URL prefix to a static-file directory.

引数

名前型省略時の値説明
prefixString省略不可名前やパスなどの先頭に付ける文字列。
dirString省略不可操作の基点となるディレクトリ。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

fallback

fallback(handler: Callable) -> void
英語原文

Register the unmatched-route handler.

引数

名前型省略時の値説明
handlerCallable省略不可リクエストを処理する関数(Callable)。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

file_at

file_at(path: String) -> GDWebResponse, Err
英語原文

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

引数

名前型省略時の値説明
pathString省略不可ファイルシステム上のパス。相対パスは実行ディレクトリ基準で、アクセス権限の設定に従います。

戻り値

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.

引数

名前型省略時の値説明
pathString省略不可ファイルシステム上のパス。相対パスは実行ディレクトリ基準で、アクセス権限の設定に従います。

戻り値

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()で取得します。

引数

名前型省略時の値説明
portint省略不可ローカルポート。0は空きポートを取得。
hostString"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, Err

PEM形式の証明書チェーンと暗号化されていない秘密鍵を使い、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を指定します。

引数

名前型省略時の値説明
portint省略不可ネットワークのポート番号。待ち受け時の0はOSがポートを選びます。
certString省略不可PEM形式のサーバー証明書チェーンへのパス。
keyString省略不可証明書に対応する、暗号化されていないPEM秘密鍵のパス。
hostString"127.0.0.1"接続または待ち受けに使うホスト名・IPアドレス。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

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.

引数

名前型省略時の値説明
portint省略不可ネットワークのポート番号。待ち受け時の0はOSがポートを選びます。
certString省略不可PEM形式のサーバー証明書チェーンへのパス。
keyString省略不可証明書に対応する、暗号化されていないPEM秘密鍵のパス。
hostString"127.0.0.1"接続または待ち受けに使うホスト名・IPアドレス。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

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.

引数

名前型省略時の値説明
contextGDAsyncContext省略不可キャンセルや制限時間を管理するコンテキスト。

戻り値

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.

引数

名前型省略時の値説明
contextGDAsyncContext省略不可キャンセルや制限時間を管理するコンテキスト。

戻り値

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を返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。