"http.server" --- HTTP サーバー
*******************************

**ソースコード:** Lib/http/server.py

======================================================================

このモジュールは HTTP サーバを実装するためのクラスを提供しています。

警告:

  "http.server" は本番環境での利用には推奨しません。 基本的なセキュリ
  ティチェック だけを実装しています。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。

クラス "HTTPServer" は "socketserver.TCPServer" のサブクラスです。
"HTTPServer" は HTTP ソケットを生成してリクエスト待ち (listen) を行い
、リクエストをハンドラに渡します。 サーバを作成して動作させるためのコ
ードは以下のようになります:

   def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
       server_address = ('', 8000)
       httpd = server_class(server_address, handler_class)
       httpd.serve_forever()

class http.server.HTTPServer(server_address, RequestHandlerClass)

   このクラスは "TCPServer" クラスを基にしており、サーバーのアドレスを
   "server_name" と "server_port" というインスタンス変数に格納します。
   ハンドラーからは、通常は "server" インスタンス変数を通じてサーバー
   にアクセスできます。

   server_name

      HTTP サーバーの完全修飾ドメイン名。

   server_port

      *server_address* から取得した HTTP サーバーのポート番号。

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)

   このクラスは HTTPServer と同じですが、"ThreadingMixIn" を使い、スレ
   ッドでリクエストを処理します。 ウェブブラウザーがあらかじめ開いたソ
   ケットに対応するのに便利です。 このようなソケットでは "HTTPServer"
   は無期限に待機してしまいます。

   Added in version 3.7.

class http.server.HTTPSServer(server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)

   "ssl" モジュールでソケットをラップした "HTTPServer" のサブクラスで
   す。 "ssl" モジュールが利用できない場合、"HTTPSServer" オブジェクト
   のインスタンス化は "RuntimeError" で失敗します。

   *certfile* 引数は SSL 証明書チェーンファイルのパス、*keyfile* は秘
   密鍵を含むファイルのパスです。

   PKCS#8 で保護しラップしたファイルには *password* を指定できますが、
   コードに埋め込んだパスワードが平文で露出する可能性がある点に注意し
   てください。

   参考:

     *certfile*、*keyfile*、*password* に指定できる値については、
     "ssl.SSLContext.load_cert_chain()" を参照してください。

   *alpn_protocols* 引数を指定する場合、サーバーがサポートする「
   Application-Layer Protocol Negotiation」(ALPN) のプロトコルを表す文
   字列のシーケンスでなければなりません。 ALPN を使うと、TLS ハンドシ
   ェイク中にサーバーとクライアントがアプリケーションプロトコルをネゴ
   シエートできます。

   デフォルトは "["http/1.1"]" で、サーバーが HTTP/1.1 をサポートする
   ことを意味します。

   Added in version 3.14.

class http.server.ThreadingHTTPSServer(server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)

   このクラスは "HTTPSServer" と同じですが、"ThreadingMixIn" を継承し
   、スレッドでリクエストを処理します。 "ThreadingHTTPServer" に相当す
   るクラスで、"HTTPSServer" を使う点だけが異なります。

   Added in version 3.14.

The "HTTPServer", "ThreadingHTTPServer", "HTTPSServer" and
"ThreadingHTTPSServer" must be given a *RequestHandlerClass* on
instantiation, of which this module provides three different variants:

