gd 公式マニュアル
English | 日本語
gdは何のための道具か
gdは、GDScriptでCLIツール、Webサイト、Web API、定期処理、データ処理を書くための単体コマンドです。 画面表示を使わない小さな実行環境をGodotから作っています。project.godotを用意せず、1つの.gdファイルを書くだけで実行できます。
PythonやNode.jsでスクリプトを書く感覚で始められます。必要に応じて型検査やテストを加え、パッケージ、データベース、Webサーバーも使えます。完成したスクリプトは、1つの実行ファイルにまとめて配布できます。ゲームの画面や描画を作る用途にはGodot本家を使ってください。
Godot本家とあわせれば、アプリもフロントもサーバーもCLIツールも、一つの言語GDScriptで書けます。 同じスクリプトがmacOS、Linux、Windowsで動き、通信とデータベースの待ちはほかの処理を止めません。 GDExtensionでC++と直接つながります。
速度も重視しています。HTTP/2に対応し、通信を待つ間もほかの処理が進みます。文字列とJSONの処理も高速です。
導入
配布バイナリはmacOS arm64/x86_64、Linux x86_64、Windows x86_64向けです。Linux arm64はソースからビルドできます。 ReleasesからOSに合うアーカイブを取得し、gdをPATHの通ったディレクトリへ置く方法も使えます。
macOS / Linux
curl -fsSL https://gd.progsha.com/install.sh | sh~/.local/binへ導入します。PATHに未設定の場合だけy/Nで追加を確認します。yを選ぶと利用中のシェルに合う設定へ保存し、新しいターミナルから使えます。Linux配布バイナリにはx86_64とglibc 2.38以降が必要です。
Windows(PowerShell)
Invoke-WebRequest -UseBasicParsing https://gd.progsha.com/install.ps1 -OutFile install-gd.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-gd.ps1導入先がPATHに未設定の場合だけy/Nで確認し、yを選ぶとユーザーのPATHへ追加します。
Homebrew(macOS)
brew tap prog-sha/gd https://github.com/prog-sha/gd
brew install prog-sha/gd/gdapt(Linux amd64)
Ubuntu 24.04、Debian 13など、glibc 2.38以降のapt対応環境で利用できます。
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://gd.progsha.com/apt/gd.asc | sudo tee /etc/apt/keyrings/gd.asc >/dev/null
sudo chmod 0644 /etc/apt/keyrings/gd.asc
echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/gd.asc] https://gd.progsha.com/apt stable main' | sudo tee /etc/apt/sources.list.d/gd.list
sudo apt update
sudo apt install gd更新
gd upgrade # Move to the latest release.
gd upgrade 0.8.0 # Move to a chosen version.
gd upgrade --dry-run # Show the version without installing it.配布元のSHA-256と照合してから、実行中のgdを置き換えます。Homebrewやaptで入れたgdは、それぞれのbrew upgrade gd、apt upgrade gdで更新してください。
ソースからビルド
Python、uv、SCons、C/C++コンパイラーを用意します。実行ファイルはbin/に生成されます。
git clone --branch master https://github.com/prog-sha/gd.git
cd gd
scons platform=macos target=template_release -j8
# Linux ARM64: platform=linuxbsd arch=arm64
# Linux x86-64: platform=linuxbsd arch=x86_64
# Windows: platform=windows arch=x86_64 use_mingw=yes windows_subsystem=consoleクイックスタート
hello.gdを1つ作ります。設定ファイルやパッケージは要りません。main()が入口で、返した整数がプロセスの終了コードになります。
func main():
print("Hello, world")
return 0gd hello.gd実行せずに型と構文を調べるにはcheckを使います。
gd check hello.gdスクリプトの読み込みと共通定数
ローカルファイルは@import "./settings"、導入済みパッケージは@import hello。読み込んだ名前をそのまま使います。.gdやas settingsは省略できます。
共有する値をsettings.gdに置きます。
const TITLE = "Hello"
const USER = "world"main.gdから使います。
@import "./settings"
func main():
print(settings.TITLE, ", ", settings.USER, "!")
return 0これでHello, world!と表示します。共有が必要になったときの書き方です。
- 1つのスクリプトでしか使わない値や処理は、そのスクリプトに置けば十分です。
asは、名前がぶつかるときだけ使います。- 組み込みの
GD.webなどは、importなしで使えます。
パッケージの導入とバージョン固定はパッケージと配布を参照してください。
用途から選ぶ
標準APIはGDにまとまっています。ファイル操作はGD.file、WebサービスはGD.webのように、用途に合わせて選びます。
| やりたいこと | 入口 | 例 |
|---|---|---|
| ファイル、文字、日時、HTTP クライアント、非同期処理 | GD | GD.file.read_text("a.txt") |
| WebサイトとWeb API | GD.web | GD.web.app() |
| SQLiteまたはPostgreSQL | GD.database | GD.database.client() |
| Redis | GD.database.redis | GD.database.redis.client() |
| TCP、UDP、TLS | GD.net | GD.net.listen_tcp("127.0.0.1", 8080) |
| メールの解析とSMTP送信 | GD.mail | GD.mail.parse_address("me@example.com") |
APIの調べ方
コマンドの使い方はgd --help、コマンドごとの引数とオプションはgd install --helpのように調べます。
APIはgd doc GD.file.read_textのように、調べたい関数や型の名前を渡します。関数名・引数・戻り値の情報は、実行プログラムから取得しています。
gd doc # Show a short guide and entry points.
gd doc manual # Read the complete manual.
gd doc GD # List the standard modules.
gd doc GD.file # file API
gd doc GD.http.fetch # Inspect the returned HTTP response.
gd doc GD.web.app # Web application
gd doc SceneTree # Inspect a public engine class.
gd doc all # List public types.戻り値に使われる型のErr、GDWebRequestは名前だけで引きます。Node、SceneTree、TimerなどGodot由来の型は Godotのクラスリファレンスも参照してください。 手引きの言語はLC_ALLまたはLANGがjaで始まるとき日本語、それ以外は英語です。 Web版はgd.progsha.comにあり、日本語と英語を切り替えられます。
GDScriptの基本
掲載例では型名を繰り返しません。:=で代入する変数は右辺から型を推論します。 注釈を省いた引数は動的型です。受け取る値や返す値の型を限定したい箇所には、型名を書けます。
引数とオプション
スクリプト名の後ろに置いた引数はmain(argv)で受け取ります。--name=gdのようにgd自身のオプションと紛らわしい引数は、 --の後ろへ置くとスクリプトへ渡ります。
func main(argv):
for arg in argv:
print(arg)
return 0gd main.gd apple orange
gd main.gd -- --name=gdオプションとして解釈したいときはGD.cli.flags()を使います。--name gd、--name=gd、-name=gdのどの綴りも受けます。
func main(argv):
var flags := GD.cli.flags()
flags.flag_str("name", "world", "挨拶する相手")
var _parsed, parse_err := flags.parse(argv)
if parse_err:
print(flags.usage())
return 1
print("Hello, " + flags.get_str("name"))
return 0外のコマンドを呼ぶ
外の道具はGD.cli.run()で呼びます。待つのは呼び出したGDScriptだけなので、gd serveのハンドラーの中から呼んでも他のリクエストは進みます。 --strictでは--allow-runが要ります。--allow-run=/usr/bin/gitのように相手を絞れます。
func main():
var got, err := await GD.cli.run("git", ["rev-parse", "HEAD"])
if err:
return 1
print("code=", got["code"], " out=", got["output"])
return 0子プロセスの終了コードが0以外ならErrを返します。終了コードはvalue.code、出力はvalue.outputで読めます。時間切れやキャンセルのときも、そこまでの出力は残ります。
第3引数のoptsで挙動を変えられます。
| 名前 | 既定 | 意味 |
|---|---|---|
timeout | 0 | 完了を待つ秒数。0は無期限。時間を超えると子プロセスを終了し、Err.TIMED_OUTを返す |
output | true | 出力を集める。falseなら親の標準入出力へ直結し、集めない |
処理結果とエラー
失敗する可能性がある関数は、値とErrの2つを返します。 var 値, e :=で両方を受け取れます。型は関数の宣言から推論され、eがnullでなければ失敗です。 既存の変数には値, e = call()で代入できます。先に型なしで宣言した変数はVariantのままなので、静的に型を検査するならvar 値: Tとvar e: Errを宣言します。
func main():
var text, e := GD.file.read_text("note.txt")
if e:
print(e.text())
return 1
print(text)
return 0エラー処理を短く書く
関数呼び出しの末尾に?を付けると、失敗時は値とErrを呼び出し元へ返します。成功時は値だけを使えます。 ?を使う関数は値とErrを返します。返却型を省くとreturnの値から第一結果を推論し、必要なら-> String, Errのように明示できます。正常時のreturn 値は、第二結果のnullを省略した形です。
func title(path) -> String, Err:
var text := GD.file.read_text(path)?
return text.strip_edges()
func main():
var text, e := title("note.txt")
if e:
print(e.note("題名を読む").text())
return 1
print(text)
return 0自分でエラーを返す
ファイルを読めても、内容が空なら失敗にしたい場合は、自分でErrを作って返します。Err("説明", 種類, 追加情報)の形で、説明文、Err.INVALID_DATAなどの種類、必要な情報を指定します。次をread_message.gdに保存してください。
# Read a message and reject empty contents.
func read_message(path: String) -> String, Err:
var text := GD.file.read_text(path)?
if text.strip_edges().is_empty():
return "", Err("Message is empty", Err.INVALID_DATA, {"path": path})
return text, null
# Print the message or report the failure to the caller.
func main() -> int:
var text, err := read_message("message.txt")
if err != null:
printerr(err)
return 1
print(text)
return 0printf 'Hello!\n' > message.txt
gd read_message.gd
printf '' > message.txt
gd read_message.gd最初の実行はHello!を表示し、空ファイルにした後の実行はMessage is emptyというエラーを表示して終了コード1を返します。
-> String, Errは、文字列とエラーの2つを返すという宣言です。- 成功したら
return text, null、失敗したらreturn "", Err(...)を返します。 - 呼び出し側は
var text, err := read_message(...)で受け取り、errを確かめてからtextを使います。 - ファイルを読めなかったときは、
?がそのエラーをそのまま返します。
待つ処理と同時実行
HTTP、データベース、GD.net、ファイルなどの待つメソッドは、普通の関数呼び出しとして書けます。 待つのは呼び出したGDScriptだけで、ほかの通信やタイマーは進みます。
func main():
var res := GD.http.fetch("https://example.com/")!
print(res.status)
return 0複数の処理を同時に始めたいときは、末尾が_asyncの版とGD.async.all()を使います。
func main():
var got = await GD.async.all([
GD.http.fetch_async.bind("https://example.com/a"),
GD.http.fetch_async.bind("https://example.com/b"),
])
for result: Array in got:
var res: GDHTTPResponse = result[0]
var e: Err = result[1]
if e:
print(e.text())
return 1
print(res.status)
return 0| 入口 | 用途 |
|---|---|
名前_async() | 処理を始めて、すぐ次へ進む。後でawaitすると通常名と同じ結果を受け取れる |
GD.async.all(list) | 複数の処理を同時に進め、結果を渡した順に返す |
GD.async.spawn(fn) | 関数を裏で動かす。main()が返った後も動く |
GD.async.sleep(sec) | 指定秒だけ待つ |
1つだけ待つときはvar value, e := await GD.http.fetch_async(url)のように、通常名と同じ形で受け取れます。
気を付ける点は3つです。
all()には、上の例のように.bind()で作ったCallableを渡します。終わるのが早い処理の結果も取りこぼしません。spawn()は処理を別スレッドへ移しません。大きなデータを標準モジュールで処理するときは_asyncの版を使います。- 待つメソッドは
main()や自分で書いた関数の中で呼びます。Array.map()へ渡す関数、_init()、メンバー変数の初期化の中では待てないので、forかGD.async.all()で書きます。
チュートリアル: SQLiteを使うメモAPI
ここまでの知識で、JSONを受けてSQLiteへ保存する小さなAPIを1つのスクリプトで作ります。 できあがるのは、入力を検査し、SQL文と値を分けて渡す、権限を絞って起動する開発用サーバーです。
1. 作業ディレクトリを作る
mkdir notes-api
cd notes-api2. APIを書く
次をmain.gdとして保存します。
# Store notes in an embedded database and expose a JSON API.
extends RefCounted
const PORT := 18080 # Development listener port on loopback.
const DB_PATH := "user://notes.sqlite3" # Writable storage isolated per user.
var app := GD.web.app()
var db := GD.database.client()
# Return notes as JSON in newest-first order.
func list_notes(req: GDWebRequest) -> GDWebResponse, Err:
var got, query_err := await GD.async.with_context_pair(req.context, db.query_async("SELECT id, title FROM notes ORDER BY id DESC"))
if query_err:
return query_err
return GD.web.json(got.rows)
# Save a validated title and return the created row.
func add_note(req: GDWebRequest) -> GDWebResponse, Err:
var body := req.valid("body")
var made, query_err := await GD.async.with_context_pair(req.context, db.query_async(
"INSERT INTO notes(title) VALUES($1) RETURNING id, title",
[body.title]
))
if query_err:
return query_err
return GD.web.json(made.rows[0], 201)
# Prepare the database and routes, then listen on loopback.
func main() -> int, Err:
db.open({"driver": "sqlite", "path": DB_PATH})?
db.query("CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, title TEXT NOT NULL)")?
app.route("GET", "/notes", list_notes)
app.route("POST", "/notes", add_note, [GD.web.json_body(GD.web.object_rule({
"title": GD.web.text_rule({"min": 1, "max": 120}),
}))])
app.listen(PORT, "127.0.0.1")?
print("listening on http://127.0.0.1:%d" % PORT)
return 0上から順に読みます。
appはルーター、dbはデータベース接続です。main()が返った後もサーバーが動き続けられるよう、両方ともスクリプトの変数として持ちます。main()はまずSQLiteを開き、表を作ります。DB_PATHのuser://は、gdが利用者ごとに用意する書き込み領域です。app.route()に、HTTP メソッド、パス、そのときに呼ぶ関数(ハンドラー)を登録します。- ハンドラーは
GDWebRequestを受け取り、GD.web.json()で返事を作ります。途中の?は失敗をサーバーへ返し、ステータスコード500などになります。 - POSTには
GD.web.json_body()を付けています。本文が検証ルールに合うときだけハンドラーが呼ばれ、通った値がreq.valid("body")に入ります。 - SQLの
$1に入れる値は、別の引数で渡します。文字列連結でSQLを組み立てません。
3. 権限を絞って起動する
未確認のスクリプトや外へ公開するサーバーは、権限を既定で拒否する--strictで実行します。ここでは待ち受け先をループバックの一つのポートに絞ります。 serveはmain()が返った後もプロセスを残すコマンドで、サーバーにはこれを使います。
gd check main.gd
gd --strict --allow-net=127.0.0.1:18080 serve main.gd4. 別の端末から使う
curl -s -X POST http://127.0.0.1:18080/notes \
-H 'Content-Type: application/json' \
-d '{"title":"gdを試す"}'
curl -s http://127.0.0.1:18080/notes最初はステータス 201と作成した一件、次は保存済みの配列が返ります。空の題名、120文字を超える題名、 JSONでない本文は400で拒否されます。止めるときは起動したターミナルでCtrl-Cを押します。
公開環境ではこのプロセスをループバックのままTLS リバースプロキシの後ろへ置き、異常終了耐性が必要な保存先は PostgreSQLへ切り替えます。接続情報はソースへ書かず、許可した環境変数から読みます。
権限
最初は通常実行を使います。--strictは、必要な権限を自分で設計・設定する上級者向けの実行方式です。
| 方式 | 向く場面 | 制限 |
|---|---|---|
| 通常実行 | 信頼できるソースを開発中に動かす | ファイルもネットワークも制限しない |
--strict | 未確認のスクリプト、公開サーバー | 起動ディレクトリ配下は読み取り専用で、外部の絶対パスは拒否。ネットワーク、環境変数、子プロセス、ネイティブ拡張機能、システム情報を既定で拒否 |
--strictでは、使うものを挙げて起動します。
gd --strict \
--mount store=/srv/app:rw \
--allow-net=db.example.com:5432 \
--allow-env=DATABASE_URL \
main.gd| 指定 | 許すもの |
|---|---|
--mount name=path:r / --mount name=path:rw | 名前を付けたディレクトリの読み取り、または読み書き |
--allow-net=host:port,... | 接続と待ち受け。値を省くと全て |
--allow-env=name,... | 環境変数 |
--allow-run=command,... | 子プロセス |
--allow-ext=path,... | スクリプトが実行中に読むネイティブ拡張機能 |
--allow-sys=item,... | 機種とシステム情報 |
--deny-* | 対応するallowより優先する拒否 |
-A | ファイル以外を全て許す。開発中の一時的な利用向け |
--strictが効くのは、スクリプトを実行するrun、serve、test、task、eval、replです。checkやfmt、パッケージ操作のようにスクリプトを実行しないコマンドには影響しません。
ファイルの置き場
スクリプトから見えるファイルの置き場は次の4種類です。置き場の名前をパスの先頭に書くか、絶対パスをそのまま書きます。
| 書き方 | 指す場所 | strictでの扱い |
|---|---|---|
res://a.txt | スクリプトを起動したディレクトリ | 読み取り専用 |
user://a.txt | gdが利用者ごとに用意する書き込み領域 | 読み書き可能 |
store://a.txt | --mount store=/srv/app:rwで付けた名前 | 指定した権限 |
/etc/hosts | このコンピューター上の指定した場所 | 起動ディレクトリの外なら拒否 |
迷ったら、読むだけのファイルはres://、保存するファイルはuser://へ置きます。
- strictで起動ディレクトリの外を使うときは
--mountで名前を付けます。-Aを付けてもファイルの範囲は広がりません。 - マウント名は
storeやuploadsのように、小文字の英数字と-で付けます。res、user、file、httpなどgdが使っている名前は選べません。 - Windowsでは
--mountと絶対パスを使えません。res://かuser://へ置いてください。
ネットワークと拡張機能の許可
--allow-netのlocalhost:8080は、同じポートのIPv4 ループバック127.0.0.0/8とIPv6::1も表します。*.example.com:443はその下位ホストを許します。- ネイティブ拡張機能は同じプロセスで動くため、信頼できるものに限ってください。
serveとSceneTree
gd serveはSceneTreeを作らない常駐用の実行方式です。通信、タイマー、await、自作Signal、GD.async.sleep()、 ツリー外Nodeのqueue_free()は動きます。仕事が無ければ次の期限か通信の通知まで眠るため、周期の調整は要りません。
| やりたいこと | 方法 |
|---|---|
| Webサーバーや定期処理を常駐させる | gd serve main.gd |
Nodeの_process()、_physics_process()、process_frame、SceneTreeTimer、高水準マルチプレイを使う | serveを付けない通常実行 |
| SceneTreeやMainLoopを継承したスクリプトを動かす | serveを付けない通常実行 |
| SceneTreeが紛れ込んでいないか開発中に調べる | gd --no-scene-tree --allow-net serve app.gd |
| 複数プロセスで待ち受ける | --workers=<n>または--workers=auto。nは1以上の整数 |
serveではNodeを継承しただけのスクリプトはツリーへ追加されません。 --no-scene-treeはSceneTreeが作られた時点で診断を出し、終了コード 1で止まります。--watchと--workersの子にも引き継がれます。
エディタ
gd editorでエディタを開きます。初回は画面用の実行ファイルgd-godotを自動で導入します。
| やりたいこと | コマンド |
|---|---|
| エディタを開く | gd editor |
| プロジェクトを指定して開く | gd editor <プロジェクトディレクトリ> |
| プロジェクトを画面付きで実行する | gd run-game <プロジェクトディレクトリ> |
TCPとUDP
低水準の通信にはGD.netを使います。Godot本家の低水準の型も使えますが、新しいコードはGD.netで書きます。
func echo() -> int, Err:
var listener := GD.net.listen_tcp("127.0.0.1", 8080)?
var conn := listener.accept()?
var data := conn.read(65536)?
conn.write(data)?
conn.close()
return 0GDTCPConnは読み取りと書き込みを別々の順番待ちで処理するため、複数のGDScriptから同時に呼べます。- 期限メソッドは今からの秒数を設定し、0で解除します。
close()を呼ぶと、待っている読み書きはErr.INTERRUPTEDで終わります。リスナーの受付待ちも同じです。- 接続は名前解決で得たIPv4とIPv6の候補を順に試し、成功した一本だけを残します。全体の
timeoutは延びません。
TLS
TLSはGD.net.dial_tls(host, port, opts)で開きます。既定で証明書チェーンと接続先のホスト名を検証し、失敗しても平文へ戻りません。 戻り値はTCPと同じGDTCPConnです。
opts | 意味 |
|---|---|
timeout | 接続とTLSの初期通信が完了するまでの制限時間(秒) |
ca_file | 私設CA。環境変数の設定より優先する |
cert_file、key_file | クライアント認証。許可されたマウント内のファイルを対で指定する |
server_name | 証明書を照合する宛名を接続先と別にする |
next_protos | ALPN名の配列。1名は1–255 バイト、全体で65535バイトまで |
insecure_skip_verify | 検証を省く。検証不要と判断できる試験時だけ使う |
交渉結果はconnection_state()のnegotiated_protocolとversionで読めます。TLS1.2は771、TLS1.3は772です。
信頼するCAは、未指定ならmacOSとWindowsではOSの信頼設定、Linuxではシステム CA証明書の一覧です。 起動前にSSL_CERT_FILEまたはSSL_CERT_DIRを設定すると、どのOSでも指定したCAを使います。 ディレクトリの区切りはUnixで:、Windowsで;です。
サーバーがクライアント証明書を求めるときは、app.listen_tls(port, cert, key, host, opts)のoptsへclient_ca(信頼するCA証明書の一覧)とclient_authを渡します。 client_caが未指定ならシステムの信頼設定を使います。
client_auth | 動作 |
|---|---|
none | 証明書を要求しない |
request | 任意提示。検証しない |
require | 提示だけ必須。検証しない |
verify_if_given | 提示された場合だけ検証する |
require_and_verify | 検証済みの証明書を必須にする |
UDPと名前解決
UDPはGD.net.listen_udp()で開きます。届いたパケットには送り主のhostとportが入っているので、そのまま返信できます。
func echo_udp() -> int, Err:
var conn := GD.net.listen_udp("127.0.0.1", 9000)?
var packet := conn.read_from()?
conn.write_to(packet.data, packet.host, packet.port)?
conn.close()
return 0write_to()の宛先はIPアドレスで渡します。ホスト名は先にGD.net.resolve(name)?でIPアドレスにします。- 1回の
read_from()が1つのパケットです。受け取る大きさを超えた分は捨てられ、packet.truncatedがtrueになります。 - このコンピューターのアドレスは
GD.net.local_addresses()で調べます。
メール
GD.mailはメールアドレスやヘッダーを解析し、SMTPサーバーへメールを送ります。
send_mailには、ヘッダーと本文を含むメール全体をバイト列で渡します。- 成功は「SMTPサーバーが受け取った」という意味で、相手に届いたことまでは保証しません。
--strictでは、接続先に--allow-netが要ります。
func main() -> int, Err:
var message := "From: me@example.com\r\nTo: you@example.com\r\nSubject: Hello\r\n\r\nHello\r\n".to_utf8_buffer()
GD.mail.send_mail("smtp.example.com", 587, "me@example.com", PackedStringArray(["you@example.com"]), message, {
"tls": "starttls", "timeout": 10.0,
"auth": GD.mail.plain_auth("me@example.com", "secret"),
})?
return 0ファイルとデータ
GD.fileでファイルの読み書きとパス操作をします。起動したディレクトリがres://で、絶対パスも書けます。 strictで外部ディレクトリへ書くときは--mount store=/srv/app:rwで付けた名前をstore://users.csvのように書きます。
func main() -> int, Err:
var rows := GD.data.csv_objects(GD.file.read_text("store://users.csv")?)?
GD.file.write_text("store://users.json", JSON.stringify(rows))?
return 0ファイルの操作は、通常名でも呼び出したGDScriptだけを待たせます。Webサーバーのハンドラーから読んでも他のリクエストは進みます。 複数の操作を同時に始めるときだけ、末尾が_asyncの版を使います。
func handler(_req) -> GDWebResponse:
var body, read_err := GD.file.read_text("store://big.json")
if read_err:
return GD.web.text("読めません", 500)
return GD.web.text(body)compileで同梱したファイルも、同じAPIで読み取り、列挙、static配信ができます。
大きなファイルを読む
全体をメモリへ置かず読むときはGD.file.open(path, mode)でGDFileStreamを開きます。 modeはread、write、append、read_writeで、使い終えたらclose()を呼びます。
| メソッド | 動作 |
|---|---|
read(max) | 最大max バイトを返す。少なく返ることがある。maxが正のとき、エラーがなく空ならファイルの末尾まで読み取り済み |
write(bytes) | 全て書いてバイト数を返す。途中で失敗しても第一結果に書き込み済みバイト数が残る |
同じストリームの操作は受付順、別のストリームは並列に進みます。appendはseekの後も常に末尾へ書きます。 read_bytes()も途中で失敗したときは取得済みのバイト列を第一結果に残します。 read_text()はStringに収まらない大きさの入力を切り詰めずエラーにするので、大きなファイルはバイト列かストリームで扱います。
同時に更新されるファイル
複数のプロセスが同じファイルを更新するときはGD.file.replace_text(path, old, body)を使います。 読み取ったoldと現在の内容が同じときだけ置き換えるため、並行編集を黙って上書きしません。新規作成ではoldにnullを渡します。
データ形式の入口
| 用途 | 入口 |
|---|---|
CSV、TOML、YAML、JSONL、JSONC、XML、INI、TAR、front matter、.envのファイルを読む | GD.file.read_csv(path)など |
| 同じ形式のメモリ上の変換、JSON、エンコード・デコード、ハッシュ、HMAC、PBKDF2、HKDF、バイト列 | GD.data |
| UUIDとULID | GD.id |
| 日時の変換と計算 | GD.time |
| 文字の整形と比較 | GD.text |
| HTML エンティティ、タグ、gdhtml(Mustache構文のマイクロテンプレート) | GD.html |
| オプションと環境変数 | GD.cli |
| 配列と辞書の操作 | GD.collection |
| 数学の特殊値とビット演算 | GD.math |
| バージョンの比較 | GD.version |
| ターミナルとファイルへのログ | GD.log |
| テストの検査 | GD.test |
環境変数と.envは、読む対象で入口が分かれます。
| 読む対象 | 入口 |
|---|---|
| プロセスの環境変数 | GD.cli.env(name, fallback)、GD.cli.require_env(name)。strictでは--allow-envが要る |
.env ファイル | GD.file.read_env(path)。ファイルを読んで辞書にする |
| dotenv形式の文字列 | GD.data.env(src)とGD.data.to_env(data)。メモリ上で辞書と変換する |
メモリ上の変換は通常名がその場で計算し、_asyncの版は別のスレッドで計算します。大きな入力には_asyncを使います。 正確な一覧はgd doc GD.fileとgd doc GD.dataで引けます。形式ごとの検査と上限は、APIリファレンスの各入口の説明にあります。
GD.collectionのCallableを使う操作は、約1 msごとにほかの処理へ実行権を譲ります。 GD.logの各呼び出しは書き込み完了まで待ち、本文を切り捨てません。失敗は第二結果のErrで確認でき、GD.log.flush()でそれ以前の出力完了を待てます。
JSONの規則
値はGD.data.json_encode(value)でJSONのバイト列にし、受け取ったバイト列はGD.data.json_decode(bytes)で読みます。 GDWebRequest.json()、GDHTTPResponse.json()、JSONLの各行も同じ規則です。
func main() -> int, Err:
var bytes := GD.data.json_encode({"id": 1, "tags": ["a", "b"]})?
var value := GD.data.json_decode(bytes)?
print(value.id)
return 0- 整数は
intのまま戻ります。小数と指数表記はfloatになります。 - 壊れた文字コードや同じ名前の重複など、あいまいなJSONは読まずに失敗にします。
- 署名やキャッシュのキーのように、同じ値から毎回同じバイト列が要るときは
{"deterministic": true}を渡します。
ハッシュと鍵導出
GD.dataはSHA-1、SHA-224/256/384/512、SHA3-224/256/384/512を返します。HMAC、PBKDF2、HKDFでは sha1、sha224、sha256、sha384、sha512、sha3-224、sha3-256、sha3-384、sha3-512から方式を選べます。 PBKDF2とHKDFは出力長を指定でき、不正な方式や表現範囲外の設定はErrとして返します。PBKDF2の繰り返す回数が1以下なら1回として計算します。
Webフレームワーク
同じディレクトリにmain.gdとindex.htmlを作ります。一方のルートでHTMLテンプレートに挨拶を埋め込み、もう一方で同じデータをJSONとして返します。
main.gd:
# Serve a greeting as an HTML page and a JSON response.
var app := GD.web.app()
# Build the shared response data from the requested name.
func greeting(req: GDWebRequest) -> Dictionary, Err:
var name := req.query.get("name", "world")
if not name is String:
return {}, Err("name must be text", Err.INVALID_DATA)
return {"name": name, "message": "Hello, " + name + "!"}
# Render the page with escaped template values.
func home(req: GDWebRequest) -> GDWebResponse, Err:
return GD.web.view("index.html", greeting(req)?)
# Return the same data as JSON.
func hello(req: GDWebRequest) -> GDWebResponse, Err:
return GD.web.json(greeting(req)?)
# Listen locally, using an optional port argument.
func main(args):
var port := 8080 if args.is_empty() else int(args[0])
app.route("GET", "/", home)
app.route("GET", "/api/hello", hello)
app.listen(port, "127.0.0.1")!
print("http://127.0.0.1:", app.port())
return 0index.html:
<!doctype html>
<!-- Display a greeting and let visitors choose the name. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{message}}</title>
<style>
body { max-width: 36rem; margin: 4rem auto; padding: 0 1rem; font-family: system-ui, sans-serif; line-height: 1.6; }
input, button { padding: .6rem; font: inherit; max-width: 100%; box-sizing: border-box; }
</style>
</head>
<body>
<h1>{{message}}</h1>
<form action="/" method="get">
<label>Your name <input name="name" value="{{name}}"></label>
<button type="submit">Say hello</button>
</form>
<p><a href="/api/hello?name={{name}}">View the JSON response</a></p>
</body>
</html>そのディレクトリで実行します。
gd serve main.gdhttp://127.0.0.1:8080/?name=Aliceを開くと、{{message}}へ「Hello, Alice!」を埋め込みます。/api/hello?name=Aliceは{"name":"Alice","message":"Hello, Alice!"}を返します。テンプレートの値はHTMLの文脈に応じてエスケープされます。
serveはmain()が返ったあとも待ち受けを続けます。終了はCtrl+Cです。
ルートと返事
route(method, pattern, handler)でHTTP メソッドとパスをハンドラーへ結びます。patternの:nameはreq.params["name"]に入ります。 HEADの要求にはGETのルートで応えます。パスは合うのにメソッドが違う要求には405を返します。 ハンドラーはGDWebRequestを受け取ります。本文はreq.read()、bytes()、text()、json()、save()で必要な分だけ読みます。 HTMLのフォームから届く本文はGD.http.decode_query(req.text()?)で辞書にします。
ハンドラーが返した値が返事になります。return GD.web.json(data)のように、下の表の値をそのまま返します。
途中の操作が失敗したら、call()?でそのErrを返します。Errは表の最後の行のステータスコードになります。返事を自分で決めたいときはapp.on_error(handler)を登録します。
| 返した値 | 返事 |
|---|---|
GD.web.html(body)、GD.web.view(path, data) | HTML |
GD.web.json(data) | JSON |
GD.web.text(body)、GD.web.bytes(body, type) | テキスト、任意のメディアタイプ |
GD.web.stream(producer) | 本文を少しずつ送信する。「Webの運用と高度な機能」を参照 |
GD.web.redirect(to) | 302。toは同じサイト内のパスに限り、他所へ送るときはawayをtrueにする |
GD.web.not_found() | 404 |
| 文字列 | テキスト/plainの200 |
bodyを持つ辞書 | 手書きの返事。status、type、headersも指定できる |
bodyを持たない辞書 | JSONの200 |
null | 204 |
失敗のErr | 種類に応じたステータスコード。INVALID_DATA → 400、UNAUTHENTICATED → 401、PERMISSION_DENIED → 403、NOT_FOUND → 404、LIMITED → 429、UNSUPPORTED → 501、TIMED_OUT → 504、他は500(いずれもErrの定数) |
返事は次のように調整できます。
- ステータスコードは
GD.web.text("見つかりません", 404)のように第2引数で変えます。bytesはメディアタイプの後ろに書きます。 GD.web.header(reply, name, value)で返事にヘッダーを足します。GD.web.guard(reply)でContent-Security-Policyなどの防御ヘッダーをまとめて足します。- 失敗の理由は既定では本文に出しません。開発中は
app.show_errors(true)で表示できます。 req.queryの値は文字列とは限りません。上の例のようにis Stringで確かめてから使います。req.pathは%20などを元の文字へ戻したパスです。届いたままの文字列はreq.targetで読めます。
ルーターには次も登録できます。
| 登録 | 用途 |
|---|---|
app.static("/assets", "res://public") | 接頭辞以下のGETとHEADをディレクトリのファイルで返す。メディアタイプは拡張子から決め、ディレクトリの外は返さない。/のindexはrouteで書く |
app.group("/api", [middleware]) | 共通接頭辞とミドルウェアを持つルートグループ。戻り値にroute()とuse()がある |
app.fallback(handler) | どのルートにも一致しない要求。404ページをここで返す |
app.on_error(handler) | ハンドラーが失敗を返したときの返事 |
app.after(handler) | 返事を送る前の加工。func(req, reply)で受け、ヘッダーを足して返す |
ミドルウェア
ミドルウェアは、ハンドラーの前に呼ばれる関数です。GDWebRequestを受け取り、nullを返すと次へ進み、返事を返すとそこで止まります。 handle(req)を持つオブジェクトも使えます。後段へ渡す値はreq.keep(name, value)で置き、req.kept(name)で読みます。
| 登録 | 掛かる範囲 |
|---|---|
app.pre(mw) | ルート選択の前。全要求 |
app.use(mw) | ルート選択の後。全ルート。req.paramsを読める |
group.use(mw) | そのグループのルート |
app.route(method, pattern, handler, [mw]) | そのルートだけ |
入力検査もミドルウェアです。GD.web.json_body(rule)、GD.web.query(rule)、GD.web.params(rule)が本文、クエリ、パスの値を検査し、 通った値をreq.valid("body")、req.valid("query")、req.valid("params")に入れます。 検証ルールはGD.web.text_rule()、int_rule()、number_rule()、bool_rule()、list_rule()、object_rule()で組み、 GD.web.optional()とGD.web.one_of()で省略と選択肢を表します。クエリとparamsの値は文字列なのでtext_rule()で検査し、必要ならto_int()で変換します。
var app := GD.web.app()
func show(req) -> GDWebResponse, Err:
var params := req.valid("params")
return GD.web.json({"id": params.id})
func main():
app.route("GET", "/posts/:id", show, [GD.web.params(GD.web.object_rule({"id": GD.web.text_rule({"min": 1, "max": 20})}))])
app.listen(8080)!
return 0組み込みのミドルウェアはGD.web.sessions()、GD.web.csrf()、GD.web.jwt()、GD.web.rate()です。認証の節で使います。
HTMLテンプレート
ページが増えてきたらHTMLをテンプレートファイルへ出し、GD.web.view(path, data)で描画します。 テンプレートはgdhtml(Mustache構文のマイクロテンプレート)で、{{name}}、{{{html}}}、#if、#unless、#each、 #with、else、{{> header}}を扱います。views/page.htmlから{{> header}}を使うと、 同じ階層のviews/partials/header.htmlを読みます。
<!-- views/page.html -->
{{> header}}
<main><h1>{{title}}</h1></main><!-- views/partials/header.html -->
<header><a href="/">gd app</a></header>func page(_req) -> GDWebResponse, Err:
return GD.web.view("views/page.html", {"title": "Top"})二重括弧の値は、置かれた位置から文脈を判定してエスケープします。テンプレートの作者を信頼し、差し込む値を信頼しない前提です。
| 文脈 | 扱い |
|---|---|
| HTML本文、引用・未引用属性、属性名 | HTML エスケープ |
href="{{url}}" | 相対URLとhttp、https、mailtoを通す。data-hrefも同じ |
href="/work/{{path}}"、href="/?q={{query}}" | パスは区切りを保って正規化、クエリはpercent エスケープ |
onclick、script本文 | JSON化し、application/jsonでも</script>が構造を壊さない形にする |
style | 安全な単独CSS値とCSS文字列・URLを通す |
| 危険なURL、srcset、CSS値、属性名 | 画面全体を失敗させず、#ZgdunsafeZまたはZgdunsafeZへ置き換える |
- 三重括弧
{{{html}}}はエスケープしない唯一の入口で、HTML本文以外では使えません。固定HTMLか十分に検査済みの値だけを渡してください。 - 「検査済み」の印を付けて二重括弧のエスケープを省く方法はありません。
- 分岐の両側や
eachの反復が異なる文脈で終わるテンプレート、閉じていないタグ、曖昧なURLやJavaScript文脈は描画の失敗になります。 - テンプレートの大きさに固定上限はありません。再帰する部品の深さだけは100000までです。
- 描画が終わるまで、渡した辞書を変更しないでください。
同じテンプレートを何度も描画するサーバーでは、起動時にGD.html.template(source, partials)?で一度だけ解析し、 返った値のexecute(data)?を各要求から呼びます。解析結果は不変で、複数の要求から同時に使えます。 execute_bytes(data)?はUTF-8のバイト列を直接作るので、GD.web.bytes(body, "text/html; charset=utf-8")でそのまま返せます。
認証とCSRF
ログインの状態はGD.web.sessions()で持ちます。issue(value)でセッション IDを作り、cookie(id)の値をSet-Cookieで返します。 同じstoreをミドルウェアとして付けたルートでは、CookieのIDに対応する値がreq.kept("user")に入り、無ければ401になります。 ミドルウェアの設定が不正なら生成関数はnullを返し、app.use()やルートに渡した場合はapp.listen()が設定エラーを返します。
var app := GD.web.app()
var sessions := GD.web.sessions()
func login(req: GDWebRequest) -> GDWebResponse, Err:
var form := GD.http.decode_query(req.text()?)?
var user := str(form.get("user", [""])[0])
if user.is_empty():
return GD.web.text("user is required", 400)
var reply := GD.web.redirect("/me")
return GD.web.header(reply, "Set-Cookie", sessions.cookie(sessions.issue(user)?))
func me(req) -> GDWebResponse, Err:
return GD.web.text("hello, " + str(req.kept("user")))
func main():
app.route("POST", "/login", login)
app.route("GET", "/me", me, [sessions])
app.listen(8080)!
return 0cookie(id)はSecureとHttpOnly付きで作ります。TLSなしの開発中に届かない場合はcookie(id, false)にします。 ログアウトはdrop(id)とclear_cookie()で行います。セッションはプロセス内で持つため、--workersで複数プロセスにするときはJWTか外部の保存先を使います。
Cookieで認証する書き込み経路にはGD.web.csrf()を付けます。GET、HEAD、OPTIONS以外はブラウザーの Sec-Fetch-Site: same-originが必要です。古いブラウザーやブラウザー以外のクライアントも受ける場合に GD.web.csrf({"allow_missing": true})を選び、別のトークン検証を組み合わせてください。
var app := GD.web.app()
var sessions := GD.web.sessions()
func save_email(_r):
return "saved"
func main():
app.route("POST", "/account/email", save_email, [GD.web.csrf(), sessions])
app.listen(8080)!
return 0JWTをログインセッションに使う場合は、パスワード変更やログアウトで既発行トークンを失効させます。 checkは署名と標準クレームの検証後に呼ばれ、trueを返したときだけ認証を通します。 例えばトークンへ利用者のverを入れ、パスワード変更時に保存済みバージョンを増やします。 複数ワーカーでは各プロセスの辞書でなく、共有DBから同期したキャッシュなどで照合します。
func token_auth(key, versions):
return GD.web.jwt(key, {"check": func(claims):
return versions.get(claims.get("sub", ""), -1) == claims.get("ver", -2)
})リバースプロキシの後ろでIP単位に制限するときは、そのプロキシのIPまたはCIDRをtrusted_proxiesへ明示します。 gdはX-Forwarded-Forの右端から信頼済みプロキシを除き、最初の未信頼IPをkeyにします。 未指定のときと未信頼の接続元からのX-Forwarded-Forは無視するため、クライアント自身によるIP偽装を許しません。 IPv4とIPv4-mapped IPv6は別物として照合するので、mapped アドレスを信頼する場合はIPv6のCIDRを指定します。zone付きのプロキシ設定は拒否します。
var per_ip := GD.web.rate({"limit": 60, "trusted_proxies": ["127.0.0.1", "172.18.0.0/16"]})制限を通過した応答と429応答にはX-RateLimit-LimitとX-RateLimit-Remainingが付きます。429応答には、再試行までの秒数を示すRetry-Afterも付きます。
停止
終了待ちはapp.shutdown(context)を使います。新規受付とkeep-aliveを止め、処理中リクエストの完了を待ちます。 期限を越えた場合はErr.TIMED_OUTを返しますが、処理中リクエストは強制終了しません。 直ちに全接続を閉じる必要がある場合にapp.stop()を使います。
func close(app: GDWebApp):
var context := GD.async.context().with_timeout(10.0)
var _stopped, stop_err := app.shutdown(context)
if stop_err:
app.stop()ハンドラーではreq.contextからリクエストの完了と切断を受け取れます。 with_cancel()とwith_timeout()は親を変更せず子のコンテキストを返し、親の打ち切りは子へ伝わります。 HTTP、データベース、プロセスなどの二値の待ちを打ち切れるようにするには、コンテキストを先頭に渡してwith_context_pair()で包みます。一値のSignalにはwith_context()を使います。 処理が先に終わればその結果を返し、コンテキストが先に終われば処理を取り消します。
func load(req: GDWebRequest, db: GDDatabaseClient) -> Variant, Err:
return await GD.async.with_context_pair(req.context, db.query_async("SELECT * FROM posts"))Webの運用と高度な機能
上限と大きなアップロード
大きな本文や長いハンドラーを扱うときは、待ち受け前にlimits()で上限を明示します。
func main():
var limited_app := GD.web.app()
limited_app.limits({"header_bytes": 1048576, "header_values": 500, "header_timeout": 15.0, "body_timeout": 10.0, "job_timeout": 30.0, "jobs": 128})
return 01 GBのZIPを受ける場合は要求ごとの上限を置き、書き込み可能なマウントへ逐次保存します。
func main():
var app := GD.web.app()
app.limits({"body_timeout": 600.0})
app.route("POST", "/upload", func(req: GDWebRequest) -> GDWebResponse, Err:
req.limit(1000 * 1000 * 1000)?
req.save("uploads://package.zip")?
return GD.web.text("saved")
)
var _server, listen_err := app.listen(8080, "127.0.0.1")
return 0 if listen_err == null else 1gd --strict --allow-net=127.0.0.1:8080 --mount=uploads=/srv/uploads:rw serve main.gd本文の読み方で、使うメモリが変わります。
| 読み方 | メモリの使い方 |
|---|---|
read()、save() | 少しずつ読む。save()は全体をメモリへ置かない |
bytes()、text()、json() | 残りの本文全体をメモリへ読む。大きな本文にはsave()を使う |
req.limit(bytes) | その要求の本文の上限。超えると、読んだ操作が失敗する |
- 本文の大きさに既定の上限はありません。外へ公開するサーバーでは
req.limit()を置きます。 - リクエストヘッダーは既定で1 MiBまでです。
limits()のheader_bytesで変えられます。 - 遅い接続が待たせるのはその接続だけです。
本文を少しずつ送信する
GD.web.stream(producer, length=-1, type="application/octet-stream", status=200)は、producer(writer)がGDWebWriterへ書いた分だけ送ります。 全体をメモリに結合しません。本文を生成する関数の中でawaitでき、voidまたは二値を返して終わります。
GDWebWriter | 動作 |
|---|---|
write(data, offset=0, count=-1) | バイト列の範囲を送り、受け付けたバイト数を返す。送信が詰まっていれば進むまで待つ |
write_text(text, offset=0, count=-1) | 文字列の範囲をUTF-8で送る。offsetとcountの単位は文字、結果の単位はバイト |
flush() | それまでのwriteの送信完了を待つ。切断はここのエラーとreq.contextのキャンセルでわかる |
- ストリームは一回限りです。応答ごとに新しく作ります。受信本文はストリームを返す前に読み終えてください。
lengthは送るバイト数です。宣言と実際が合わないと接続を閉じます。不明長(-1)はHTTP/2でDATA フレーム、HTTP/1.1でchunked、HTTP/1.0で接続終了が終端になります。- HEADと本文を持てないステータスコードでは本文を生成する関数を呼びません。
- 長く待つ本文を生成する関数では
req.contextのキャンセルを確認してください。 - 1回のwriteが1つのデータ片に対応するとは限りません。空の文字列や空のバイト列は終端になりません。
HTTPSとHTTP/2
HTTPSはapp.listen_tls(8443, "cert://chain.pem", "cert://key.pem", "127.0.0.1")で開始し、第二結果のErrを確認します。 証明書のディレクトリは--mount cert=/path/to/certs:rで読み取り専用にします。PEM形式の証明書チェーンと暗号化されていない秘密鍵を渡します。 鍵の検証に失敗したときはポートを開きません。
TLS 1.2と1.3に対応し、ALPNでHTTP/2とHTTP/1.1を選びます。HTTP/2の各ストリームは独立に進み、一つのキャンセルは他のストリームを閉じません。 header_timeoutは完了していないTLSの初期通信にも適用されます。クライアント証明書の要求は「TCPとUDP」のTLSの表を参照してください。
gzip圧縮
GD.data.gzip_writer(writer, level=-1)は、書いたバイト列をgzipにして出力先へ渡すGDGzipWriterを作ります。 出力先にはGDFileStream、TCP接続、GDWebWriterを使えます。全体をメモリに貯めません。
| 項目 | 内容 |
|---|---|
| メソッド | write(bytes)、flush()、close()、reset(writer)。どれも値とErrを返す |
level | -2(Huffmanのみ)、-1(既定)、0..9 |
close() | gzipの末尾を完成する。出力先は閉じない |
reset(writer) | エラーを消し、同じlevelで使い回す |
header | name、comment(NULを含まないLatin-1)、extra(65535 バイトまで)、mod_time(0〜4294967295のUnix秒)、os(既定255)。最初の書き込みより前に設定する |
HTTPで返すときはGD.web.header(GD.web.stream(producer), "Content-Encoding", "gzip")を返し、本文を生成する関数の中で圧縮器を作って書き、close()の結果を返します。 Accept-Encodingの確認とVaryの設定は呼び出し側で行います。秘密情報と外部入力を一緒に圧縮せず、圧縮済みの本文や部分応答には使わないでください。
待ち受けアドレスとポート
IPv6のlocalhostだけで待ち受けるにはapp.listen(8080, "::1")!を指定します。strictでは--allow-net=[::1]:8080、接続先はhttp://[::1]:8080/です。 ::1と127.0.0.1は別の待ち受けで、全インターフェースを示す::とも異なります。
空きポートをOSに選ばせる場合はapp.listen(0)の直後にapp.port()を読みます。待ち受けを保持したまま番号を得るので、他のプロセスに取られません。 待受け開始後のソケット障害はapp.serve_error()で確認できます。一時的な資源不足では短く待って再試行し、継続できない障害では待受けを閉じます。 strictでは選ばれるポートを事前に限定できないため、--allow-net=127.0.0.1のようにホスト全体を許可します。 GD.net.free_port()とis_free()は診断用の瞬間的な確認で、その番号を確保する機能ではありません。
HTTP クライアントの接続
- HTTPSではHTTP/2を使い、同じ宛先への並行要求は一本の接続を共有します。非対応の相手と平文HTTPにはHTTP/1.1を使います。
- HTTP/1.1の接続は、本文を末尾まで読むと同じ宛先へ再利用します。空き接続は全体100本、宛先ごと2本、90秒まで保持します。
- 再利用した直後に閉じられた場合、安全に再送できるメソッドだけ1度開き直します。
- HTTP/2では、相手が未処理と明示した要求だけを最大7回、間隔を延ばしながら再送します。要求の期限とキャンセルは守ります。
Webの設定一覧
GD.http.fetch()とGD.webの各関数に辞書で渡す設定と、その既定値です。時間は秒、大きさはバイトです。
| 入口 | 設定と既定 | 意味 |
|---|---|---|
GD.http.fetch | method="GET", headers={}, body=null | HTTP メソッド、送信ヘッダー、送信本文 |
| 同上 | timeout=0.0, max_body=0 | 要求全体の秒と応答本文のバイト。0は上限なし。新規TCP接続は30秒、TLS初期通信は10秒が既定 |
| 同上 | save="", sha256="" | 2xx 本文をsaveへ逐次保存し、返却本文は空。sha256はsave必須の64桁16進数で、一致した完了ファイルだけを置く |
| 同上 | authority="host:port" | CONNECTだけのリクエストの送信先 |
GDWebApp.limits | jobs=0, job_timeout=0.0 | 保持する非同期ハンドラー数と秒。0は無制限 |
| 同上 | header_timeout=0.0, body_timeout=0.0 | リクエストヘッダー/bodyを受け終える秒。0は無期限 |
| 同上 | header_bytes=1048576, header_values=2147483647 | リクエスト lineを含むヘッダー バイトと、ヘッダー行数 |
GD.web.jwt_sign | ttl=900 | iat/expを補う秒。0は自動付与しない |
GD.web.jwt / jwt_verify | leeway=0.0, require_exp=true | 時刻許容秒とexp必須化 |
| 同上 | iss="", aud="", keep="jwt" | 空でない場合のissuer/audience一致と保持名 |
| 同上 | check=Callable() | 署名検証後にクレームを受け取る失効判定。指定時は真だけを許可 |
GD.web.sessions | total=1024, per_user=3 | プロセス内の全セッション数と同一ユーザー数 |
| 同上 | idle=1800, life=43200 | 操作がない場合の有効期間と、セッション全体の有効期間(秒) |
| 同上 | cookie="sid", keep="user" | Cookie名とリクエスト内の保持名。Cookie名はASCIIのトークン文字 |
GD.web.rate | limit=60, window=60.0 | keyごとの最大連続回数と、その回数分を補充する時間(秒) |
| 同上 | expires=180.0 | 最後の要求からkeyを解放するまでの秒数 |
| 同上 | keys=0, key=Callable() | プロセス内で保持するkey数とkey選択関数。0は無制限。明示した保持枠が満杯なら期限が最も早いkeyを追い出す |
| 同上 | trusted_proxies=PackedStringArray() | 転送元IPを信頼するプロキシのIPまたはCIDR |
GD.web.csrf | allow_missing=false | 状態変更でFetch Metadataが無いクライアントを許すか |
GD.web.text_rule | min=0, max=4096 | テキストの文字数 |
GD.web.int_rule | min=-9223372036854775808, max=9223372036854775807 | 64ビット整数の範囲 |
GD.web.number_rule | min=-1e308, max=1e308 | 有限浮動小数の範囲 |
GD.web.list_rule | min=0, max=1024 | 要素数 |
GD.web.object_rule | extra=false | 未定義フィールドを残すか |
GDWebApp.limitsは表にある6つの設定名だけを受け、綴り違いやbody_limitを誤りとして拒否します。
範囲外の値は設定時に失敗します。受け付ける範囲は、APIリファレンスの各関数の説明にあります。
データベース
GD.database.client()が返すクライアントは、SQLiteとPostgreSQLを同じ書き方で扱います。 ローカル開発は組み込みSQLite、本番はPostgreSQLという切り替えは、open()に渡すdriverで行います。
func main() -> int, Err:
var local := GD.cli.env("DB_DRIVER", "sqlite") == "sqlite"
var db := GD.database.client()
db.open({
"driver": "sqlite" if local else "postgres",
"path": "user://app.sqlite3",
"host": "127.0.0.1",
"database": "app",
"user": "app",
"password": GD.cli.env("PGPASSWORD", ""),
})?
db.query("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")?
db.query("INSERT INTO users (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [1, "ada"])?
var out := db.query("SELECT id, name FROM users WHERE id=$1", [1])?
print(out.rows[0].name)
db.close()
return 0表の作成もINSERTもSELECTもquery()一つで送ります。受け取るのはcolumns、rows、tagを持つ辞書で、 rowsは列名を鍵にした辞書の配列です。上の例ならout.rows[0].nameがadaになります。 SQLに入れる値は、$1、$2に対応する順番で渡します。両ドライバーで同じ書き方です。SQLは変換しないため、両方で通るSQLを使います。
| メソッド | 用途 |
|---|---|
query(sql, args) | 結果を全部集めて返す |
query_row(sql, args) | 先頭1行だけ返す。行が無ければErr.NOT_FOUND |
query_rows(sql, args) | GDDatabaseRowsを開き、1行ずつ読む。大量の結果向き |
stats() | 接続数、使用中、空き、待ち回数、待ち時間、接続を閉じた理由別の累積数 |
query_rows()はwhile rows.next()で進め、scan()で列名付きの辞書、values()で列順の配列を得ます。 next()がfalseになったらerr()を調べます。途中で止める場合はclose()を呼びます。
func list_users(db: GDDatabaseClient) -> Variant, Err:
var rows := db.query_rows("SELECT id, name FROM users ORDER BY id")?
while rows.next():
var user := rows.scan()?
print(user.id, " ", user.name)
if rows.err() != null:
return null, rows.err()
return null制約違反では第二結果のe.infoにプログラムでの判定用の情報が入ります。violationはduplicate、not_null、foreign_keyのいずれか、 columnsは関係する列名です。PostgreSQLではcode、table、constraintもサーバーが返した場合に入ります。 値そのものはinfoへ残しません。SQLite自身が報告した失敗ではsource="sqlite"と拡張source_codeを保ちます。 SQLiteのforeign keyエラーメッセージには列名が無いため、その場合のcolumnsは空です。
func save(db: GDDatabaseClient) -> void:
var _saved, e := db.query(
"INSERT INTO users(id,name) VALUES($1,$2)",
[1, "ada"])
if e and e.info.get("violation") == "duplicate":
var columns := e.info.get("columns", PackedStringArray())
print("重複した列: ", columns)トランザクションとマイグレーション
複数の更新をまとめて確定または取り消したいときはtransaction()を使います。渡した関数には、専用の接続を使う GDDatabaseTxが渡ります。コールバックの第二結果がnullならコミットし、Errならロールバックします。
func save(db: GDDatabaseClient, id: int, title: String) -> Variant, Err:
return db.transaction(func(tx: GDDatabaseTx) -> int, Err:
tx.query("INSERT INTO posts(id,title) VALUES($1,$2)", [id, title])?
tx.query("UPDATE counters SET value=value+1 WHERE name='posts'")?
return id
)- コールバックの中では、渡された
txだけでSQLを実行します。元のdb.query()はこのトランザクションに入りません。 - コミットの失敗はそのまま失敗として返ります。
- close()やキャンセルはCOMMITの開始前ならロールバックし、開始後なら結果が確定してから接続を閉じます。
- コールバックが終わった後は、保存しておいた
txも新しいSQLを受け付けません。
PostgreSQLで、同時に走る別のトランザクションとぶつかって失敗する場合(SQLSTATE 40001)は、serialize()でやり直せます。
- 渡す関数は
transaction()と同じ形で、やり直すたびに新しいトランザクションで呼ばれます。 - やり直しは最大10回です。別のエラーやキャンセルではそこで止まります。
- メール送信のように取り消せない処理は、関数の外で行ってください。
func increment(db: GDDatabaseClient, id: int) -> int, Err:
var saved, e := db.serialize(func(tx: GDDatabaseTx) -> int, Err:
tx.query("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE")?
tx.query("UPDATE counters SET value=value+1 WHERE id=$1", [id])?
return id
)
return saved, eテーブル構成を順番に適用するときは、SQLをセミコロンで分割せず、SQL文の配列をmigrate()へ渡します。 途中の一文が失敗すると全体をロールバックし、成功時は適用した文の数を返します。 バージョンとチェックサムはアプリケーション側で管理します。
func migrate(db):
return db.migrate([
"CREATE TABLE posts(id INTEGER PRIMARY KEY, title TEXT NOT NULL)",
"CREATE INDEX posts_title ON posts(title)",
])データベースの高度な機能
ドライバーの違い
| 項目 | SQLite | PostgreSQL |
|---|---|---|
| 向く用途 | ローカル開発、単一プロセス | 本番、異常終了耐性、複数ワーカー |
| 接続 | クライアントごとに一つ。変更履歴と一時表はメモリに置く | 必要な接続だけ作るプール。pool=25のように最大数を指定できる |
| 追加の入口 | 短い処理をその場で行うGD.database.sqlite.open() | まとめ送り、配列、JSONBを使うGD.database.postgres |
| 注意 | 永続DBはrollback journalで未完了の書込みを回復する。既存の-wal、-shmは通常のSQLiteでチェックポイントしてから開く | ループバック以外のホストではTLS証明書とホスト名を既定で検証。ループバックはTLSなしが既定 |
GD.database.postgres.client()とGD.database.redis.client()のopen()はopen(host, port, opts)の形で、接続先を引数に取ります。
SQLiteの並行
同じクライアントのquery()は受付順に実行します。別のクライアントは並行に進みますが、同じデータベースファイルへの書き込みはSQLiteのロックに従います。 GD.database.sqlite.open()が返すGDSQLiteDBとGDSQLiteStatementは、呼び出し元でそのまま実行する同期APIです。 短い処理だけに使い、同時利用はしないでください。並行処理にはGDDatabaseClientを使います。
PostgreSQLの接続と型
接続はプールが必要な分だけ作り、使い終わると戻します。ふだんは接続を意識せずquery()を呼ぶだけです。空きが無いときは順番に待ちます。
| やりたいこと | 方法 |
|---|---|
| 複数のSQLを1つのまとまりで実行する | BEGINを自分で送らずtransaction()を使う |
| 複数のSQLをまとめて送る | query_many、fetch_many、exec_many |
| 重複登録を見分ける | Err.ALREADY_EXISTS。細かい原因はe.info.codeのSQLSTATEで調べる |
| 接続が足りているか調べる | stats()のwait_count(接続待ちの回数) |
| 認証方式を固定する | auth="scram"。auth="md5"は古いサーバー用 |
列の値は次の型で届きます。
| 列の型 | 受け取る値 |
|---|---|
real、double precision | float |
numeric | 桁を失わないよう文字列 |
json、jsonb | 辞書や配列。整数はintのまま |
int[]、text[]などの配列 | 同じ要素型のArray。nullと入れ子も保つ |
キャンセルや期限切れになった問い合わせは接続ごと閉じます。サーバー側のSQLがすぐ止まるとは限りません。文字コードはUTF-8です。
Redisの接続
RedisはGD.database.redis.client()で使います。コマンド名と引数を分けてquery()へ渡します。
func main() -> int, Err:
var redis := GD.database.redis.client()
redis.open("127.0.0.1", 6379)?
redis.query("SET", ["greeting", "hello"])?
print(redis.query("GET", ["greeting"])?)
redis.close()
return 0| やりたいこと | 方法 |
|---|---|
| 値が無いことを見分ける | GETはErr.NOT_FOUNDを返す |
| 複数のコマンドをまとめて送る | pipeline(cmds)。結果は送った順のArray |
| 多くの要求から同時に使う | GD.database.redis.pool()。接続は最初のquery()で作る |
MULTI、WATCH、SELECT、購読を使う | プールではなく専用のGDRedisClientを使う |
| 期限を決める | open()のtimeout(秒) |
TLSの選び方はPostgreSQLと同じです。
データベースの設定一覧
open()に辞書で渡す設定と、その既定値です。
| 入口 | 設定と既定 | 意味 |
|---|---|---|
GDDatabaseClient.open | driver="postgres", path="" | ドライバーとSQLite パス。SQLite時はuser://...または:memory:が必要 |
| 同上 | host="127.0.0.1", port=5432 | PostgreSQLの接続先 |
| 同上 | pool=0 | PostgreSQL最大接続数。0は上限なし、SQLiteでは使わない |
| 同上 | max_rows=0, max_bytes=0 | query()が集める1結果の行数とバイト。0は無制限。query_rows()には適用しない |
GDPostgresClient.open | user="postgres", database="postgres", password="" | 認証とDB名 |
| 同上 | connect_timeout=0.0, timeout=0 | 接続と問い合わせの秒。プールの接続待ちも問い合わせ時間に含む。0は無期限。必要なら各期限を設定する |
| 同上 | auth="any", allow_cleartext_password=false | auth="scram"/"md5"で方式固定。平文パスワード応答は明示時のみ |
| 同上 | tls=<hostで決定>, ca="" | 外部ホストはverify-full、ループバックはdisable。CA ファイルは明示時だけ |
GD.database.sqlite.open | busy_ms=0, max_ms=0, foreign_keys=false | ロック待ちと実行期限のミリ秒。busy_ms=0は競合を即時通知し、max_ms=0は実行期限なし。外部キー検査は明示して有効にする |
| 同上 | max_rows=0, max_bytes=0 | 1結果の行数とバイト。0は無制限 |
GDRedisClient.open | password="", dial_timeout=5, read_timeout=5, write_timeout=5 | パスワードと接続・読取り・書込み期限の秒。各期限の明示0は無期限。timeoutを指定すると三つをまとめて設定でき、個別指定が優先される |
| 同上 | tls=<hostで決定>, ca="" | PostgreSQLと同じTLS選択 |
GD.database.postgres.pool | size既定0、0または1..2147483647 | 0は上限なし。接続は必要になった分だけ作る |
GDPostgresPool.open | max_idle=2 | 仕事を終えた後に保持する接続数。0は保持せず、最大接続数を超えない |
GD.database.redis.pool | size既定0、0..2147483647 | 最大接続数。0はCPU数の10倍。同時に作る接続は最大接続数まで |
GDRedisPool.open | pool_timeout=read_timeout+1.0(読取り期限が0なら30秒)、conn_max_idle_time=1800 | 接続の空きを待つ期限と、返却後に再利用できる期間。各設定の明示0は無期限。期限を過ぎたidle接続は次の貸出時に閉じる |
長いRedis問い合わせが必要な場合は、read_timeoutを明示して期限を延ばせます。
max_rowsまたはmax_bytesを越えたquery()は、その問い合わせだけを失敗にします。 期限切れや壊れた応答で順序を失った場合は接続全体を閉じます。
範囲外の値は設定時に失敗します。受け付ける範囲は、APIリファレンスの各関数の説明にあります。
定期処理
決まった時刻に一度だけ動かす仕事は、普通のスクリプトとして書き、OSのcronやsystemd タイマーから呼びます。 gd側に常駐の仕組みは要りません。
func collect() -> int, Err:
var now := GD.time.to_iso(GD.time.now())
GD.file.append_text("store://log.txt", now + "\n")?
return 0
func main() -> int, Err:
collect()?
return 0gd --strict --mount store=/var/lib/app:rw collect.gd自分で間隔を持って回り続ける仕事は、GD.async.spawn()へ渡してgd serveで常駐させます。 spawn()へ渡した処理はmain()が返った後も動き続けます。
func every(sec, fn):
while true:
await GD.async.sleep(sec)
fn.call()
func collect():
print(GD.time.to_iso(GD.time.now()))
func main():
var _job := GD.async.spawn(every.bind(60.0, collect))
return 0gd serve schedule.gd止めるときはプロセスを終わらせます。Webサーバーと同じ常駐なので、ここでもserveが必要です。
公式拡張モジュール
本体を小さく保ち、外部サービス固有の機能は必要なプロジェクトだけへGDScript パッケージまたはGDExtensionとして加えます。
| 入口 | 用途 | 導入 |
|---|---|---|
Discord | DiscordのGatewayとRESTを使う、GDScriptだけで書かれたテキストBot | gd add @mofukuma/discord |
GDMemcached | TCP接続を再利用するキャッシュクライアント | gd add ext:@mofukuma/memcached |
GDSupabase | DatabaseとAuthのクライアント | gd add ext:@mofukuma/supabase |
公開中のパッケージはパッケージ一覧で探せます。任意で導入するため、本体から生成するAPIリファレンスには含まれません。
gd addで入れた拡張は起動時に信頼して読み込むため、読み込み許可のオプションは要りません。--strictでは接続先の--allow-netが必要です。--allow-extと--deny-extが効くのは、スクリプトが実行中にGDExtensionManager.load_extension()で読む場合です。- 入れた拡張はプロセスと同じ権限で動くので、信頼する版を
gd.lockで固定してコミットしてください。
パッケージと配布
他の人が公開したパッケージを使うときは、gd initでgd.jsonを作ってから追加します。公開中のパッケージはパッケージ一覧かgd searchで探せます。
gd init
gd add hello| やりたいこと | コマンド |
|---|---|
| 探す | gd search discord |
| 追加する | gd add hello(gd install helloも同じ) |
| スコープや版の範囲を指定する | gd add @mofukuma/hello@^0.1.0 |
| 呼び名を決めて追加する | gd add greet @mofukuma/hello |
| ネイティブ拡張を追加する | gd add ext:@mofukuma/memcached |
| URLや手元のディレクトリから追加する | gd add util https://example.com/util.gd、gd add ../mylib |
| 別の環境で同じ版を復元する | gd install --frozen |
| 新しい版を調べる、上げる | gd outdated、gd update |
| 外す | gd uninstall hello |
| 入れたものを一覧する | gd info |
依存はgd.json(何を使うか)とgd.lock(どの版を使うか)に記録されます。両方をコミットしてください。引数なしのgd installはgd.jsonの依存を復元します。--frozen・--cached-only・--syncはこの復元で使います。
パッケージを使う
入れたパッケージは、スクリプトの先頭で@import 呼び名と書いて読み込みます。
@import hello- パッケージの実体は利用者ごとの共有キャッシュ(
pkg://<呼び名>/)に置かれ、プロジェクトへは複製しません。 gd.jsonに書いた依存がキャッシュに無ければ、最初の実行で取得します。--strictでは登録所への--allow-netが要ります。gd add helloのような短い名前は登録所で探します。同じ名前が2つ以上あるときは、どれにするか尋ねます。gd addの既定の呼び名は、パッケージ名の-と.を_にした識別子です。エンジンクラスやキーワードと同じ呼び名は断ります。- コミットするのは
gd.jsonとgd.lockです。gd initはpkg/を.gitignoreへ書きます。 --frozenはロックを変更しません。オフラインの配布先では、ネットワークのある環境で先に取得し、--cached-onlyを併用します。- install、add、updateが途中で失敗したときは、プロジェクトの配置とロックを元へ戻します。
- ロックは登録所に結び付いています。別の登録所へ切り替えるには明示的なロック移行が必要です。
コマンドとして導入する
gd install -gは、パッケージやスクリプトをmy-toolのようなコマンドとして導入します。作業中のプロジェクトのgd.jsonとgd.lockは変更しません。
gd install -g tool # Install a published package by its short name.
gd install -g @scope/tool@1.0.0 # Choose the scope and version.
gd install -g --name my-tool ./tool.gd # Install a local script.
gd uninstall -g my-tool| 指定 | 意味 |
|---|---|
-n / --name | コマンド名。省略するとパッケージ名かスクリプト名(main.gdやmod.gdなら親ディレクトリ名) |
--root <dir> | 導入先。省略するとGD_INSTALL_ROOT、それも無ければ既定のキャッシュ。その中のbin/をPATHへ追加する |
-f / --force | 導入済みのコマンドを更新する |
-- 引数 | 起動のたびに先頭へ渡す固定引数 |
toolのような短い名前は登録所で探します。同じ名前のパッケージが2つ以上あるときは、候補を並べてどれにするか尋ねます。@scope/toolと書けば尋ねません。- 入口は
main(args)を持つスクリプトです。公開パッケージはmod.gd、ローカルのディレクトリはgd.jsonのmainを使います。 - 導入時に付けた
--allow-*と--mountは、起動のたびに同じ設定で使われます。 - 更新に失敗したときは、導入済みのコマンドをそのまま残します。
--rootを付けて導入したコマンドは、同じ--rootを付けて削除します。
importの短い書き方
@importはconst 名 = preload(...)の短い書き方です。
外部依存がなくても使えます。実際の登録所の依存とロックファイルを含むsamples/packagesを用意しています。
@import greet
@import "./util"
@import greet/style as theme- 引用符の無い名前は、
gd.jsonのimportsに宣言した呼び名だけを解決します。同名のファイルを探しに行きません。 - 相対ファイルは引用符で
./または../から書きます。.gdは省略できます。同名のファイルとディレクトリが両方あるときは"./util.gd"のように指定します。 - 識別子は
asが無ければ最後の要素そのままで、mod.gdを持つディレクトリはディレクトリ名です。 gd fmtは@importをそのまま残します。- 本家Godotは
@importを知らないので、Godotと共有するファイルではconstとpreloadを書いてください。
パッケージを作る
パッケージはgd.jsonを根に持つ一つのプロジェクトです。gd init @scope/nameがmod.gdとテストのテンプレートを作り、 gd testで回し、gd publishで公開します。
{"name":"@scope/hello","version":"1.0.0","main":"src/mod.gd","include":["src"]}gd publish
gd add hello gd:@scope/hello@^1.0.0公式の登録所へ投稿したパッケージは、審査で承認されると検索・インストールできます。gd publishが審査番号を表示した場合は、承認されるまで公開されません。
- 入口は
mod.gdです。複数ファイルならincludeへファイルまたはディレクトリを明示します。 - mainのディレクトリがパッケージの根になるので、パッケージ内の相対preloadはそのまま動きます。
- パッケージは自分の
gd.jsonのimportsで他の登録所パッケージを使えます。gd publishがそのimportsを登録所へ載せます。 class_nameは公開できます。installは同名クラスの衝突を検査し、衝突すれば全体を元へ戻します。gd.jsonのgodotをtrueにすると、gd固有のAPIを使わず本家Godotでも動くという作者の宣言になり、gd searchが[godot]と示します。
開発中のパッケージはgd add ../pathでローカルから足します。呼び名は先のgd.jsonのnameから取ります。 チェックアウトをpkg/<呼び名>/へ複製し、内容を比較するハッシュ値が変われば次の実行で複製し直します。 .で始まるファイル、pkg/、tmp/、gd.jsonを持つ下位ディレクトリ、tokenは複製しません。 gd publishは、ローカル importの先にnameとversionのあるgd.jsonがあれば登録所の範囲に変換し、無ければ拒みます。
ローカル開発チャンネル
リポジトリで、実際の登録所をループバックで起動できます。公開した版とデータはtmp/dev-channel/dataへ保存されます。
export GD_TOKEN='開発用のトークン'
uv run --no-project python -B devtools/channel.py serve --scope dev --port 8787別のターミナルでGD_REGISTRY=http://127.0.0.1:8787と同じGD_TOKENを設定し、@dev/nameのパッケージからgd publish --dry-run、gd publishを実行します。利用側もGD_REGISTRYを設定すれば、gd search、gd add、gd install、gd install -g、gd compileがその登録所を使います。プロジェクトのgd.jsonにregistryがある場合は、そのURLが優先します。
依存の解決
gd installは依存グラフ全体を解決します。版は、gd.lockが固定した版、今回すでに選んだ版のうち範囲を満たすもの、 登録所の最新一致の順で選びます。
gd.lockは解決したimportsの設定も保持します。設定が変わった実行では同じ依存関係の解決処理で再解決し、要求外の古い版を使いません。 --frozenは設定の不一致を拒否します。同じパッケージに複数の別名がある場合、辞書順で最初の別名を配置先に使います。
- GDScriptだけで書かれたパッケージは、版ごとに別のものとして共存できます。
- ネイティブ拡張はプロセスに一つしか読めないため、一つの版に揃えます。範囲が両立しなければ取得前に止まります。
- 複数のプラグインで同じ依存パッケージを共有するためのpeer依存には対応していません。
- 登録所パッケージの正式なパスは
pkg://@scope/name@版/です。pkg://<呼び名>/は、書いたスクリプトが属するパッケージのimportsで正式パスへ展開されます。同じ呼び名でもパッケージごとに違う版を指せ、同じ版はどこから辿っても一つのスクリプトです。 gd.lockには各パッケージのimportsの解決先も記録され、gd infoが一覧します。gd uninstallとgd updateは、どのパッケージも使わなくなったものをgd.lockとpkg/から外します。- 検索の順位が変わっても、既知のパッケージのinstallとロックの検証には影響しません。
Godotと共有する置き場
本家Godotなどres://しか読めない環境と共有するときは、gd.jsonへ"place": "project"を書きます。 パッケージをpkg/<呼び名>/へ複製し、pkg://もres://pkg/もそこを指します。 他のパッケージだけが使うものはpkg/@scope/name@版/へ置きます。
gd install --godotは、パッケージをaddons/<呼び名>/へ複製します。add、update、uninstall、infoでも--godotを指定します。パッケージ内にaddons/があっても、その部分だけを取り出すことはありません。project.godotのあるディレクトリではplaceの既定がprojectになり、.gitignoreは書きません。gdの無い同僚が開けるようpkg/をコミットします。- installは
preload、load、extendsに書かれたres://参照を配置先へ書き換えます。文字列、コメント、実行時に組み立てるパスは書き換えません。 placeはファイルの置き場を決めるだけで、gd固有のAPIや構文をGodot向けに変換する機能ではありません。共有するソースは標準構文と相対preloadで書きます。
ネイティブ拡張のパッケージ
- ネイティブ拡張は読み込みに実ファイルが要るため、
placeに関わらずpkg/<呼び名>/へ置きます。 - スクリプトから名指せるのは、自分のパッケージが
ext:で取り込んだ拡張のクラスだけです。プロジェクトのスクリプトならgd.json、パッケージのスクリプトならそのパッケージのimportsが基準です。 - 登録所の外にある拡張はプロジェクトのスクリプトだけが使えます。
- 登録所のパッケージの拡張が、設定ファイルの
[classes]に無いクラスを登録すると起動時に止まります。 - 配布先のOSで取得するか、
gd compileを配布先のOSで実行してください。
設定と環境変数
gd.jsonの設定は次の11件です。
| 名前 | gd initの生成値 / 未指定時 | 意味 |
|---|---|---|
name | my-tool / 必須 | プロジェクト名。publishは@scope/nameが必要 |
version | 0.1.0 / 必須 | パッケージのバージョン |
tasks | run/testの2件 / 無し | gd taskから呼ぶコマンド |
imports | {} / {} | 呼び名と依存先。publishするパッケージでは登録所パッケージだけ |
registry | 未指定 / 環境または公開登録所 | プロジェクト固定の登録所URL |
main | 未指定 / mod.gd | publishするmod.gdまたは.gdextension入口 |
include | 未指定 / mainだけ | GDScriptだけで書かれたパッケージへ含めるmain ディレクトリ内のファイルまたはディレクトリ |
place | 未指定 / cache(project.godotがあればproject) | パッケージの置き場。projectでpkg/へ複製する |
godot | 未指定 / false | gd固有のAPIを使わず本家Godotでも動くパッケージの宣言 |
description | 未指定 / 空 | 登録所に出す説明 |
assets | 未指定 / 無し | Godotアセットの管理用の呼び名とチャンネル:作者/名前[@版]。addons/へ配置する |
gdが読む環境変数は次の通りです。スクリプトから環境を読む実行では--allow-envで名前を許可します。
| 環境変数 | 用途 |
|---|---|
GD_CACHE_HOME | パッケージのキャッシュ根。未指定はWindowsのLocalAppData内gd。macOS/Linuxは絶対パスのXDG_CACHE_HOME/gd、それがなければホームディレクトリ内.gd。HOME未設定時はOSの利用者情報を使う |
GD_INSTALL_ROOT | gd install -gで入れるコマンドの置き場。--rootが優先 |
GD_USER_HOME | user://の保存先。絶対パスを指定する。未指定では作業ディレクトリごとの一時領域を使う |
GD_REGISTRY | 登録所。未指定はhttps://gd.progsha.com/pkg。gd.jsonのregistryが優先 |
GD_RELEASES | gd upgradeが読む配布元。未指定はhttps://github.com/prog-sha/gd/releases |
GD_TOKEN | publishのトークン。設定ファイルへ書かず、publishするプロセスだけへ渡す |
LC_ALL、LANG | gd docの手引きの言語 |
GD_WORKER | --workersが作る内部印。利用者が設定する値ではない |
遠隔パッケージと登録所はHTTPSを使います。ループバックの開発用登録所に限りHTTPも使えます。 取得したパッケージとネイティブライブラリは登録所索引のSHA-256と照合します。 パッケージの全ファイル合計は500 MiBまでです。
1つの実行ファイルにまとめて配布する
compileで、スクリプト、HTMLテンプレート、静的ファイル、マイグレーション、依存パッケージ、対象OSのGDExtensionを1つの実行ファイルへまとめます。配布先にキャッシュは要りません。
gd compile -o app main.gd
./appgd.jsonが名指すパッケージと、それらが取り込むパッケージを全部同梱します。- 同梱したWebアプリも
./app serve --no-scene-tree --allow-netで常駐できます。 - ローカルパスのパッケージからは、
.envなど.で始まるファイルとgd.jsonのtokenを除きます。 - 秘密情報をソースへ埋め込まないでください。compileは
.envを除外しますが、ソースに書いた値は実行ファイルに残ります。
アセットチャンネル
gd searchはパッケージに加え、Godotの公開アセットカタログとgdの審査済みカタログを検索します。独自の登録所を設定している場合は、その登録所だけを検索します。
| チャンネル | 用途 |
|---|---|
official | Godot Asset Storeのアセット |
gd | gdの審査済みアセット |
検索結果のasset:チャンネル:作者/名前を、そのままgd addに渡します。
gd search dialog
gd add asset:official:publisher/dialog
gd add ui asset:gd:publisher/dialog@1.2.0
gd install --frozen --cached-only
gd update ui
gd uninstall ui- バージョン名が重複する場合は、版の一覧にあるIDを
asset:official:publisher/dialog@#123のように指定します。名前に空白を含む場合は引数全体を引用符で囲みます。 - チャンネルを省略すると
officialになります。取得に失敗しても別のチャンネルへ切り替えません。 gd.jsonのassetsに依存先を記録し、gd.lockに取得元・選んだ版・SHA-256を固定します。両方をコミットしてください。asset:で指定するGodotアセットは、ZIP内のaddons/以下をプロジェクトのaddons/へ配置します。assetsの呼び名は管理用です。通常のパッケージはimportsに記録し、@importで読み込みます。- 最初の取得では対応するエンジンのバージョンを確認し、安定版を優先します。以後のinstallはロックした版を使い、updateで再選択します。
@1.2.0のように指定した版はupdateでも変わりません。 --frozenではロックを変更せず、--cached-onlyでは通信しません。キャッシュのない版をオフラインで取得することはできません。- 手作業で置いたアドオンや利用者が編集したファイルは上書きしません。処理が失敗したら、パッケージ・アドオン・設定・ロックを元へ戻します。
- gdチャンネルはアセットの説明、配布URL、SHA-256を審査して登録します。アーカイブは作者の配布先から取得し、gdがSHA-256を照合します。Godotエディタはこの追加のハッシュ値を使わないため、同じ照合は行いません。
アセットの詳細や版の一覧を調べるには、ソース配布に含むクライアントも使えます。
gd tools/store.gd channels
gd tools/store.gd search official 4.7 dialog
gd tools/store.gd show gd publisher dialog
gd tools/store.gd releases gd publisher dialog対応範囲と報告
gdはAPIが固まる前の公開版です。後方互換は前提にしないでください。変更した点と基準にしたGodotの版は CHANGELOGに書きます。 gdはGodot FoundationまたはGodot Engine プロジェクトの公式製品ではありません。
不具合はIssuesへ、公開すべきでない脆弱性は GitHubの非公開報告から知らせてください。