This port's purpose is to develop HTTP servers (REST services or Web applications). Servers will handle connections in order to process requests using http_handlers.md.

Adapters implementing this port are in charge of starting up a server to handle incoming connections, convert requests to the Hexagon model, process these requests using the supplied http_handlers.md, convert the generated response to the server format and send it to the client.

Install the Dependency

This module is not meant to be used directly. You should include and Adapter implementing this feature (as http_server_jetty.md) 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:

• 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.

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.