Skip to content

Commit 38f8999

Browse files
authored
Add max_body_size to Starlette and route classes (#3431)
1 parent c41236c commit 38f8999

9 files changed

Lines changed: 619 additions & 9 deletions

File tree

‎docs/middleware.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,36 @@ hostname either use `allowed_hosts=["*"]` or omit the middleware.
208208

209209
If an incoming request does not validate correctly then a 400 response will be sent.
210210

211+
## RequestBodyLimitMiddleware
212+
213+
Limits the total size of incoming HTTP request bodies. The limit applies to the
214+
raw body bytes, including multipart file data and multipart encoding overhead.
215+
Requests that exceed the limit receive a `413 Content Too Large` response.
216+
217+
```python
218+
from starlette.applications import Starlette
219+
from starlette.middleware import Middleware
220+
from starlette.middleware.body_limit import RequestBodyLimitMiddleware
221+
222+
223+
routes = ...
224+
225+
middleware = [
226+
Middleware(RequestBodyLimitMiddleware, max_body_size=10 * 1024 * 1024)
227+
]
228+
229+
app = Starlette(routes=routes, middleware=middleware)
230+
```
231+
232+
The following argument is supported:
233+
234+
* `max_body_size` - The non-negative maximum request body size in bytes.
235+
236+
The middleware uses `Content-Length` to reject an oversized body before reading
237+
it when possible, and always counts the body bytes received from the ASGI server.
238+
This also supports requests without `Content-Length` and prevents an understated
239+
header from bypassing the limit.
240+
211241
## GZipMiddleware
212242

213243
Handles GZip responses for any request that includes `"gzip"` in the `Accept-Encoding` header.

‎docs/requests.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,10 @@ Request files are normally sent as multipart form data (`multipart/form-data`).
115115

116116
Signature: `request.form(max_files=1000, max_fields=1000, max_part_size=1024*1024)`
117117

118-
You can configure the number of maximum fields or files with the parameters `max_files` and `max_fields`; and part size using `max_part_size`:
118+
You can configure the maximum number of fields or files with `max_files` and
119+
`max_fields`. The `max_part_size` parameter limits the size of each non-file
120+
field; uploaded files are spooled to temporary storage and are not limited by
121+
`max_part_size`:
119122

120123
```python
121124
async with request.form(max_files=1000, max_fields=1000, max_part_size=1024*1024):
@@ -125,6 +128,10 @@ async with request.form(max_files=1000, max_fields=1000, max_part_size=1024*1024
125128
!!! info
126129
These limits are for security reasons, allowing an unlimited number of fields or files could lead to a denial of service attack by consuming a lot of CPU and memory parsing too many empty fields.
127130

131+
To limit the complete request body, including uploaded files and multipart
132+
encoding overhead, configure `max_body_size` on the application, router, mount,
133+
or route, or use `RequestBodyLimitMiddleware`.
134+
128135
When you call `async with request.form() as form` you receive a `starlette.datastructures.FormData` which is an immutable
129136
multidict, containing both file uploads and text input. File upload items are represented as instances of `starlette.datastructures.UploadFile`.
130137

‎docs/routing.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,37 @@ app = Router(routes=[
293293
])
294294
```
295295

296+
## Request body size limits
297+
298+
Use a non-negative `max_body_size` to limit the total number of request body
299+
bytes accepted by an application. The limit includes multipart file data and
300+
multipart encoding overhead. It defaults to `None`, which preserves the existing
301+
unlimited behavior.
302+
303+
```python
304+
app = Starlette(
305+
routes=[
306+
Route("/", homepage),
307+
Route("/upload", upload, methods=["POST"], max_body_size=100 * 1024 * 1024),
308+
],
309+
max_body_size=10 * 1024 * 1024,
310+
)
311+
```
312+
313+
`Router` and `Mount` also accept `max_body_size`. A limit on an inner route,
314+
mount, or router overrides the outer limit after routing. This allows an upload
315+
route to accept a larger body than the rest of the application.
316+
317+
Application middleware runs before routing. If such middleware reads the body,
318+
the application-level limit applies to those bytes before a route can raise the
319+
limit. Keep the application limit large enough for the largest legitimate route
320+
when using body-consuming application middleware.
321+
322+
Starlette counts the actual body bytes received from the ASGI server.
323+
`Content-Length` is used only to reject an oversized request early and is not
324+
trusted to enforce the limit. A reverse proxy request-body limit and a quota on
325+
temporary storage provide additional deployment-level safeguards.
326+
296327
## WebSocket Routing
297328

298329
When working with WebSocket endpoints, you should use `WebSocketRoute`

‎starlette/applications.py‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66
from starlette.datastructures import State, URLPath
77
from starlette.middleware import Middleware, _MiddlewareFactory
8+
from starlette.middleware.body_limit import RequestBodyLimitMiddleware
89
from starlette.middleware.errors import ServerErrorMiddleware
910
from starlette.middleware.exceptions import ExceptionMiddleware
1011
from starlette.requests import Request
@@ -26,6 +27,8 @@ def __init__(
2627
middleware: Sequence[Middleware] | None = None,
2728
exception_handlers: Mapping[Any, ExceptionHandler] | None = None,
2829
lifespan: Lifespan[AppType] | None = None,
30+
*,
31+
max_body_size: int | None = None,
2932
) -> None:
3033
"""Initializes the application.
3134
@@ -46,10 +49,13 @@ def __init__(
4649
lifespan: A lifespan context function, which can be used to perform
4750
startup and shutdown tasks. This is a newer style that replaces the
4851
`on_startup` and `on_shutdown` handlers. Use one or the other, not both.
52+
max_body_size: Non-negative maximum total size in bytes of an HTTP request
53+
body. The default, `None`, does not limit request body size.
4954
"""
5055
self.debug = debug
5156
self.state = State()
5257
self.router = Router(routes, lifespan=lifespan)
58+
self.max_body_size = max_body_size
5359
self.exception_handlers = {} if exception_handlers is None else dict(exception_handlers)
5460
self.user_middleware = [] if middleware is None else list(middleware)
5561
self.middleware_stack: ASGIApp | None = None
@@ -65,11 +71,11 @@ def build_middleware_stack(self) -> ASGIApp:
6571
else:
6672
exception_handlers[key] = value
6773

68-
middleware = (
69-
[Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)]
70-
+ self.user_middleware
71-
+ [Middleware(ExceptionMiddleware, handlers=exception_handlers, debug=debug)]
72-
)
74+
middleware = [Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)]
75+
if self.max_body_size is not None:
76+
middleware.append(Middleware(RequestBodyLimitMiddleware, max_body_size=self.max_body_size))
77+
middleware += self.user_middleware
78+
middleware.append(Middleware(ExceptionMiddleware, handlers=exception_handlers, debug=debug))
7379

