gh-135056: Add a --header CLI argument to http.server

Doc/library/http.server.rst

@@ -362,7 +362,8 @@ instantiation, of which this module provides three different variants:
          delays, it now always returns the IP address.
 
 
-.. class:: SimpleHTTPRequestHandler(request, client_address, server, directory=None)
+.. class:: SimpleHTTPRequestHandler(request, client_address, server, \
+                                    *, directory=None, extra_response_headers=None)
 
    This class serves files from the directory *directory* and below,
    or the current directory if *directory* is not provided, directly
@@ -374,6 +375,9 @@ instantiation, of which this module provides three different variants:
    .. versionchanged:: 3.9
       The *directory* parameter accepts a :term:`path-like object`.
 
+   .. versionchanged:: next
+      Added *extra_response_headers* parameter.
+
    A lot of the work, such as parsing the request, is done by the base class
    :class:`BaseHTTPRequestHandler`.  This class implements the :func:`do_GET`
    and :func:`do_HEAD` functions.
@@ -396,6 +400,12 @@ instantiation, of which this module provides three different variants:
          This dictionary is no longer filled with the default system mappings,
          but only contains overrides.
 
+   .. attribute:: 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.
+
    The :class:`SimpleHTTPRequestHandler` class defines the following methods:
 
    .. method:: do_HEAD()
@@ -428,6 +438,9 @@ instantiation, of which this module provides three different variants:
       followed by a ``'Content-Length:'`` header with the file's size and a
       ``'Last-Modified:'`` header with the file's modification time.
 
+      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.
 
@@ -543,6 +556,14 @@ The following options are accepted:
 
    .. versionadded:: 3.14
 
+.. option:: -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.
+
+   .. versionadded:: next
+
 
 .. _http.server-security:
 

Doc/whatsnew/3.15.rst

@@ -541,6 +541,19 @@ http.cookies
   (Contributed by Nick Burns and Senthil Kumaran in :gh:`92936`.)
 
 
+http.server
+-----------
+
+* Added a new ``extra_response_headers`` keyword argument to
+  :class:`~http.server.SimpleHTTPRequestHandler` to support custom headers in
+  HTTP responses.
+  (Contributed by Anton I. Sipos in :gh:`135057`.)
+
+* Added a ``-H`` or ``--header`` flag to the :program:`python -m http.server`
+  command-line interface to support custom headers in HTTP responses.
+  (Contributed by Anton I. Sipos in :gh:`135057`.)
+
+
 inspect
 -------
 

Lib/http/server.py

@@ -699,10 +699,11 @@ class SimpleHTTPRequestHandler(BaseHTTPRequestHandler):
         '.xz': 'application/x-xz',
     }
 
-    def __init__(self, *args, directory=None, **kwargs):
+    def __init__(self, *args, directory=None, extra_response_headers=None, **kwargs):
         if directory is None:
             directory = os.getcwd()
         self.directory = os.fspath(directory)
+        self.extra_response_headers = extra_response_headers
         super().__init__(*args, **kwargs)
 
     def do_GET(self):
@@ -720,6 +721,12 @@ def do_HEAD(self):
         if f:
             f.close()
 
+    def _send_extra_response_headers(self):
+        """Send the headers stored in self.extra_response_headers"""
+        if self.extra_response_headers is not None:
+            for header, value in self.extra_response_headers:
+                self.send_header(header, value)
+
     def send_head(self):
         """Common code for GET and HEAD commands.
 
@@ -802,6 +809,7 @@ def send_head(self):
             self.send_header("Content-Length", str(fs[6]))
             self.send_header("Last-Modified",
                 self.date_time_string(fs.st_mtime))
+            self._send_extra_response_headers()
             self.end_headers()
             return f
         except:
@@ -866,6 +874,7 @@ def list_directory(self, path):
         self.send_response(HTTPStatus.OK)
         self.send_header("Content-type", "text/html; charset=%s" % enc)
         self.send_header("Content-Length", str(len(encoded)))
+        self._send_extra_response_headers()
         self.end_headers()
         return f
 
@@ -974,25 +983,33 @@ def _get_best_family(*address):
     return family, sockaddr
 
 
+def _make_server(HandlerClass=BaseHTTPRequestHandler,
+                 ServerClass=ThreadingHTTPServer,
+                 protocol="HTTP/1.0", port=8000, bind=None,
+                 tls_cert=None, tls_key=None, tls_password=None):
+    ServerClass.address_family, addr = _get_best_family(bind, port)
+    HandlerClass.protocol_version = protocol
+
+    if tls_cert:
+        return ServerClass(addr, HandlerClass, certfile=tls_cert,
+                           keyfile=tls_key, password=tls_password)
+    else:
+        return ServerClass(addr, HandlerClass)
+
+
 def test(HandlerClass=BaseHTTPRequestHandler,
          ServerClass=ThreadingHTTPServer,
          protocol="HTTP/1.0", port=8000, bind=None,
          tls_cert=None, tls_key=None, tls_password=None):
     """Test the HTTP request handler class.
 
     This runs an HTTP server on port 8000 (or the port argument).
