gh-135056: Add a --cors CLI argument to http.server #135057

aisipos · 2025-06-03T05:19:08Z

As proposed in #135056, Add a --cors command line argument to the stdlib http.server module, which will add an Access-Control-Allow-Origin: * header to all responses.

Invocation:

python -m http.server --cors

As part of this implementation, add a response_headers argument to SimpleHTTPRequestHandler and HTTPServer, which allows callers to add addition headers to the response. Ideally it would have been possible to just have made a CorsHttpServer class, but a couple of issues made that difficult:

The http.server CLI uses more than one HTTP Server class, in order to support TLS/HTTPS. So a single CorsHttpServer child class wouldn't work to support both use cases.
Much of the work in specifying HTTP behavior is handled by the various RequestHandler classes. However, the HttpServer classes didn't have an easy way to pass arguments down into the instantiated handlers.

As a result, this PR updates both HTTPServer and SimpleHTTPRequestHandler to accept a response_headers argument, which allows callers to specify an additional set of HTTP headers to pass in the response.

HTTPServer now overrides finish_request to pass this new kwarg down to its RequestHandler.
SimpleHTTPRequestHandler now accepts a resposnse_headers kwarg, to optionally specify a dictionary of additional headers to send in the response.

Care is taken to not pass the response_headers argument to any instance constructors when not provided, to ensure backwards compatibility. I tried to keep the implementation as short and simple as possible.

With the addition of a response_headers argument, we allow ourselves to have a future possible custom header http argument, such as:

python -m http.server -H 'custom-header: custom-value'

Issue: Add a --cors command line option to stdlib http.server #135056

📚 Documentation preview 📚: https://cpython-previews--135057.org.readthedocs.build/

python-cla-bot · 2025-06-03T05:19:12Z

All commit authors signed the Contributor License Agreement.

bedevere-app · 2025-06-03T05:19:13Z

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

Add a --cors command line argument to the stdlib http.server module, which will add an `Access-Control-Allow-Origin: *` header to all responses. As part of this implementation, add a `response_headers` argument to SimpleHTTPRequestHandler and HttpServer, which allows callers to add addition headers to the response.

hugovk

(I'd prefer a general headers option, but will comment on the issue or Discourse topic)

Doc/library/http.server.rst

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

aisipos · 2025-06-03T05:54:56Z

test_wsgiref is failing. I'll look into it.

This fixes the breakage to HttpServer as used by wsgiref.

aisipos · 2025-06-03T06:41:31Z

test_wsgiref fixed in a3256fd. This should fix any backwards incompatibility errors erroneously introduced in the first commit.

donBarbos · 2025-06-03T09:04:53Z

I think it's worth adding to this What's New entry (./Doc/whatsnew/3.15.rst)

Zheaoli · 2025-06-06T21:58:44Z

For me, I don't think add --cors CLI argument would be a good idea. Base on following reasons:

The CORS policy is a complicated idea. Six response headers are included by the word(If I'm correct). If you set the Access-Control-Allow-Origin, and now the people may need Access-Control-Allow-Methods( Allow for OPTION method). What is the next argument we need to add?
The CLI for http.server is just for a debug target. So we design the CLI as simple as we can. The developer don't need to care about any extra detail when they run just a simple debug server.
if we need CORS policy in the future. I suggest we setup all the header for developer and don't need to add cli for it.

hugovk · 2025-06-09T09:39:24Z

@Zheaoli Please comment in the discussion thread: https://discuss.python.org/t/any-interest-in-adding-a-cors-option-to-python-m-http-server/92120.

hugovk · 2025-06-09T09:39:52Z

(I'd prefer a general headers option, but will comment on the issue or Discourse topic)

https://discuss.python.org/t/any-interest-in-adding-a-cors-option-to-python-m-http-server/92120/24

picnixz

I'm not very fond of how the HTTP server class is growing more and more with more __init__ parameters, but I don't have a better idea for now. Maybe a generic configuration object but this would be an overkill for this class in particular I think.

picnixz · 2025-06-07T23:02:48Z

Doc/library/http.server.rst

@@ -543,6 +553,14 @@ The following options are accepted:

   .. versionadded:: 3.14

+.. option:: --cors


As Hugo said, since we're anyway exposing response-headers, I think we should also expose it from the CLI. It could be useful for users in general (e.g., --add-header NAME VALUE with the -H alias).

picnixz · 2025-06-07T23:08:34Z

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

@@ -0,0 +1,2 @@
+Add a ``--cors`` cli option to :program:`python -m http.server`. Contributed by


Let's also update What's New/3.15.rst

I used blurb to make this entry in NEWS.d, not knowing when it's appropriate to edit the main 3.15.rst file. I think once we know if we're doing --cors / --header , or both, I can make the appropriate update to What's New/3.15.rst

picnixz · 2025-06-09T10:12:57Z

Lib/http/server.py

@@ -132,7 +144,7 @@ class ThreadingHTTPServer(socketserver.ThreadingMixIn, HTTPServer):
 class HTTPSServer(HTTPServer):
    def __init__(self, server_address, RequestHandlerClass,
                 bind_and_activate=True, *, certfile, keyfile=None,
-                 password=None, alpn_protocols=None):
+                 password=None, alpn_protocols=None, response_headers=None):


Suggested change

password=None, alpn_protocols=None, response_headers=None):

password=None, alpn_protocols=None, **http_server_kwargs):

