本文へ移動
Hikari 仕様

std:net — TCP クライアント

標準ライブラリモジュール (index.md)。本書中の裸の §N は本書の節を指す。言語の意味論は ../language-spec.md を参照。

import net := "std:net" は TCP クライアント接続のコンストラクター 2 つと不透明ハンドル型 Conn を slot に持つ namespace object を net に束縛する。バイナリプロトコル (DB ワイヤプロトコル等) のクライアント実装の土台である。std:net の import 自体が「このコードはネットワークに触れる」ことの能力宣言になる (index.md)。

std:fs と同じ外部リソース I/O であり、ブロッキング操作は Future(Result(...)) を返す (prelude.md §9.4)。

import net := "std:net"

conn := net.connect("127.0.0.1", 3306)!.unwrap_or_else { e | panic(e.message) }
conn.set_timeout(5000)              # 以降の read/write は 5 秒で timeout
header := conn.read_exact(4)!       # Result(Bytes)
conn.write(packet)!
conn.close()!

1. コンストラクター

名前 形 効果 意味
connect net.connect(host, port) Net 平文 TCP で接続する → Future(Result(Conn))
connect_tls net.connect_tls(host, port) Net TLS で接続する (システムルート CA・ホスト名検証あり) → Future(Result(Conn))
  • host は String (IP またはホスト名)、port は 1..65535 の Int。型違いは静的エラー、範囲違反は Error (std:http/server の port http/server.md §9 と同じ範囲)。0 は範囲外である — 繋ぐ先としてのポート 0 は宛先を指さない。
  • 接続失敗 (拒否・DNS 解決失敗・TLS 検証失敗) は Err (§3)。

2. Conn のメソッド

メソッド 形 効果 意味
read c.read(n) Net 最大 n bytes 読む → Ok(Bytes)。Ok の空 Bytes は EOF (相手が閉じた)
read_exact c.read_exact(n) Net 丁度 n bytes 読む → Ok(Bytes)。揃う前に EOF なら Err(eof)。長さが決まっているプロトコルフレームの読み取りに使う
write c.write(bytes) Net 全量書く → Ok(())
set_timeout c.set_timeout(ms) Mut 以降の read / write の期限をミリ秒で設定する (0 で解除)。同期・即値 () (Future ではない)。非 Int は静的エラー、負数と 64bit に収まらない Int は Error
close c.close() Net 切断する → Ok(())。呼んだ時点でハンドルは封印され、以降どのメソッドも Error (use after close)

write に空の Bytes を渡した場合も Ok(()) を返す。
封印済みハンドルへの書き込みは、空の Bytes でも使用後エラーになる。

Conn は非 Copyable である (../language-spec.md の複製の節)。ホストのソケットを持つ可変ハンドルで、作り直しても同じものにならないためである。copy の直接の呼び出しは静的エラーになり、spawn / std:parallel の捕獲検査も弾く。

Conn はExactlyOnce の多重度型である (../language-spec.md の多重度型の節)。close が Consuming メソッドで、read / write / set_timeout は借用である。

効果 (../language-spec.md §17.9) はメソッドごとに分かれる。各メソッドが持つラベルは上の表が定める。set_timeout だけが Net ではなく Mut なのは、接続へ何も送らずハンドルが持つ期限を書き換えるだけだからである — 書き換えは以降の read / write の挙動を変えるので呼び出し元から観測でき、フレーム外の可変状態への書き込みにあたる。

read / read_exact の n は 1..2^30 (1 GiB) の Int。範囲外 (0・負数・2^30 超) は Future を作らず同期 Error。n を 0 未満・上限超のまま OS へ渡すと巨大確保やクラッシュにつながるため、呼び出し時点で弾く (0 を禁止することで「Ok の空 Bytes は EOF」との曖昧さも消える)。

ハンドル規律は fs.md の File と同一 (束縛 immutable・内部状態のみ前進・値型ではない)。Conn は std:net の型メンバーとして export される (net.Conn)。

3. エラー

I/O 失敗は Err({kind, message}) で運ぶ (fs.md と同じ形)。kind:

kind 意味
timeout set_timeout の期限超過
eof read_exact が揃う前に相手が閉じた
io_error その他 (接続拒否・DNS 失敗・TLS 検証失敗・切断ほか)

引数の型違いは静的エラー。範囲違反と封印後使用は Error (バグ層、language-spec.md §16.2)。

操作の Future を取り消すと、その操作を打ち切る (prelude.md §9.8)。Future はキャンセルの panic で解決する。Future を ! で待っているフローを取り消した場合も同じ扱いにする。

  • read・read_exact・write を打ち切ると、接続を閉じる。 どこまで読んだか・書いたかを呼び手は知れないので、続けて読み書きすると相手との間で切れ目が食い違う。以降の read・write は Err(io_error) になる。ハンドルは封印しないので、close は通る
  • connect・connect_tls を打ち切ると、張りかけの接続を閉じる。Conn は渡さない

4. TLS

connect_tls はシステムのルート CA でサーバー証明書を検証し、host を SNI / 検証名に使う。検証失敗は Err(io_error)。TLS があることで、MySQL caching_sha2_password のフル認証が TLS 経由で完結し、RSA 公開鍵暗号を必要としない。

5. 制約

TCP クライアントのみを提供し、待ち受けと UDP は持たない。
接続は 30 秒で打ち切って Err(io_error) にし、呼び手が指定する手段は無い (set_timeout は接続した後の読み書きにだけ効く)。
TLS はシステムのルート CA で検証し、クライアント証明書・独自 CA・検証スキップの設定は持たない。