class http.server.BaseHTTPRequestHandler(request, client_address, server)

   このクラスは、サーバーに届いた HTTP リクエストを処理するために使い
   ます。 このクラス単独では実際の HTTP リクエストに応答できません。
   サブクラスを作り、各リクエストメソッド ("'GET'" や "'POST'" など)
   を処理する必要があります。 "BaseHTTPRequestHandler" は、サブクラス
   が利用するためのさまざまなクラス変数、インスタンス変数、メソッドを
   提供します。

   ハンドラーはリクエストとヘッダーを解析してから、リクエストの種類に
   対応するメソッドを呼び出します。 メソッド名はリクエストから組み立て
   ます。 例えば、リクエストメソッドが "SPAM" なら、"do_SPAM()" メソッ
   ドを引数なしで呼び出します。 関連する情報はすべてハンドラーのインス
   タンス変数に格納されます。 サブクラスで "__init__()" メソッドをオー
   バーライドしたり拡張したりする必要はないはずです。

   "BaseHTTPRequestHandler" は以下のインスタンス変数を持っています:

   client_address

      HTTP クライアントのアドレスを参照している、"(host, port)" の形式
      をとるタプルが入っています。

   server

      server インスタンスが入っています。

   close_connection

      "handle_one_request()" が返る前に設定すべき真偽値で、別のリクエ
      ストが期待されているかどうか、もしくはコネクションを切断すべきか
      どうかを指し示しています。

   requestline

      HTTP リクエスト行の文字列表現を保持しています。 末尾の CRLF は除
      去されています。 この属性は "handle_one_request()" によって設定
      されるべきです。 妥当なリクエスト行が1行も処理されなかった場合は
      、空文字列に設定されるべきです。

   command

      HTTP 命令 (リクエスト形式) が入っています。例えば "'GET'" です。

   path

      リクエストのパスを保持します。 URL にクエリー部分がある場合、
      "path" にはクエリーも含まれます。 **RFC 3986** の用語では、ここ
      での "path" には "hier-part" と "query" が含まれます。

   request_version

      リクエストのバージョン文字列が入っています。例えば "'HTTP/1.0'"
      です。

   headers

      "MessageClass" クラス変数で指定したクラスのインスタンスを保持し
      ます。 このインスタンスは、HTTP リクエストのヘッダーを解析し管理
      します。 解析には "http.client" の "parse_headers()" 関数を使う
      ため、HTTP リクエストは有効な **RFC 5322** 形式のヘッダーを提供
      する必要があります。

   rfile

      入力データがあればその先頭から読み込める状態の
      "io.BufferedIOBase" 入力ストリームです。

   wfile

      クライアントにレスポンスを書き返すための出力ストリームを保持しま
      す。 HTTP クライアントと正しくやり取りするため、このストリームへ
      の書き込みは HTTP プロトコルに正しく従う必要があります。

      バージョン 3.6 で変更: "io.BufferedIOBase" ストリームになりまし
      た。

   "BaseHTTPRequestHandler" は以下の属性を持っています:

   server_version

      サーバのソフトウェアバージョンを指定します。この値は上書きする必
      要が生じるかもしれません。書式は複数の文字列を空白で分割したもの
      で、各文字列はソフトウェア名[/バージョン] の形式をとります。例え
      ば、"'BaseHTTP/0.2'" です。

   sys_version

      Python 処理系のバージョンが, "version_string" メソッドや
      "server_version" クラス変数で利用可能な形式で入っています。例え
      ば "'Python/1.4'" です。

   error_message_format

      "send_error()" メソッドがクライアントへのエラーレスポンスを組み
      立てる際に使う書式文字列を指定します。 デフォルトでは、
      "send_error()" に渡したステータスコードに応じて "responses" から
      得た値を文字列に埋め込みます。

   error_content_type

      エラーレスポンスをクライアントに送信する時に使う Content-Type
      HTTP ヘッダを指定します。デフォルトでは "'text/html'" です。

   protocol_version

      サーバーが準拠する HTTP バージョンを指定します。 この値はレスポ
      ンスで送信され、後続のリクエストで使えるサーバーの通信機能をクラ
      イアントに知らせます。 "'HTTP/1.1'" にすると HTTP の持続的接続を
      許可しますが、その場合はクライアントへのすべてのレスポンスに、
      ("send_header()" を使って) 正確な "Content-Length" ヘッダーを含
      める *必要があります*。 後方互換性のため、デフォルトは
      "'HTTP/1.0'" です。

   MessageClass

      HTTP ヘッダを解釈するための "email.message.Message" 類似のクラス
      を指定します。 通常この値が上書きされることはなく、デフォルトの
      "http.client.HTTPMessage" になっています。

   responses

      この属性は、整数のエラーコードから、短いメッセージと長いメッセー
      ジを含む 2 要素タプルへのマッピングを保持します。 例えば "{code:
      (shortmessage, longmessage)}" です。 通常、*shortmessage* はエラ
      ーレスポンスの *message* キー、*longmessage* は *explain* キーと
      して使います。 "send_response_only()" メソッドと "send_error()"
      メソッドがこの属性を使います。

   "BaseHTTPRequestHandler" インスタンスは以下のメソッドを持っています
   :

   handle()

      "handle_one_request()" を 1 回 (持続的接続が有効な場合は複数回)
      呼び出し、届いた HTTP リクエストを処理します。 このメソッドをオ
      ーバーライドする必要はないはずです。 代わりに、適切な "do_*()"
      メソッドを実装してください。

   handle_one_request()

      このメソッドは、リクエストを解析して適切な "do_*()" メソッドに振
      り分けます。 このメソッドをオーバーライドする必要はないはずです
      。

   handle_expect_100()

      HTTP/1.1 に準拠するサーバーが "Expect: 100-continue" リクエスト
      ヘッダーを受信すると、"100 Continue" に続けて "200 OK" ヘッダー
      を返します。 サーバーがクライアントに処理を続けさせたくない場合
      、このメソッドをオーバーライドしてエラーを返せます。 例えば、レ
      スポンスヘッダーとして "417 Expectation Failed" を送信し、
      "return False" を実行できます。

      Added in version 3.2.

   send_error(code, message=None, explain=None)

      完全なエラー応答をクライアントに送信し、ログに記録します。 数値
      の *code* は HTTP エラーコードを指定します。 オプションの
      *message* には、人間が読める短いエラー説明を指定します。
      *explain* 引数には、エラーについてより詳しい情報を指定できます。
      この情報は "error_message_format" 属性を使って書式化し、ヘッダー
      全体の後にレスポンス本体として出力します。 "responses" 属性は、
      値を指定しなかったときに使う *message* と *explain* のデフォルト
      値を保持します。 未知のコードでは、どちらのデフォルト値も文字列
      "???" です。 メソッドが HEAD の場合や、レスポンスコードが
      "1*xx*"、"204 No Content"、"205 Reset Content"、"304 Not
      Modified" のいずれかの場合、本体は空になります。

      バージョン 3.4 で変更: エラーレスポンスに Content-Length ヘッダ
      ーを含めるようになりました。 *explain* 引数を追加しました。

   send_response(code, message=None)

      レスポンスヘッダーをヘッダーバッファーに追加し、受け付けたリクエ
      ストをログに記録します。 HTTP レスポンス行を内部バッファーに書き
      込み、続いて *Server* ヘッダーと *Date* ヘッダーを書き込みます。
      これらの値は、それぞれ "version_string()" メソッドと
      "date_time_string()" メソッドから取得します。 "send_header()" メ
      ソッドで他のヘッダーを送信する予定がなければ、"send_response()"
      の後に "end_headers()" を呼び出してください。

      バージョン 3.3 で変更: ヘッダーは内部バッファーに保持されるよう
      になったため、"end_headers()" を明示的に呼び出す必要があります。

   send_header(keyword, value)

      HTTP ヘッダーを内部バッファーに追加します。 "end_headers()" また
      は "flush_headers()" を呼び出すと、このバッファーを出力ストリー
      ムに書き出します。 *keyword* にはヘッダーのキーワード、*value*
      にはその値を指定します。 "send_header()" の呼び出しを終えたら、
      処理を完了するために必ず "end_headers()" を呼び出してください。

      このメソッドは、CRLF シーケンスを含む入力を拒否しません。

      バージョン 3.2 で変更: ヘッダは内部バッファに保存されます。

   send_response_only(code, message=None)

      Sends the response header only, used for the purposes when "100
      Continue" response is sent by the server to the client. The
      headers are not buffered and sent directly the output stream. If
      the *message* is not specified, the HTTP message corresponding
      the response *code*  is sent.

      このメソッドは、CRLF シーケンスを含む *message* を拒否しません。

      Added in version 3.2.

   end_headers()

      ヘッダーバッファーに空行 (レスポンスの HTTP ヘッダーの終わりを示
      す行) を追加し、"flush_headers()" を呼び出します。

      バージョン 3.2 で変更: バッファされたヘッダは出力ストリームに書
      き出されます。

   flush_headers()

      最終的にヘッダを出力ストリームに送り、内部ヘッダバッファをフラッ
      シュします。

      Added in version 3.3.

   log_request(code='-', size='-')

      受理された (成功した) リクエストをログに記録します。*code* には
      この応答に関連付けられた HTTP コード番号を指定します。応答メッセ
      ージの大きさを知ることができる場合、*size* パラメタに渡すとよい
      でしょう。

   log_error(...)

      リクエストを遂行できなかった際に、エラーをログに記録します。標準
      では、メッセージを "log_message()" に渡します。従って同じ引数
      (*format* と追加の値) を取ります。

   log_message(format, ...)

      任意のメッセージを "sys.stderr" に記録します。 独自のエラーログ
      機構を作るには、通常このメソッドをオーバーライドします。
      *format* 引数は標準的な printf 形式の書式文字列で、
      "log_message()" への追加の引数を書式化の入力に使います。 記録す
      る各メッセージの前には、クライアントの IP アドレスと現在の日時を
      付けます。

   version_string()

      サーバーのソフトウェアのバージョンを示す文字列を返します。 その
      文字列は、"server_version" と "sys_version" の属性が含まれます。

   date_time_string(timestamp=None)

      メッセージヘッダ向けに書式化された、 *timestamp* ("None" または
      "time.time()" のフォーマットである必要があります)で与えられた日
      時を返します。もし *timestamp* が省略された場合には、現在の日時
      が使われます。

      出力は "'Sun, 06 Nov 1994 08:49:37 GMT'" のようになります。

   log_date_time_string()

      ログ記録向けに書式化された、現在の日付および時刻を返します。

   address_string()

      クライアントのアドレスを返します。

      バージョン 3.3 で変更: 以前は名前の検索を行っていました。 名前解
      決による遅延を避けるため、常に IP アドレスを返すようになりました
      。

class http.server.SimpleHTTPRequestHandler(request, client_address, server, *, directory=None, extra_response_headers=None)

   このクラスは、ディレクトリ構造を HTTP リクエストに直接対応付け、
   *directory* とその下位ディレクトリにあるファイルを配信します。
   *directory* を省略すると、現在のディレクトリを使います。

   バージョン 3.7 で変更: *directory* 引数を追加しました。

   バージョン 3.9 で変更: *directory* 引数が *path-like object* を受け
   付けるようになりました。

   バージョン 3.15 で変更: *extra_response_headers* 引数を追加しました
   。

   リクエストの解釈のような、多くの作業は基底クラス
   "BaseHTTPRequestHandler" で行われます。このクラスは関数 "do_GET()"
   および "do_HEAD()" を実装しています。

   "SimpleHTTPRequestHandler" では以下のメンバ変数を定義しています:

   server_version

      この値は ""SimpleHTTP/" + __version__" になります。"__version__"
      はこのモジュールで定義されている値です。

   default_content_type

      リクエストされた URL のファイル拡張子から MIME 型を推測できない
      場合に送信する、Content-Type ヘッダーの値を指定します。 デフォル
      トは "'application/octet-stream'" です。

      Added in version 3.15.

   index_pages

      ディレクトリのインデックスページとして扱うファイル名を指定します
      。

      デフォルトは "("index.html", "index.htm")" です。

      Added in version 3.12.

   extensions_map

      拡張子から MIME 型へのマッピングで、システムのデフォルトのマッピ
      ングを上書きする独自の設定を保持する辞書です。 大文字と小文字を
      区別せずに使うため、キーには小文字だけを含めてください。

      バージョン 3.9 で変更: この辞書にシステムのデフォルトのマッピン
      グを格納しなくなり、上書きする設定だけを含むようになりました。

   extra_response_headers

      HTTP ステータス 200 の成功レスポンスごとに追加する、利用者定義の
      HTTP レスポンスヘッダーを含む "(name, value)" ペアのシーケンスで
      す。 これらのヘッダーは、他のステータスコードのレスポンスには含
      めません。

      "Content-Type" などのサーバーが自動で送信するヘッダーは、
      "extra_response_headers" では上書きされません。

   "SimpleHTTPRequestHandler" では以下のメソッドを定義しています:

   do_HEAD()

      このメソッドは "'HEAD'" 型のリクエスト処理を実行します: すなわち
      、 "GET" リクエストの時に送信されるものと同じヘッダを送信します
      。送信される可能性のあるヘッダについての完全な説明は "do_GET()"
      メソッドを参照してください。

   do_GET()

      リクエストを現在の作業ディレクトリからの相対的なパスとして解釈す
      ることで、リクエストをローカルシステム上のファイルと対応付けます
      。

      リクエストがディレクトリに対応する場合、"index_pages" で指定され
      たインデックスページがあるか調べます。 見つかればそのファイルの
      内容を返し、なければ "list_directory()" メソッドを呼び出してディ
      レクトリ一覧を生成します。 このメソッドは "os.listdir()" でディ
      レクトリを調べ、"listdir()" が失敗した場合は "404" エラーレスポ
      ンスを返します。

      リクエストがファイルに対応する場合、そのファイルを開きます。 フ
      ァイルを開く際に発生した "OSError" 例外は、"404"、"'File not
      found'" エラーに対応付けます。 リクエストに "'If-Modified-
      Since'" ヘッダーがあり、ファイルがその日時より後に変更されていな
      ければ、"304"、"'Not Modified'" レスポンスを送信します。 そうで
      なければ、*extensions_map* 変数を使う "guess_type()" メソッドを
      呼び出してコンテントタイプを推測し、ファイルの内容を返します。

      出力は "'Content-type:'" と推測されたコンテントタイプで、その後
      にファイルサイズを示す "'Content-Length:'" ヘッダと、ファイルの
      更新日時を示す "'Last-Modified:'" ヘッダが続きます。

      インスタンス属性 "extra_response_headers" は、利用者定義の追加の
      レスポンスヘッダーを含む "(name, value)" ペアのシーケンスです。

      続いてヘッダーの終わりを示す空行を出力し、その後にファイルの内容
      を出力します。

      使用例は Lib/http/server.py の "test" 関数の実装を参照してくださ
      い。

      バージョン 3.7 で変更: "'If-Modified-Since'" ヘッダーをサポート
      しました。

   list_directory(path)

      インデックスページがない場合に、*path* の内容を一覧表示するため
      のヘルパーです。

      *file-like object* (呼び出し側が閉じる必要があります) を返すか、
      エラーを示す "None" を返します。 後者の場合、呼び出し側がそれ以
      上行うことはありません。 どちらの場合もヘッダーを送信します。

   guess_type(path)

      指定された *path* にあるファイルの型を推測します。

      MIME の Content-type ヘッダーに使える "type/subtype" 形式の文字
      列を返します。

      デフォルトの実装は "extensions_map" でファイルの拡張子を調べ、見
      つからなければ "mimetypes.guess_file_type()"、さらに
      "default_content_type" の順に試します。

      バージョン 3.13 で変更: フォールバックとして
      "mimetypes.guess_file_type()" を追加しました。