And pass http_server_kwargs to super()

picnixz · 2025-06-09T10:16:08Z

Lib/http/server.py

+        args = (request, client_address, self)
+        kwargs = {}
+        response_headers = getattr(self, 'response_headers', None)
+        if response_headers:
+            kwargs['response_headers'] = self.response_headers
+        self.RequestHandlerClass(*args, **kwargs)


Suggested change

args = (request, client_address, self)

kwargs = {}

response_headers = getattr(self, 'response_headers', None)

if response_headers:

kwargs['response_headers'] = self.response_headers

self.RequestHandlerClass(*args, **kwargs)

kwargs = {}

if hasattr(self, 'response_headers'):

kwargs['response_headers'] = self.response_headers

self.RequestHandlerClass(request, client_address, self, **kwargs)

@picnixz I made this requested change in 77b5fff. Note though that now HTTPServer will pass response_headers to the RequestHandler class even if response_headers is None or {}. Most RequestHandler implementation constructor implementations don't take this argument, so in order for this to work I added **kwargs as an argument to BaseRequestHandler.__init__. My earlier implementation was trying to prevent this, to keep any changes to only http/server.py and not need to touch anything in socketserver.py. Perhaps the **kwargs addition is ok, or I'm open to other solutions if we can think of better ones.

picnixz · 2025-06-09T10:17:52Z

Lib/http/server.py

+    def __init__(self, *args, directory=None, response_headers=None, **kwargs):
        if directory is None:
            directory = os.getcwd()
        self.directory = os.fspath(directory)
+        self.response_headers = response_headers or {}


Suggested change

def __init__(self, *args, directory=None, response_headers=None, **kwargs):

if directory is None:

directory = os.getcwd()

self.directory = os.fspath(directory)

self.response_headers = response_headers or {}

def __init__(self, *args, directory=None, response_headers=None, **kwargs):

if directory is None:

directory = os.getcwd()

self.directory = os.fspath(directory)

self.response_headers = response_headers

You're already checking for is not None later

picnixz · 2025-06-09T10:19:59Z

Lib/http/server.py

@@ -970,7 +991,7 @@ def _get_best_family(*address):
 def test(HandlerClass=BaseHTTPRequestHandler,
         ServerClass=ThreadingHTTPServer,
         protocol="HTTP/1.0", port=8000, bind=None,
-         tls_cert=None, tls_key=None, tls_password=None):
+         tls_cert=None, tls_key=None, tls_password=None, response_headers=None):


Suggested change

tls_cert=None, tls_key=None, tls_password=None, response_headers=None):

tls_cert=None, tls_key=None, tls_password=None,

response_headers=None):

Let's group the parameters per purpose

picnixz · 2025-06-09T10:22:05Z

Lib/http/server.py

+            handler_args = (request, client_address, self)
+            handler_kwargs = dict(directory=args.directory)
+            if self.response_headers:
+                handler_kwargs['response_headers'] = self.response_headers
+            self.RequestHandlerClass(*handler_args, **handler_kwargs)


Suggested change

handler_args = (request, client_address, self)

handler_kwargs = dict(directory=args.directory)

if self.response_headers:

