package finch
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.
- Alphabetic
- By Inheritance
- finch
- ValidationRules
- Outputs
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Package Members
- package internal
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.
Type Members
- abstract class Accept extends AnyRef
Models an HTTP Accept header (see RFC2616, 14.1).
Models an HTTP Accept header (see RFC2616, 14.1).
- Note
This API doesn't validate the input primary/sub types.
- See also
https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
- class Bootstrap[F[_], ES <: HList, CTS <: HList] extends AnyRef
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 .configure(negotiateContentType = true, enableMethodNotAllowed = true) .serve[Application.Json](getUser :+: postUser) .serve[Text.Plain](healthcheck) .toService
Supported Configuration Options
-
includeDateHeader
(default:true
): whether or not to include the Date header into each response (see RFC2616, section 14.18)-
includeServerHeader
(default:true
): whether or not to include the Server header into each response (see RFC2616, section 14.38)-
enableMethodNotAllowed
(default:false
): whether or not to enable 405 MethodNotAllowed HTTP response (see RFC2616, section 10.4.6)-
enableUnsupportedMediaType
(default:false
) whether or not to enable 415 UnsupportedMediaType HTTP response (see RFC7231, section 6.5.13)- See also
https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
https://tools.ietf.org/html/rfc7231#section-6.5.13
- trait Compile[F[_], ES <: HList, CTS <: HList] extends AnyRef
Compiles a given list of Endpoints and their content-types into single Endpoint.Compiled.
Compiles a given list of Endpoints and their content-types into single Endpoint.Compiled.
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 an endpoint is not matched - respond with 405 when an endpoint is not matched because method wasn't allowed (serve back an
Allow
header) - include the date header on each response (unless disabled) - include the server header on each response (unless disabled)- Annotations
- @implicitNotFound("""An Endpoint you're trying to compile is missing one or more encoders.
Make sure each endpoint in ${ES}, ${CTS} is one of the following:
* A com.twitter.finagle.http.Response
* A value of a type with an io.finch.Encode instance (with the corresponding content-type)
* A coproduct made up of some combination of the above
See https://github.com/finagle/finch/blob/master/docs/src/main/tut/cookbook.md#fixing-the-toservice-compile-error
""")
- trait Decode[A] extends AnyRef
Decodes an HTTP payload represented as Buf (encoded with Charset) into an arbitrary type
A
. - trait DecodeEntity[A] extends AnyRef
Decodes an HTTP entity (eg: header, query-string param) represented as UTF-8
String
into an arbitrary typeA
. - trait DecodePath[A] extends AnyRef
Decodes an HTTP path (eg: /foo/bar/baz) represented as UTF-8
String
into an arbitrary typeA
. - trait DecodeStream[S[_[_], _], F[_], A] extends AnyRef
Stream HTTP streamed payload represented as S[F, Buf] into a S[F, A] of arbitrary type
A
. - trait Encode[A] extends AnyRef
Encodes an HTTP payload (represented as an arbitrary type
A
) with a given Charset. - trait EncodeStream[F[_], S[_[_], _], A] extends AnyRef
A type-class that defines encoding of a stream in a shape of
S[F[_], A]
to Finagle's Reader. - trait Endpoint[F[_], A] extends AnyRef
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 asRequest =1=> (A =2=> Future[B]) =3=> Future[Response]
, where transformation1
is a request decoding (deserialization), transformation2
- is a business logic and transformation3
is - a response encoding (serialization). The only interesting part here is transformation2
(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 internal.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" :: path[String]) { s: String => Ok(Bar(s)) }
Endpoint
s are also composable in terms of or-else combinator (known as a "space invader" operator:+:
) that takes twoEndpoint
s and returns a coproductEndpoint
.import io.finch._ val foobar: Endpoint[Foo :+: Bar :+: CNil] = foo :+: bar
An
Endpoint
might be converted into a Finagle Service withEndpoint.toService
method so it can be served within Finagle HTTP.import com.twitter.finagle.Http Http.server.serve(foobar.toService)
- trait EndpointModule[F[_]] extends AnyRef
Enables users to construct Endpoint instances without specifying the effect type
F[_]
every time.Enables users to construct Endpoint instances without specifying the effect type
F[_]
every time.For example, via extending the
Endpoint.Module[F[_]]
:import io.finch._ import io.cats.effect.IO object Main extends App with Endpoint.Module[IO] { def foo = path("foo") }
It's also possible to instantiate an EndpointModule for a given effect and import its symbols into the score. For example:
import io.finch._ import io.cats.effect.IO object Main extends App { val io = Endpoint[IO] import io._ def foo = path("foo") }
There is a pre-defined EndpointModule for Cats'
IO
, available via the import:import io.finch._ import io.finch.catsEffect._ object Main extends App { def foo = path("foo") }
- sealed abstract class EndpointResult[F[_], +A] extends AnyRef
A result returned from an Endpoint.
A result returned from an Endpoint. This models
Option[(Input, Future[Output])]
and represents two cases:- Endpoint is matched (think of 200).
- Endpoint is not matched (think of 404, 405, etc).
In its current state,
EndpointResult.NotMatched
represented with two cases:EndpointResult.NotMatched
(very generic result usually indicating 404)EndpointResult.NotMatched.MethodNotAllowed
(indicates 405)
- sealed abstract class Error extends Exception with NoStackTrace
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
orshouldNot
combinators - case class Errors(errors: NonEmptyList[Error]) extends Exception with NoStackTrace with Product with Serializable
Multiple errors from an Endpoint.
- trait HighPriorityDecode extends LowPriorityDecode
- trait HighPriorityEncodeInstances extends LowPriorityEncodeInstances
- final case class Input(request: Request, route: List[String]) extends Product with Serializable
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 asSeq[String]
) needed for matching (e.g.,path
) - trait LiftReader[S[_[_], _], F[_]] extends AnyRef
Create stream
S[F, A]
from Reader. - trait LowPriorityDecode extends AnyRef
- trait LowPriorityEncodeInstances extends AnyRef
- sealed trait Output[+A] extends AnyRef
An output of Endpoint.
- trait Outputs extends AnyRef
- case class ServerSentEvent[A](data: A, id: Option[String] = None, event: Option[String] = None, retry: Option[Long] = None) extends Product with Serializable
- type ToAsync[F[_], E[_]] = finch.internal.ToAsync[F, E]
- trait ToResponse[F[_], A] extends AnyRef
Represents a conversion from
A
to Response. - trait ToResponseInstances extends AnyRef
- case class ToService[F[_]](compiled: Compiled[F])(implicit F: Effect[F]) extends Service[Request, Response] with Product with Serializable
Representation of
Endpoint.Compiled
as Finagle Service - sealed trait Trace extends AnyRef
Models a trace of a matched Endpoint.
Models a trace of a matched Endpoint. For example,
/hello/:name
.- Note
represented as a linked-list-like structure for efficiency.
- trait ValidationRule[A] extends AnyRef
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 shouldor
shouldNotmethods and with other
ValidationRules using logical methods
andand
or.
case class User(name: String, age: Int) val user: Endpoint[User] = ( param("name").validate(beLongerThan(3)) :: param("age").as[Int].should(beGreaterThan(0) and beLessThan(120)) ).as[User]
- trait ValidationRules extends AnyRef
Value Members
- def Accepted[A]: Output[A]
- Definition Classes
- Outputs
- def BadGateway(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def BadRequest(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def Conflict(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def Created[A](a: A): Output[A]
- Definition Classes
- Outputs
- def EnhanceYourCalm(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def Forbidden(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def GatewayTimeout(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def Gone(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def InsufficientStorage(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def InternalServerError(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def LengthRequired(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def MethodNotAllowed(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def NoContent[A]: Output[A]
- Definition Classes
- Outputs
- def NotAcceptable(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def NotFound(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def NotImplemented(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def Ok[A](a: A): Output[A]
- Definition Classes
- Outputs
- def PaymentRequired(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def PreconditionFailed(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def RequestEntityTooLarge(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def RequestTimeout(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def RequestedRangeNotSatisfiable(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def ServiceUnavailable(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def TooManyRequests(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def Unauthorized(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def UnprocessableEntity(cause: Exception): Output[Nothing]
- Definition Classes
- Outputs
- def beGreaterThan[A](n: A)(implicit ev: Numeric[A]): ValidationRule[A]
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
.- Definition Classes
- ValidationRules
- def beLessThan[A](n: A)(implicit ev: Numeric[A]): ValidationRule[A]
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
.- Definition Classes
- ValidationRules
- def beLongerThan(n: Int): ValidationRule[String]
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.- Definition Classes
- ValidationRules
- def beShorterThan(n: Int): ValidationRule[String]
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.- Definition Classes
- ValidationRules
- object Accept
- object Application
- object Audio
- object Bootstrap extends Bootstrap[Id, HNil, HNil]
- object Compile
- object Decode
- object DecodeEntity extends HighPriorityDecode
- object DecodePath
- object DecodeStream
- object Encode extends HighPriorityEncodeInstances
- object EncodeStream
- object Endpoint
Provides extension methods for Endpoint to support coproduct and path syntax.
- object EndpointModule
- object EndpointResult
- object Error extends Serializable
- object Image
- object Input extends Serializable
Creates an input for Endpoint from Request.
- object Output
- object ServerSentEvent extends Serializable
- object Text
- object ToResponse extends ToResponseInstances
- object Trace
- object ValidationRule
Allows the creation of reusable validation rules for Endpoints.
- object catsEffect extends EndpointModule[IO]
- object items