"http.server" --- HTTP 서버
***************************

**소스 코드:** Lib/http/server.py

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

이 모듈은 HTTP 서버를 구현하기 위한 클래스를 정의합니다.

경고:

  "http.server" is not recommended for production. It only implements
  basic security checks.

가용성: not WASI.

이 모듈은 웹어셈블리에서 작동하지 않거나 제공되지 않습니다. 자세한 내
용은 웹어셈블리 플랫폼을 참조하세요.

"HTTPServer" 클래스는 "socketserver.TCPServer" 서브 클래스입니다. HTTP
소켓을 만들고 리스닝하면서 요청을 처리기로 디스패치 합니다. 서버를 만
들고 실행하는 코드는 다음과 같습니다:

   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" 인스턴스 변수를 통해 서버에 액세
   스 할 수 있습니다.

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)

   Subclass of "HTTPServer" with a wrapped socket using the "ssl"
   module. If the "ssl" module is not available, instantiating a
   "HTTPSServer" object fails with a "RuntimeError".

   The *certfile* argument is the path to the SSL certificate chain
   file, and the *keyfile* is the path to file containing the private
   key.

   A *password* can be specified for files protected and wrapped with
   PKCS#8, but beware that this could possibly expose hardcoded
   passwords in clear.

   더 보기:

     See "ssl.SSLContext.load_cert_chain()" for additional information
     on the accepted values for *certfile*, *keyfile* and *password*.

   When specified, the *alpn_protocols* argument must be a sequence of
   strings specifying the "Application-Layer Protocol Negotiation"
   (ALPN) protocols supported by the server. ALPN allows the server
   and the client to negotiate the application protocol during the TLS
   handshake.

   By default, it is set to "["http/1.1"]", meaning the server
   supports 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)

   This class is identical to "HTTPSServer" but uses threads to handle
   requests by inheriting from "ThreadingMixIn". This is analogous to
   "ThreadingHTTPServer" only using "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)

   This class is used to handle the HTTP requests that arrive at the
   server.  By itself, it cannot respond to any actual HTTP requests;
   it must be subclassed to handle each request method (for example,
   "'GET'" or "'POST'"). "BaseHTTPRequestHandler" provides a number of
   class and instance variables, and methods for use by subclasses.

   처리기는 요청과 헤더를 구문 분석한 다음, 요청 유형에 특정한 메서드
   를 호출합니다. 메서드 이름은 요청으로부터 구성됩니다. 예를 들어, 요
   청 메서드 "SPAM"의 경우, "do_SPAM()" 메서드가 인자 없이 호출됩니다.
   모든 관련 정보는 처리기의 인스턴스 변수에 저장됩니다. 서브 클래스는
   "__init__()" 메서드를 대체하거나 확장할 필요가 없습니다.

   "BaseHTTPRequestHandler"에는 다음과 같은 인스턴스 변수가 있습니다:

   client_address

      클라이언트 주소를 나타내는 "(host, port)" 형식의 튜플을 포함합니
      다.

   server

      서버 인스턴스를 포함합니다.

   close_connection

      "handle_one_request()"가 반환되기 전에 설정해야 하는 불리언으로,
      다른 요청이 기대되는지, 또는 연결을 종료해야 하는지를 나타냅니다
      .

   requestline

      HTTP 요청 줄의 문자열 표현을 포함합니다. 종료 CRLF가 제거됩니다.
      이 어트리뷰트는 "handle_one_request()"에서 설정해야 합니다. 유효
      한 요청 줄이 처리되지 않았으면, 빈 문자열로 설정해야 합니다.

   command

      명령(요청 유형)을 포함합니다. 예를 들어, "'GET'".

   path

      Contains the request path. If query component of the URL is
      present, then "path" includes the query. Using the terminology
      of **RFC 3986**, "path" here includes "hier-part" and the
      "query".

   request_version

      요청의 버전 문자열을 포함합니다. 예를 들어, "'HTTP/1.0'".

   headers

      Holds an instance of the class specified by the "MessageClass"
      class variable. This instance parses and manages the headers in
      the HTTP request. The "parse_headers()" function from
      "http.client" is used to parse the headers and it requires that
      the HTTP request provide a valid **RFC 5322** style header.

   rfile

      선택적 입력 데이터의 시작부터 읽을 준비가 된 "io.BufferedIOBase"
      입력 스트림.

   wfile

      클라이언트로 돌려줄 응답을 쓰기 위한 출력 스트림을 포함합니다.
      HTTP 클라이언트와의 성공적인 상호 운용을 위해서 이 스트림에 쓸
      때 HTTP 프로토콜을 올바르게 준수해야 합니다.

      버전 3.6에서 변경: 이것은 "io.BufferedIOBase" 스트림입니다.

   "BaseHTTPRequestHandler"에는 다음과 같은 어트리뷰트가 있습니다:

   server_version

      서버 소프트웨어 버전을 지정합니다. 이것을 재정의하고 싶을 수 있
      습니다. 형식은 여러 공백으로 구분된 문자열이며, 각 문자열은
      name[/version] 형식입니다. 예를 들어, "'BaseHTTP/0.2'".

   sys_version

      "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 지속적 연결(persistent
      connections)을 허용합니다; 그러나, 이때 서버는 *반드시* 클라이언
      트에 대한 모든 응답에 ("send_header()"를 사용해서) 정확한
      "Content-Length" 헤더를 포함해야 합니다. 이전 버전과의 호환성을
      위해, 기본 설정은 "'HTTP/1.0'"입니다.

   MessageClass

      HTTP 헤더를 구문 분석할 "email.message.Message"와 유사한 클래스
      를 지정합니다. 일반적으로, 이는 재정의되지 않으며, 기본값은
      "http.client.HTTPMessage"입니다.

   responses

      이 어트리뷰트에는 에러 코드 정수에서 짧고 긴 메시지를 포함하는
      두 요소 튜플로의 매핑이 포함됩니다. 예를 들어, "{code:
      (shortmessage, longmessage)}". *shortmessage*는 일반적으로 에러
      응답에서 *message* 키로 사용되고, *longmessage*는 *explain* 키로
      사용됩니다. "send_response_only()"와 "send_error()" 메서드에서
      사용됩니다.

   "BaseHTTPRequestHandler" 인스턴스에는 다음과 같은 메서드가 있습니다
   :

   handle()

      들어오는 HTTP 요청을 처리하기 위해 "handle_one_request()"를 한
      번 (또는, 지속적 연결이 활성화되었으면, 여러 번) 호출합니다. 재
      정의할 필요는 없습니다; 대신 적절한 "do_*()" 메서드를 구현하십시
      오.

   handle_one_request()

      이 메서드는 요청을 구문 분석하여 적절한 "do_*()" 메서드로 디스패
      치 합니다. 재정의할 필요는 없습니다.

   handle_expect_100()

      When an HTTP/1.1 conformant server receives an "Expect:
      100-continue" request header it responds back with a "100
      Continue" followed by "200 OK" headers. This method can be
      overridden to raise an error if the server does not want the
      client to continue.  For example, the server can choose to send
      "417 Expectation Failed" as a response header and "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)

      "end_headers()"나 "flush_headers()"가 호출될 때 출력 스트림에 기
      록될 내부 버퍼에 HTTP 헤더를 추가합니다. *keyword*는 헤더 키워드
      를 지정하고, *value*는 값을 지정해야 합니다. send_header 호출이
      완료된 후, 작업을 완료하려면 반드시 "end_headers()"를 호출해야
      함에 유의하십시오.

      This method does not reject input containing CRLF sequences.

      버전 3.2에서 변경: 헤더는 내부 버퍼에 저장됩니다.

   send_response_only(code, message=None)

      응답 헤더만 보내는데, 서버가 "100 Continue" 응답을 클라이언트로
      전송할 목적으로 사용됩니다. 헤더는 버퍼링 되지 않고 출력 스트림
      으로 직접 전송합니다. *message*를 지정하지 않으면, 응답 *code*에
      해당하는 HTTP 메시지가 전송됩니다.

      This method does not reject *message* containing CRLF sequences.

      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에서 변경: 이전에는, 이름 조회가 수행되었습니다. 이름 결
      정(name resolution) 지연을 피하고자, 이제 항상 IP 주소를 반환합
      니다.

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

   이 클래스는 디렉터리 구조를 HTTP 요청에 직접 매핑하여 디렉터리
   *directory*와 그 이하의, 또는 *directory*가 제공되지 않으면 현재 디
   렉터리의 파일을 제공합니다.

   버전 3.7에서 변경: Added the *directory* parameter.

   버전 3.9에서 변경: *directory* 매개 변수는 *경로류 객체*를 받아들입
   니다.

   버전 3.15에서 변경: Added *extra_response_headers* parameter.

   요청 구문 분석과 같은 많은 작업이 베이스 클래스
   "BaseHTTPRequestHandler" 에 의해 수행됩니다. 이 클래스는 "do_GET()"
   과 "do_HEAD()" 함수를 구현합니다.

   다음은 "SimpleHTTPRequestHandler" 의 클래스 수준 어트리뷰트로 정의
   됩니다:

   server_version

      이것은 ""SimpleHTTP/" + __version__"이며, 여기서 "__version__"은
      모듈 수준에서 정의됩니다.

   default_content_type

      Specifies the Content-Type header value sent when the MIME type
      cannot be guessed from the file extension of the requested URL.
      By default, it is set to "'application/octet-stream'".

      Added in version 3.15.

   extensions_map

      접미사를 MIME 형식으로 매핑하는 딕셔너리. 기본 시스템 매핑에 대
      한 사용자 정의 재정의를 포함합니다. 매핑은 대소 문자를 구분 없이
      사용되므로, 소문자 키만 포함해야 합니다.

      버전 3.9에서 변경: 이 딕셔너리는 더는 기본 시스템 매핑으로 채워
      지지 않고, 재정의 만 포함합니다.

   extra_response_headers

      A sequence of "(name, value)" pairs containing user-defined
      extra HTTP response headers to add to each successful HTTP
      status 200 response. These headers are not included in other
      status code responses.

      Headers that the server sends automatically such as "Content-
      Type" will not be overwritten by "extra_response_headers".

   "SimpleHTTPRequestHandler" 클래스는 다음 메서드를 정의합니다:

   do_HEAD()

      이 메서드는 "'HEAD'" 요청 유형을 제공합니다: 동등한 "GET" 요청에
      대해 전송할 헤더를 전송합니다. 가능한 헤더에 대한 더 완전한 설명
      은 "do_GET()" 메서드를 참조하십시오.

   do_GET()

      요청을 현재 작업 디렉터리에 상대적인 경로로 해석하여 요청은 로컬
      파일에 매핑됩니다.

      요청이 디렉터리에 매핑되었으면, 디렉터리는 "index.html"이나
      "index.htm" (이 순서대로) 파일을 검사합니다. 발견되면, 파일 내용
      이 반환됩니다; 그렇지 않으면 "list_directory()" 메서드를 호출하
      여 디렉터리 목록이 생성됩니다. 이 메서드는 "os.listdir()"을 사용
      하여 디렉터리를 스캔하고, "listdir()"이 실패하면 "404" 에러 응답
      을 반환합니다.

      요청이 파일에 매핑되었으면, 파일을 엽니다. 요청된 파일을 열 때
      발생하는 "OSError" 예외는 "404", "'File not found'" 에러로 매핑
      됩니다. 요청에 "'If-Modified-Since'" 헤더가 있고, 이 시간 이후
      파일이 수정되지 않았으면, "304", "'Not Modified'" 응답이 전송됩
      니다. 그렇지 않으면, 콘텐츠 유형은 "guess_type()" 메서드를 호출
      하여 추측되며, 이 메서드는 *extensions_map* 변수를 사용합니다.
      그런 다음 파일 내용이 반환됩니다.

      추측된 콘텐츠 유형의 "'Content-type:'" 헤더가 출력되고, 파일 크
      기가 담긴 "'Content-Length:'" 헤더와 파일 수정 시간이 담긴
      "'Last-Modified:'" 헤더가 뒤따릅니다.

      The instance attribute "extra_response_headers" is a sequence of
      "(name, value)" pairs containing user-defined extra response
      headers.

      Then follows a blank line signifying the end of the headers, and
      then the contents of the file are output.

      사용 예로는, Lib/http/server.py 모듈에서 "test" 함수 구현을 참조
      하십시오.

      버전 3.7에서 변경: "'If-Modified-Since'" 헤더 지원.