"SimpleHTTPRequestHandler" クラスを使うと、現在のディレクトリを基準に
ファイルを配信する、ごく基本的なウェブサーバーを次のように作れます。

   import http.server
   import socketserver

   PORT = 8000

   Handler = http.server.SimpleHTTPRequestHandler

   with socketserver.TCPServer(("", PORT), Handler) as httpd:
       print("serving at port", PORT)
       httpd.serve_forever()

"SimpleHTTPRequestHandler" のサブクラスを作って、動作を拡張することも
できます。 例えば、クラス属性 "index_pages" を上書きすると、異なるイン
デックスファイル名を使えます。


コマンドライン・インターフェース
================================

"http.server" は、インタープリタの "-m" オプションで直接起動することも
できます。 以下の例は、現在のディレクトリを基準にファイルを配信する方
法を示します。

   python -m http.server [OPTIONS] [port]

以下のオプションが使用できます:

port

   サーバーはデフォルトでポート 8000 で待ち受けます。 使いたいポート番
   号を引数として渡すと変更できます。

      python -m http.server 9000

-b, --bind <address>

   バインド先のアドレスを指定します。 IPv4 と IPv6 の両方に対応してい
   ます。 デフォルトでは、サーバーはすべてのインターフェースにバインド
   します。 例えば、次のコマンドでは localhost だけにバインドします。

      python -m http.server --bind 127.0.0.1

   Added in version 3.4.

   バージョン 3.8 で変更: "--bind" オプションで IPv6 をサポートしまし
   た。

