gdドキュメント0.8.0

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/gd

apt(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 0
gd 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!と表示します。共有が必要になったときの書き方です。

パッケージの導入とバージョン固定はパッケージと配布を参照してください。

用途から選ぶ

標準APIはGDにまとまっています。ファイル操作はGD.file、WebサービスはGD.webのように、用途に合わせて選びます。

やりたいこと入口例
ファイル、文字、日時、HTTP クライアント、非同期処理GDGD.file.read_text("a.txt")
WebサイトとWeb APIGD.webGD.web.app()
SQLiteまたはPostgreSQLGD.databaseGD.database.client()
RedisGD.database.redisGD.database.redis.client()
TCP、UDP、TLSGD.netGD.net.listen_tcp("127.0.0.1", 8080)
メールの解析とSMTP送信GD.mailGD.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 0
gd 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で挙動を変えられます。

名前既定意味
timeout0完了を待つ秒数。0は無期限。時間を超えると子プロセスを終了し、Err.TIMED_OUTを返す
outputtrue出力を集める。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 0
printf 'Hello!\n' > message.txt
gd read_message.gd
printf '' > message.txt
gd read_message.gd

最初の実行はHello!を表示し、空ファイルにした後の実行はMessage is emptyというエラーを表示して終了コード1を返します。

待つ処理と同時実行

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つです。

チュートリアル: SQLiteを使うメモAPI

ここまでの知識で、JSONを受けてSQLiteへ保存する小さなAPIを1つのスクリプトで作ります。 できあがるのは、入力を検査し、SQL文と値を分けて渡す、権限を絞って起動する開発用サーバーです。

1. 作業ディレクトリを作る

mkdir notes-api
cd notes-api

2. 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

上から順に読みます。

3. 権限を絞って起動する

未確認のスクリプトや外へ公開するサーバーは、権限を既定で拒否する--strictで実行します。ここでは待ち受け先をループバックの一つのポートに絞ります。 serveはmain()が返った後もプロセスを残すコマンドで、サーバーにはこれを使います。

gd check main.gd
gd --strict --allow-net=127.0.0.1:18080 serve main.gd

4. 別の端末から使う

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.txtgdが利用者ごとに用意する書き込み領域読み書き可能
store://a.txt--mount store=/srv/app:rwで付けた名前指定した権限
/etc/hostsこのコンピューター上の指定した場所起動ディレクトリの外なら拒否

迷ったら、読むだけのファイルはres://、保存するファイルはuser://へ置きます。

ネットワークと拡張機能の許可

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 0

TLS

TLSはGD.net.dial_tls(host, port, opts)で開きます。既定で証明書チェーンと接続先のホスト名を検証し、失敗しても平文へ戻りません。 戻り値はTCPと同じGDTCPConnです。

opts意味
timeout接続とTLSの初期通信が完了するまでの制限時間(秒)
ca_file私設CA。環境変数の設定より優先する
cert_file、key_fileクライアント認証。許可されたマウント内のファイルを対で指定する
server_name証明書を照合する宛名を接続先と別にする
next_protosALPN名の配列。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 0

メール

GD.mailはメールアドレスやヘッダーを解析し、SMTPサーバーへメールを送ります。

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とULIDGD.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

ハッシュと鍵導出

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 0

index.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.gd

http://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
null204
失敗のErr種類に応じたステータスコード。INVALID_DATA → 400、UNAUTHENTICATED → 401、PERMISSION_DENIED → 403、NOT_FOUND → 404、LIMITED → 429、UNSUPPORTED → 501、TIMED_OUT → 504、他は500(いずれもErrの定数)

返事は次のように調整できます。

ルーターには次も登録できます。

登録用途
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へ置き換える

同じテンプレートを何度も描画するサーバーでは、起動時に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 0

cookie(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 0

JWTをログインセッションに使う場合は、パスワード変更やログアウトで既発行トークンを失効させます。 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 0

1 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 1
gd --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)その要求の本文の上限。超えると、読んだ操作が失敗する

本文を少しずつ送信する

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のキャンセルでわかる

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で使い回す
headername、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 クライアントの接続

Webの設定一覧

GD.http.fetch()とGD.webの各関数に辞書で渡す設定と、その既定値です。時間は秒、大きさはバイトです。

入口設定と既定意味
GD.http.fetchmethod="GET", headers={}, body=nullHTTP メソッド、送信ヘッダー、送信本文
同上timeout=0.0, max_body=0要求全体の秒と応答本文のバイト。0は上限なし。新規TCP接続は30秒、TLS初期通信は10秒が既定
同上save="", sha256=""2xx 本文をsaveへ逐次保存し、返却本文は空。sha256はsave必須の64桁16進数で、一致した完了ファイルだけを置く
同上authority="host:port"CONNECTだけのリクエストの送信先
GDWebApp.limitsjobs=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_signttl=900iat/expを補う秒。0は自動付与しない
GD.web.jwt / jwt_verifyleeway=0.0, require_exp=true時刻許容秒とexp必須化
同上iss="", aud="", keep="jwt"空でない場合のissuer/audience一致と保持名
同上check=Callable()署名検証後にクレームを受け取る失効判定。指定時は真だけを許可
GD.web.sessionstotal=1024, per_user=3プロセス内の全セッション数と同一ユーザー数
同上idle=1800, life=43200操作がない場合の有効期間と、セッション全体の有効期間(秒)
同上cookie="sid", keep="user"Cookie名とリクエスト内の保持名。Cookie名はASCIIのトークン文字
GD.web.ratelimit=60, window=60.0keyごとの最大連続回数と、その回数分を補充する時間(秒)
同上expires=180.0最後の要求からkeyを解放するまでの秒数
同上keys=0, key=Callable()プロセス内で保持するkey数とkey選択関数。0は無制限。明示した保持枠が満杯なら期限が最も早いkeyを追い出す
同上trusted_proxies=PackedStringArray()転送元IPを信頼するプロキシのIPまたはCIDR
GD.web.csrfallow_missing=false状態変更でFetch Metadataが無いクライアントを許すか
GD.web.text_rulemin=0, max=4096テキストの文字数
GD.web.int_rulemin=-9223372036854775808, max=922337203685477580764ビット整数の範囲
GD.web.number_rulemin=-1e308, max=1e308有限浮動小数の範囲
GD.web.list_rulemin=0, max=1024要素数
GD.web.object_ruleextra=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
	)