-
     """
-    ServerClass.address_family, addr = _get_best_family(bind, port)
-    HandlerClass.protocol_version = protocol
-
-    if tls_cert:
-        server = ServerClass(addr, HandlerClass, certfile=tls_cert,
-                             keyfile=tls_key, password=tls_password)
-    else:
-        server = ServerClass(addr, HandlerClass)
-
-    with server as httpd:
+    with _make_server(
+        HandlerClass=HandlerClass, ServerClass=ServerClass,
+        protocol=protocol, port=port, bind=bind,
+        tls_cert=tls_cert, tls_key=tls_key, tls_password=tls_password
+    ) as httpd:
         host, port = httpd.socket.getsockname()[:2]
         url_host = f'[{host}]' if ':' in host else host
         protocol = 'HTTPS' if tls_cert else 'HTTP'
@@ -1031,6 +1048,10 @@ def _main(args=None):
     parser.add_argument('port', default=8000, type=int, nargs='?',
                         help='bind to this port '
                              '(default: %(default)s)')
+    parser.add_argument('-H', '--header', nargs=2, action='append',
+                        metavar=('HEADER', 'VALUE'),
+                        help='Add a custom response header '
+                             '(can be specified multiple times)')
     args = parser.parse_args(args)
 
     if not args.tls_cert and args.tls_key:
@@ -1059,7 +1080,8 @@ def server_bind(self):
 
         def finish_request(self, request, client_address):
             self.RequestHandlerClass(request, client_address, self,
-                                     directory=args.directory)
+                                     directory=args.directory,
+                                     extra_response_headers=args.header)
 
     class HTTPDualStackServer(DualStackServerMixin, ThreadingHTTPServer):
         pass

Lib/test/test_httpservers.py

@@ -503,8 +503,16 @@ def test_err(self):
         self.assertEndsWith(lines[1], '"ERROR / HTTP/1.1" 404 -')
 
 
+class CustomHeaderSimpleHTTPRequestHandler(SimpleHTTPRequestHandler):
+    extra_response_headers = None
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('extra_response_headers', self.extra_response_headers)
+        super().__init__(*args, **kwargs)
+
+
 class SimpleHTTPServerTestCase(BaseTestCase):
-    class request_handler(NoLogRequestHandler, SimpleHTTPRequestHandler):
+    class request_handler(NoLogRequestHandler, CustomHeaderSimpleHTTPRequestHandler):
         pass
 
     def setUp(self):
@@ -861,6 +869,39 @@ def test_path_without_leading_slash(self):
         self.assertEqual(response.getheader("Location"),
                          self.tempdir_name + "/?hi=1")
 
+    def test_extra_response_headers_list_dir(self):
+        with mock.patch.object(self.request_handler, 'extra_response_headers', [
+            ('X-Test1', 'test1'),
+            ('X-Test2', 'test2'),
+        ]):
+            response = self.request(self.base_url + '/')
+            self.assertEqual(response.status, 200)
+            self.assertEqual(response.getheader("X-Test1"), 'test1')
+            self.assertEqual(response.getheader("X-Test2"), 'test2')
+
+    def test_extra_response_headers_get_file(self):
+        with mock.patch.object(self.request_handler, 'extra_response_headers', [
+            ('Set-Cookie', 'test1=value1'),
+            ('Set-Cookie', 'test2=value2'),
+            ('X-Test1', 'value3'),
+        ]):
+            data = b"Dummy index file\r\n"
+            with open(os.path.join(self.tempdir_name, 'index.html'), 'wb') as f:
+                f.write(data)
+            response = self.request(self.base_url + '/')
+            self.assertEqual(response.status, 200)
+            self.assertEqual(response.getheader("Set-Cookie"),
+                                                'test1=value1, test2=value2')
+            self.assertEqual(response.getheader("X-Test1"), 'value3')
+
+    def test_extra_response_headers_missing_on_404(self):
+        with mock.patch.object(self.request_handler, 'extra_response_headers', [
+            ('X-Test1', 'value'),
+        ]):
+            response = self.request(self.base_url + '/missing.html')
+            self.assertEqual(response.status, 404)
+            self.assertEqual(response.getheader("X-Test1"), None)
+
 
 class SocketlessRequestHandler(SimpleHTTPRequestHandler):
     def __init__(self, directory=None):
@@ -1409,6 +1450,21 @@ def test_protocol_flag(self, mock_func):
                     mock_func.assert_called_once_with(**call_args)
                     mock_func.reset_mock()
 
+    @mock.patch('http.server.test')
+    def test_header_flag(self, mock_func):
+        call_args = self.args
+        self.invoke_httpd('--header', 'h1', 'v1', '-H', 'h2', 'v2')
+        mock_func.assert_called_once_with(**call_args)
+        mock_func.reset_mock()
+
+    def test_extra_header_flag_too_few_args(self):
+        with self.assertRaises(SystemExit):
+            self.invoke_httpd('--header', 'h1')
+
+    def test_extra_header_flag_too_many_args(self):
+        with self.assertRaises(SystemExit):
+            self.invoke_httpd('--header', 'h1', 'v1', 'h2')
+
     @unittest.skipIf(ssl is None, "requires ssl")
     @mock.patch('http.server.test')
     def test_tls_cert_and_key_flags(self, mock_func):
@@ -1492,6 +1548,36 @@ def test_unknown_flag(self, _):
         self.assertEqual(stdout.getvalue(), '')
         self.assertIn('error', stderr.getvalue())
 
+    @mock.patch('http.server._make_server', wraps=server._make_server)
+    @mock.patch.object(HTTPServer, 'serve_forever')
+    def test_extra_response_headers_arg(self, _, mock_make_server):
+        server._main(
+            ['-H', 'Set-Cookie', 'k=v', '-H', 'Set-Cookie', 'k2=v2:v3 v4', '8080']
+        )
+        # Get an instance of the server / RequestHandler by using
+        # the spied call args, then calling _make_server with them.
+        args, kwargs = mock_make_server.call_args
+        httpd = server._make_server(*args, **kwargs)
+        self.addCleanup(httpd.server_close)
+
+        # Ensure the RequestHandler class is passed the correct response
+        # headers
+        request_handler_class = httpd.RequestHandlerClass
+        with mock.patch.object(
+            request_handler_class, '__init__'
+        ) as mock_handler_init:
+            mock_handler_init.return_value = None
+            # finish_request instantiates a request handler class,
+            # ensure extra_response_headers are passed to it
+            httpd.finish_request(mock.Mock(), '127.0.0.1')
+            mock_handler_init.assert_called_once_with(
+                mock.ANY, mock.ANY, mock.ANY,
+                directory=mock.ANY,
+                extra_response_headers=[
+                    ['Set-Cookie', 'k=v'], ['Set-Cookie', 'k2=v2:v3 v4']
+                ]
+            )
+
 
 class CommandLineRunTimeTestCase(unittest.TestCase):
     served_data = os.urandom(32)

Misc/NEWS.d/next/Library/2025-06-02-22-23-38.gh-issue-135056.yz3dSs.rst

@@ -0,0 +1,2 @@
+Add a ``-H`` or ``--header`` CLI option to :program:`python -m http.server`. Contributed by
+Anton I. Sipos.