= HTTP


////
     THIS FILE IS AUTOGENERATED!

     To make changes please edit the contents of:

     https://github.com/redpanda-data/connect/tree/main/cmd/tools/docs_gen/templates/http.adoc.tmpl
////

// © 2024 Redpanda Data Inc.

When {page-component-title} runs it kicks off an HTTP server that provides a few generally useful endpoints and is also where configured components such as the xref:components:inputs/http_server.adoc[`http_server` input] xref:components:outputs/http_server.adoc[and output] can register their own endpoints if they don't require their own host/port.

The configuration for this server lives under the `http` namespace, with the following default values:



[tabs]
======
Common::
+
--

```yaml
# Common config fields, showing default values
http:
  enabled: true
  address: 0.0.0.0:4195
  root_path: /benthos
  debug_endpoints: false
```

--
Advanced::
+
--

```yaml
# All config fields, showing default values
http:
  enabled: true
  address: 0.0.0.0:4195
  root_path: /benthos
  debug_endpoints: false
  cert_file: ""
  key_file: ""
  cors:
    enabled: false
    allowed_origins: []
  basic_auth:
    enabled: false
    realm: restricted
    username: ""
    password_hash: ""
    algorithm: sha256
    salt: ""
```
--
======
The field `enabled` can be set to `false` in order to disable the server.

The field `root_path` specifies a general prefix for all endpoints, this can help isolate the service endpoints when using a reverse proxy with other shared services. All endpoints will still be registered at the root as well as behind the prefix, e.g. with a `root_path` set to `/foo` the endpoint `/version` will be accessible from both `/version` and `/foo/version`.

== Enabling HTTPS

By default {page-component-title} will serve traffic over HTTP. In order to enforce TLS and serve traffic exclusively over HTTPS you must provide a `cert_file` and `key_file` path in your config, which point to a file containing a certificate and a matching private key for the server respectively.

If the certificate is signed by a certificate authority, the `cert_file` should be the concatenation of the server's certificate, any intermediates, and the CA's certificate.

== Enabling basic authentication

By default {page-component-title} does not do any sort of authentication for the service-wide HTTP server. However, it's possible to configure basic authentication with the <<basic-auth,`basic_auth`>> field. Passwords configured must be hashed according to the specified algorithm and base64 encoded, for some hashing algorithms you can do this using {page-component-title} itself:

```sh
echo mynewpassword | rpk connect blobl 'root = content().hash("sha256").encode("base64")'
```

== Endpoints

The following endpoints will be generally available when the HTTP server is enabled:

- `/version` provides version info.
- `/ping` can be used as a liveness probe as it always returns a 200.
- `/ready` can be used as a readiness probe as it serves a 200 only when both the input and output are connected, otherwise a 503 is returned.
- `/metrics`, `/stats` both provide metrics when the metrics type is either xref:components:metrics/json_api.adoc[`json_api`] or xref:components:metrics/prometheus.adoc[`prometheus`].
- `/endpoints` provides a JSON object containing a list of available endpoints, including those registered by configured components.

== CORS

In order to serve Cross-Origin Resource Sharing headers, which instruct browsers to allow CORS requests, set the subfield `cors.enabled` to `true`.

=== allowed_origins

A list of allowed origins to connect from. The literal value `*` can be specified as a wildcard. Note `cors.enabled` must be set to `true` for this list to take effect.

== Debug endpoints

The field `debug_endpoints` when set to `true` prompts {page-component-title} to register a few extra endpoints that can be useful for debugging performance or behavioral problems:

- `/debug/config/json` returns the loaded config as JSON.
- `/debug/config/yaml` returns the loaded config as YAML.
- `/debug/pprof/block` responds with a pprof-formatted block profile.
- `/debug/pprof/heap` responds with a pprof-formatted heap profile.
- `/debug/pprof/mutex` responds with a pprof-formatted mutex profile.
- `/debug/pprof/profile` responds with a pprof-formatted cpu profile.
- `/debug/pprof/goroutine` responds with a pprof-formatted goroutine profile.
- `/debug/pprof/symbol` looks up the program counters listed in the request, responding with a table mapping program counters to function names.
- `/debug/pprof/trace` responds with the execution trace in binary form. Tracing lasts for duration specified in seconds GET parameter, or for 1 second if not specified.
- `/debug/stack` returns a snapshot of the current service stack trace.

== Fields

The schema of the `http` section is as follows:

=== `enabled`

Whether to enable to HTTP server.


*Type*: `bool`

*Default*: `true`

=== `address`

The address to bind to.


*Type*: `string`

*Default*: `"0.0.0.0:4195"`

=== `root_path`

Specifies a general prefix for all endpoints, this can help isolate the service endpoints when using a reverse proxy with other shared services. All endpoints will still be registered at the root as well as behind the prefix, e.g. with a root_path set to `/foo` the endpoint `/version` will be accessible from both `/version` and `/foo/version`.


*Type*: `string`

*Default*: `"/benthos"`

=== `debug_endpoints`

Whether to register a few extra endpoints that can be useful for debugging performance or behavioral problems.


*Type*: `bool`

*Default*: `false`

=== `cert_file`

An optional certificate file for enabling TLS.


*Type*: `string`

*Default*: `""`

=== `key_file`

An optional key file for enabling TLS.


*Type*: `string`

*Default*: `""`

=== `cors`

Adds Cross-Origin Resource Sharing headers.


*Type*: `object`

Requires version 3.63.0 or newer

=== `cors.enabled`

Whether to allow CORS requests.


*Type*: `bool`

*Default*: `false`

=== `cors.allowed_origins`

An explicit list of origins that are allowed for CORS requests.


*Type*: `array`

*Default*: `[]`

=== `basic_auth`

Allows you to enforce and customise basic authentication for requests to the HTTP server.


*Type*: `object`


=== `basic_auth.enabled`

Enable basic authentication


*Type*: `bool`

*Default*: `false`

=== `basic_auth.realm`

Custom realm name


*Type*: `string`

*Default*: `"restricted"`

=== `basic_auth.username`

Username required to authenticate.


*Type*: `string`

*Default*: `""`

=== `basic_auth.password_hash`

Hashed password required to authenticate. (base64 encoded)


*Type*: `string`

*Default*: `""`

=== `basic_auth.algorithm`

Encryption algorithm used to generate `password_hash`.


*Type*: `string`

*Default*: `"sha256"`

```yml
# Examples

algorithm: md5

algorithm: sha256

algorithm: bcrypt

algorithm: scrypt
```

=== `basic_auth.salt`

Salt for scrypt algorithm. (base64 encoded)


*Type*: `string`

*Default*: `""`

