`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 は `Error`
`close`	`c.close()`	`Net`	切断する → `Ok(())`。呼んだ時点でハンドルは封印され、以降どのメソッドも `Error` (use after close)

Conn は非 Copyable である (../language-spec.md の複製の節)。ホストのソケットを持つ可変ハンドルで、作り直しても同じものにならないためである。copy は panic し、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)。

4. TLS

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

5. 将来枠

サーバー側 (listen / accept)・UDP
TLS 詳細オプション (クライアント証明書・独自 CA・検証スキップ)
接続タイムアウトの明示指定 (connect は OS 既定に従う)