Skip to content

fix: reject requests whose body could not be read entirely - #2872

Open
Derjuju wants to merge 1 commit into
php:mainfrom
Derjuju:fix/request-body-incomplete
Open

Derjuju wants to merge 1 commit into
php:mainfrom
Derjuju:fix/request-body-incomplete

Conversation

@Derjuju

@Derjuju Derjuju commented Nov 20, 2026

Copy link
Copy Markdown

Summary

FrankenPHP must not give PHP a truncated request body as a complete body.

Before this change, go_read_post examined only one read error: *http.MaxBytesError (#2785). It ignored all other read errors. Thus, PHP used the bytes received before the error as the complete body, and the script ran.

This change rejects the request when the body read stops with an error other than io.EOF, or when the body ends before its Content-Length:

  • 400 request body incomplete: the client closes the connection before the end of the body, a chunked body has no last chunk, an HTTP/2 or HTTP/3 stream is reset, or an HTTP/3 stream ends before the announced length.
  • 408 request body read timeout: read_body or request_body_timeout stops the read.
  • 413 request body too large: no change (fix: return 413 when the request body exceeds the configured limit #2785).

This change applies the rule that #2785 started: "PHP can't see read errors: fail the request rather than expose a truncated body." It also applies the "faithful transport" principle of docs/security.md.

The maintainers asked for this public PR after a private report. They classified the problem as a bug, not as a vulnerability.

Behavior change

This change has an effect on the behavior that applications see:

  • Before, a body read that stopped for longer than request_body_timeout gave a 200 response, and the script ran with the bytes received. Now, the response is 408, and the script does not run on the partial body.
  • Before, a script that read a truncated body through php://input got the bytes and no error. Now, the read throws FrankenPHP\RequestBodyIncompleteException. If the script does not catch it, the script stops at the read. If no header was sent, the client gets the 400 or 408 response, not a 500 response.

We used the fix: prefix, as #2785 did for the same type of change. If you prefer fix!:, we can change it.

Problem

Example: the client announces Content-Length: 25 and sends only name=demo&amount=12. Then the client closes its write side.

Version HTTP status What the script gets
1.13.5 200 $_POST['amount'] = '12'. No error.
This PR 400 The script does not run.

The application cannot find the problem in these cases:

  • A multipart/form-data text field is cut. PHP reads the body, and php://input is empty.
  • A chunked body has no last chunk. There is no Content-Length to compare.

A truncated value can pass validation (12345.33 becomes 12). The script then writes it to the database or sends it to other services.

Change

frankenphp.go, go_read_post():

  • Any read error other than io.EOF stops the request, as *http.MaxBytesError does now.
  • os.ErrDeadlineExceeded gives 408. All other errors give 400.
  • A body that ends with io.EOF before its Content-Length is also incomplete (400). With HTTP/3, quic-go accepts a stream that ends before the announced length, and gives io.EOF. Before this change, PHP got the received bytes as the complete body.
  • go_read_post returns a value of the new C enum frankenphp_read_post_error (frankenphp.h) instead of a boolean. Go and C use the same constants.
  • The debug log of the read error uses the logger of the server (fc.logger).

frankenphp.c, frankenphp_read_post():

  • A read error in user code (php://input, request_parse_body()) throws the new exception FrankenPHP\RequestBodyIncompleteException.
  • The new class FrankenPHP\RequestBodyException is the parent of RequestBodyIncompleteException and of the existing RequestBodyTooLargeException. Thus, one catch gets the two exceptions. RequestBodyTooLargeException continues to extend \Exception, thus existing code does not change.

Documentation: docs/config.md, a new "Incomplete request bodies" section after "Request body size limit" (#2785), and the request_body_timeout line.

Test matrix

Each cell shows the result on the official 1.13.5 image, then the result on an image built from this branch (1.13.5 → this PR). PHP 8.5.13, Caddy 2.11.9. The client announces 100,000 bytes and sends 60,000 bytes.

Protocol Mode PATCH cut, client waits PATCH, client resets the stream PATCH chunked, no last chunk PATCH, body stops (read_body 3 s) POST cut Multipart file cut PATCH cut, script does not read Complete body
HTTP/1.1 classic 200 → 400 – 200 → 400 200 → 408 200 → 400 200 UPLOAD_ERR_PARTIAL → 400 200 → 200 200 → 200
HTTP/1.1 worker 200 → 400 – 200 → 400 200 → 408 200 → 400 200 UPLOAD_ERR_PARTIAL → 400 200 → 200 200 → 200
HTTP/2 (h2c) classic 200 → 400 no response (a) → no response, exception – 200 → 408 200 → 400 200 UPLOAD_ERR_PARTIAL → 400 200 → 200 200 → 200
HTTP/2 (h2c) worker 200 → 400 no response (a) → no response, exception – 200 → 408 200 → 400 200 UPLOAD_ERR_PARTIAL → 400 200 → 200 200 → 200
HTTP/2 (TLS) classic 200 → 400 no response → no response, exception – 200 → 408 200 → 400 – – 200 → 200
HTTP/2 (TLS) worker 200 → 400 no response → no response, exception – 200 → 408 200 → 400 – – 200 → 200
HTTP/3 classic 200 → 400 200 → 400 (b) – 200 → 408 200 → 400 – – 200 → 200
HTTP/3 worker 200 → 400 200 → 400 (b) – 200 → 408 200 → 400 – – 200 → 200
HTTP/1.1, Laravel 13.43 + Octane 2.25 worker 200 → 400 – – 200 → 408 200 → 400 – – 200 → 200
HTTP/1.1, Symfony 8.1 Runtime worker 200 → 400 – – 200 → 408 200 → 400 – – 200 → 200
HTTP/1.1, Symfony 8.1 Runtime classic 200 → 400 – – 200 → 408 200 → 400 – – 200 → 200
  • Before (1.13.5): in all the cut cases with a response, the script gets the received bytes as a complete body, without an error.
  • After, PATCH: the script runs and reads 57,344 bytes. Then the read throws FrankenPHP\RequestBodyIncompleteException.
  • After, POST and multipart: PHP reads the body before the script starts. The script does not run.
  • "Client waits": with HTTP/1.1, the client closes only its write side. With HTTP/2 and HTTP/3, the client ends its stream before the announced length.
  • "No response": the client reset the stream, thus it cannot get a response.
  • (a) On 1.13.5, the result depends on the timing: the script gets the received bytes without an error, or the script does not start.
  • (b) With HTTP/3, a stream reset by the client stops only the request direction. The client gets the response.
  • "–": we did not do this test in this context.

The worker did not restart after these requests. There was no fatal error and no panic.

Effect on applications that use a partial body

You asked what changes for applications that use UPLOAD_ERR_PARTIAL or read a partial php://input, for example resumable uploads.

We measured this with a black-box test on the official image (1.13.5) and on an image built from this branch. The test script reads php://input in blocks of 8 KiB, as a tus server does. The client announces 100,000 bytes and sends 60,000 bytes.

We got the same results in classic mode and in worker mode, with HTTP/1.1, HTTP/2 (h2c and TLS) and HTTP/3. With HTTP/3, the last block is also 57,344 bytes. On 1.13.5, all the truncated cases with HTTP/3 give 200 and 60,000 bytes.

Case 1.13.5 This PR
PATCH, client stops before the end 200. The script gets 60,000 bytes. No error. The script runs. It gets 57,344 bytes, then RequestBodyIncompleteException. The client gets 400.
PATCH, HTTP/2 RST_STREAM The script gets 60,000 bytes. No error. The script gets 57,344 bytes, then the exception. No response is possible.
PATCH, body stops for longer than read_body 200, 60,000 bytes Same as the first line, with 408
POST (tus creation with upload), client stops 200, 60,000 bytes 400. The script does not run.
multipart/form-data, file cut by the transport 200, UPLOAD_ERR_PARTIAL 400. The script does not run.
multipart/form-data, body complete but no closing boundary 200, UPLOAD_ERR_PARTIAL No change: 200, UPLOAD_ERR_PARTIAL
PATCH, body cut, script does not read the body 200 200, no error
PATCH, complete body, full read or read of 1,000 bytes 200 No change

Laravel Octane and Symfony Runtime

We did the same tests with HTTP/1.1 on Laravel 13.43 with Octane 2.25 (worker mode), and on Symfony 8.1 with the native FrankenPHP runtime (worker mode and classic mode). The routes read the body with Request::getContent(), or read a form with $request->all().

The results are in the test matrix below.

The framework catches the exception in its error handler and reports it. Laravel writes ERROR: Request body incomplete in its log, and Symfony writes it to the error log. The client gets the 400 or 408 response of FrankenPHP, not the 500 response of the framework. To stop these reports, an application can ignore FrankenPHP\RequestBodyException in its error handler.

Resumable uploads (tus)

PHP reads a PATCH body only when the script reads php://input. Thus, the script gets the bytes before the error, catches the exception, and keeps its offset. The client asks for the offset (HEAD) and sends the remaining data. This is the usual tus procedure, so resumable uploads continue to work.

The script does not get the last partial block. In the tests, it got 57,344 bytes (7 × 8,192) of 60,000. The offset agrees with the data that the script wrote, so the data stays correct. The client sends some bytes again. A later change can give these bytes to the script and throw the exception at the next read.

PHP reads a POST body before the script starts. Thus, a tus "creation with upload" request with a truncated body gets 400, and the script does not run. The client must start the upload again.

UPLOAD_ERR_PARTIAL

PHP reads multipart/form-data before the script starts. When the transport fails, the script does not run, and the client gets 400 or 408.

UPLOAD_ERR_PARTIAL stays available when the multipart content is not correct but the transport is complete, for example when the closing boundary is missing. Thus, the error now shows a content problem only. It does not hide a network problem.

With nginx and PHP-FPM, nginx keeps the full body in a buffer before it sends the request to PHP. Thus, PHP-FPM applications behind nginx do not see UPLOAD_ERR_PARTIAL for a transport failure. This PR gives the same result.

Response control

When the read fails before PHP sends the headers, FrankenPHP writes the 400 or 408 response. FrankenPHP discards the output of the script. The script cannot change the status or the body of this response. The 413 response of #2785 operates in the same way.

This is important only when the client waits for a response: a body that stops for too long (408), or a client that closes only its write side. When the connection is closed or the stream is reset, the client cannot get a response.

Body that the script does not read

FrankenPHP reads a PATCH, PUT or DELETE body only when PHP asks for it. If the script does not read the body, the read error does not occur during the request, and the response is 200. The script did not use the truncated data, thus the data stays correct. To find this case, FrankenPHP must read the full body before the script starts (#2541). This PR does not do that.

Client that closed the connection

When the client closes the connection, the 400 response is not received. But the access logs and the metrics count it as a 4xx response. Caddy writes 499 ("client closed request") in its reverse proxy when the request context is canceled. FrankenPHP never wrote 499 before this change: before, the script ran on the truncated body, and the log showed the status of the script, usually 200.

We examined whether FrankenPHP can use 499 when the client is gone. We used a server with the same configuration as Caddy (net/http with golang.org/x/net/http2, Go 1.27):

Case Read error r.Context().Err() Client gets the response
HTTP/1.1, client closes its write side only unexpected EOF context canceled Yes (400)
HTTP/1.1, client closes the connection (FIN) unexpected EOF context canceled No
HTTP/1.1, connection reset (RST) unexpected EOF or connection reset by peer context canceled No
HTTP/2, RST_STREAM (CANCEL) http2.StreamError (CANCEL) context canceled No
HTTP/2, connection closed client disconnected context canceled No
HTTP/2, END_STREAM before the announced length request declared a Content-Length of 25 but only wrote 19 bytes nil Yes (400)
  • HTTP/1.1: FrankenPHP cannot know if the client is gone. A client that closes only its write side and a client that closes the connection send the same FIN. The context is canceled in the two cases, and the write of the response does not fail. A TCP reset does not always give connection reset by peer: in our tests, it also gave unexpected EOF.
  • HTTP/2: in our tests, a canceled context agrees with a gone client. The client that ends its stream too early waits for the response, and its context is not canceled.
  • HTTP/3: when the client resets its request stream (RESET_STREAM), the response direction stays open. In our tests, the client got the 400 response. Thus, a reset request stream does not show that the client is gone.

Thus, 499 can be correct for HTTP/2 only. This PR does not add 499. If you want 499 for HTTP/2, we can add it.

request_body_timeout question

TestRequestBodyTimeout and TestRequestBodyTimeoutHTTP2 expected a 200 response after the timeout, with an empty body. This PR changes them: they expect a 408 response, and the script does not run on the partial body.

We think that 408 is the correct result:

  • The script cannot know that its input is not complete.
  • RFC 9110 §15.5.9 defines 408 for this case: "the server did not receive a complete request message within the time that it was prepared to wait."
  • RFC 9112 §8 lets a server send an error response when it gets an incomplete request message ("canceled request or triggered timeout").

Questions for the maintainers:

  1. Lazy read, exception only. For PATCH, PUT and DELETE, the script already runs when the read fails. FrankenPHP could throw the exception and not reject the request. Then the application writes its own response. If the application does not catch the exception, the result is a 500 error. This does not apply to POST, because PHP reads a POST body before the script starts. Do you want this variant?
  2. Identifiable rejections. The rejection response has no explicit headers. Thus, the Caddy intercept directive cannot separate a FrankenPHP rejection from a 400 response of the application. We prepared a separate change for this problem: the reject_header option of php_server and php (WithRequestRejectHeader in the library). The option is off by default. When the user sets it, FrankenPHP adds a header with this name to each rejection, with the rejection message as value. Each rejection also gets Content-Type: text/plain; charset=utf-8 and X-Content-Type-Options: nosniff. With the option, intercept replaces the rejections (400, 408) with a JSON response, and the 400 responses of the application do not change. Without the option, FrankenPHP adds no header that a client can use to identify it. The change has Go tests (option, Caddyfile, end-to-end with intercept) and a black-box test in classic mode and worker mode. It is ready in the branch Derjuju/frankenphp:feat/reject-header. Do you want a PR for it?

Tests

New file requestbodyincomplete_test.go:

  • TestRequestBodyIncomplete: three read errors (unexpected EOF, connection reset, deadline) × six request types (POST urlencoded, multipart, text/csv, without Content-Type, PUT JSON, PUT urlencoded) × with and without chunked encoding. A body that PHP reads before the script starts: the script does not run. A body that the script reads: the script catches the exception with catch (FrankenPHP\RequestBodyException).
  • TestRequestBodyIncompleteMultipartTextField: a multipart/form-data text field that is cut.
  • TestWorkerRequestBodyIncomplete: worker mode. The callback does not run, and the worker does not restart.
  • TestRequestBodyClientClosed: a real TCP client that closes before the end of the body, with Content-Length and with chunked encoding.
  • TestRequestBodyStreamResetHTTP2: an HTTP/2 stream reset.
  • TestRequestBodyShorterThanContentLength: a body that ends with io.EOF before its Content-Length, as HTTP/3 allows.
  • TestRequestParseBodyIncomplete: request_parse_body() on a cut body (urlencoded and multipart). This test runs on PHP 8.4 and later.

Changed: TestRequestBodyTimeout and TestRequestBodyTimeoutHTTP2 (see above). testdata/read-input-then-touch.php catches the parent class, thus the RequestBodyTooLarge tests also check the new class hierarchy.

These tests fail without the fix and pass with it. The full suite and the caddy/ tests pass with -race, without a data race. The HTTP/2 and TCP tests passed 20 times in sequence. golangci-lint, go mod tidy -diff, gofmt, clang-format and markdownlint show no problem. frankenphp_arginfo.h is generated by gen_stub.php (PHP 8.5). We also did the black-box tests above, with the image of this branch and with the official 1.13.5 image as a reference.

Related: #2785 (merged), #2541 and #2835 (open).

AI assistance

We used an AI assistant (Claude) to analyze the code, write the tests and the patch, and write this description. A human did a check of all the code and all the results. We did the measurements on real builds.

go_read_post only rejected *http.MaxBytesError; any other read error
(client closing before Content-Length, unterminated chunked body, read
deadline, HTTP/2 stream reset) was swallowed and PHP ran the script on
the bytes received so far. A truncated multipart text field or a body
without Content-Length cannot be detected by the application.

Reject with 400 (request body incomplete) or 408 (read timeout) and
keep 413 for MaxBytesError. A body that ends before its Content-Length
without an error, as HTTP/3 (quic-go) allows, is also incomplete. When
the script itself reads php://input or calls request_parse_body() and
the read fails, throw FrankenPHP\RequestBodyIncompleteException; the
400/408 response is still sent if headers were not sent yet.

RequestBodyIncompleteException and RequestBodyTooLargeException now
extend the new FrankenPHP\RequestBodyException, so one catch handles
both. The read result shared by Go and C is a C enum.
@Derjuju
Derjuju force-pushed the fix/request-body-incomplete branch from 30e7aac to 637a813 Compare November 20, 2026 17:54

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant