gdドキュメント0.8.0

APIリファレンス

GD.web

WebサイトやWeb APIを作るための機能です。URLと処理の対応付け、静的ファイル配信、HTMLテンプレート、セッション、CSRF対策、JWT認証、リクエスト数の制限、入力検査を利用できます。

メソッド

app

app() -> GDWebApp
英語原文

Create a routed web application.

引数

引数はありません。

戻り値

GDWebApp

エラー

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

server

server() -> GDWebServer
英語原文

Create a raw HTTP server.

引数

引数はありません。

戻り値

GDWebServer

エラー

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

text

text(body: String, status: int = 200) -> GDWebResponse

プレーンテキストのHTTPレスポンスを作ります。HTMLとして解釈させない文字列の出力に使います。

引数

名前型省略時の値説明
bodyString省略不可レスポンスの文字列。
statusint200HTTPステータス。

戻り値

GDWebResponse

プレーンテキストのContent-Typeを持つGDWebResponse。

エラー

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

関連文書

html

html(body: String, status: int = 200) -> GDWebResponse

描画済みのHTMLをレスポンスにします。この関数はテンプレートを解析せず、文字列のエスケープもしません。外部入力は先にエスケープするか、テンプレートで描画してください。

引数

名前型省略時の値説明
bodyString省略不可HTMLレスポンス本文。
statusint200HTTPステータス。

戻り値

GDWebResponse

HTMLのContent-Typeを持つGDWebResponse。

エラー

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

関連文書

json

json(data: Variant, status: int = 200) -> GDWebResponse, Err

値をJSONに変換し、HTTPレスポンスを作ります。変換に失敗する場合があるため、リクエストを処理する関数では、エラーを含む結果をそのまま返してください。

引数

名前型省略時の値説明
dataVariant省略不可JSONに変換する値。
statusint200HTTPステータス。既定は200。

戻り値

GDWebResponse, Err

成功時はGDWebResponse。

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

エラー

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

未対応の値やJSONとして不正な値はErrになります。エラーを捨ててレスポンスだけを使わないでください。

使用例

func hello(_req):
    return GD.web.json({"message": "Hello, world!"})

関連文書

bytes

bytes(body: PackedByteArray, type: String = "application/octet-stream", status: int = 200) -> GDWebResponse
英語原文

Create a binary response.

引数

名前型省略時の値説明
bodyPackedByteArray省略不可書き込む内容、またはレスポンスに含める本文。
typeString"application/octet-stream"レスポンス本文のメディア型。
statusint200HTTPレスポンスのステータスコード。

戻り値

GDWebResponse

エラー

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

stream

stream(producer: Callable, length: int = -1, type: String = "application/octet-stream", status: int = 200) -> GDWebResponse

本文を少しずつ送信するレスポンスを作ります。本文を生成する関数には、GDWebWriterが一度だけ渡されます。この関数はPackedByteArrayを書き込み、終了時にvoidまたは値とErrを返します。length=-1は長さが未定の場合です。関数内でawaitを使えますが、長く待つ場合はリクエストのキャンセルも確認してください。HEADや本文を送らないステータスコードでは、この関数を呼びません。

引数

名前型省略時の値説明
producerCallable省略不可出力先を受け取り、レスポンス本文を少しずつ書き込む関数(Callable)。
lengthint-1宣言する本文のバイト数。-1は長さが事前に決まっていないことを示します。
typeString"application/octet-stream"レスポンス本文のメディア型。
statusint200HTTPレスポンスのステータスコード。

戻り値

GDWebResponse

エラー

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

redirect

redirect(to: String, status: int = 302, away: bool = false) -> GDWebResponse
英語原文

Create a redirect response.

引数

名前型省略時の値説明
toString省略不可操作の対象となる宛先。
statusint302HTTPレスポンスのステータスコード。
awayboolfalse外部URLへのリダイレクトを許可するかどうか。

戻り値

GDWebResponse

エラー

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

guard

guard(reply: GDWebResponse) -> GDWebResponse
英語原文

Add basic security headers to a response.

引数

名前型省略時の値説明
replyGDWebResponse省略不可拡張する、または返すレスポンス値。

戻り値

GDWebResponse

エラー

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

not_found

not_found(msg: String = "Not Found") -> GDWebResponse
英語原文

Create a 404 response.

引数

名前型省略時の値説明
msgString"Not Found"この操作に添えるメッセージ。

戻り値

GDWebResponse

エラー

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

add_header

add_header(reply: GDWebResponse, name: String, value: Variant) -> GDWebResponse
英語原文

Append another response header with the same name.

引数

名前型省略時の値説明
replyGDWebResponse省略不可拡張する、または返すレスポンス値。
nameString省略不可ヘッダー名、または検証済みの値をリクエストへ保存する名前。
valueVariant省略不可保存、変換、検査など、この関数で処理する値。

戻り値