PostgreSQLで、同時に走る別のトランザクションとぶつかって失敗する場合(SQLSTATE 40001)は、serialize()でやり直せます。

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)",
	])

データベースの高度な機能

ドライバーの違い

項目SQLitePostgreSQL
向く用途ローカル開発、単一プロセス本番、異常終了耐性、複数ワーカー
接続クライアントごとに一つ。変更履歴と一時表はメモリに置く必要な接続だけ作るプール。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 precisionfloat
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.opendriver="postgres", path=""ドライバーとSQLite パス。SQLite時はuser://...または:memory:が必要
同上host="127.0.0.1", port=5432PostgreSQLの接続先
同上pool=0PostgreSQL最大接続数。0は上限なし、SQLiteでは使わない
同上max_rows=0, max_bytes=0query()が集める1結果の行数とバイト。0は無制限。query_rows()には適用しない
GDPostgresClient.openuser="postgres", database="postgres", password=""認証とDB名
同上connect_timeout=0.0, timeout=0接続と問い合わせの秒。プールの接続待ちも問い合わせ時間に含む。0は無期限。必要なら各期限を設定する
同上auth="any", allow_cleartext_password=falseauth="scram"/"md5"で方式固定。平文パスワード応答は明示時のみ
同上tls=<hostで決定>, ca=""外部ホストはverify-full、ループバックはdisable。CA ファイルは明示時だけ
GD.database.sqlite.openbusy_ms=0, max_ms=0, foreign_keys=falseロック待ちと実行期限のミリ秒。busy_ms=0は競合を即時通知し、max_ms=0は実行期限なし。外部キー検査は明示して有効にする
同上max_rows=0, max_bytes=01結果の行数とバイト。0は無制限
GDRedisClient.openpassword="", dial_timeout=5, read_timeout=5, write_timeout=5パスワードと接続・読取り・書込み期限の秒。各期限の明示0は無期限。timeoutを指定すると三つをまとめて設定でき、個別指定が優先される
同上tls=<hostで決定>, ca=""PostgreSQLと同じTLS選択
GD.database.postgres.poolsize既定0、0または1..21474836470は上限なし。接続は必要になった分だけ作る
GDPostgresPool.openmax_idle=2仕事を終えた後に保持する接続数。0は保持せず、最大接続数を超えない
GD.database.redis.poolsize既定0、0..2147483647最大接続数。0はCPU数の10倍。同時に作る接続は最大接続数まで
GDRedisPool.openpool_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 0
gd --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 0
gd serve schedule.gd

