Document and test CORS preflights for missing-route error responses

Author: jackwalkerlabs

docs/examples/decorator.md

@@ -5,3 +5,24 @@ Flask-CORS can be used as a decorator on views, which makes it easy to isolate i
 ```py
 --8<-- "examples/view_based_example.py"
 ```
+# Reading errors after a preflight request
+
+For an unknown URL, Flask normally returns 404 to both `OPTIONS` and the actual
+request. A browser requires a successful preflight response before sending the
+actual request, so it may report a CORS failure without exposing the 404 body to
+JavaScript. Adding CORS headers to the 404 preflight alone does not make it succeed.
+
+If your application needs clients to read these errors, apply `cross_origin` to
+the application's 404 handler. Keep `automatic_options=True` (the default): the
+decorator answers `OPTIONS` with 200, while the handler still returns 404 for the
+actual request. Place `@app.errorhandler` above `@cross_origin` so Flask registers
+the decorated handler. Configure the origin, methods, and headers for your API:
+
+```py
+--8<-- "examples/error_handler_example.py"
+```
+
+For example, a `GET /missing` with an `X-Request-ID` header from
+`https://client.example` can now complete preflight and expose the JSON 404 response.
+This is an application-level handler for all missing routes; choose its CORS
+policy accordingly. A successful preflight does not make the requested URL exist.

examples/error_handler_example.py

@@ -0,0 +1,13 @@
+"""Allow a browser to read a missing route's JSON error after preflight."""
+
+from flask import Flask
+
+from flask_cors import cross_origin
+
+app = Flask(__name__)
+
+
+@app.errorhandler(404)
+@cross_origin(origins=["https://client.example"], methods=["GET"], allow_headers=["X-Request-ID"])
+def not_found(error):
+    return {"error": "Not found"}, 404

tests/decorator/test_error_preflight.py

@@ -0,0 +1,35 @@
+from examples.error_handler_example import app
+
+
+def test_missing_route_preflight_and_error_response():
+    client = app.test_client()
+    response = client.options(
+        "/missing",
+        headers={
+            "Origin": "https://client.example",
+            "Access-Control-Request-Method": "GET",
+            "Access-Control-Request-Headers": "X-Request-ID",
+        },
+    )
+    assert response.status_code == 200
+    assert response.headers["Access-Control-Allow-Origin"] == "https://client.example"
+    assert response.headers["Access-Control-Allow-Methods"] == "GET"
+    assert response.headers["Access-Control-Allow-Headers"] == "X-Request-ID"
+
+    response = client.get("/missing", headers={"Origin": "https://client.example", "X-Request-ID": "123"})
+    assert response.status_code == 404
+    assert response.json == {"error": "Not found"}
+    assert response.headers["Access-Control-Allow-Origin"] == "https://client.example"
+    assert client.get("/missing").status_code == 404
+
+
+def test_error_handler_rejects_other_origins_and_methods():
+    client = app.test_client()
+    for method in (client.get, client.options):
+        response = method("/missing", headers={"Origin": "https://other.example"})
+        assert "Access-Control-Allow-Origin" not in response.headers
+    response = client.options(
+        "/missing",
+        headers={"Origin": "https://client.example", "Access-Control-Request-Method": "DELETE"},
+    )
+    assert "Access-Control-Allow-Methods" not in response.headers