GDWebResponse

エラー

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

view

view(path: String, data: Dictionary = {  }, status: int = 200, renderer: Callable = null) -> GDWebResponse, Err

HTMLテンプレートを読み込み、値を埋め込んでHTTPレスポンスを作ります。値に含まれる特殊文字は、HTML本文や属性など、埋め込む位置に合わせて変換(エスケープ)します。

引数

名前型省略時の値説明
pathString省略不可テンプレートファイルのパス。
dataDictionary{ }テンプレートの式から参照する値。
statusint200描画成功時のHTTPステータス。
rendererCallablenull独自描画用のCallable。nullなら組み込み描画を使います。

戻り値

GDWebResponse, Err

描画したHTMLのGDWebResponse。

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

エラー

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

ファイルの読み込み、テンプレートの解析、描画の失敗をErrとして保持します。

使用例

func page(_req):
    return GD.web.view("index.html", {"name": "world"})

関連文書

view_async

view_async(path: String, data: Dictionary = {  }, status: int = 200, renderer: Callable = null) -> await GDWebResponse, Err

HTMLテンプレートを読み込み、値を埋め込んでHTTPレスポンスを作ります。値に含まれる特殊文字は、HTML本文や属性など、埋め込む位置に合わせて変換(エスケープ)します。

引数

名前型省略時の値説明
pathString省略不可テンプレートファイルのパス。
dataDictionary{ }テンプレートの式から参照する値。
statusint200描画成功時のHTTPステータス。
rendererCallablenull独自描画用のCallable。nullなら組み込み描画を使います。

戻り値

await GDWebResponse, Err

描画したHTMLのGDWebResponse。

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

エラー

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

ファイルの読み込み、テンプレートの解析、描画の失敗をErrとして保持します。

使用例

func page(_req):
    return GD.web.view("index.html", {"name": "world"})

関連文書

json_async

json_async(data: Variant, status: int = 200) -> await GDWebResponse, Err

値をJSONに変換し、HTTPレスポンスを作ります。変換に失敗する場合があるため、リクエストを処理する関数では、エラーを含む結果をそのまま返してください。

引数

名前型省略時の値説明
dataVariant省略不可JSONに変換する値。
statusint200HTTPステータス。既定は200。

戻り値

await GDWebResponse, Err

成功時はGDWebResponse。

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

エラー

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

未対応の値やJSONとして不正な値はErrになります。エラーを捨ててレスポンスだけを使わないでください。

使用例

func hello(_req):
    return GD.web.json({"message": "Hello, world!"})

関連文書

error_status

error_status(error: Err) -> int
英語原文

Return the HTTP status corresponding to an Err.

引数

名前型省略時の値説明
errorErr省略不可HTTPステータスの選択時に分類するエラー値。

戻り値

int

エラー

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

jwt

jwt(key: Variant, opts: Dictionary = {  }) -> GDWebMiddleware

BearerのJWTを検証するミドルウェアを作ります。

引数

名前型省略時の値説明
keyVariant省略不可JWTアルゴリズムが受け付ける署名・検証用の鍵。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

GDWebMiddleware

エラー

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

HS256のkeyは32バイト以上です。JSONと署名の両方を検査します。leewayは有限の0以上です。

jwt_sign

jwt_sign(claims: Dictionary, key: Variant, opts: Dictionary = {  }) -> String, Err

クレームに署名してJWTを作ります。

引数

名前型省略時の値説明
claimsDictionary省略不可JWTに入れる情報。利用者や有効期限などを含めて署名します。
keyVariant省略不可JWTアルゴリズムが受け付ける署名・検証用の鍵。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

String, Err

エラー

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

ttlは0以上です。

jwt_verify

jwt_verify(token: String, key: Variant, opts: Dictionary = {  }) -> Dictionary, Err
英語原文

Verify a JWT and return its claims.

引数

名前型省略時の値説明
tokenString省略不可検証するJWTの文字列。含まれる情報を使う前に検証します。
keyVariant省略不可JWTアルゴリズムが受け付ける署名・検証用の鍵。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

Dictionary, Err

エラー

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

jwt_sign_async

jwt_sign_async(claims: Dictionary, key: Variant, opts: Dictionary = {  }) -> await String, Err

クレームに署名してJWTを作ります。

引数

名前型省略時の値説明
claimsDictionary省略不可JWTに入れる情報。利用者や有効期限などを含めて署名します。
keyVariant省略不可JWTアルゴリズムが受け付ける署名・検証用の鍵。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

await String, Err

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

エラー

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

ttlは0以上です。

jwt_verify_async

jwt_verify_async(token: String, key: Variant, opts: Dictionary = {  }) -> await Dictionary, Err
英語原文

Verify a JWT on a CPU worker.

引数

名前型省略時の値説明
tokenString省略不可検証するJWTの文字列。含まれる情報を使う前に検証します。
keyVariant省略不可JWTアルゴリズムが受け付ける署名・検証用の鍵。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