handler_kwargs['response_headers'] = self.response_headers

self.RequestHandlerClass(*handler_args, **handler_kwargs)

self.RequestHandlerClass(request, client_address, self,

directory=args.directory,

response_headers=self.response_headers)

picnixz · 2025-06-09T10:24:14Z

Lib/test/test_httpservers.py

@@ -95,7 +96,8 @@ def run(self):
                request_handler=self.request_handler,
            )
        else:
-            self.server = HTTPServer(('localhost', 0), self.request_handler)
+            self.server = HTTPServer(('localhost', 0), self.request_handler,


You must also modify create_https_server appropriately

picnixz · 2025-06-09T10:24:46Z

Lib/test/test_httpservers.py

+    server_kwargs = dict(
+        response_headers = {'Access-Control-Allow-Origin': '*'}
+    )


Suggested change

server_kwargs = dict(

response_headers = {'Access-Control-Allow-Origin': '*'}

)

server_kwargs = {

'response_headers': {'Access-Control-Allow-Origin': '*'}

}

picnixz · 2025-06-09T10:25:03Z

Lib/test/test_httpservers.py

+    server_kwargs = dict(
+        response_headers = {'Access-Control-Allow-Origin': '*'}
+    )
+    def test_cors(self):


Suggested change

def test_cors(self):

def test_cors(self):

aisipos · 2025-06-20T02:31:13Z

@picnixz I have made all your suggested changes in 77b5fff . I have also implemented a generic -H or --header cli argument in 5f89c97. Now this PR contains both --cors and --header. I don't know if we want both, there doesn't seem to yet be consensus on what we prefer, although Core devs so far seem to lean on just --header.

hugovk · 2025-06-20T07:11:27Z

I think we should just have --header, as that unlocks the ability to enable CORS. We can still add --cors later if there's demand and consensus.

hugovk · 2025-06-20T07:12:55Z

And what are your thoughts on positional args like HTTPie?

https://discuss.python.org/t/any-interest-in-adding-a-cors-option-to-python-m-http-server/92120/24

vadmium · 2025-06-09T04:29:49Z

Doc/library/http.server.rst

@@ -437,6 +444,9 @@ instantiation, of which this module provides three different variants:
      .. versionchanged:: 3.7
         Support of the ``'If-Modified-Since'`` header.

+      .. versionchanged:: next
+         Support ``response_headers`` as an instance argument.


Isn’t this redundant with the entry already under the constructor heading?

Perhaps - it seems the constructor documentation is used to make a brief mention of each argument and when it was added, with more detail being filled in later. My latest commits make several changes requested elsewhere for other reasons, but if the current version is still too redundant in multiple places I can make some more edits.

vadmium · 2025-06-20T12:38:38Z

Lib/http/server.py

@@ -1052,14 +1081,21 @@ def server_bind(self):

        def finish_request(self, request, client_address):
            self.RequestHandlerClass(request, client_address, self,
-                                     directory=args.directory)
+                                     directory=args.directory,
+                                     response_headers=self.response_headers)


Why not do this the same way the --directory or --protocol options are implemented? Either way should avoid adding internal parameters to unrelated HTTPServer and BaseRequestHandler classes.

You could build the response_headers dictionary before the DualStackServerMixin class, and then pass it by referencing the outer scope like is already done with args.directory:

Suggested change

response_headers=self.response_headers)

response_headers=response_headers)

Or set the response_headers attribute on the SimpleHTTPRequestHandler class rather than in its constructor, like is done for protocol_verison in the test function.

I followed your advice, see b1026d2. I made response_headers an argument to SimpleHTTPRequestHandler only, and send the argument to it in the DualStackServerMixin class.

vadmium · 2025-06-22T00:07:31Z

Doc/library/http.server.rst

@@ -374,6 +374,10 @@ instantiation, of which this module provides three different variants:
   .. versionchanged:: 3.9
      The *directory* parameter accepts a :term:`path-like object`.

+   .. versionchanged:: next
+      The *response_headers* parameter accepts an optional dictionary of


In previous versions, this was not a valid parameter at all.

Suggested change

The *response_headers* parameter accepts an optional dictionary of

Added *response_headers*, which accepts an optional dictionary of

Also, did you consider accepting a list or iterable of (name, value) pairs instead, like returned by http.client.HTTPResponse.getheaders? That would be better for sending multiple Set-Cookie fields.

