gdドキュメント0.8.0

APIリファレンス

GDWebRequest

リクエストを処理する関数が受け取るHTTPリクエストです。JSONの解析、キャンセルの管理、大きな本文を少しずつ保存する機能を持ちます。

pathは区切られた各部分を一度だけ復号したパスで、targetはpercentエスケープとクエリを保った原文です。%2Fは区切りになりません。復号した結果が正しいUTF-8でない場合や制御文字を含む場合は400を返します。

文字列として読めないクエリの値はPackedByteArrayで保持します。queryは壊れた組を省きます。正常な組とErrの両方を受け取るにはGD.http.decode_query()を使います。

本文の大きさに既定の上限はありません。ヘッダーを受け取るとすぐハンドラーを呼び、本文はハンドラーが読んだ分だけ接続から読みます。read()が成功して空を返したら本文の終わりです。text()が扱えるのはStringに収まる大きさまでです。

プロパティ

context : GDAsyncContext

処理のキャンセルや制限時間を管理するオブジェクトです。親から子へ、最初のキャンセル理由と期限を伝えます。

method : String
path : String
ip : String
query : Dictionary
query_all : Dictionary
params : Dictionary
target : String

メソッド

headers

headers() -> Dictionary
英語原文

Return HTTP headers as a dictionary.

引数

引数はありません。

戻り値

Dictionary

エラー

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

read

read(bytes: int = 32768) -> PackedByteArray, Err
英語原文

Read up to bytes from the stream; an empty success value denotes EOF.

引数

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

戻り値

PackedByteArray, Err

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

bytes

bytes() -> PackedByteArray, Err

リクエスト本文全体をバイト列として読みます。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。

引数

引数はありません。

戻り値

PackedByteArray, Err

文字列に変換していない本文のバイト列。

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。

関連文書

body_size

body_size() -> int
英語原文

Return the body length without reading a large body into memory.

引数

引数はありません。

戻り値

int

エラー

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

limit

limit(bytes: int) -> Err

このリクエストだけに適用する本文の上限をバイト数で設定します。

引数

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

戻り値

Err

エラー

Errオブジェクトを直接返します。処理結果とErrの2つを返す形式ではありません。エラーが見つからない場合などはnullを返します。詳しい条件は、この関数の説明を参照してください。

0..9223372036854775807バイトを受け付けます。上限を超えると、本文を読んだ操作へ失敗として返ります。

save

save(path: String) -> int, Err
英語原文

Save the remaining body inside a mount without expanding it in memory.

引数

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

戻り値

int, Err

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

text

text() -> String, Err

リクエスト本文を読み、UTF-8文字列としてデコードします。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。

引数

引数はありません。

戻り値

String, Err

デコードした本文。

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。

関連文書

json

json() -> Variant, Err

リクエスト本文を読み、厳密なJSONとして解析します。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。

引数

引数はありません。

戻り値

Variant, Err

オブジェクト、配列、スカラー、nullのいずれかのJSON値。

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。

関連文書

read_async

read_async(bytes: int = 32768) -> await PackedByteArray, Err
英語原文

Always defer completion for explicit awaiting.

引数

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

戻り値

await PackedByteArray, Err

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

bytes_async

bytes_async() -> await PackedByteArray, Err

リクエスト本文全体をバイト列として読みます。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。

引数

引数はありません。

戻り値

await PackedByteArray, Err

文字列に変換していない本文のバイト列。

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。

関連文書

save_async

save_async(path: String) -> await int, Err
英語原文

Save the remaining body inside a mount without expanding it in memory.

引数

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

戻り値

await int, Err

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

text_async

text_async() -> await String, Err

リクエスト本文を読み、UTF-8文字列としてデコードします。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。

引数

引数はありません。

戻り値

await String, Err

デコードした本文。

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。

関連文書

json_async

json_async() -> await Variant, Err

リクエスト本文を読み、厳密なJSONとして解析します。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。

引数

引数はありません。

戻り値

await Variant, Err

オブジェクト、配列、スカラー、nullのいずれかのJSON値。

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。

関連文書

keep

keep(name: String, value: Variant) -> void
英語原文

Share request-local values between middleware and later processing.

引数

名前型省略時の値説明
nameString省略不可対象を登録・参照するための名前。
valueVariant省略不可保存、変換、検査など、この関数で処理する値。

戻り値

void

値を返しません。

エラー

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

kept

kept(name: String, fallback: Variant = null) -> Variant
英語原文

Return a request-local stored value.

引数

名前型省略時の値説明
nameString省略不可対象を登録・参照するための名前。
fallbackVariantnull対象の値が存在しないか省略された場合に使う値。

戻り値

Variant

エラー

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

valid

valid(name: String, fallback: Variant = null) -> Variant
英語原文

Return a validated request value.

引数

名前型省略時の値説明
nameString省略不可対象を登録・参照するための名前。
fallbackVariantnull対象の値が存在しないか省略された場合に使う値。

戻り値

Variant

エラー

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