"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" can also be subclassed to enhance behavior,
such as using different index file names by overriding the class
attribute "index_pages".


Command-line interface
======================

"http.server" can also be invoked directly using the "-m" switch of
the interpreter.  The following example illustrates how to serve files
relative to the current directory:

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

The following options are accepted:

port

   The server listens to port 8000 by default. The default can be
   overridden by passing the desired port number as an argument:

      python -m http.server 9000

-b, --bind <address>

   Specifies a specific address to which it should bind. Both IPv4 and
   IPv6 addresses are supported. By default, the server binds itself
   to all interfaces. For example, the following command causes the
   server to bind to localhost only:

      python -m http.server --bind 127.0.0.1

   Added in version 3.4.

   버전 3.8에서 변경: Support IPv6 in the "--bind" option.

-d, --directory <dir>

   Specifies a directory to which it should serve the files. By
   default, the server uses the current directory. For example, the
   following command uses a specific directory:

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

   Added in version 3.7.

-p, --protocol <version>

   Specifies the HTTP version to which the server is conformant. By
   default, the server is conformant to HTTP/1.0. For example, the
   following command runs an HTTP/1.1 conformant server:

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

   Added in version 3.11.

--content-type <content_type>

   Specifies the default Content-Type HTTP header used when the MIME
   type cannot be guessed from the URL's file extension. By default,
   the server uses "'application/octet-stream'":

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

   Added in version 3.15.