Ah yes, sending multiple headers of the same name would indeed be necessary. I updated to use an iterable of name value pairs instead in 7a793f2

vadmium · 2025-06-22T00:14:53Z

Doc/library/http.server.rst

@@ -374,6 +374,10 @@ instantiation, of which this module provides three different variants:
   .. versionchanged:: 3.9
      The *directory* parameter accepts a :term:`path-like object`.

+   .. versionchanged:: next
+      The *response_headers* parameter accepts an optional dictionary of
+      additional HTTP headers to add to each response.


Might be worth clarifying how these fields interact with other fields such as Server specified under BaseHTTPRequestHandler.send_response, and Last-Modified under do_GET.

Also clarify which responses the fields are included in, assuming it wasn’t your intention to include them for 404 Not Found, 304 Not Modified, lower-level errors, etc.

In the latest commits, I've noted that the custom headers are only sent in success cases. What do you mean by interaction though? The custom headers currently get sent after Last-Modified, should I mention the placement of the custom headers and that they appear after Last-Modified?

vadmium · 2025-06-22T00:18:39Z

Lib/http/server.py

+                if self.response_headers is not None:
+                    for header, value in self.response_headers.items():
+                        self.send_header(header, value)


Or is moving this to an extended send_response override an option? That way you would include the fields for all responses.

vadmium · 2025-06-22T00:22:47Z

Lib/http/server.py

        if directory is None:
            directory = os.getcwd()
        self.directory = os.fspath(directory)
+        self.response_headers = response_headers


Clarify as an internal private attribute:

Suggested change

self.response_headers = response_headers

self._response_headers = response_headers

Or document SimpleHTTPRequestHandler.response_headers as a public attribute.

So far I have intended response_headers to be a public attribute. Do you mean add documentation to the docstring of SimpleHTTPRequestHandler or more documentation in Doc/library/http.server.rst?

vadmium · 2025-06-22T01:11:16Z

Lib/test/test_httpservers.py

            )
        else:
-            self.server = HTTPServer(('localhost', 0), self.request_handler)
+            self.server = HTTPServer(('localhost', 0), self.request_handler,
+                                     **self.server_kwargs)


This appears to only be testing the undocumented or internal HTTPServer parameter. It would be good to test the new documented SimpleHTTPRequestHandler parameter instead or as well.

I have removed server_kwargs in the latest updates, and updated the tests. The only external change now is response_headers as an instance arg to SimpleHTTPRequestHandler

hugovk · 2025-07-11T09:48:09Z

Lib/http/server.py

@@ -1024,6 +1035,11 @@ 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',


Remove commented code:

Suggested change

# metavar='HEADER VALUE',

hugovk · 2025-07-11T09:50:14Z

Lib/test/test_httpservers.py

+        # with mock.patch.object(
+        #     SimpleHTTPRequestHandler, '__init__'
+        # ) as mock_handler, \
+        # mock.patch.object(
+        #     HTTPServer, 'serve_forever'
+        # ) as mock_serve_forever:


Suggested change

# with mock.patch.object(

# SimpleHTTPRequestHandler, '__init__'

# ) as mock_handler, \

# mock.patch.object(

# HTTPServer, 'serve_forever'

# ) as mock_serve_forever:

hugovk · 2025-07-11T10:00:36Z

Lib/http/server.py

+    response_headers = []
+    for header, value in args.header or []:
+        response_headers.append((header, value))
+


Does this need to be a list of tuples?

Or can it be a list of lists? If so, we can use args.header directly:

Suggested change

response_headers = []

for header, value in args.header or []:

response_headers.append((header, value))

hugovk · 2025-07-11T10:01:08Z

Lib/http/server.py

@@ -1052,7 +1072,8 @@ def server_bind(self):

        def finish_request(self, request, client_address):
            self.RequestHandlerClass(request, client_address, self,
-                                     directory=args.directory)
+                                     directory=args.directory,
+                                     response_headers=response_headers)


Suggested change

response_headers=response_headers)

response_headers=args.header)

hugovk · 2025-07-11T10:08:15Z

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

@@ -0,0 +1,2 @@
+Add a ``--header`` cli option to :program:`python -m http.server`. Contributed by


Suggested change

