本文へ移動
Hikari 仕様

std:http/client — HTTP クライアント

標準ライブラリモジュール (../index.md)。本書中の裸の §N は本書の節を指す。言語の意味論は ../../language-spec.md を参照。共通型 (Request / Response / Handler) は ../http.md、HTTP サーバーは server.md を参照。

import http := "std:http/client" は get / head / delete / post / put / patch / request の 7 slot を持つ namespace object を http に束縛する。名前 destructure (language-spec.md §6.3) で個別に取り出すか、namespace のまま slot アクセスする:

# 個別に引く
import { get, post } := "std:http/client"
res := get("https://example.com")!.unwrap!
print(res.status)                       # 200

# namespace のまま使う
import http := "std:http/client"
res := http.get("https://example.com")!.unwrap!
名前 形 効果 method body 意味
get get(url) Net GET なし url を GET し、Future (Result(Response)) を返す
head head(url) Net HEAD なし url を HEAD し、Future (Result(Response)) を返す (本文なし応答)
delete delete(url) Net DELETE なし url を DELETE し、Future (Result(Response)) を返す
post post(url, body) Net POST あり url へ body を POST し、Future (Result(Response)) を返す
put put(url, body) Net PUT あり url へ body を PUT し、Future (Result(Response)) を返す
patch patch(url, body) Net PATCH あり url へ body を PATCH し、Future (Result(Response)) を返す
request request(req) Net 任意 任意 req レコードで method/url/headers/body/redirect を指定し、Future (Result(Response)) を返す

以下の例では import http := "std:http/client" で束縛したものとして http.get 等で記す。全関数は Future を返し、! で resolve 値 (Result) を待つ (prelude.md §9.4 のブロッキング I/O 規則に乗る)。

ショートカット (get〜patch) は ヘッダー指定のない常用形。リクエストヘッダーや任意メソッドが要るときは request (§8) を使う — ヘッダーを指定できる関数は request だけ。

非 2xx はエラーにしない。404 / 500 等のサーバー応答も Ok(Response) で返り、Response.status (Int) で判定する。Err になるのは URL 不正・接続失敗・タイムアウト等の トランスポート層の失敗 だけ (§9)。

1. Response レコード

成功時の Ok(res) の res はスロット { status, headers, body, body_bytes |} を持つ closed・immutable なレコード:

スロット 型 意味
status Int HTTP ステータスコード (例 200 / 404)
headers InsertionMap(String, String) 応答ヘッダー。ヘッダー名 (String) → 値 (String) (§2)
body String 応答本文を UTF-8 として読んだもの (読めないバイト列は置き換え文字 U+FFFD)
body_bytes Bytes 応答本文の生バイト列

body と body_bytes は同じ本文の 2 つの見方。テキスト API は body、バイナリ (画像等) は body_bytes を使う。本文に UTF-8 として読めないバイト列が含まれる場合、body はそこを置き換え文字 U+FFFD に置き換えた String になる (fs.read と同じ)。元のバイト列が要るなら body_bytes を使うこと。HEAD 応答など本文が無い場合は body が空 String、body_bytes が空 Bytes。

この形は std:http (../http.md) の構造的型 Response を満たす。std:http/server のハンドラー応答としてそのまま返せる。

import http := "std:http/client"

match http.get("https://example.com/api")! {
  Ok(res) =>
    match res.status {
      200 => print res.body
      404 => print "not found"
      _ => print "http status: ${res.status}"
    }
  Err(e) => print e.message
}

2. ヘッダーマップ

Response.headers と request の req.headers (§8) はともに std:map の InsertionMap (../map.md) で表す。キーがヘッダー名 (String)、値がヘッダー値 (String) である。

ヘッダー名は - を含み、Hikari の識別子として不正なのでオブジェクトのスロットでは表せない。加えてヘッダー集合は実行時に決まるものであり、書いた時点で名前が決まっている record のフィールドではない (language-spec.md §7.5)。挿入順で反復する InsertionMap を使うのは、受信・送信の順序を保つためである。

  • 応答側 (Response.headers): 同名ヘッダーが複数あるときは値を , (カンマ+空白) で連結した 1 つの String にする。キーは受信したヘッダー名を正規化した形 (各語頭大文字、例 Content-Type)。反復順は正規化後のヘッダー名の昇順で、同じ応答に対して決定的である。
  • 要求側 (req.headers): キーをヘッダー名、値を String としてそのまま送る。値が非 String のエントリがあると invalid_request (§9)。InsertionMap 以外を渡した場合も invalid_request。
  • ヘッダー名は token の綴りに限る — 空でなく、英数字と ` ! # $ % & ' * + - . ^ _ | ~ ` だけから成る (method と同じ規則。[§8](#8-httprequest))。要求側の名前が外れていれば invalid_request、受けた応答の名前が外れていれば「応答の綴りが壊れている」として connect_error ([§9](#9-エラーモデル))。名前が空や :` を含むまま送ると、受け手ごとに別の名前として読まれうる
  • 枠のヘッダーは実装が決める。 Content-Length・Transfer-Encoding・Connection・Host は、送る本文と URL から実装が付ける。req.headers に書いたものは送らない — 書いた値が本文の実際の長さや宛先と食い違うと、受け手は要求の切れ目を誤って読み、1 本の接続に別の要求を差し込まれうる
  • 名前に CR (0x0D) / LF (0x0A) / NUL (0x00) があれば拒む。
  • 値の CR / LF / NUL は送る前に除去する。 名前の検証とは別の規則であり、値のために失敗へは変えない。
    区切りを値から除くことで、1 つの値が追加のヘッダーや本文として読まれることを防ぐ。
    応答の組み立ても同じ規則に従う (server.md §3)。
  • 受けたヘッダー値は UTF-8 として読み、読めないバイト列は置き換え文字 U+FFFD に置き換える。 0x80 以上のバイトは HTTP のヘッダー値に正当に現れるので、行ごと拒まない。値の生のバイト列は持たない (本文の body と body_bytes の対は持つが、ヘッダーは持たない)。名前は token の綴りに限るので、置き換えは起きない

この正規化・連結の規則定義は本節が正であり、std:http (../http.md) の Request.headers / std:http/server の Request / Response の headers からも参照される。

import http := "std:http/client"
import m := "std:map"

res := http.get("https://example.com")!.unwrap!
res.headers.get "Content-Type"  # 受信した値。ヘッダーが無ければ None
(res.headers.get "Content-Type").or ""  # 同じ値。無ければ ""

hdrs := m.insertion.of [("Content-Type", "application/json")]
hdrs.get "Content-Type"  #> Some("application/json")

3. http.get

  • 引数: url (String) 1 個。非 String を渡すと静的エラー
  • GET リクエストを送る。リクエスト本文は無し
  • 戻り値: Future。! (= ()) で resolve 値を待つ
  • resolve 値は Result(Response):
    • 成功時: Ok(res) — res は Response レコード (§1)。HTTP ステータスに関わらず応答が返れば成功 (非 2xx も Ok)
    • 失敗時: Err(e) — 回復可能エラー { kind, message |} (§9)
import http := "std:http/client"

match http.get("https://example.com")! {
  Ok(res) => print res.body
  Err(e) => print e.message
}

4. http.head

  • 引数: url (String) 1 個。非 String を渡すと静的エラー
  • HEAD リクエストを送る。応答にヘッダーのみが期待され、Response.body / body_bytes は通常空
  • 戻り値: Future (Result(Response))。挙動は get (§3) と同じ (method のみ HEAD)

5. http.delete

  • 引数: url (String) 1 個。非 String を渡すと静的エラー
  • DELETE リクエストを送る。リクエスト本文は無し
  • 戻り値: Future (Result(Response))。挙動は get (§3) と同じ (method のみ DELETE)

6. http.post

  • 引数: (url, body) 2-tuple。url は String。url の型違いは静的エラー。body は Any として受け取り、String または Bytes の受理集合に無ければ呼び出し位置で Error
  • POST リクエストを送る。body (String ならその UTF-8 バイト列、Bytes ならそのまま) をリクエスト本文にする
  • Content-Type ヘッダーは付けない。必要なら request (§8) でヘッダー指定する
  • 戻り値: Future (Result(Response))。応答の扱いは get (§3) と同じ
import http := "std:http/client"

match http.post("https://example.com/api", "{\"name\":\"hikari\"}")! {
  Ok(res) => print res.status
  Err(e) => print e.message
}

8.1 redirect (3xx を追うか)

値 振る舞い
"follow" (既定) 3xx を自動追従する (§10)。Response は最終応答
"manual" 3xx を追わずにそのまま返す。Response.status は 3xx で、headers にはその応答の Location と Set-Cookie が載る

"manual" を持つのは、追従の途中で捨てられる情報があるからである。 自動追従は各ホップの応答を返さないので、3xx が焼いた Set-Cookie を呼び手が受け取れない。このクライアントは cookie を持ち回らないので、追わせると POST → 303 → GET の形で組んだログインの往復が書けない — 焼かれた cookie が次のホップへも呼び手へも渡らない。"manual" なら呼び手が 3xx を見て、自分で cookie を載せて次を投げられる。

  • "manual" ではホップが起きないので、上限超過の connect_error (§10) も起きない
  • 追う・追わないの判断だけを変える。method の落とし方 (§10) やタイムアウトは変わらない
  • ショートカット (get〜patch) はこのスロットを持たない。設定を取る関数は request だけであり、ヘッダーと同じ区分けである (§6)

7. http.put / http.patch

  • 引数: (url, body) 2-tuple。post (§6) と同形 (url は String、body は String または Bytes)。url の型違いは静的エラー、body の受理集合外は Error
  • それぞれ PUT / PATCH リクエストを送る。挙動は method を除き post と同じ

8. http.request

任意 method・カスタムヘッダー付きリクエストを送る汎用形。ショートカット (§3〜7) で足りない場合に使う。

  • 引数: req (レコード) 1 個。パラメーター型は Any。非レコード (スロットを持たない値) は受理集合外として呼び出し位置で Error
  • req のスロット:
スロット 必須 型 意味
method 必須 String HTTP メソッド ("GET" / "POST" 等)。大文字小文字はそのまま使う。綴りの規則は下記
url 必須 String 送信先 URL
headers 任意 InsertionMap(String, String) リクエストヘッダー (§2)。省略時はヘッダー無し
body 任意 String / Bytes リクエスト本文。省略時は本文無し
redirect 任意 String 3xx の扱い。"follow" (既定) か "manual" (§8.1)
  • method / url の欠落・非 String、headers が非 InsertionMap・値が非 String、body が String でも Bytes でもない場合は 回復可能エラー Err(invalid_request) (§9)。redirect が String でない、または "follow" / "manual" のどちらでもない場合も同じ。req 自体が非レコードのときだけ呼び出し位置で Error (API の受理集合外)
  • method は空でなく、英数字と ` ! # $ % & ' * + - . ^ _ | ~ ` だけから成る綴りに限る。** 外れた綴り (空・空白・制御文字を含むもの) は Err(invalid_request)`。method は要求行の先頭にそのまま出るので、空白や CR LF を含めたまま送れると要求行が割れ、1 本の接続へ別の要求を差し込める (§9 の URL の制御文字と同じ理由)。除去も符号化もしない** — method はどの操作を求めるかを選ぶ綴りなので、書き換えると書き手が指していない操作を送ることになる
  • 戻り値: Future (Result(Response))。応答の扱いは get (§3) と同じ

ヘッダーは std:map の InsertionMap で組み立てる (§2):

import http := "std:http/client"

import m := "std:map"

hdrs := m.insertion.of [("Content-Type", "application/json")]
match (http.request {
  method := "POST"
  url := "https://example.com/api"
  headers := hdrs
  body := "{\"name\":\"hikari\"}"
|})! {
  Ok(res) => print res.status
  Err(e) => print e.message
}

9. エラーモデル

失敗時の err は回復可能エラーオブジェクト { kind, message |} (language-spec.md §16)。std:http/client が返す正規 kind (閉じた一覧。全関数で共通):

kind 意味
invalid_url URL がパースできない、スキームが http / https 以外、authority が規則外、または生の制御文字 (U+0000〜U+001F・U+007F〜U+009F) を含む (下記)。代理の環境変数の値が規則外 (§10)
invalid_request request の req レコードのスロットが不正 (method/url 欠落・型違い・method の綴りが規則外、headers/body の型違い)。§8
timeout 既定タイムアウト (§10) を超過した
connect_error DNS 解決失敗・接続拒否・TLS 失敗など接続を確立/完了できなかった。応答の頭 (状態行とヘッダー) を読み切る前に切れた・読めなかった場合と、応答の綴りが壊れている場合を含む
io_error 応答の頭を読み切った後の本文の読み取りの失敗 (本文が途中で切れた・読み取りの I/O 失敗)

新しい kind は設けず、上記 5 種で全関数を表す。種別が紛れやすい代表的な対応:

  • 非 2xx の HTTP 応答 (404 / 500 等) → エラーではなく Ok(Response)。Response.status で判定する (§1)
  • 応答の綴りが壊れている (開始行・ヘッダー行が読めない、Content-Length が読めない — 数でない・負・64bit に収まらない・同名で値が食い違う —、chunked の綴りが壊れている) → connect_error。読めない Content-Length を「接続が閉じるまでが本文」と読み替えない — 長さの分からない本文として読むと、途中で切れた応答を完全な応答として呼び手へ渡すことになる
  • リダイレクト上限超過・リダイレクト先での接続失敗 → connect_error
  • リダイレクト先の URL (Location) が読めない、またはスキームが http / https 以外 → invalid_url (§10)
  • 応答の status が 1xx (100 Continue ほか) なら中間応答として読み飛ばし、続く最終応答を返す。100〜599 の外の status は「応答の綴りが壊れている」として connect_error
  • 応答の行の終わりは CR LF だが、LF だけでも受け付ける (要求を読むサーバーと同じ。server.md §4)。Transfer-Encoding の chunked は大文字小文字を問わない
  • 状態行は HTTP/1.0 か HTTP/1.1・3 桁の数字の status・理由句 (空でもよい) の並びに限る。外れた状態行 (+200 のような status を含む) は「応答の綴りが壊れている」として connect_error
  • chunked 以外の Transfer-Encoding を持つ応答は、本文を復号できないので connect_error
  • chunked のチャンク長の行は 16 進の数字だけに限り (符号・前後の空白は不可)、; から後ろの拡張は読み飛ばす。外れた行は「chunked の綴りが壊れている」である
  • チャンク本体の直後は CR LF に限る。 LF だけのものは「chunked の綴りが壊れている」である — 長さの行や空行と違い、ここは数えた本体の切れ目なので、1 バイトの揺れを許すと中継とこちらで本文の切れ目が割れうる
  • 終端チャンクの後のトレーラーは読み捨てる。 headers には混ぜない — 本文の後ろで届く欄を頭のヘッダーと混ぜると、本文を読み始めた後でヘッダーが書き換わる
  • chunked の Transfer-Encoding と Content-Length を両方持つ応答は chunked で読み、Content-Length は見ない。 chunked 以外の符号化は Content-Length を併せ持っても復号できないので connect_error である。本文を持たない応答 (HEAD への応答・204・304) は本文を読まないので、Transfer-Encoding を見ない
  • 生の制御文字を含む URL → invalid_url。CR (U+000D) / LF (U+000A) は要求行とヘッダーの区切りなので、含んだまま送れると要求行そのものが割れて 1 本の接続へ 2 本目の要求を差し込める (http.get(base + id) のように外から来た綴りを URL へ継ぐ形で踏む)。ヘッダーの値のように除去はしない — URL は運ぶデータではなくどの資源を取るかを選ぶ綴りなので、/a + CR LF + b を /ab へ縮めると書き手が指していないものを知らせずに取りに行くことになる。RFC 3986 の URI に生の制御文字は現れないので、拒否して失う正当な綴りも無い (載せたい制御文字は percent 符号化して書く。%0d%0a は素通しし、復号するのは受け手である)。経路と query の空白は拒否しない — 送るときに %20 へ符号化する。ASCII 以外の文字も、UTF-8 のバイト列を %XX に符号化して送る (全角空白 U+3000 も同じ)。生の空白は要求行の区切りなので、そのまま送ると受け手は要求行を読めない (server.md §4) が、空白を書いた呼び手の意図は 1 つに決まるので、拒否せずに符号化する。同じ規則を応答の組み立て側も持つ (server.md §3)
  • スキームは大文字小文字を問わない (HTTP://h/ は http://h/ と同じ)。% で始まる綴りは検めずに送る — 復号するのは受け手である
  • authority (// から最初の /・?・# まで) は [利用者情報@]ホスト[:ポート] に限る。 外れた綴りは invalid_url である。利用者情報は authority の最後の @ までである
    • ホストは空でなく、ASCII の英数字と -・.・_ だけから成る名前か、[ と ] で囲んだ IPv6 アドレスである。[ ] の後ろには :ポート しか書けない
    • 空白と ASCII 以外の文字を含むホストは、符号化せずに invalid_url にする。 ホストは名前解決へ渡す綴りで、経路のように %XX へ符号化しても誰も復号しないので、書き手の指した宛先に届かない。ASCII 以外の文字を含むドメイン名は、変換済みの綴り (xn-- で始まる形) で書く
    • ポートは : に続く 1 桁以上の 10 進数字で、1〜65535 に限る。0・符号・空 (http://h:/)・: の重ね (http://h:80:80/) は invalid_url である。範囲は std:net の connect (net.md) と同じで、ポート 0 は宛先を指さない
  • URL の # から後ろ (フラグメント) と利用者情報 (user:pass@) は送らない — どちらも取りに行く資源を選ぶ綴りではない。要求行・Host・代理へ渡す絶対 URI のどれにも載せない。パスの有無に依らず同じである (http://h?q#f は /?q を送る)。リダイレクト先の Location も同じ規則に従う (§10)
  • シグネチャが要求する引数の 型 が違う (get(123) など) → 静的エラー。Any で受け取る body / req の受理集合外は Error。request の req レコード内のスロット不正のみ invalid_request で回復可能 (§8)

message は http.get: ... のように関数名を含む人間可読文字列。分岐は match res { Ok(v) => … Err(e) => match e.kind {...} } で行い、message の文字列マッチに依存しないこと。

10. 既定動作 (タイムアウト・リダイレクト)

要求ごとに期限や代理を指定する手段は持たず、以下の既定で動く:

  • タイムアウト: 全関数に 30 秒の上限を内蔵する (接続〜本文読み取り完了まで)。超過は timeout (§9)。無制限ハングを避けるための既定で、無効化・延長の手段は持たない
  • 代理: 平文の要求は HTTP_PROXY (無ければ http_proxy)、https の要求は HTTPS_PROXY (無ければ https_proxy) の代理を通す。値は http://ホスト:ポート か ホスト:ポート で、ポートを省けば 80 である。ホストとポートの規則は URL の authority と同じ (§9)。外れた値 (経路・利用者情報・http 以外のスキームを持つもの) はその要求を invalid_url にする — 代理なしで直に出すと、代理を通すつもりの要求が知らせずに直に出る。ループバック (localhost とループバックのアドレス) と、NO_PROXY (無ければ no_proxy) のカンマ区切りの並びに当たるホストは代理を通さない — 並びの * はすべてに当たり、example.com (先頭の . は有っても無くても同じ) はそのホストと下位のホストに当たる。並びの :ポート は見ず、アドレスの範囲 (CIDR) の綴りは解さない
  • リダイレクト: 301・302・303・307・308 を自動追従する (上限 10 ホップ)。上限超過は connect_error。Response.status には最終応答のステータスが入る。request (§8.1) だけがこの既定を要求ごとに外せる — 他の関数は外す手段を持たない
    • 次の要求の method と本文は、応答のステータスで決まる:
ステータス method 本文
301・302 POST は GET に変える。他は保つ GET に変えたら落とす。保ったら保つ
303 GET・HEAD は保ち、他は GET に変える 同上
307・308 保つ 保つ

本文を落とすときは、呼び手が書いたヘッダーのうち本文を説明するもの (Content-Type・Content-Encoding・Content-Language・Content-Location) も送らない — 無い本文を説明するヘッダーが残ると、受け手は本文の欠けた要求として読む

  • Location を複数持つ 3xx は最初の 1 つを追う
  • 上の 5 つ以外の 3xx (300・304 ほか) と、Location を持たないか値が空の 3xx は追わずにその応答を返す — 追う先が決まらないので、判断を呼び手に任せる (空の Location は今の URL へ解けるので、追っても同じ要求を上限まで繰り返すだけになる)
  • Location は RFC 3986 の参照解決で今の URL から解く。スキームを持つ参照 (英字で始まり、/・?・# より前に : がある綴り) は絶対参照で、それ以外は相対参照である — //host/x はスキームだけを、/x はスキームと authority を、?q はパスまでを今の URL から引き継ぎ、x は今のパスの最後の / までに続ける。# から後ろは送らない。クエリに :// を含む相対参照 (/login?next=http://…) も相対参照である
  • 解いた URL が読めない、またはスキームが http / https 以外なら invalid_url (§9)

11. ネットワークと capability

std:http/client の各関数は ホストのネットワーク経由でリクエストを送る。std:http/client を import すること自体が「このコードはネットワーク能力を使う」という宣言になり、どのコードが外部通信するかが静的に追える (../index.md の capability 可視化)。実際の到達可否は実行環境のネットワークポリシー (プロキシ・許可ホスト等) に従い、std:http/client はそれを上書きしない。

hikari build (../../build.md) が生成する embed バイナリにも std:http/client モジュール (ホストコード) は常に含まれ、std:http/client の import は常に解決可能 (language-spec.md §13.4)。

ブラウザー (wasm) では自分のプログラムが立てた待ち受けにだけ届く

wasm ビルドはブラウザーの中で処理系を走らせる。ブラウザーは網を持たないので、外部の host へは届かない — connect_error (§9) になり、理由は「この環境が網を持たない」ことを述べる。「相手が落ちている」とは言わない。

https は届かないのではなく、呼び出しで止まる。 ブラウザーは TLS の実装を持たず、ページが積むのも平文のバイト列なので、https:// の URL を渡した http.get などは要求を 1 バイトも出さずに止まる。持っていない能力を「送れなかった」の顔をした Err に化けさせない規律 (§9) に従う — tls を渡した serve が呼び出しで止まる (server.md §14) のと対である。走り出した要求が https へ転送された場合だけは、止めるには遅いので connect_error (§9) になる。

例外は同じプログラムが立てた待ち受けである。std:http/server の serve (server.md §14) が待ち受けている port へ loopback の綴り (127.0.0.1 / localhost) で要求を出すと、その要求はソケットを介さずにその待ち受けへ届く。生の HTTP を組んで渡すので、応答の形も本書が定めるとおりになる。

待ち受けが始まる前に叩けば connect_error である。したがって「繋がるまで短く刻んで待つ」形はブラウザーでもそのまま働く。

12. 制約

本文は一括読み込みで、ストリーミングとチャンク送信は持たない。
クッキー管理・自動リトライ・コネクションプールの明示制御・multipart 構築ヘルパーは提供しない。

http.* が返す Future を取り消すと、要求を打ち切って接続を閉じる (prelude.md §9.8)。Future はキャンセルの panic で解決する。Future を ! で待っているフローを取り消した場合も同じ扱いにする — 待つ者のいなくなった要求を、上限の 30 秒まで走らせない。打ち切りは送り終えた分を取り戻さないので、相手は受け取った要求を処理しうる。

Future / scheduler との関係は prelude.md §9.4 と同じ。root リテラル本体の評価が完了した時点で未解決の http Future は language-spec.md §13.3 のとおり放棄される (実装は進行中の要求を打ち切る責任を持つ)。