--tls-cert

   Specifies a TLS certificate chain for HTTPS connections:

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

   Added in version 3.14.

--tls-key

   Specifies a private key file for HTTPS connections.

   This option requires "--tls-cert" to be specified.

   Added in version 3.14.

--tls-password-file

   Specifies the password file for password-protected private keys:

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

   This option requires "--tls-cert" to be specified.

   Added in version 3.14.

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

   Specify an additional extra HTTP Response Header to send on
   successful HTTP 200 responses. Can be used multiple times to send
   additional custom response headers. Headers that are sent
   automatically by the server (for instance Content-Type) will not be
   overwritten by the server.

   Added in version 3.15.


Security considerations
=======================

"SimpleHTTPRequestHandler" will follow symbolic links when handling
requests, this makes it possible for files outside of the specified
directory to be served.

Methods "BaseHTTPRequestHandler.send_header()" and
"BaseHTTPRequestHandler.send_response_only()" assume sanitized input
and do not perform input validation such as checking for the presence
of CRLF sequences. Untrusted input may result in HTTP Header injection
attacks.

Earlier versions of Python did not scrub control characters from the
log messages emitted to stderr from "python -m http.server" or the
default "BaseHTTPRequestHandler" ".log_message" implementation. This
could allow remote clients connecting to your server to send nefarious
control codes to your terminal.

버전 3.12에서 변경: Control characters are scrubbed in stderr logs.