Add a ``--header`` cli option to :program:`python -m http.server`. Contributed by

Add a ``--header`` CLI option to :program:`python -m http.server`. Contributed by

hugovk · 2025-07-11T10:09:59Z

Lib/test/test_httpservers.py

+        with mock.patch.object(
+            HTTPServer, 'serve_forever'
+        ) as mock_serve_forever:


Suggested change

with mock.patch.object(

HTTPServer, 'serve_forever'

) as mock_serve_forever:

with mock.patch.object(HTTPServer, 'serve_forever'):

bedevere-app bot added the awaiting review label Jun 3, 2025

bedevere-app bot mentioned this pull request Jun 3, 2025

Add a --cors command line option to stdlib http.server #135056

Open

aisipos force-pushed the https-server-cors-issue-135056 branch from 3f11652 to 0d02fbe Compare June 3, 2025 05:24

hugovk reviewed Jun 3, 2025

View reviewed changes

gh-issue-135056: Fix doc versionchanged and NEWS entries.

1838da7

pythongh-13056: Allow unspecified response_headers in HTTPServer.

a3256fd

This fixes the breakage to HttpServer as used by wsgiref.

aisipos requested a review from hugovk June 6, 2025 23:05

picnixz self-requested a review June 7, 2025 23:15

picnixz reviewed Jun 9, 2025

View reviewed changes

aisipos added 2 commits June 19, 2025 18:49

pythongh-135056: Simplifications and cleanups to http cors changes.

77b5fff

pythongh-135056: Add a --header argument to http.server cli.

5f89c97

aisipos force-pushed the https-server-cors-issue-135056 branch from 3024d3d to 5f89c97 Compare June 20, 2025 01:50

vadmium reviewed Jun 22, 2025

View reviewed changes

aisipos added 4 commits July 6, 2025 10:48

pythongh-135056: Remove --cors opt from http.server in favor of --header

a3243fe

pythongh-135056: Use response_headers only in SimpleHTTPRequestHandler

b1026d2

pythongh-135056: Add test for http.server cli --header argument

6f88c13

pythongh-135056: Support multiple headers of the same name.

7a793f2

aisipos requested a review from vadmium July 10, 2025 07:22

hugovk reviewed Jul 11, 2025

View reviewed changes

		@@ -543,6 +553,14 @@ The following options are accepted:

		.. versionadded:: 3.14

		.. option:: --cors

		@@ -0,0 +1,2 @@
		Add a ``--cors`` cli option to :program:`python -m http.server`. Contributed by

	password=None, alpn_protocols=None, response_headers=None):
	password=None, alpn_protocols=None, **http_server_kwargs):

	tls_cert=None, tls_key=None, tls_password=None, response_headers=None):
	tls_cert=None, tls_key=None, tls_password=None,
	response_headers=None):

	response_headers=self.response_headers)
	response_headers=response_headers)

	The response_headers parameter accepts an optional dictionary of
	Added response_headers, which accepts an optional dictionary of

	self.response_headers = response_headers
	self._response_headers = response_headers

	response_headers = []
	for header, value in args.header or []:
	response_headers.append((header, value))

	response_headers=response_headers)
	response_headers=args.header)

		@@ -0,0 +1,2 @@
		Add a ``--header`` cli option to :program:`python -m http.server`. Contributed by

Uh oh!

gh-135056: Add a --cors CLI argument to http.server #135057

Are you sure you want to change the base?

gh-135056: Add a --cors CLI argument to http.server #135057

Conversation

aisipos commented Jun 3, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot bot commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bedevere-app bot commented Jun 3, 2025

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aisipos commented Jun 3, 2025

Uh oh!

aisipos commented Jun 3, 2025

Uh oh!

donBarbos commented Jun 3, 2025

Uh oh!

Zheaoli commented Jun 6, 2025

Uh oh!

hugovk commented Jun 9, 2025

Uh oh!

hugovk commented Jun 9, 2025

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

picnixz Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aisipos commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Jun 20, 2025

Uh oh!

hugovk commented Jun 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

aisipos commented Jun 3, 2025 •

edited by github-actions bot

Loading

python-cla-bot bot commented Jun 3, 2025 •

edited

Loading

picnixz Jun 9, 2025 •

edited

Loading

aisipos commented Jun 20, 2025 •

edited

Loading