http

Type Members

1. trait HttpMuxHandler extends Service[Request, Response]

   

   Trait HttpMuxHandler is used for service-loading HTTP handlers.

2. class HttpMuxer extends Service[Request, Response]

   

   A service that dispatches incoming requests to registered handlers.

   A service that dispatches incoming requests to registered handlers. In order to choose which handler to dispatch the request to, we take the path of the request and match it with the patterns of the pre-registered handlers. The pattern matching follows these rules:

   • Patterns ending with "/" use exclusive prefix matching. Eg: the pattern "foo/bar/" matches these paths: "foo/bar/", "foo/bar/baz", etc but NOT "foo/bar" Similarly, the pattern "/" matches all paths
   • Patterns not ending with "/" use exact matching. Eg: the pattern "foo/bar" ONLY matches this path: "foo/bar"
   • Special case: The pattern "" matches only "/" and ""

   NOTE: When multiple pattern matches exist, the longest pattern wins.

3. class MethodBuilder extends MethodBuilderScaladoc[MethodBuilder]

   

   MethodBuilder is a collection of APIs for client configuration at a higher level than the Finagle 6 APIs while improving upon the deprecated ClientBuilder.

   MethodBuilder is a collection of APIs for client configuration at a higher level than the Finagle 6 APIs while improving upon the deprecated ClientBuilder. MethodBuilder provides:

   • Logical success rate metrics.
   • Retries based on application-level requests and responses (e.g. an HTTP 503 response code).
   • Configuration of per-attempt and total timeouts.

   All of these can be customized per method (or endpoint) while sharing a single underlying Finagle client. Concretely, a single service might offer both GET statuses/show/:id as well as POST statuses/update, whilst each having wildly different characteristics. The GET is idempotent and has a tight latency distribution while the POST is not idempotent and has a wide latency distribution. If users want different configurations, without MethodBuilder they must create separate Finagle clients for each grouping. While long-lived clients in Finagle are not expensive, they are not free. They create duplicate metrics and waste heap, file descriptors, and CPU.

   Example

   A client that has timeouts and retries on a 418 status code.

   import com.twitter.conversions.time._
   import com.twitter.finagle.Http
   import com.twitter.finagle.service.{ReqRep, ResponseClass}
   import com.twitter.util.Return
   
   val client: Http.Client = ???
   client.methodBuilder("inet!example.com:80")
     .withTimeoutPerRequest(50.milliseconds)
     .withTimeoutTotal(100.milliseconds)
     .withRetryForClassifier {
       case ReqRep(_, Return(rep)) if rep.statusCode == 418 => ResponseClass.RetryableFailure
     }
     .newService("an_endpoint_name")

   Timeouts

   Defaults to using the StackClient's configuration.

   An example of setting a per-request timeout of 50 milliseconds and a total timeout of 100 milliseconds:

   import com.twitter.conversions.time._
   import com.twitter.finagle.Http
   import com.twitter.finagle.http.MethodBuilder
   
   val builder: MethodBuilder = ???
   builder
     .withTimeoutPerRequest(50.milliseconds)
     .withTimeoutTotal(100.milliseconds)

   Retries

   Retries are intended to help clients improve success rate by trying failed requests additional times. Care must be taken by developers to only retry when it is known to be safe to issue the request multiple times. This is because the client cannot always be sure what the backend service has done. An example of a request that is safe to retry would be a read-only request.

   Defaults to using the client's ResponseClassifier to retry failures marked as retryable. See withRetryForClassifier for details.

   A com.twitter.finagle.service.RetryBudget is used to prevent retries from overwhelming the backend service. The budget is shared across clients created from an initial MethodBuilder. As such, even if the retry rules deem the request retryable, it may not be retried if there is insufficient budget.

   Finagle will automatically retry failures that are known to be safe to retry via com.twitter.finagle.service.RequeueFilter. This includes WriteExceptions and retryable nacks. As these should have already been retried, we avoid retrying them again by ignoring them at this layer.

   Additional information regarding retries can be found in the user guide.

   The classifier is also used to determine the logical success metrics of the method. Logical here means after any retries are run. For example should a request result in retryable failure on the first attempt, but succeed upon retry, this is exposed through metrics as a success. Logical success rate metrics are scoped to "clnt/your_client_label/method_name/logical" and get "success" and "requests" counters along with a "request_latency_ms" stat.

   Unsuccessful requests are logged at com.twitter.logging.Level.DEBUG level. Further details, including the request and response, are available at TRACE level.

   See also

   The user guide.

   com.twitter.finagle.Http.Client.methodBuilder to construct instances.

4. class RequestBuilder[HasUrl, HasForm] extends AnyRef

   

5. case class Route(pattern: String, handler: Service[Request, Response], index: Option[RouteIndex] = None) extends Product with Serializable

   

   Represents an element which can be routed to via the HttpMuxer.

   Represents an element which can be routed to via the HttpMuxer.

   pattern

   The pattern the handler is bound to. This is also often used as the path to access the route, but if something more detailed is required, the RouteIndex.path parameter can be used.

   handler

   The service which requests are routed to.

   index

   Optionally contains information for the route UI.

6. case class RouteIndex(alias: String, group: String, path: Option[String] = None, method: Method = Get) extends Product with Serializable

   

   Contains the route UI information.

   Contains the route UI information.

   alias

   A short name used to identify the route when listed in index.

   group

   A grouping used to organize the route in the index. Routes with the same grouping are displayed together.

   path

   The path used to access the route. A request is routed to the path as per the com.twitter.finagle.http.HttpMuxer spec. The path only needs to be specified if the URL accessed in the admin interface is different from the pattern provided in Route.pattern.

   method

   Specifies which HTTP Method to use from com.twitter.finagle.http.Method. The default is Method.Get. Only Method.Get and Method.Post are supported.

7. class TlsFilter extends SimpleFilter[Request, Response]

   

   Adds the host headers to for TLS-enabled requests.