Add documentation about request_body directive in Caddyfile

[pic]

No description provided.

[mholt]

Looking good, thank you! Just a few minor fixes first.

[pic]

@francislavoie @mholt thanks for the suggestions, I've applied all of them

[mholt]

It occurred to me that we should probably document what happens when more than the maximum body size is read by the server, just for convenience so people don't have to cross-reference the JSON docs. But this LGTM for now, thanks for the contribution!

[airblade]

It occurred to me that we should probably document what happens when more than the maximum body size is read by the server, just for convenience so people don't have to cross-reference the JSON docs.

Please could you tell me what happens?

I would expect a 413 Payload Too Large response but looking at the code it seems to silently drop any excess bytes and carry on as if nothing erroneous had happened.

BTW, I tried to "cross-reference the JSON docs" but I'm not sure what or where they are.

[mholt]

@airblade It should depend on the handler that's reading the body, it's the job of the terminating handler to handle errors in a way that is suitable for it.

BTW, I tried to "cross-reference the JSON docs" but I'm not sure what or where they are.

The "JSON Config Structure" in the docs: https://caddyserver.com/docs/json/ (or the list of config modules: https://caddyserver.com/docs/modules/http.handlers.request_body)

[airblade]

@mholt Thanks for the response, much appreciated.

I've been looking further at the docs and browsing the code but I'm still can't figure out what would happen when a request body exceeds the maximum allowed size. (In my scenario it would be the user uploading a file via an HTML form to Caddy, through to an upstream Puma app server running a Rails app.)

[mholt]

@airblade Like I said, it depends on the terminating handler and how it chooses to handle the error. Since you mentioned you have an upstream app, I'm going to assume you are using reverse_proxy, which uses a transport module to perform the round trip. The default HTTP transport is implemented by the Go standard library, which controls that part of the logic (reading the request body):

https://github.com/golang/go/blob/ab4085ce84f8378b4ec2dfdbbc44c98cb92debe5/src/net/http/transport.go#L503-L504

[francislavoie]

To clarify - r.Body = http.MaxBytesReader(w, r.Body, rb.MaxSize) wraps r.Body with a check if Caddy tries to read too many bytes that will emit an error.

The error will get triggered in whatever subsequent handler which tries to read the body (like Matt said, possibly in reverse_proxy) and will bubble up to server.go's ServeHTTP which is the entrypoint for the handlers.

From there, Caddy will try to invoke the error handler chain (see https://caddyserver.com/docs/caddyfile/directives/handle_errors) if any is defined. So you get to choose what happens if an error happens.

I think you can use an expression matcher like this maybe (i.e. the error message here https://github.com/golang/go/blob/ab4085ce84f8378b4ec2dfdbbc44c98cb92debe5/src/net/http/request.go#L1178):

handle_errors {
	@bodyTooLarge expression `{http.error.status_text} == "http: request body too large"`
	handle @bodyTooLarge {
		respond "Oops, you tried to send too much data" 413
	}
}

[mholt]

I hadn't thought of that, I suppose that might be possible. Haven't tried it though.

[francislavoie]

Actually == comparison might not be precise enough here, might need to use a contains:

expression `{http.error.status_text}.contains("http: request body too large")`

YMMV. I haven't tried this. Just a hunch.

[airblade]

Thank you both for the explanations. I'm not too familiar with Go – sorry for being slow on the uptake.

Yes, I'm using reverse_proxy over a Unix socket to my upstream app server. Instead of trying to deduce from the code what would happen when uploading a too-large file, I just tried it. The upstream app server never saw the uploaded file, as I would expect. Caddy logged a 502 error (extract below):

{
  "level": "error",
  "logger": "http.log.error.log0",
  "msg": "http: request body too large",
  "request": {
    "proto": "HTTP/2.0",
    "method": "POST",
    "headers": {
      "Content-Length": [
        "150956774"
      ],
      "Content-Type": [
        "multipart/form-data; boundary=----WebKitFormBoundaryb8nKVz5ofss7vuyX"
      ]
    },
  },
  "duration": 5.752661917,
  "status": 502,
  "err_id": "ijuczeucu",
  "err_trace": "reverseproxy.statusError (reverseproxy.go:857)"
}

So to convert this into a 413 status code I would need to set up my own error handling, as above? I can certainly do that.

@mholt This is my first time using Caddy after years of Nginx. It is fantastic and I will not be going back :)

[francislavoie]

Yeah, I think that's right. Try adding handle_errors and see if it changes what the response looks like.