# Plugin Helper: Http Server

The `http_server` helper creates an HTTP server. This helper was introduced in v1.6.0.

It supports [`async-http`](https://github.com/socketry/async-http)-based server to improve the performance.

Here is an example:

```ruby
require 'fluent/plugin/input'

module Fluent::Plugin
  class ExampleInput < Input
    Fluent::Plugin.register_output('example', self)

    # 1. Load http_server helper
    helpers :http_server

    config_param :bind, :string
    config_param :port, :integer

    def start
      super

      # 2. Create and start HTTP server
      create_http_server(:example_http_server, addr: @bind, port: @port, logger: log) do |serv|
        # Define endpoint `/hello` with GET method
        serv.get('/hello') { [200, { 'Content-Type' => 'text/plain' }, 'hello!'] }
      end
    end
  end
end
```

**NOTE**: The launched plugin itself is managed by its plugin helper which stops it automatically. No need to stop it in the `stop` method.

## Methods

### `create_http_server(title, addr:, port:, logger:, default_app: nil, &block)` (deprecated)

**This method is deprecated! Use `http_server_create_http_server` method instead.**

### `http_server_create_http_server(title, addr:, port:, logger:, default_app: nil, proto: nil, tls_opts: nil, &block)`

It creates and starts an HTTP server with the given routes defined in `&block`.

* `title`: The name of the listening thread. Must be unique!
* `addr`: The address to listen to.
* `port`: The port to listen to.
* `logger`: The logger used in the server helper.
* `default_app`: The object to handle the requests with unregistered paths. This

  object must have a `#call` method or must be a `Proc` object.
* `proto`: Protocol type. Supported values: {`:tcp`, `:tls`} (default: `:tcp`)
* `tls_opts`: TLS options. Same as the Server Helper's

  [`server_create_connection` `tls_options`](/plugin-helper-overview/api-plugin-helper-server.md).

### `http_server_create_https_server(title, addr:, port:, logger:, default_app: nil, tls_opts: nil, &block)`

It creates and starts an HTTPS server with the given routes defined in `&block`.

* `title`: The name of the listening thread. Must be unique!
* `addr`: The address to listen to.
* `port`: The port to listen to.
* `logger`: The logger used in the server helper.
* `default_app`: The object to handle the requests with unregistered paths. This

  object must have a `#call` method or must be a `Proc` object.
* `tls_opts`: TLS options. Same as the Server Helper's

  [`server_create_connection` `tls_options`](/plugin-helper-overview/api-plugin-helper-server.md).

## Handling of other HTTP Methods

```ruby
create_http_server(:example_http_server, addr: @bind, port: @port, logger: log) do |serv|
  # define POST method `/hello`
  serv.post('/hello') { [200, { 'Content-Type' => 'text/plain' }, 'hello!'] }

  # define HEAD method `/hello`
  serv.head('/hello') { [200, { 'Content-Type' => 'text/plain' }, nil] }
end
```

## Request and Response

#### Request

Request supports these following methods:

* `query_string`: returns query string like `hoge=v1&fuga=v2`
* `query`: returns query which is `query_string` parsed by `CGI.parse`
* `body`: returns the request body
* `path`: returns the request path
* `headers`: returns `Protocol::HTTP::Headers` object to read the request headers (since v1.19.0)

#### Response

The `http_server` helper expects an array as the return value i.e.:

```ruby
[${response_status}, ${headers}, ${body}]
```

* `${response_status}` should be an `Integer`
* `${headers}` should be a `Hash`
* `${body}` should be a `String` or `nil`

#### Example

Here is an example of request and response in JSON format:

```ruby
create_http_server(:example_json_http_server, addr: @bind, port: @port, logger: log) do |serv|
  serv.post('/hello.json') do |req|
    body = JSON.parse(req.body)
    log.info(body)

    [code, { 'Content-Type' => 'application/json' }, { 'status' => 'success' }.to_json]
  end
end
```

## Plugins using `http_server`

* [`in_monitor_agent`](/input/monitor_agent.md)

If this article is incorrect or outdated, or omits critical information, please [let us know](https://github.com/fluent/fluentd-docs-gitbook/issues?state=open). [Fluentd](http://www.fluentd.org/) is an open-source project under [Cloud Native Computing Foundation (CNCF)](https://cncf.io/). All components are available under the Apache 2 License.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-http_server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.