7480
app = self.router
7581
for cls, args, kwargs in reversed(middleware):

‎starlette/formparsers.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -288,10 +288,10 @@ async def parse(self) -> FormData:
288288
self._file_parts_to_write.clear()
289289
self._file_parts_to_finish.clear()
290290
parser.finalize()
291-
except (MultiPartException, OSError) as exc:
292-
# Close all the files if there was an error.
291+
except BaseException:
292+
# Close all the files if parsing or reading the request stream fails.
293293
for file in self._files_to_close_on_error:
294294
file.close()
295-
raise exc
295+
raise
296296

297297
return FormData(self.items)

‎starlette/middleware/body_limit.py‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
from __future__ import annotations
2+
3+
from typing import cast
4+
5+
from starlette.datastructures import Headers
6+
from starlette.exceptions import HTTPException
7+
from starlette.responses import PlainTextResponse
8+
from starlette.types import ASGIApp, Message, Receive, Scope, Send
9+
10+
MAX_BODY_SIZE_SCOPE_KEY = "starlette.max_body_size"
11+
_BODY_LIMIT_RESPONDER_SCOPE_KEY = "starlette._body_limit_responder"
12+
13+
14+
class _Missing:
15+
__slots__ = ()
16+
17+
18+
_MISSING = _Missing()
19+
20+
21+
class _RequestBodyTooLarge(HTTPException):
22+
def __init__(self) -> None:
23+
super().__init__(status_code=413, detail="Content Too Large")
24+
25+
26+
class _RequestBodyLimitResponseSent(Exception):
27+
pass
28+
29+
30+
class RequestBodyLimitMiddleware:
31+
"""Limit the total size of an HTTP request body."""
32+
33+
def __init__(self, app: ASGIApp, max_body_size: int) -> None:
34+
self.app = app
35+
self.max_body_size = max_body_size
36+
37+
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
38+
if scope["type"] != "http":
39+
return await self.app(scope, receive, send)
40+
41+
responder = RequestBodyLimitResponder(self.app, self.max_body_size)
42+
await responder(scope, receive, send)
43+
44+
45+
class RequestBodyLimitResponder:
46+
def __init__(self, app: ASGIApp, max_body_size: int) -> None:
47+
self.app = app
48+
self.max_body_size = max_body_size
49+
self._scope: Scope | None = None
50+
self._receive: Receive | None = None
51+
self._send: Send | None = None
52+
self.content_length: int | None = None
53+
self.total_size = 0
54+
self.response_started = False
55+
56+
@property
57+
def scope(self) -> Scope:
58+
assert self._scope is not None
59+
return self._scope
60+
61+
@property
62+
def receive(self) -> Receive:
63+
assert self._receive is not None
64+
return self._receive
65+
66+
@property
67+
def send(self) -> Send:
68+
assert self._send is not None
69+
return self._send
70+
71+
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
72+
previous_scope_limit = cast(int | _Missing, scope.get(MAX_BODY_SIZE_SCOPE_KEY, _MISSING))
73+
scope[MAX_BODY_SIZE_SCOPE_KEY] = self.max_body_size
74+
75+
active_responder = cast(RequestBodyLimitResponder | None, scope.get(_BODY_LIMIT_RESPONDER_SCOPE_KEY))
76+
if active_responder is not None:
77+
active_responder.max_body_size = self.max_body_size
78+
if active_responder.total_size > active_responder.max_body_size:
79+
raise _RequestBodyTooLarge
80+
return await self.app(scope, receive, send)
81+
82+
self._scope = scope
83+
self._receive = receive
84+
self._send = send
85+
self.content_length = _get_content_length(scope)
86+
scope[_BODY_LIMIT_RESPONDER_SCOPE_KEY] = self
87+
88+
try:
89+
await self.app(scope, self.receive_with_limit, self.send_with_limit)
90+
except _RequestBodyTooLarge:
91+
if self.response_started:
92+
raise
93+
response = PlainTextResponse("Content Too Large", status_code=413)
94+
await response(scope, receive, send)
95+
except _RequestBodyLimitResponseSent:
96+
pass
97+
finally:
98+
scope.pop(_BODY_LIMIT_RESPONDER_SCOPE_KEY, None)
99+
if isinstance(previous_scope_limit, _Missing):
100+
scope.pop(MAX_BODY_SIZE_SCOPE_KEY, None)
101+
else:
102+
scope[MAX_BODY_SIZE_SCOPE_KEY] = previous_scope_limit
103+
104+
async def receive_with_limit(self) -> Message:
105+
if self.content_length is not None and self.content_length > self.max_body_size:
106+
raise _RequestBodyTooLarge
107+
108+
message = await self.receive()
109+
if message["type"] == "http.request":
110+
self.total_size += len(message.get("body", b""))
111+
if self.total_size > self.max_body_size:
112+
raise _RequestBodyTooLarge
113+
return message
114+
115+
async def send_with_limit(self, message: Message) -> None:
116+
if message["type"] == "http.response.start":
117+
self.response_started = True
118+
if self.content_length is not None and self.content_length > self.max_body_size:
119+
response = PlainTextResponse("Content Too Large", status_code=413)
120+
await response(self.scope, self.receive, self.send)
121+
raise _RequestBodyLimitResponseSent
122+
await self.send(message)
123+
124+
125+
def _get_content_length(scope: Scope) -> int | None:
126+
content_length = Headers(scope=scope).get("content-length")
127+
if content_length is None:
128+
return None
129+
try:
130+
return int(content_length)
131+
except ValueError:
132+
return None

