finch

This package introduces types and functions that enable _request processing_ in Finch. The io.finch.request primitives allow both to _read_ the various request items (query string param, header and cookie) using the RequestReader and _validate_ them using the ValidationRule.

The cornerstone abstraction of this package is a RequestReader, which is responsible for reading any amount of data from the HTTP request. RequestReaders might be composed with each other using either monadic API (flatMap method) or applicative API (:: method). Regardless the API used for RequestReaders composition, the main idea behind it is to use primitive readers (i.e., param, paramOption) in order to _compose_ them together and _map_ to the application domain data.

case class Complex(r: Double, i: Double)
val complex: RequestReader[Complex] = (
  param("real").as[Double] ::
  paramOption("imaginary").as[Double].withDefault(0.0)
).as[Complex]

A ValidationRule enables a reusable way of defining a validation rules in the application domain. It might be composed with RequestReaders using either should or shouldNot methods and with other ValidationRules using logical methods and and or.

case class User(name: String, age: Int)
val user: RequestReader[User] = (
  param("name").should(beLongerThan(3)) ::
  param("age").as[Int].should(beGreaterThan(0) and beLessThan(120))
).as[User]

This package enables a reasonable approach of building HTTP responses using the ResponseBuilder abstraction. The ResponseBuilder provides an immutable way of building concrete Response instances by specifying their status, headers and cookies. There are plenty of predefined builders named by HTTP statuses, i.e., Ok, Created, NotFound. Thus, the typical use case of the ResponseBuilder abstraction involves usage of concrete builder instead of abstract ResponseBuilder itself.

val ok: Response = Ok("Hello, World!")

In addition to text/plain responses, the ResponseBuilder is able to build any response, whose content-type is specified by an implicit type-class EncodeResponse instance. In fact, any type A may be passed to a RequestReader if there is a corresponding EncodeRequest[A] instance available in the scope.

implicit val encodeBigInt = EncodeResponse[BigInt]("text/plain") { _.toString }
val ok: Response = Ok(BigInt(100))

This package contains various of functions and types that enable _router combinators_ in Finch. Finch's route.Router is an abstraction that is responsible for routing the HTTP requests using their method and path information.

A companion object for Endpoint

Allows for the creation of Endpoints without an explicit service.

Endpoint {
  Method.Get -> Root / "hello" => Ok("world").toFuture
}