-d, --directory <dir>

   ファイルを配信するディレクトリを指定します。 デフォルトでは現在のデ
   ィレクトリを使います。 例えば、次のコマンドでは特定のディレクトリを
   使います。

      python -m http.server --directory /tmp/

   Added in version 3.7.

-p, --protocol <version>

   サーバーが準拠する HTTP バージョンを指定します。 デフォルトでは
   HTTP/1.0 に準拠します。 例えば、次のコマンドでは HTTP/1.1 に準拠す
   るサーバーを実行します。

      python -m http.server --protocol HTTP/1.1

   Added in version 3.11.

--content-type <content_type>

   URL のファイル拡張子から MIME 型を推測できない場合に使う、デフォル
   トの Content-Type HTTP ヘッダーを指定します。 デフォルトでは
   "'application/octet-stream'" を使います。

      python -m http.server --content-type text/html

   Added in version 3.15.

--tls-cert

   HTTPS 接続に使う TLS 証明書チェーンを指定します。

      python -m http.server --tls-cert fullchain.pem

   Added in version 3.14.

--tls-key

   HTTPS 接続に使う秘密鍵ファイルを指定します。

   このオプションには "--tls-cert" の指定が必要です。

   Added in version 3.14.

--tls-password-file

   パスワードで保護された秘密鍵のパスワードファイルを指定します。

      python -m http.server \
             --tls-cert cert.pem \
             --tls-key key.pem \
             --tls-password-file password.txt

   このオプションには "--tls-cert" の指定が必要です。

   Added in version 3.14.