await Dictionary, Err

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

エラー

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

csrf

csrf(opts: Dictionary = {  }) -> GDWebMiddleware
英語原文

Create CSRF middleware that permits only same-origin writes.

引数

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

戻り値

GDWebMiddleware

エラー

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

sessions

sessions(opts: Dictionary = {  }) -> GDWebSessionStore

Cookieを使うセッションの保存先とミドルウェアを作ります。

引数

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

戻り値

GDWebSessionStore

エラー

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

totalとper_userは1..2147483647、idleとlifeは1..9223372036秒を受け付けます。セッションの値は文字列と整数の識別子です。セッションはプロセス内で持ち、--workersの間では共有しません。

rate

rate(opts: Dictionary = {  }) -> GDWebMiddleware

keyごとに要求の回数を制限するミドルウェアを作ります。

引数

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

戻り値

GDWebMiddleware

エラー

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

limitと、明示したkeysは1..2147483647を受け付けます。keyはプロセス内で持ち、--workersの間では共有しません。

text_rule

text_rule(opts: Dictionary = {  }) -> Dictionary
英語原文

Create a text-length validation rule.

引数

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

戻り値

Dictionary

エラー

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

int_rule

int_rule(opts: Dictionary = {  }) -> Dictionary
英語原文

Create an integer-range validation rule.

引数

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

戻り値

Dictionary

エラー

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

number_rule

number_rule(opts: Dictionary = {  }) -> Dictionary
英語原文

Create a numeric-range validation rule.

引数

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

戻り値

Dictionary

エラー

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

bool_rule

bool_rule() -> Dictionary
英語原文

Create a boolean validation rule.

引数

引数はありません。

戻り値

Dictionary

エラー

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

list_rule

list_rule(item: Dictionary = {  }, opts: Dictionary = {  }) -> Dictionary
英語原文

Create an array item and length validation rule.

引数

名前型省略時の値説明
itemDictionary{ }確認する要素、または各要素に適用する規則。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

Dictionary

エラー

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

object_rule

object_rule(fields: Dictionary, opts: Dictionary = {  }) -> Dictionary
英語原文

Create an object-field validation rule.

引数

名前型省略時の値説明
fieldsDictionary省略不可オブジェクトのフィールド名と検証規則の対応。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

Dictionary

エラー

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

optional

optional(rule: Dictionary, fallback: Variant = null) -> Dictionary
英語原文

Add a default value for missing input to a rule.

引数

名前型省略時の値説明
ruleDictionary省略不可受け付ける入力を定義する検証規則。
fallbackVariantnull対象の値が存在しないか省略された場合に使う値。

戻り値

Dictionary

エラー

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

one_of

one_of(values: Array) -> Dictionary
英語原文

Create a rule from an allowed-value list.

引数

名前型省略時の値説明
valuesArray省略不可調べる値、または許可する選択肢の値。

戻り値

Dictionary

エラー

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

validate

validate(value: Variant, rule: Dictionary) -> Variant, Err
英語原文

Validate a value with a rule and return the safe value.

引数

名前型省略時の値説明
valueVariant省略不可保存、変換、検査など、この関数で処理する値。
ruleDictionary省略不可受け付ける入力を定義する検証規則。

戻り値

Variant, Err

エラー

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

validate_async

validate_async(value: Variant, rule: Dictionary) -> await Variant, Err
英語原文

Dispatch nested input validation to a CPU worker.

引数

名前型省略時の値説明
valueVariant省略不可保存、変換、検査など、この関数で処理する値。
ruleDictionary省略不可受け付ける入力を定義する検証規則。

戻り値

await Variant, Err

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

エラー

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

json_body

json_body(rule: Dictionary, name: String = "body") -> GDWebMiddleware
英語原文

Create JSON-body validation middleware.

引数

名前型省略時の値説明
ruleDictionary省略不可受け付ける入力を定義する検証規則。
nameString"body"ヘッダー名、または検証済みの値をリクエストへ保存する名前。

戻り値

GDWebMiddleware

エラー

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

query

query(rule: Dictionary, name: String = "query") -> GDWebMiddleware
英語原文

Create query validation middleware.

引数

名前型省略時の値説明
ruleDictionary省略不可受け付ける入力を定義する検証規則。
nameString"query"ヘッダー名、または検証済みの値をリクエストへ保存する名前。

戻り値

GDWebMiddleware

エラー

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

params

params(rule: Dictionary, name: String = "params") -> GDWebMiddleware
英語原文

Create route-parameter validation middleware.

引数

名前型省略時の値説明
ruleDictionary省略不可受け付ける入力を定義する検証規則。
nameString"params"ヘッダー名、または検証済みの値をリクエストへ保存する名前。

戻り値

GDWebMiddleware

エラー

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