github.com/Jeffail/benthos/v3@v3.65.0/website/docs/components/inputs/http_server.md (about) 1 --- 2 title: http_server 3 type: input 4 status: stable 5 categories: ["Network"] 6 --- 7 8 <!-- 9 THIS FILE IS AUTOGENERATED! 10 11 To make changes please edit the contents of: 12 lib/input/http_server.go 13 --> 14 15 import Tabs from '@theme/Tabs'; 16 import TabItem from '@theme/TabItem'; 17 18 19 Receive messages POSTed over HTTP(S). HTTP 2.0 is supported when using TLS, which is enabled when key and cert files are specified. 20 21 22 <Tabs defaultValue="common" values={[ 23 { label: 'Common', value: 'common', }, 24 { label: 'Advanced', value: 'advanced', }, 25 ]}> 26 27 <TabItem value="common"> 28 29 ```yaml 30 # Common config fields, showing default values 31 input: 32 label: "" 33 http_server: 34 address: "" 35 path: /post 36 ws_path: /post/ws 37 allowed_verbs: 38 - POST 39 timeout: 5s 40 rate_limit: "" 41 ``` 42 43 </TabItem> 44 <TabItem value="advanced"> 45 46 ```yaml 47 # All config fields, showing default values 48 input: 49 label: "" 50 http_server: 51 address: "" 52 path: /post 53 ws_path: /post/ws 54 ws_welcome_message: "" 55 ws_rate_limit_message: "" 56 allowed_verbs: 57 - POST 58 timeout: 5s 59 rate_limit: "" 60 cert_file: "" 61 key_file: "" 62 cors: 63 enabled: false 64 allowed_origins: [] 65 sync_response: 66 status: "200" 67 headers: 68 Content-Type: application/octet-stream 69 metadata_headers: 70 include_prefixes: [] 71 include_patterns: [] 72 ``` 73 74 </TabItem> 75 </Tabs> 76 77 If the `address` config field is left blank the [service-wide HTTP server](/docs/components/http/about) will be used. 78 79 The field `rate_limit` allows you to specify an optional [`rate_limit` resource](/docs/components/rate_limits/about), which will be applied to each HTTP request made and each websocket payload received. 80 81 When the rate limit is breached HTTP requests will have a 429 response returned with a Retry-After header. Websocket payloads will be dropped and an optional response payload will be sent as per `ws_rate_limit_message`. 82 83 ### Responses 84 85 It's possible to return a response for each message received using [synchronous responses](/docs/guides/sync_responses). When doing so you can customise headers with the `sync_response` field `headers`, which can also use [function interpolation](/docs/configuration/interpolation#bloblang-queries) in the value based on the response message contents. 86 87 ### Endpoints 88 89 The following fields specify endpoints that are registered for sending messages, and support path parameters of the form `/{foo}`, which are added to ingested messages as metadata: 90 91 #### `path` (defaults to `/post`) 92 93 This endpoint expects POST requests where the entire request body is consumed as a single message. 94 95 If the request contains a multipart `content-type` header as per [rfc1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) then the multiple parts are consumed as a batch of messages, where each body part is a message of the batch. 96 97 #### `ws_path` (defaults to `/post/ws`) 98 99 Creates a websocket connection, where payloads received on the socket are passed through the pipeline as a batch of one message. 100 101 You may specify an optional `ws_welcome_message`, which is a static payload to be sent to all clients once a websocket connection is first established. 102 103 It's also possible to specify a `ws_rate_limit_message`, which is a static payload to be sent to clients that have triggered the servers rate limit. 104 105 ### Metadata 106 107 This input adds the following metadata fields to each message: 108 109 ``` text 110 - http_server_user_agent 111 - http_server_request_path 112 - http_server_verb 113 - All headers (only first values are taken) 114 - All query parameters 115 - All path parameters 116 - All cookies 117 ``` 118 119 You can access these metadata fields using [function interpolation](/docs/configuration/interpolation#metadata). 120 121 ## Fields 122 123 ### `address` 124 125 An alternative address to host from. If left empty the service wide address is used. 126 127 128 Type: `string` 129 Default: `""` 130 131 ### `path` 132 133 The endpoint path to listen for POST requests. 134 135 136 Type: `string` 137 Default: `"/post"` 138 139 ### `ws_path` 140 141 The endpoint path to create websocket connections from. 142 143 144 Type: `string` 145 Default: `"/post/ws"` 146 147 ### `ws_welcome_message` 148 149 An optional message to deliver to fresh websocket connections. 150 151 152 Type: `string` 153 Default: `""` 154 155 ### `ws_rate_limit_message` 156 157 An optional message to delivery to websocket connections that are rate limited. 158 159 160 Type: `string` 161 Default: `""` 162 163 ### `allowed_verbs` 164 165 An array of verbs that are allowed for the `path` endpoint. 166 167 168 Type: `array` 169 Default: `["POST"]` 170 Requires version 3.33.0 or newer 171 172 ### `timeout` 173 174 Timeout for requests. If a consumed messages takes longer than this to be delivered the connection is closed, but the message may still be delivered. 175 176 177 Type: `string` 178 Default: `"5s"` 179 180 ### `rate_limit` 181 182 An optional [rate limit](/docs/components/rate_limits/about) to throttle requests by. 183 184 185 Type: `string` 186 Default: `""` 187 188 ### `cert_file` 189 190 Enable TLS by specifying a certificate and key file. Only valid with a custom `address`. 191 192 193 Type: `string` 194 Default: `""` 195 196 ### `key_file` 197 198 Enable TLS by specifying a certificate and key file. Only valid with a custom `address`. 199 200 201 Type: `string` 202 Default: `""` 203 204 ### `cors` 205 206 Adds Cross-Origin Resource Sharing headers. Only valid with a custom `address`. 207 208 209 Type: `object` 210 Requires version 3.63.0 or newer 211 212 ### `cors.enabled` 213 214 Whether to allow CORS requests. 215 216 217 Type: `bool` 218 Default: `false` 219 220 ### `cors.allowed_origins` 221 222 An explicit list of origins that are allowed for CORS requests. 223 224 225 Type: `array` 226 Default: `[]` 227 228 ### `sync_response` 229 230 Customise messages returned via [synchronous responses](/docs/guides/sync_responses). 231 232 233 Type: `object` 234 235 ### `sync_response.status` 236 237 Specify the status code to return with synchronous responses. This is a string value, which allows you to customize it based on resulting payloads and their metadata. 238 This field supports [interpolation functions](/docs/configuration/interpolation#bloblang-queries). 239 240 241 Type: `string` 242 Default: `"200"` 243 244 ```yaml 245 # Examples 246 247 status: "200" 248 249 status: ${! json("status") } 250 251 status: ${! meta("status") } 252 ``` 253 254 ### `sync_response.headers` 255 256 Specify headers to return with synchronous responses. 257 This field supports [interpolation functions](/docs/configuration/interpolation#bloblang-queries). 258 259 260 Type: `object` 261 Default: `{"Content-Type":"application/octet-stream"}` 262 263 ### `sync_response.metadata_headers` 264 265 Specify criteria for which metadata values are added to the response as headers. 266 267 268 Type: `object` 269 270 ### `sync_response.metadata_headers.include_prefixes` 271 272 Provide a list of explicit metadata key prefixes to match against. 273 274 275 Type: `array` 276 Default: `[]` 277 278 ```yaml 279 # Examples 280 281 include_prefixes: 282 - foo_ 283 - bar_ 284 285 include_prefixes: 286 - kafka_ 287 288 include_prefixes: 289 - content- 290 ``` 291 292 ### `sync_response.metadata_headers.include_patterns` 293 294 Provide a list of explicit metadata key regular expression (re2) patterns to match against. 295 296 297 Type: `array` 298 Default: `[]` 299 300 ```yaml 301 # Examples 302 303 include_patterns: 304 - .* 305 306 include_patterns: 307 - _timestamp_unix$ 308 ``` 309 310