-H, --header <header> <value>

   HTTP 200 の成功レスポンスで送信する追加の HTTP レスポンスヘッダーを
   指定します。 複数回指定して、独自のレスポンスヘッダーを追加できます
   。 Content-Type などサーバーが自動で送信するヘッダーは上書きされま
   せん。

   Added in version 3.15.


セキュリティで考慮すべき点
==========================

"SimpleHTTPRequestHandler" はリクエストの処理時にシンボリックリンクを
たどるため、指定したディレクトリの外にあるファイルを配信できてしまいま
す。

"BaseHTTPRequestHandler.send_header()" メソッドと
"BaseHTTPRequestHandler.send_response_only()" メソッドは、入力が安全な
形に処理されていると想定し、CRLF シーケンスの有無の確認などの入力検証
を行いません。 信頼できない入力により、HTTP ヘッダーインジェクション攻
撃を受ける可能性があります。

以前の Python では、"python -m http.server" や
"BaseHTTPRequestHandler" のデフォルトの ".log_message" 実装が stderr
に出力するログメッセージから、制御文字を除去していませんでした。 その
ため、サーバーに接続したリモートクライアントが、悪意のある制御コードを
端末に送信できる可能性がありました。

バージョン 3.12 で変更: stderr のログから制御文字を除去するようになり
ました。
