Packages

p

io

finch

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.

Source
package.scala
Linear Supertypes
ValidationRules, Outputs, Endpoints, FileUploadsAndAttributes, Cookies, ParamAndParams, Headers, Paths, Bodies, AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. finch
  2. ValidationRules
  3. Outputs
  4. Endpoints
  5. FileUploadsAndAttributes
  6. Cookies
  7. ParamAndParams
  8. Headers
  9. Paths
  10. Bodies
  11. AnyRef
  12. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

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[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)

    - negotiateContentType (default: false): whether or not to enable server-driven content type negotiation (see RFC2616, section 12.1)

    - enableMethodNotAllowed (default: false): whether or not to enable 405 MethodNotAllowed HTTP response (see RFC2616, section 10.4.6)

    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

  3. trait Decode[A] extends AnyRef

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

  4. trait DecodeEntity[A] extends AnyRef

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

  5. trait DecodePath[A] extends AnyRef

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

  6. trait Encode[A] extends AnyRef

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

  7. trait Endpoint[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 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" :: 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)
  8. sealed abstract class EndpointResult[+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)

    API methods exposed on this type are mostly introduced for testing.

    This class also provides various of awaitX methods useful for testing and experimenting.

  9. trait Endpoints extends Bodies with Paths with Headers with ParamAndParams with Cookies with FileUploadsAndAttributes

    A collection of Endpoint combinators.

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

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

  12. trait HighPriorityDecode extends LowPriorityDecode
  13. trait HighPriorityEncodeInstances extends LowPriorityEncodeInstances
  14. trait HighPriorityToResponseInstances extends LowPriorityToResponseInstances
  15. final case class Input(request: Request, route: Seq[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)

  16. trait IterateeInstances extends LowPriorityInstances
  17. trait LowPriorityDecode extends AnyRef
  18. trait LowPriorityEncodeInstances extends AnyRef
  19. trait LowPriorityInstances extends FutureModule
  20. trait LowPriorityToResponseInstances extends AnyRef
  21. sealed trait Output[+A] extends AnyRef

    An output of Endpoint.

  22. trait Outputs extends AnyRef
  23. trait ToResponse[A] extends AnyRef

    Represents a conversion from A to Response.

  24. trait ToService[ES <: HList, CTS <: HList] extends AnyRef

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

  26. 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]
  27. trait ValidationRules extends AnyRef

Value Members

  1. def Accepted[A]: Output[A]
    Definition Classes
    Outputs
  2. def BadGateway(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  3. def BadRequest(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  4. def Conflict(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  5. def Created[A](a: A): Output[A]
    Definition Classes
    Outputs
  6. def EnhanceYourCalm(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  7. def Forbidden(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  8. def GatewayTimeout(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  9. def Gone(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  10. def InsufficientStorage(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  11. def InternalServerError(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  12. def LengthRequired(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  13. def MethodNotAllowed(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  14. def NoContent[A]: Output[A]
    Definition Classes
    Outputs
  15. def NotAcceptable(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  16. def NotFound(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  17. def NotImplemented(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  18. def Ok[A](a: A): Output[A]
    Definition Classes
    Outputs
  19. def PaymentRequired(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  20. def PreconditionFailed(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  21. def RequestEntityTooLarge(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  22. def RequestTimeout(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  23. def RequestedRangeNotSatisfiable(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  24. def ServiceUnavailable(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  25. def TooManyRequests(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  26. def Unauthorized(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  27. def UnprocessableEntity(cause: Exception): Output[Nothing]
    Definition Classes
    Outputs
  28. val asyncBody: Endpoint[AsyncStream[Buf]]

    An evaluating Endpoint that reads a required chunked streaming binary body, interpreted as an AsyncStream[Buf].

    An evaluating Endpoint that reads a required chunked streaming binary body, interpreted as an AsyncStream[Buf]. The returned Endpoint only matches chunked (streamed) requests.

    Definition Classes
    Bodies
  29. 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
  30. 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
  31. 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
  32. 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
  33. val binaryBody: Endpoint[Array[Byte]]

    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.

    Definition Classes
    Bodies
  34. val binaryBodyOption: Endpoint[Option[Array[Byte]]]

    An evaluating Endpoint that reads a binary request body, interpreted as a Array[Byte], into an Option.

    An evaluating Endpoint that reads a binary request body, interpreted as a Array[Byte], into an Option. The returned Endpoint only matches non-chunked (non-streamed) requests.

    Definition Classes
    Bodies
  35. def body[A, CT](implicit d: Dispatchable[A, CT], ct: ClassTag[A]): Endpoint[A]

    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.

    Definition Classes
    Bodies
  36. def bodyOption[A, CT](implicit d: Dispatchable[A, CT], ct: ClassTag[A]): Endpoint[Option[A]]

    An Endpoint that reads an optional request body represented as CT (ContentType) and interpreted as A, into an Option.

    An Endpoint that reads an optional request body represented as CT (ContentType) and interpreted as A, into an Option. The returned Endpoint only matches non-chunked (non-streamed) requests.

    Definition Classes
    Bodies
  37. implicit def booleanToPath(b: Boolean): Endpoint[HNil]
    Definition Classes
    Paths
  38. def cookie(name: String): Endpoint[Cookie]

    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.

    Definition Classes
    Cookies
  39. def cookieOption(name: String): Endpoint[Option[Cookie]]

    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.

    Definition Classes
    Cookies
  40. def header[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[A]

    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.

    Definition Classes
    Headers
  41. def headerOption[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[Option[A]]

    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.

    Definition Classes
    Headers
  42. implicit def intToPath(i: Int): Endpoint[HNil]
    Definition Classes
    Paths
  43. def jsonBody[A](implicit arg0: Json[A], arg1: ClassTag[A]): Endpoint[A]

    Alias for body[A, Application.Json].

    Alias for body[A, Application.Json].

    Definition Classes
    Bodies
  44. def jsonBodyOption[A](implicit arg0: Json[A], arg1: ClassTag[A]): Endpoint[Option[A]]

    Alias for bodyOption[A, Application.Json].

    Alias for bodyOption[A, Application.Json].

    Definition Classes
    Bodies
  45. def multipartAttribute[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[A]

    An evaluating Endpoint that reads a required attribute from a multipart/form-data request.

    An evaluating Endpoint that reads a required attribute from a multipart/form-data request.

    Definition Classes
    FileUploadsAndAttributes
  46. def multipartAttributeOption[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[Option[A]]

    An evaluating Endpoint that reads an optional attribute from a multipart/form-data request.

    An evaluating Endpoint that reads an optional attribute from a multipart/form-data request.

    Definition Classes
    FileUploadsAndAttributes
  47. def multipartAttributes[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[Seq[A]]

    An evaluating Endpoint that reads a required attribute from a multipart/form-data request.

    An evaluating Endpoint that reads a required attribute from a multipart/form-data request.

    Definition Classes
    FileUploadsAndAttributes
  48. def multipartAttributesNel[A](name: String)(implicit d: DecodeEntity[A], t: ClassTag[A]): Endpoint[NonEmptyList[A]]

    An evaluating Endpoint that reads a required attribute from a multipart/form-data request.

    An evaluating Endpoint that reads a required attribute from a multipart/form-data request.

    Definition Classes
    FileUploadsAndAttributes
  49. def multipartFileUpload(name: String): Endpoint[FileUpload]

    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.

    Definition Classes
    FileUploadsAndAttributes
  50. def multipartFileUploadOption(name: String): Endpoint[Option[FileUpload]]

    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.

    Definition Classes
    FileUploadsAndAttributes
  51. def multipartFileUploads(name: String): Endpoint[Seq[FileUpload]]

    An evaluating Endpoint that optionally reads multiple file uploads from a multipart/form-data request.

    An evaluating Endpoint that optionally reads multiple file uploads from a multipart/form-data request.

    Definition Classes
    FileUploadsAndAttributes
  52. def multipartFileUploadsNel(name: String): Endpoint[NonEmptyList[FileUpload]]

    An evaluating Endpoint that requires multiple file uploads from a multipart/form-data request.

    An evaluating Endpoint that requires multiple file uploads from a multipart/form-data request.

    Definition Classes
    FileUploadsAndAttributes
  53. def param[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[A]

    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.

    Definition Classes
    ParamAndParams
  54. def paramOption[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[Option[A]]

    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.

    Definition Classes
    ParamAndParams
  55. def params[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[Seq[A]]

    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.

    Definition Classes
    ParamAndParams
  56. def paramsNel[A](name: String)(implicit d: DecodeEntity[A], tag: ClassTag[A]): Endpoint[NonEmptyList[A]]

    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.

    Definition Classes
    ParamAndParams
  57. def path(s: String): Endpoint[HNil]

    An Endpoint that matches a given string.

    An Endpoint that matches a given string.

    Definition Classes
    Paths
  58. def path[A](implicit arg0: DecodePath[A], arg1: ClassTag[A]): Endpoint[A]

    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.

    Definition Classes
    Paths
  59. def paths[A](implicit arg0: DecodePath[A], arg1: ClassTag[A]): Endpoint[Seq[A]]

    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.

    Definition Classes
    Paths
  60. val stringBody: Endpoint[String]

    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.

    Definition Classes
    Bodies
  61. val stringBodyOption: Endpoint[Option[String]]

    An evaluating Endpoint that reads an optional request body, interpreted as a String, into an Option.

    An evaluating Endpoint that reads an optional request body, interpreted as a String, into an Option. The returned Endpoint only matches non-chunked (non-streamed) requests.

    Definition Classes
    Bodies
  62. implicit def stringToPath(s: String): Endpoint[HNil]
    Definition Classes
    Paths
  63. def textBody[A](implicit arg0: finch.Decode.Text[A], arg1: ClassTag[A]): Endpoint[A]

    Alias for body[A, Text.Plain]

    Alias for body[A, Text.Plain]

    Definition Classes
    Bodies
  64. def textBodyOption[A](implicit arg0: finch.Decode.Text[A], arg1: ClassTag[A]): Endpoint[Option[A]]

    Alias for bodyOption[A, Text.Plain]

    Alias for bodyOption[A, Text.Plain]

    Definition Classes
    Bodies
  65. object Accept
  66. object Application

    See also

    https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types

  67. object Audio

    See also

    https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types

  68. object Bootstrap extends Bootstrap[HNil, HNil]
  69. object Decode
  70. object DecodeEntity extends HighPriorityDecode
  71. object DecodePath
  72. object Encode extends HighPriorityEncodeInstances
  73. object Endpoint

    Provides extension methods for Endpoint to support coproduct and path syntax.

  74. object EndpointResult
  75. object * extends Endpoint[HNil]

    An Endpoint that skips all path segments.

    An Endpoint that skips all path segments.

    Definition Classes
    Endpoints
  76. object / extends Endpoint[HNil]

    An identity Endpoint.

    An identity Endpoint.

    Definition Classes
    Endpoints
  77. object root extends Endpoint[Request]

    A root Endpoint that always matches and extracts the current request.

    A root Endpoint that always matches and extracts the current request.

    Definition Classes
    Endpoints
  78. object Error extends Serializable
  79. object Image

    See also

    https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types

  80. object Input extends Serializable

    Creates an input for Endpoint from Request.

  81. object Output
  82. object Text

    See also

    https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types

  83. object ToResponse extends HighPriorityToResponseInstances
  84. object ToService
  85. object Trace
  86. object ValidationRule

    Allows the creation of reusable validation rules for Endpoints.

  87. object items

Inherited from ValidationRules

Inherited from Outputs

Inherited from Endpoints

Inherited from FileUploadsAndAttributes

Inherited from Cookies

Inherited from ParamAndParams

Inherited from Headers

Inherited from Paths

Inherited from Bodies

Inherited from AnyRef

Inherited from Any

Ungrouped