Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 15365] ファイルの概要

このコミットは、Go言語の標準ライブラリ net/url パッケージにおける URL 構造体の Opaque フィールドに関するドキュメントの修正です。特に、クライアントリクエストを作成する際に Opaque フィールドをどのように使用すべきかについての注記を明確にすることを目的としています。

コミット

commit 0462aad9a485d1df06ea935d7f9d1044a29ad746
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Thu Feb 21 14:39:16 2013 -0800

    net/url: fix URL Opaque notes on making client requests
    
    Fixes #4860
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/7375047

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/0462aad9a485d1df06ea935d7f9d1044a29ad746

元コミット内容

net/url: fix URL Opaque notes on making client requests

このコミットは、net/url パッケージの URL 構造体における Opaque フィールドに関する注記を修正し、クライアントリクエストを作成する際の正しい使用方法を明確にすることを目的としています。

変更の背景

このコミットは、GoのIssue #4860「net/url: URL.Opaque のドキュメントは、クライアントリクエストの作成方法について誤解を招く可能性がある」を修正するために行われました。

元のドキュメントでは、URL{Opaque: "/Go%2f"} のような例が示されていましたが、これはホスト情報を含まないため、HTTPクライアントが外部リソースにリクエストを送信する際には不完全でした。HTTPクライアントがリクエストを送信するためには、通常、ホスト情報が必要です。Opaque フィールドは、スキーム固有の階層的でない部分（例: mailto:user@example.com の user@example.com）や、パスがエンコードされた形式で厳密に扱われるべき場合に使用されます。しかし、HTTPリクエストの文脈では、ホスト情報が欠落していると、クライアントがどのサーバーに接続すべきかを判断できません。

この問題は、URL 構造体の Opaque フィールドのドキュメントが、特にHTTPクライアントがリクエストを構築する際の具体的な例において、誤解を招く可能性があったために発生しました。Opaque フィールドは、URLのパス部分がエンコードされた形式でそのまま扱われるべき場合に利用されますが、HTTPリクエストにおいては、通常 Host フィールドも適切に設定されている必要があります。元の例では Host フィールドが省略されており、これが混乱の原因となっていました。

前提知識の解説

URL (Uniform Resource Locator)

URLは、インターネット上のリソースの位置を示す統一リソース識別子 (URI) の一種です。一般的なURLは、以下のコンポーネントで構成されます。

  • スキーム (Scheme): リソースにアクセスするためのプロトコル（例: http, https, ftp, mailto）。
  • ユーザー情報 (User Info): ユーザー名とパスワード（通常は省略される）。
  • ホスト (Host): リソースが配置されているサーバーのドメイン名またはIPアドレス。
  • ポート (Port): サーバー上の特定のサービスを識別する番号（通常はスキームのデフォルトポートが使用されるため省略される）。
  • パス (Path): サーバー上のリソースの階層的な位置。
  • クエリ (Query): リソースに渡される追加のパラメータ。
  • フラグメント (Fragment): リソース内の特定の部分を指す識別子。

Go言語の net/url パッケージ

Go言語の net/url パッケージは、URLの解析と構築のための機能を提供します。このパッケージの中心となるのが URL 構造体です。

type URL struct {
    Scheme     string
    Opaque     string    // encoded opaque data
    User       *Userinfo // username and password information
    Host       string    // host or host:port
    Path       string    // path (relative paths may omit leading slash)
    RawPath    string    // encoded path hint (see EscapedPath method)
    ForceQuery bool      // append a query ('?') even if RawQuery is empty
    RawQuery   string    // encoded query values, without '?'
    Fragment   string    // fragment for references, without '#'
}

URL 構造体の Opaque フィールドと Path フィールド

  • Path フィールド: これはURLの階層的なパス部分を表します。例えば、http://example.com/foo/bar の場合、Path は /foo/bar となります。Path フィールドは、通常、URLエンコード/デコードの規則に従って処理されます。
  • Opaque フィールド: このフィールドは、URLのスキーム固有の部分が階層的でない場合、またはその部分がエンコードされた形式でそのまま扱われるべき場合に利用されます。例えば、mailto:user@example.com の場合、Opaque は user@example.com となります。Opaque が設定されている場合、Path、RawPath、RawQuery、ForceQuery、Fragment フィールドは無視され、URL の文字列表現は Scheme と Opaque の組み合わせ（例: scheme:opaque）になります。

Opaque フィールドは、主に mailto: や urn: のようなスキームで、URLのパス部分が階層構造を持たない場合や、エンコードされた形式をそのまま保持したい場合に設計されています。HTTP/HTTPSのような階層的なURLでは、通常 Path フィールドが使用されます。

技術的詳細

このコミットの技術的なポイントは、net/url パッケージの URL 構造体の Opaque フィールドのドキュメントが、HTTPクライアントがリクエストを構築する際の具体的な例において、誤解を招く可能性があった点を修正したことです。

