finch

Type Members

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

2. 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://tools.ietf.org/html/rfc7231#section-6.5.13

   https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

   https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html

   https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

3. 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( ... )

4. trait Decode[A] extends AnyRef

   

   Decodes an HTTP payload represented as Buf (encoded with Charset) into an arbitrary type A.

5. trait DecodeEntity[A] extends AnyRef

   

   Decodes an HTTP entity (eg: header, query-string param) represented as UTF-8 String into an arbitrary type A.

6. trait DecodePath[A] extends AnyRef

   

   Decodes an HTTP path (eg: /foo/bar/baz) represented as UTF-8 String into an arbitrary type A.

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

8. trait Encode[A] extends AnyRef

   

   Encodes an HTTP payload (represented as an arbitrary type A) with a given Charset.

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

10. 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 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 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)) }

    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)

11. 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")
    }

12. 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)

13. 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 or shouldNot combinators

14. case class Errors(errors: NonEmptyList[Error]) extends Exception with NoStackTrace with Product with Serializable

    

    Multiple errors from an Endpoint.

    Multiple errors from an Endpoint.

    This type of error indicates that an endpoint is able to accumulate multiple Errors into a single instance of Errors that embeds a non-empty list.

    Error accumulation happens as part of the .product (or adjoin, ::) combinator.

15. trait HighPriorityDecode extends LowPriorityDecode

    

16. trait HighPriorityEncodeInstances extends LowPriorityEncodeInstances

    

17. 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 as Seq[String]) needed for matching (e.g., path)

18. trait LiftReader[S[_[_], _], F[_]] extends AnyRef

    

    Create stream S[F, A] from Reader.

19. trait LowPriorityDecode extends AnyRef

    

20. trait LowPriorityEncodeInstances extends AnyRef

    

21. sealed trait Output[+A] extends AnyRef

    

    An output of Endpoint.

22. trait Outputs extends AnyRef

    

23. case class ServerSentEvent[A](data: A, id: Option[String] = None, event: Option[String] = None, retry: Option[Long] = None) extends Product with Serializable

    

24. type ToAsync[F[_], E[_]] = finch.internal.ToAsync[F, E]

    

25. trait ToResponse[F[_], A] extends AnyRef

    

    Represents a conversion from A to Response.

26. trait ToResponseInstances extends AnyRef

    

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

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

29. 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 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").validate(beLongerThan(3)) ::
      param("age").as[Int].should(beGreaterThan(0) and beLessThan(120))
    ).as[User]

30. trait ValidationRules extends AnyRef