o

org.http4s.server.middleware

BracketRequestResponse

object BracketRequestResponse

Middlewares which allow for bracketing on a Request/Response, including the completion of the Response body stream.

These are analogous to cats.effect.Bracket and fs2.Stream.bracket. The reason that they exist is because due to the full termination of a Response being a function of the termination of the fs2.Stream which backs the response body, you can't actually use either cats.effect.Bracket or fs2.Stream.bracket directly.

Source
BracketRequestResponse.scala
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. BracketRequestResponse
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Type Members

  1. type FullContextMiddleware[F[_], A, B] = (Kleisli[[β$0$]OptionT[F, β$0$], ContextRequest[F, A], ContextResponse[F, B]]) => Kleisli[[β$1$]OptionT[F, β$1$], Request[F], Response[F]]

    A Middleware which uses both a ContextRequest and ContextResponse.

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def bracketRequestResponseApp[F[_], A](acquire: F[A])(release: (A) => F[Unit])(implicit F: MonadCancelThrow[F]): (Kleisli[F, ContextRequest[F, A], Response[F]]) => Kleisli[F, Request[F], Response[F]]

    As bracketRequestResponseCaseApp, but release is simplified, ignoring the exit condition.

    As bracketRequestResponseCaseApp, but release is simplified, ignoring the exit condition.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

  6. def bracketRequestResponseAppR[F[_], A](resource: Resource[F, A])(implicit F: MonadCancelThrow[F]): (Kleisli[F, ContextRequest[F, A], Response[F]]) => Kleisli[F, Request[F], Response[F]]

    As bracketRequestResponseApp, but acquire and release are defined in terms of a cats.effect.Resource.

    As bracketRequestResponseApp, but acquire and release are defined in terms of a cats.effect.Resource.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

  7. def bracketRequestResponseCaseApp[F[_], A](acquire: F[A])(release: (A, Outcome[F, Throwable, Unit]) => F[Unit])(implicit F: MonadCancelThrow[F]): (Kleisli[F, ContextRequest[F, A], Response[F]]) => Kleisli[F, Request[F], Response[F]]

    As bracketRequestResponseCaseRoutes but defined for HttpApp, rather than HttpRoutes.

    As bracketRequestResponseCaseRoutes but defined for HttpApp, rather than HttpRoutes.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

  8. def bracketRequestResponseCaseRoutes[F[_], A](acquire: F[A])(release: (A, Outcome[F, Throwable, Unit]) => F[Unit])(implicit F: MonadCancelThrow[F]): ContextMiddleware[F, A]

    Bracket on the start of a request and the completion of processing the response body Stream.

    Bracket on the start of a request and the completion of processing the response body Stream.

    acquire

    Effect to run each time a request is received. The result of it is put into a ContextRequest and passed to the underlying routes.

    release

    Effect to run at the termination of each response body, or on any error after acquire has run. Will always be called exactly once if acquire is invoked, for each request/response.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

    ,

    A careful reader might be wondering where the analogous use parameter from cats.effect.Bracket has gone. The use of the acquired resource is running the request, thus the use function is actually just the normal context route function from http4s Kleisli[OptionT[F, *], ContextRequest[F, A], Response[F]].

  9. def bracketRequestResponseCaseRoutes_[F[_], A, B](acquire: (Request[F]) => F[ContextRequest[F, A]])(release: (A, Option[B], Outcome[F, Throwable, Unit]) => F[Unit])(implicit F: MonadCancelThrow[F]): FullContextMiddleware[F, A, B]

    Bracket on the start of a request and the completion of processing the response body Stream.

    Bracket on the start of a request and the completion of processing the response body Stream.

    This middleware uses a context on both the Request and Response. This is the most general possible encoding for bracketing on a Request/Response interaction. It is required to express certain types of bracketing use cases (see Metrics), but for most cases it is more general than is needed. Before attempting to use this middleware, you should consider if bracketRequestResponseRoutes or bracketRequestResponseCaseRoutes will work for your use case.

    acquire

    Function of the Request to a F[ContextRequest] to run each time a new Request is received.

    release

    Function to run on the termination of a Request/Response interaction, in all cases. The first argument is the request context, which is guaranteed to exist if acquire succeeds. The second argument is the response context, which will only exist if the generation of the ContextResponse is successful. The third argument is the exit condition, either completed, canceled, or error.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

    ,

    For some use cases, you might want to differentiate between each of the three exit branches where release may be invoked. The three exit branches are, running a Request and receiving OptionT.none[F, Response[F]], running a Request and encountering an error or cancellation before the Response is generated, or at the full consumption of the Response body stream (regardless of the ExitCase). One may determine the in which branch release is being invoked by inspecting the ExitCase and the Option[B] response context. If the response context is defined, e.g. Some(_: B), then you can be certain that the release function was executed at the termination of the body stream. This is because the response context is only (and always) present if the Response value was generated successfully (whether or not the body stream fails). If the ExitCase is Completed and the response context is None, then that means that the underlying HttpRoutes did not yield a Response, e.g. we got OptionT.none: OptionT[F, Response[F]]. Otherwise, if the ExitCase is either Error(_: Throwable) or Canceled, and the response context is None, then release is executed in response to an error or cancellation during the generation of the Response value proper, e.g. when running the underlying HttpRoutes.

    ,

    A careful reader might be wondering where the analogous use parameter from cats.effect.Bracket has gone. The use of the acquired resource is running the request, thus the use function is actually just the normal context route function from http4s Kleisli[OptionT[F, *], ContextRequest[F, A], Response[F]].

  10. def bracketRequestResponseRoutes[F[_], A](acquire: F[A])(release: (A) => F[Unit])(implicit F: MonadCancelThrow[F]): ContextMiddleware[F, A]

    As bracketRequestResponseCaseRoutes, but release is simplified, ignoring the exit condition.

    As bracketRequestResponseCaseRoutes, but release is simplified, ignoring the exit condition.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

  11. def bracketRequestResponseRoutesR[F[_], A](resource: Resource[F, A])(implicit F: MonadCancelThrow[F]): ContextMiddleware[F, A]

    As bracketRequestResponseRoutes, but acquire and release are defined in terms of a cats.effect.Resource.

    As bracketRequestResponseRoutes, but acquire and release are defined in terms of a cats.effect.Resource.

    Note

    The bracketing semantics defined here differ in one very important way from cats-effect or fs2 bracketing semantics. If the Response body is not evaluated after the application of the middleware, then the release handler will not run, effectively creating a resource leak. This can happen due to a bug in a server implementation, where it fails to drain the body, or due to a user code if the Response body stream (or the Response itself) is discarded after the application of this middleware. Unfortunately, there is currently no way to avoid this. For this reason, it is strongly recommended that this middleware be applied at the most outer scope possible. Appending to or transforming the Response body is safe to do after the application of this middleware.

  12. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  13. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  14. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  15. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  16. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  18. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  19. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  20. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  21. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  22. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  23. def toString(): String
    Definition Classes
    AnyRef → Any
  24. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  25. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  26. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()

Deprecated Value Members

  1. def exitCaseToOutcome[F[_]](ec: ExitCase)(implicit F: Applicative[F]): Outcome[F, Throwable, Unit]
    Annotations
    @deprecated
    Deprecated

    (Since version 0.23.8) Use ExitCase.toOutcome instead

Inherited from AnyRef

Inherited from Any

Ungrouped