元のドキュメントの例: an HTTP client can use URL{Opaque: "/Go%2f"} instead of URL{Path: "/Go/"}.

この例は、Opaque フィールドに /Go%2f を設定することで、パスがエンコードされた形式で扱われることを示唆していますが、HTTPクライアントが実際にリクエストを送信するためには、どのホストに接続すべきかという情報（Host フィールド）が不可欠です。Opaque フィールドは、URLのスキーム固有の部分が階層的でない場合（例: mailto:user@example.com）や、パスがエンコードされた形式で厳密に扱われるべき場合に利用されます。しかし、HTTPリクエストの文脈では、ホスト情報が欠落していると、クライアントがどのサーバーに接続すべきかを判断できません。

修正後のドキュメントの例: an HTTP client can use URL{Host: "example.com", Opaque: "//example.com/Go%2f"} instead of URL{Host: "example.com", Path: "/Go/"}.

この修正により、Host フィールドが明示的に追加され、HTTPクライアントがリクエストを送信する際に必要な情報がすべて揃うようになりました。また、Opaque フィールドの値も //example.com/Go%2f となり、これは URL 構造体の String() メソッドが Opaque フィールドをどのように処理するか（scheme:opaque の形式）を考慮したものです。HTTP URLの場合、Opaque フィールドに //host/path の形式で値を設定することで、URL.String() が http://host/path のような形式を生成するようになります。

この変更は、Opaque フィールドの本来の意図と、HTTPクライアントがURLを構築する際の現実的な要件との間のギャップを埋めるものです。Opaque は、URLのパス部分がエンコードされた形式でそのまま扱われるべき場合に利用されますが、HTTPリクエストにおいては、通常 Host フィールドも適切に設定されている必要があります。この修正は、開発者が net/url パッケージをより正確に、かつ意図した通りに使用できるようにするための重要なドキュメント改善です。

コアとなるコードの変更箇所

変更は src/pkg/net/url/url.go ファイルの1箇所のみです。

--- a/src/pkg/net/url/url.go
+++ b/src/pkg/net/url/url.go
@@ -225,7 +225,8 @@ func escape(s string, mode encoding) string {
 // slashes in the raw URL and which were %2f. This distinction is rarely important,
 // but when it is a client must use other routines to parse the raw URL or construct
 // the parsed URL. For example, an HTTP server can consult req.RequestURI, and
-// an HTTP client can use URL{Opaque: "/Go%2f"} instead of URL{Path: "/Go/"}.
+// an HTTP client can use URL{Host: "example.com", Opaque: "//example.com/Go%2f"}\n+// instead of URL{Host: "example.com", Path: "/Go/"}.
 type URL struct {
  	Scheme   string
  	Opaque   string    // encoded opaque data

具体的には、URL 構造体の Opaque フィールドに関するコメントが以下のように変更されました。

  • 変更前: an HTTP client can use URL{Opaque: "/Go%2f"} instead of URL{Path: "/Go/"}.
  • 変更後: an HTTP client can use URL{Host: "example.com", Opaque: "//example.com/Go%2f"} instead of URL{Host: "example.com", Path: "/Go/"}.

コアとなるコードの解説

この変更は、net/url パッケージの URL 構造体のドキュメントコメントを修正するものです。

元のコメントでは、HTTPクライアントが Opaque フィールドを使用してURLを構築する例として URL{Opaque: "/Go%2f"} が挙げられていました。しかし、HTTPリクエストを送信する際には、通常、どのホストにリクエストを送信するかを示す Host フィールドが必要です。Opaque フィールドは、URLのスキーム固有の部分が階層的でない場合（例: mailto: スキーム）や、パスがエンコードされた形式でそのまま扱われるべき場合に利用されます。HTTPのような階層的なURLでは、Opaque を使用する場合でも、ホスト情報が適切に設定されている必要があります。

修正後のコメントでは、URL{Host: "example.com", Opaque: "//example.com/Go%2f"} という例が示されています。これにより、HTTPクライアントが Opaque フィールドを使用する際に、Host フィールドも適切に設定する必要があることが明確になります。また、Opaque フィールドの値が //example.com/Go%2f となっているのは、URL 構造体の String() メソッドが Opaque フィールドをどのように処理するか（scheme:opaque の形式）を考慮したものです。HTTP URLの場合、Opaque フィールドに //host/path の形式で値を設定することで、URL.String() が http://host/path のような形式を生成するようになります。

この修正は、Opaque フィールドのドキュメントをより正確にし、開発者がHTTPクライアントで net/url パッケージを扱う際の混乱を避けることを目的としています。これにより、Opaque フィールドの本来の意図と、HTTPクライアントがURLを構築する際の現実的な要件との間のギャップが埋められます。

関連リンク

参考にした情報源リンク