From 751acd5e50f7b0d1da8132780b2369442d310d2a Mon Sep 17 00:00:00 2001
From: Daijiro Fukuda <fukuda@clear-code.com>
Date: Wed, 15 May 2024 18:14:09 +0900
Subject: [PATCH] in_http: add descriptions about Content-Type

Need to add `application/x-ndjson` and `application/csp-report`.

Related:

* https://github.com/fluent/fluentd/pull/3616
* https://github.com/fluent/fluentd/pull/4282

Signed-off-by: Daijiro Fukuda <fukuda@clear-code.com>
---
 input/http.md | 75 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 61 insertions(+), 14 deletions(-)

diff --git a/input/http.md b/input/http.md
index 55e4903c..2c3f6523 100644
--- a/input/http.md
+++ b/input/http.md
@@ -22,11 +22,43 @@ For the full list of the configurable options, see the [Parameters](http.md#para
 
 ## Basic Usage
 
-Here is a simple example to post a record using `curl`, which uses the default Content-Type `application/x-www-form-urlencoded`
+By default, the data format depends on the `Content-Type`.
+In summary, you can send the follwoing format.
 
-```text
-# Post a record with the tag "app.log"
-$ curl -X POST -d 'json={"foo":"bar"}' http://localhost:9880/app.log
+* `json`
+* `ndjson`
+* `msgpack`
+
+Here is a simple example to post a record using `curl`, which uses the default Content-Type `application/x-www-form-urlencoded`.
+
+Example: post JSON data with the tag "app.log":
+
+```bash
+curl -X POST -d 'json={"foo":"bar"}' http://localhost:9880/app.log
+```
+
+Example: post NDJSON data with the tag "app.log":
+
+```bash
+ndjson=`echo -e 'ndjson={"k1":"v1"}\n{"k2":"v2"}\n'`
+curl -X POST -d "$ndjson" http://localhost:9880/app.log
+```
+
+Example: post MessagePack data with the tag "app.log":
+
+```bash
+msgpack=`echo -e "msgpack=\x81\xa3foo\xa3bar"`
+curl -X POST -d "$msgpack" http://localhost:9880/app.log
+```
+
+Some `Content-Type` other than `application/x-www-form-urlencoded` support specific formats.
+In that case, the format type specification as `json=` in the data is not necessary.
+
+Example: Post JSON data with `Content-Type: application/json`:
+
+```bash
+curl -X POST -d '{"foo":"bar"}' -H 'Content-Type: application/json' \
+  http://localhost:9880/app.log
 ```
 
 **For more details regarding the message body syntax and `Content-Type` see [How to use HTTP Content-Type Header](http.md#how-to-use-http-content-type-header)**
@@ -230,24 +262,39 @@ $ curl -X POST -d "msgpack=$msgpack" http://localhost:9880/app.log
 
 `in_http` plugin recognizes HTTP `Content-Type` header in the incoming requests.
 
-By default `curl` uses `-H "Content-Type: application/x-www-form-urlencoded"`, which allows the use of the syntax `json=` and `msgpack=` as seen on the previous examples.
- 
+If you use the default `<parse>` setting, the data format depends on the `Content-Type`.
+(If you set the `<parse>` directive to use a specific Parser, the `Content-Type` is not used).
 
-However, you can send a JSON payload without the `json=` prefix by setting the content type `application/json`:
+By default `curl` uses `-H "Content-Type: application/x-www-form-urlencoded"`, which allows the use of the prefix `json=`, `ndjson=`, and `msgpack=` as seen on the previous examples.
 
-```text
-$ curl -X POST -d '{"foo":"bar"}' -H 'Content-Type: application/json' \
+On the other hand, some `Content-Type` other than `application/x-www-form-urlencoded` support specific formats.
+In that case, the prefix such as `json=` in the data is not necessary.
+
+Here is the list of supported `Content-Type`:
+
+| `Content-Type`           | data format | version |
+| :---                     | :---        | :---    |
+| `application/json`       | JSON        | -       |
+| `application/csp-report` | JSON        | 1.17.0  |
+| `application/msgpack`    | MessagePack | -       |
+| `application/x-ndjson`   | NDJSON      | 1.14.5  |
+
+Examples:
+
+```bash
+curl -X POST -d '{"foo":"bar"}' -H 'Content-Type: application/json' \
   http://localhost:9880/app.log
 ```
 
-To use MessagePack, set the content type to `application/msgpack`:
-
-```text
-$ msgpack=`echo -e "\x81\xa3foo\xa3bar"`
-$ curl -X POST -d "$msgpack" -H 'Content-Type: application/msgpack' \
+```bash
+msgpack=`echo -e "\x81\xa3foo\xa3bar"`
+curl -X POST -d "$msgpack" -H 'Content-Type: application/msgpack' \
   http://localhost:9880/app.log
 ```
 
+Also, you can use `multipart/form-data`.
+For more details about `multipart/form-data`, please see [Why `in_http` removes '+' from my log](http.md#why-in_http-removes--from-my-log).
+
 ### Handle Other Formats using Parser Plugins
 
 You can handle various input formats by using the `<parse>` directive. For example, add the following settings to the configuration file: