セッション

**未公開。**Glac のブラウザはまだ利用できません。このページは、構築中の仕組みを公開前に説明したもので、公開までに変わることがあります。

呼び出し一覧

セッションの作成、変更、スリープ、終了には write スコープを持つキーが、読み取りには read スコープが必要です。アドレスは認証情報なので、url スコープのないキーで読むと、cdp_url と live_url は null になります。

セッションの作成

どのフィールドも省略できます。

POST /v1/browsers
{"name": "agent-42", "region": "eu", "sleep_after_seconds": 30}

レスポンスはセッション（201）で、Location: /v1/browsers/<id> が付きます。作成には Idempotency-Key を指定でき、同じキーで再送した作成には、最初と同じレスポンスが返ります。

作成は、プランでアカウントが同時に稼働させられる上限によって拒否されることがあります（403 plan_cap_reached、param は instances、vcpus、memory_bytes のいずれか）。また、今すぐ収容できるマシンがない場合も拒否されます（503 no_capacity、retryable）。その種類のイメージが与えられていないコントロールプレーンでは、その種類のセッションは作成できません（503 not_served_here、param は kind）。ブラウザを起動できなかったセッション（イメージを取得できなかった、ブラウザが立ち上がらなかった）はセッションになりません。作成は拒否され（503 session_failed、retryable）、マシンが返した内容とそのコードが message に入り、何も残りません。

セッションが持つもの

同じ名前なら同じセッション

プロジェクトにあるセッションの名前で作成すると、そのセッションが、スリープしたところから復帰し、ページもそのままの状態で返されます（200）。エージェントが毎ターン agent-42 を求めれば、同じブラウザが返ってきます。この復帰も、ほかの復帰と同じく、プランでアカウントが同時に稼働させられる上限の対象です。同じ名前で同時に 2 回作成しても作られるセッションは 1 つで、両方にそのセッションが返されます。

プロジェクトの通常のサンドボックスが使っている名前は拒否されます（409 name_taken）。サンドボックスがセッションになることはありません。別の種類のセッションの名前も拒否され、プロファイルのアドレスである profiles も拒否されます（400 invalid_name）。

稼働とスリープ

セッションは、ブラウザ（chromium セッションでは画面）にクライアントが接続している間、ページが何をしていても稼働中です。ページのタイマーやネットワーク通信だけでは稼働し続けません。最後の接続が閉じて（最後のリクエストが終わって）から sleep_after_seconds 秒後に、メモリとディスクを保持したままスリープし、復帰したときにはタブもページもそのまま残っています。connection_idle_seconds の間どちらの方向にも何も流れない接続は閉じられるため、接続を閉じずにいなくなったクライアントがセッションを稼働させ続けることはありません。

• POST /v1/browsers/{id}/sleep は、セッションをすぐにスリープさせます。開いている接続は開いたままで、次のメッセージでセッションが復帰します。
• アドレスへの接続で復帰します。
• PATCH /v1/browsers/{id} は、sleep_after_seconds、connection_idle_seconds、delete_after_idle_seconds、metadata（全体を置き換え）、proxy を変更します。時間を null にするとデフォルトに戻り、delete_after_idle_seconds: null ならセッションは削除されずに残り、proxy: null でプロキシを外します。

新しいアドレス

POST /v1/browsers/{id}/rotate-url は、セッションのアドレスに新しいシークレットを与えます。それまでに発行したアドレスはすべてそれ以降拒否され（401 invalid_link）、それらのアドレスで入った接続は、CDP クライアントのものも含め、呼び出しが応答する前に切断されます。レスポンスは新しい cdp_url を持つセッションです。見られてはいけない人にアドレスを見られたときに実行してください。

自前のプロキシ

有料プランでは、セッションの Web トラフィックを自前の HTTP プロキシ経由で送信できます。作成時に proxy を指定するか、後から変更します。

POST /v1/browsers
{"name": "agent-42", "proxy": {"url": "http://user:password@proxy.example.com:3128"}}

• 経由するもの：セッションのポート 80 と 443 への TCP 接続で、ブラウザがページを読み込むのに使う接続です。ブラウザを動かすマシン上でブラウザの隣にあるリレーが、各接続の行き先（TLS ハンドシェイクのサーバー名、HTTP リクエストの Host）を読み取り、そこへのトンネルを自前のプロキシに要求します（CONNECT name:port、認証情報は Proxy-Authorization: Basic ヘッダー）。サイトから見えるのはプロキシのアドレスで、名前はプロキシで解決されます。トンネルの中では何も読み取られず、変更もされません。TLS はブラウザとサイトの間で続きます。
• QUIC は拒否：HTTP プロキシでは運べないポート 443 への UDP はセッションから出られないため、ブラウザはプロキシを通じて TCP 上の HTTP で通信します。ほかのポートへの接続は、プロキシがない場合と同じように送信されます。
• ブラウザには知らされない：ブラウザの設定にプロキシは現れず、そのために再起動されるものもなく、セッションの中に認証情報を持つものもありません（ファイルにも、環境変数にも、プロセスにもありません）。認証情報はセッションが動くマシンが保持し、API のどのレスポンスにも含まれません。proxy に表示されるのはアドレスとユーザー名です。
• プロキシは、ポート 80 と 443 への CONNECT を受け付ける HTTP プロキシで、インターネット上のホスト名かアドレスにあるものです（Squid は、ポート 80 も許可しない限り、ポート 443 への CONNECT しか通しません）。http:// のみで、ユーザー名とパスワードに URL で使えない文字（@、:、/）が含まれる場合は %XX で表記します。TLS 経由で接続するプロキシ（https://）、SOCKS、サンドボックスから到達できないアドレス（プライベートアドレス範囲、リンクローカル、ループバック）は拒否されます（400 invalid_proxy、param は proxy.url）。メッセージに URL が繰り返されることはありません。
• 変更：PATCH /v1/browsers/{id} で別の proxy を指定する（なしにするなら null）と、次の接続から反映されます。ブラウザとページはそのまま動き続け、それまでのプロキシ経由の接続は切断され、ブラウザは現在の設定どおりの経路で新しい接続を開きます。
• プロキシがトンネルを受け付けない場合（到達できない、または CONNECT に 2xx 以外を返す。受け付けない認証情報には 407）：HTTP で読み込むページには 502 proxy_failed が返り、そのメッセージにはプロキシのアドレスと応答が示されますが、認証情報は含まれません。HTTPS で読み込むページは TLS ハンドシェイクに失敗します。セッションのマシンは、認証情報を除いてこれをログに記録します。
• 料金：プロキシを通過したデータは双方向で数えられ（usage.proxy_bytes）、ほかと同じくセッションのトラフィックです。プロキシへ出ていくデータは送信トラフィックで、サンドボックスと同じ料金です。
• リクエストのルールとは併用不可：ネットワークルールがリクエストを読み取る（inject、http）セッションには、プロキシを設定できません（400 invalid_proxy）。アドレス、ポート、名前によるルールは、プロキシを経由するものにも、ほかと同じく適用されます。
• プロキシはセッションのためのものです。通常のサンドボックスには設定できません（400 unknown_field）。

ネットワーク

セッションはサンドボックスと同じようにインターネットに接続しますが、ポート 25、465、587（メール）や、マイニングプールが待ち受けるポート（3333、4444、5555、7777、14444、45700）には決して届きません。マシンがほかの何よりも先に拒否します。セッションのネットワークルールは PATCH /v1/sandboxes/{id} の egress で変更し、ルールの内容にかかわらず、これらのポートは閉じたままです。