止めるときはプロセスを終わらせます。Webサーバーと同じ常駐なので、ここでもserveが必要です。

公式拡張モジュール

本体を小さく保ち、外部サービス固有の機能は必要なプロジェクトだけへGDScript パッケージまたはGDExtensionとして加えます。

入口用途導入
DiscordDiscordのGatewayとRESTを使う、GDScriptだけで書かれたテキストBotgd add @mofukuma/discord
GDMemcachedTCP接続を再利用するキャッシュクライアントgd add ext:@mofukuma/memcached
GDSupabaseDatabaseとAuthのクライアントgd add ext:@mofukuma/supabase

公開中のパッケージはパッケージ一覧で探せます。任意で導入するため、本体から生成するAPIリファレンスには含まれません。

パッケージと配布

他の人が公開したパッケージを使うときは、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

コマンドとして導入する

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導入済みのコマンドを更新する
-- 引数起動のたびに先頭へ渡す固定引数

importの短い書き方

@importはconst 名 = preload(...)の短い書き方です。

外部依存がなくても使えます。実際の登録所の依存とロックファイルを含むsamples/packagesを用意しています。

@import greet
@import "./util"
@import greet/style as theme

パッケージを作る

パッケージは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が審査番号を表示した場合は、承認されるまで公開されません。

開発中のパッケージは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は設定の不一致を拒否します。同じパッケージに複数の別名がある場合、辞書順で最初の別名を配置先に使います。

Godotと共有する置き場

本家Godotなどres://しか読めない環境と共有するときは、gd.jsonへ"place": "project"を書きます。 パッケージをpkg/<呼び名>/へ複製し、pkg://もres://pkg/もそこを指します。 他のパッケージだけが使うものはpkg/@scope/name@版/へ置きます。

ネイティブ拡張のパッケージ

設定と環境変数

gd.jsonの設定は次の11件です。

名前gd initの生成値 / 未指定時意味
namemy-tool / 必須プロジェクト名。publishは@scope/nameが必要
version0.1.0 / 必須パッケージのバージョン
tasksrun/testの2件 / 無しgd taskから呼ぶコマンド
imports{} / {}呼び名と依存先。publishするパッケージでは登録所パッケージだけ
registry未指定 / 環境または公開登録所プロジェクト固定の登録所URL
main未指定 / mod.gdpublishするmod.gdまたは.gdextension入口
include未指定 / mainだけGDScriptだけで書かれたパッケージへ含めるmain ディレクトリ内のファイルまたはディレクトリ
place未指定 / cache(project.godotがあればproject)パッケージの置き場。projectでpkg/へ複製する
godot未指定 / falsegd固有の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_ROOTgd install -gで入れるコマンドの置き場。--rootが優先
GD_USER_HOMEuser://の保存先。絶対パスを指定する。未指定では作業ディレクトリごとの一時領域を使う
GD_REGISTRY登録所。未指定はhttps://gd.progsha.com/pkg。gd.jsonのregistryが優先
GD_RELEASESgd upgradeが読む配布元。未指定はhttps://github.com/prog-sha/gd/releases
GD_TOKENpublishのトークン。設定ファイルへ書かず、publishするプロセスだけへ渡す
LC_ALL、LANGgd docの手引きの言語
GD_WORKER--workersが作る内部印。利用者が設定する値ではない

遠隔パッケージと登録所はHTTPSを使います。ループバックの開発用登録所に限りHTTPも使えます。 取得したパッケージとネイティブライブラリは登録所索引のSHA-256と照合します。 パッケージの全ファイル合計は500 MiBまでです。

1つの実行ファイルにまとめて配布する

compileで、スクリプト、HTMLテンプレート、静的ファイル、マイグレーション、依存パッケージ、対象OSのGDExtensionを1つの実行ファイルへまとめます。配布先にキャッシュは要りません。

gd compile -o app main.gd
./app

アセットチャンネル

gd searchはパッケージに加え、Godotの公開アセットカタログとgdの審査済みカタログを検索します。独自の登録所を設定している場合は、その登録所だけを検索します。

チャンネル用途
officialGodot Asset Storeのアセット
gdgdの審査済みアセット

検索結果の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

アセットの詳細や版の一覧を調べるには、ソース配布に含むクライアントも使えます。

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の非公開報告から知らせてください。