finch
Bootstraps a Finagle HTTP service out of the collection of Finch endpoints.
Bootstraps a Finagle HTTP service out of the collection of Finch endpoints.
val api: Service[Request, Response] = Bootstrap
.serve[Application.Json](getUser :+: postUser)
.serve[Text.Plain](healthcheck)
.toServiceThis API is experimental/unstable. Use with caution.
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 io.finch.syntax.Mapper:
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 result returned from an Endpoint.
A result returned from an Endpoint. This models Option[(Input, Future[Output])] and
represents two cases:
remainder and output is returned.None is returned.API methods exposed on this type are mostly introduced for testing.
This class also provides various of awaitX methods useful for testing and experimenting.
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 that glues two individual pieces together:
An input for Endpoint that glues two individual pieces together:
- Finagle's Request needed for evaluating (e.g., body, param)
- Finch's route (represented as Seq[String]) needed for matching (e.g., path)
An output of Endpoint.
Represents a conversion from A to Response.
Wraps a given list of Endpoints and their content-types with a Finagle Service.
Wraps a given list of Endpoints and their content-types with a Finagle Service.
Guarantees to:
- handle Finch's own errors (i.e., Error and Error) as 400s - copy requests's HTTP version onto a response - respond with 404 when en endpoint is not matched
- include the date header on each response (unless disabled) - include the server header on each response (unless disabled)
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]
An Endpoint that skips all path segments.
An identity Endpoint.
Provides extension methods for Endpoint to support coproduct and path syntax.
Creates an input for Endpoint from Request.
Wraps a given Endpoint with a Finagle Service.
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 value from the current path segment.
A matching Endpoint that reads a boolean value from the current path segment.
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 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.
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 evaluating Endpoint that reads a required file upload from a multipart/form-data
request.
An evaluating Endpoint that reads an optional file upload from a multipart/form-data
request into an Option.
An evaluating Endpoint 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.
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.
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.
A matching Endpoint that reads an integer value from the current path segment.
A matching Endpoint that reads an integer value from the current path segment.
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 a string tail from the current path segment.
A matching Endpoint that reads a string 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 value from the current path segment.
A matching Endpoint that reads a long value from the current path segment.
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 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.
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 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 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.
An Endpoint that matches a given string.
An Endpoint that matches a given string.
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 tail value A (using the implicit
DecodePath instances defined for A) from the entire path.
A matching Endpoint that reads a tail value A (using the implicit
DecodePath instances defined for A) from the entire path.
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.
A matching Endpoint that reads a string value from the current path segment.
A matching Endpoint that reads a string value from the current path segment.
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.
A matching Endpoint that reads a string tail from the current path segment.
Enables Sinatra-like syntax extensions for endpoints.
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 a UUID value from the current path segment.
A matching Endpoint that reads a UUID value from the current path segment.
A matching Endpoint that reads an UUID value from the current path segment.
A matching Endpoint that reads an UUID value from the current path segment.
A matching Endpoint that reads a UUID tail from the current path segment.
A matching Endpoint that reads a UUID tail from the current path segment.
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.