finch
Maintains Basic HTTP Auth for an arbitrary Endpoint.
Decodes an HTTP payload represented as Buf (encoded with Charset) into
an arbitrary type A.
Decodes an HTTP entity (eg: header, query-string param) represented as UTF-8 String into
an arbitrary type A.
Decodes an HTTP path (eg: /foo/bar/baz) represented as UTF-8 String into
an arbitrary type A.
Encodes an HTTP payload (represented as an arbitrary type A) with a given Charset.
An Endpoint represents the HTTP endpoint.
An Endpoint represents the HTTP endpoint.
It is well known and widely adopted in Finagle that "Your Server is a Function"
(i.e., Request => Future[Response]). In a REST/HTTP API setting this function may be viewed as
Request =1=> (A =2=> Future[B]) =3=> Future[Response], where transformation 1 is a request
decoding (deserialization), transformation 2 - is a business logic and transformation 3 is -
a response encoding (serialization). The only interesting part here is transformation 2 (i.e.,
A => Future[B]), which represents an application business.
An Endpoint transformation (map, mapAsync, etc.) encodes the business logic, while the
rest of Finch ecosystem takes care about both serialization and deserialization.
A typical way to transform (or map) the Endpoint is to use Mapper and Endpoint.apply
method, which, depending on the argument type, delegates the map operation to the underlying
function.
import io.finch._ case class Foo(i: Int) case class Bar(s: String) val foo: Endpoint[Foo] = get("foo") { Ok(Foo(42)) } val bar: Endpoint[Bar] = get("bar" :: string) { s: String => Ok(Bar(s)) }
Endpoints are also composable in terms of or-else combinator (known as a "space invader"
operator :+:) that takes two Endpoints and returns a coproduct Endpoint.
import io.finch._ val foobar: Endpoint[Foo :+: Bar :+: CNil] = foo :+: bar
An Endpoint might be converted into a Finagle Service with Endpoint.toService method so
it can be served within Finagle HTTP.
import com.twitter.finagle.Http
Http.server.serve(foobar.toService)
A collection of Endpoint combinators.
A single error from an Endpoint.
A single error from an Endpoint.
This indicates that one of the Finch's built-in components failed. This includes, but not limited by:
- reading a required param, body, header, etc.
- parsing a string-based endpoint with .as[T] combinator
- validating an endpoint with .should or shouldNot combinators
Multiple errors from an Endpoint.
An input for Endpoint.
An output of Endpoint.
A ValidationRule enables a reusable way of defining a validation rules in the application
domain.
A ValidationRule enables a reusable way of defining a validation rules in the application
domain. It might be composed with Endpoints 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: Endpoint[User] = ( param("name").should(beLongerThan(3)) :: param("age").as[Int].should(beGreaterThan(0) and beLessThan(120)) ).as[User]
(Since version 0.11) Use io.finch.Decode instead
(Since version 0.11) Use io.finch.Encode instead
An Endpoint that skips all path segments.
An identity Endpoint.
An Exception representing a failed authorization with BasicAuth.
Provides extension methods for Endpoint to support coproduct and path syntax.
Creates an input for Endpoint from Request.
Allows the creation of reusable validation rules for Endpoints.
An evaluating Endpoint that reads a required chunked streaming binary body, interpreted as
an AsyncStream[Buf].
A ValidationRule that makes sure the numeric value is greater than given n.
A ValidationRule that makes sure the numeric value is greater than given n.
A ValidationRule that makes sure the numeric value is less than given n.
A ValidationRule that makes sure the numeric value is less than given n.
A ValidationRule that makes sure the string value is longer than n symbols.
A ValidationRule that makes sure the string value is longer than n symbols.
A ValidationRule that makes sure the string value is shorter than n symbols.
A ValidationRule that makes sure the string value is shorter than n symbols.
An evaluating Endpoint that reads a required binary request body, interpreted as an
Array[Byte], or throws a Error.NotPresent exception.
An evaluating Endpoint that reads a required binary request body, interpreted as an
Array[Byte], or throws a Error.NotPresent exception. The returned Endpoint only
matches non-chunked (non-streamed) requests.
An evaluating Endpoint that reads a binary request body, interpreted as a Array[Byte],
into an Option.
An Endpoint that reads the required request body represented as CT (ContentType) and
interpreted as A, or throws an Error.NotPresent exception.
An Endpoint that reads the required request body represented as CT (ContentType) and
interpreted as A, or throws an Error.NotPresent exception. The returned Endpoint
only matches non-chunked (non-streamed) requests.
An Endpoint that reads an optional request body represented as CT (ContentType) and
interpreted as A, into an Option.
A matching Endpoint that reads a boolean value from the current path segment.
A matching Endpoint that reads a boolean tail from the current path segment.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
An evaluating Endpoint that reads a required cookie from the request or raises an Error.NotPresent exception when the cookie is missing.
An evaluating Endpoint that reads a required cookie from the request or raises an Error.NotPresent exception when the cookie is missing.
An evaluating Endpoint that reads an optional HTTP cookie from the request into an
Option.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
An evaluating Endpoint that reads a required file upload from a multipart/form-data request.
An evaluatingEndpoint that reads an optional file upload from a multipart/form-data request
into an Option.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
An evaluating Endpoint that reads a required HTTP header name from the request or raises
an Error.NotPresent exception when the header is missing.
An evaluating Endpoint that reads a required HTTP header name from the request or raises
an Error.NotPresent exception when the header is missing.
A matching Endpoint that only matches the requests that contain a given header name.
An evaluating Endpoint that reads an optional HTTP header name from the request into an
Option.
A matching Endpoint that reads an integer value from the current path segment.
This package contains an internal-use only type-classes and utilities that power Finch's API.
This package contains an internal-use only type-classes and utilities that power Finch's API.
It's not recommended to use any of the internal API directly, since it might change without any deprecation cycles.
A matching Endpoint that reads an integer tail from the current path segment.
Alias for body[A, Application.Json].
Alias for body[A, Application.Json].
Alias for bodyOption[A, Application.Json].
Alias for bodyOption[A, Application.Json].
A matching Endpoint that reads a long value from the current path segment.
A matching Endpoint that reads a long tail from the current path segment.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
An evaluating Endpoint that reads a required query-string param name from the
request or raises an Error.NotPresent exception when the param is missing; an
Error.NotValid exception is the param is empty.
An evaluating Endpoint that reads a required query-string param name from the
request or raises an Error.NotPresent exception when the param is missing; an
Error.NotValid exception is the param is empty.
A matching Endpoint that only matches the requests that contain a given query-string
param name.
An evaluating Endpoint that reads an optional query-string param name from the request
into an Option.
An evaluating Endpoint that reads an optional (in a meaning that a resulting
Seq may be empty) multi-value query-string param name from the request into a Seq.
An evaluating Endpoint that reads a required multi-value query-string param name
from the request into a NonEmptyList or raises a Error.NotPresent exception
when the params are missing or empty.
An evaluating Endpoint that reads a required multi-value query-string param name
from the request into a NonEmptyList or raises a Error.NotPresent exception
when the params are missing or empty.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
A matching Endpoint that reads a value of type A (using the implicit
DecodePath instances defined for A) from the current path segment.
A matching Endpoint that reads a value of type A (using the implicit
DecodePath instances defined for A) from the current path segment.
A matching Endpoint that reads a string value from the current path segment.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
A combinator that wraps the given Endpoint with additional check of the HTTP method.
A root Endpoint that always matches and extracts the current request.
A matching Endpoint that reads a string value from the current path segment.
An evaluating Endpoint that reads the required request body, interpreted as a String, or
throws an Error.NotPresent exception.
An evaluating Endpoint that reads the required request body, interpreted as a String, or
throws an Error.NotPresent exception. The returned Endpoint only matches non-chunked
(non-streamed) requests.
An evaluating Endpoint that reads an optional request body, interpreted as a String, into
an Option.
A matching Endpoint that reads a string tail from the current path segment.
Alias for body[A, Text.Plain]
Alias for body[A, Text.Plain]
Alias for bodyOption[A, Text.Plain]
Alias for bodyOption[A, Text.Plain]
Implicit conversion that allows the same inline rules to be used for required and optional values.
Implicit conversion that allows the same inline rules to be used for required and optional values. If the optional value is non-empty, it gets validated (and validation may fail, producing error), but if it is empty, it is always treated as valid.
In order to help the compiler determine the case when inline rule should be converted, the type of the validated value should be specified explicitly.
paramOption("foo").should("be greater than 50") { i: Int => i > 50 }
the underlying function to convert
A combinator that wraps the given Endpoint with additional check of the HTTP method.
A matching Endpoint that reads an UUID value from the current path segment.
A matching Endpoint that reads an UUID tail from the current path segment.
An Endpoint that reads the required request body, interpreted as Buf, or throws an Error.NotPresent exception.
An Endpoint that reads the required request body, interpreted as Buf, or throws an Error.NotPresent exception. The returned Endpoint only matches non-chunked (non-streamed) requests.
(Since version 0.11) Use body[A, ContentType] instead
An Endpoint that reads an optional request body, interpreted as Buf, into
an Option.
An evaluating Endpoint that reads a required (in a meaning that a resulting Seq will have
at least one element) multi-value query-string param name from the request into a Seq or
raises a Error.NotPresent exception when the params are missing or empty.
An evaluating Endpoint that reads a required (in a meaning that a resulting Seq will have
at least one element) multi-value query-string param name from the request into a Seq or
raises a Error.NotPresent exception when the params are missing or empty.
(Since version 0.11) Use paramsNel and NonEmptyList instead
This is a root package of the Finch library, which provides an immutable layer of functions and types atop of Finagle for writing lightweight HTTP services.