This port's purpose is to develop HTTP servers (REST services or Web applications). It defines a DSL to declare HTTP request handlers.

Adapters implementing this port are in charge of processing HTTP requests through a list of handlers.

Install the Dependency

This module is not meant to be used directly. You should include and Adapter implementing this feature (as http_server_jetty) in order to create an HTTP server.

Context on HTTP processing

An HTTP server is nothing more than a function that takes a request and returns a response. Requests and responses comply with several Web standards.

For the sake of ease of use, HTTP toolkits (or frameworks) are built. These tools make easier to write an HTTP server that has to deal with different behaviour based on requests attributes.

These development tools usually have different layers/parts (the ones below are some of the most common ones):

• IO: sockets and buffers management, SSL and thread scheduling is usually handled here also.

• HTTP messages parsing: parse requests to internal model and serialize responses to bytes.

• Routing: makes easy to run different blocks of code based on requests (usually supporting pipelining among different blocks).

Hexagon takes care of the third layer, it's "just" an abstraction layer for the IO engine and HTTP parser underneath, those two layers depends on the adapter (which you can select from a few alternatives).

This particularity allows users to swap adapters for different use cases. For example, You can use a low memory for embedded boards (as Raspberry Pi) or high through-output for servers, another use case would be to use a fast boot adapter for development, and select a different one for production.

To be agnostic of the adapter below, a custom HTTP model is implemented in Hexagon, and adapters must map their own structures to this model.

Now we'll talk about how HTTP routing is done in the toolkit. The cornerstone of HTTP handling in Hexagon is the handler: Hexagon handlers are a list of functions that may or may not be applied to an HTTP call depending on a predicate.

Handlers have a predicate, and they are only applied to a given request if the current request matches the predicate.

The functions that handle HTTP requests (named 'callbacks' in Hexagon) are blocks of code that get an HTTP call and return an HTTP call (probably the received one with a modified response), callbacks operate on immutable structures (the HTTP model).

Below you can find an in deep description of the concepts and components of this toolkit.

Servers

A server is a process listening to HTTP requests on a TCP port.

You can run multiple ones on different ports at the same time on the same JVM (this can be useful to test many microservices at the same time).

The server can be server settings. If you do not provide a value for them, they are searched inside the application settings and lastly, a default value is picked. This is the parameters list:

• banner: informative text shown at start up logs. If not set only runtime information is displayed.

• bindAddress: address to which this process is bound. If none is provided, 127.0.0.1 is taken.

• bindPort: the port which the process listens to. By default, it is 2010.

• contextPath: initial path used for the rest of the routes, by default it is empty.

To create a server, you need to provide a handler (check the handlers section for more information), and after creating a server you can run it or stop it with start() and stop() methods.