‎starlette/routing.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
from starlette.datastructures import URL, Headers, URLPath
2121
from starlette.exceptions import HTTPException, StarletteDeprecationWarning
2222
from starlette.middleware import Middleware
23+
from starlette.middleware.body_limit import RequestBodyLimitMiddleware
2324
from starlette.requests import Request
2425
from starlette.responses import PlainTextResponse, RedirectResponse, Response
2526
from starlette.types import ASGIApp, Lifespan, Receive, Scope, Send
@@ -203,6 +204,7 @@ def __init__(
203204
name: str | None = None,
204205
include_in_schema: bool = True,
205206
middleware: Sequence[Middleware] | None = None,
207+
max_body_size: int | None = None,
206208
) -> None:
207209
assert path.startswith("/"), "Routed paths must start with '/'"
208210
self.path = path
@@ -225,6 +227,8 @@ def __init__(
225227
if middleware is not None:
226228
for cls, args, kwargs in reversed(middleware):
227229
self.app = cls(self.app, *args, **kwargs)
230+
if max_body_size is not None:
231+
self.app = RequestBodyLimitMiddleware(self.app, max_body_size=max_body_size)
228232

229233
if methods is None:
230234
self.methods = None
@@ -365,6 +369,7 @@ def __init__(
365369
name: str | None = None,
366370
*,
367371
middleware: Sequence[Middleware] | None = None,
372+
max_body_size: int | None = None,
368373
) -> None:
369374
assert path == "" or path.startswith("/"), "Routed paths must start with '/'"
370375
assert app is not None or routes is not None, "Either 'app=...', or 'routes=' must be specified"
@@ -377,6 +382,8 @@ def __init__(
377382
if middleware is not None:
378383
for cls, args, kwargs in reversed(middleware):
379384
self.app = cls(self.app, *args, **kwargs)
385+
if max_body_size is not None:
386+
self.app = RequestBodyLimitMiddleware(self.app, max_body_size=max_body_size)
380387
self.name = name
381388
self.path_regex, self.path_format, self.param_convertors = compile_path(self.path + "/{path:path}")
382389

@@ -574,6 +581,7 @@ def __init__(
574581
lifespan: Lifespan[Any] | None = None,
575582
*,
576583
middleware: Sequence[Middleware] | None = None,
584+
max_body_size: int | None = None,
577585
) -> None:
578586
self.routes = [] if routes is None else list(routes)
579587
self.redirect_slashes = redirect_slashes
@@ -602,6 +610,8 @@ def __init__(
602610
if middleware:
603611
for cls, args, kwargs in reversed(middleware):
604612
self.middleware_stack = cls(self.middleware_stack, *args, **kwargs)
613+
if max_body_size is not None:
614+
self.middleware_stack = RequestBodyLimitMiddleware(self.middleware_stack, max_body_size=max_body_size)
605615

606616
async def not_found(self, scope: Scope, receive: Receive, send: Send) -> None:
607617
if scope["type"] == "websocket":

0 commit comments

Comments
 (0)