package http
- Alphabetic
- By Inheritance
- http
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Package Members
Type Members
- sealed abstract class Chunk extends AnyRef
Represents a piece of an HTTP stream, commonly referred to as a chunk.
Represents a piece of an HTTP stream, commonly referred to as a chunk.
HTTP semantics treat trailing headers as the end of stream signal hence no writes (neither trailers nor data) are allowed after them, only
close(EOS) is valid. This is typically enforced by an HTTP dispatcher in both clients and servers.Similarly, when consumed via com.twitter.io.Reader, trailers are always followed by
None, readers's EOS. Users MUST read until the end of stream to ensure resource hygiene.The following example demonstrates one way of doing so: wiring in one extra read before returning from a read-loop:
def accumulate(r: Reader[Chunk]): Future[(Buf, Option[HeaderMap])] = { def loop(acc: Buf, trailers: Option[HeaderMap]): Future[(Buf, Option[HeaderMap])] = r.read().flatMap { case Some(chunk) => if (chunk.isLast && !chunk.trailers.isEmpty) loop(acc.concat(chunk.content), Some(chunk.trailers)) else loop(acc.concat(chunk.content), None) case None => Future.value(acc -> trailers) } loop(Buf.Empty, None) }
The HTTP dispatcher guarantees that
Chunk.Lastwill be issued in the inbound stream no matter if itstrailersorcontentpresent.Note: when consuming interleaved HTTP streams (i.e., via
Reader.flatMap) it's expected to observe multiple trailers before reaching the EOS. These inter-stream trailers space out individual HTTP streams from child readers. - final class Cookie extends AnyRef
- Note
domainandpathmay be null.
- class CookieMap extends CookieMapVersionSpecific
Adapt cookies of a Message to a mutable Map where cookies are indexed by their name.
Adapt cookies of a Message to a mutable Map where cookies are indexed by their name. Requests use the Cookie header and Responses use the Set-Cookie header. If a cookie is added to the CookieMap, a header is automatically added to the Message. You can add the same cookie more than once. Use getAll to retrieve all of them, otherwise only the first one is returned. If a cookie is removed from the CookieMap, a header is automatically removed from the message
- abstract class CookieMapVersionSpecific extends Map[String, Cookie]
- Attributes
- protected
- final case class FileElement(name: String, content: Buf, contentType: Option[String] = None, filename: Option[String] = None, isText: Boolean = false) extends FormElement with Product with Serializable
- sealed abstract class FormElement extends AnyRef
- abstract class HeaderMap extends HeaderMapVersionSpecific with Map[String, String]
Mutable message headers map.
- abstract class HeaderMapVersionSpecific extends AnyRef
- Attributes
- protected
- trait HttpMuxHandler extends Service[Request, Response]
Trait HttpMuxHandler is used for service-loading HTTP handlers.
- 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.
- final class InvalidUriException extends ChannelException with FailureFlags[InvalidUriException] with HasLogLevel
- class MapParamMap extends ParamMap
Map-backed ParamMap.
- abstract class Message extends AnyRef
Rich Message
Rich Message
Base class for Request and Response. There are both input and output methods, though only one set of methods should be used.
- final class Method extends AnyRef
Represents the HTTP method.
Represents the HTTP method.
The method is a case-sensitive string defined as part of the request line of the HTTP protocol.
- See also
https://tools.ietf.org/html/rfc7230#section-3.1.1
- class MethodBuilder extends BaseMethodBuilder[MethodBuilder]
MethodBuilderis a collection of APIs for client configuration at a higher level than the Finagle 6 APIs while improving upon the deprecated ClientBuilder.MethodBuilderis a collection of APIs for client configuration at a higher level than the Finagle 6 APIs while improving upon the deprecated ClientBuilder.MethodBuilderprovides:- 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/:idas well asPOST statuses/update, whilst each having wildly different characteristics. TheGETis idempotent and has a tight latency distribution while thePOSTis not idempotent and has a wide latency distribution. If users want different configurations, withoutMethodBuilderthey 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.DurationOps._ 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.DurationOps._ 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.DEBUGlevel. Further details, including the request and response, are available atTRACElevel.- See also
com.twitter.finagle.Http.Client.methodBuilder to construct instances.
The user guide.
- abstract class ParamMap extends ParamMapVersionSpecific
Request parameter map.
Request parameter map.
This is a persistent (immutable) multi-map.
Use
getAll()to get all values for a key. - abstract class ParamMapVersionSpecific extends Map[String, String]
- Attributes
- protected
- case class ProxyCredentials(username: String, password: String) extends Product with Serializable
- abstract class Request extends Message
Rich HttpRequest.
Rich HttpRequest.
Use RequestProxy to create an even richer subclass.
- class RequestBuilder[HasUrl, HasForm] extends AnyRef
- class RequestParamMap extends ParamMap
Http Request-backed ParamMap. This ParamMap contains both parameters provided as part of the request URI and parameters provided as part of the request body.
- Note
Request body parameters are considered if the following criteria are true:
- The request is not a TRACE request. 2. The request media type is 'application/x-www-form-urlencoded' 3. The content length is greater than 0.
- abstract class RequestProxy extends Proxy
Proxy for Request.
Proxy for Request. This can be used to create a richer request class.
- abstract class Response extends Message
Rich HttpResponse
- abstract class ResponseProxy extends Proxy
Proxy for Response.
Proxy for Response. This can be used to create a richer response class.
- 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.
- 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.
- final case class SimpleElement(name: String, content: String) extends FormElement with Product with Serializable
- case class Status(code: Int) extends Product with Serializable
Represents an HTTP status code.
Represents an HTTP status code.
The set of commonly known HTTP status codes have an associated reason phrase (see
reasons). We don't provide a way to set the reason phrase because:- it simplifies construction (users only supply the code) - it avoids the need to validate user-defined reason phrases - it omits the possibility of statuses with duplicate reason phrases
The only downside is that we lose the ability to create custom statuses with "vanity" reason phrases, but this should be tolerable.
- class TlsFilter extends SimpleFilter[Request, Response]
Adds the host headers to for TLS-enabled requests.
- final class TooLongMessageException extends ChannelException with FailureFlags[TooLongMessageException]
The Message was too long to be handled correctly
- final class Uri extends AnyRef
Represents an immutable URI.
- final case class Version extends Product with Serializable
Represents the HTTP version.
Value Members
- object AuthenticatedIdentityContext
- object Chunk
- object Cookie
- object EmptyParamMap extends ParamMap
Empty ParamMap
- object Fields
- object HeaderMap
- object HttpMuxer extends HttpMuxer
Singleton default multiplex service.
Singleton default multiplex service.
- See also
HttpMuxers for Java compatibility APIs.
- object HttpMuxers
Java compatibility APIs for HttpMuxer.
- object HttpTracing
- object KerberosAuthenticationFilter
Apply kerberos authentication to http requests.
- object LoadBalancedHostFilter
Adds host header to load balanced requests.
Adds host header to load balanced requests.
Overriding the TlsFilter host header setting with this module:
import com.twitter.finagle.Http import com.twitter.finagle.loadbalancer.LoadBalancerFactory Http.client.withStack(Http.client.stack.remove(TlsFilter.role) .insertAfter(LoadBalancerFactory.role, LoadBalancedHostFilter.module))
- Note
If Transporter.EndpointAddr was not created via java.net.InetSocketAddress.createUnresolved, the filter will make an asynchronous network call to determine the hostname.
,Since this stack module expects a Transporter.EndpointAddr to be set, it only makes sense to configure it below a module that sets the Transporter.EndpointAddr (typically via com.twitter.finagle.loadbalancer.LoadBalancerFactory).
- See also
com.twitter.finagle.loadbalancer.LoadBalancerFactory for details on how Transporter.EndpointAddr is selected
Example: - object MapParamMap
- object MediaType
- object Message
- object Method
- object MethodBuilder
- object ParamMap
- object ProxyCredentials extends Serializable
- object Request
- object RequestBuilder
Factory for com.twitter.finagle.http.RequestBuilder instances
- object Response
- object SpnegoAuthenticator
A SPNEGO HTTP authenticator as defined in https://tools.ietf.org/html/rfc4559, which gets its credentials from a provided CredentialSource...
A SPNEGO HTTP authenticator as defined in https://tools.ietf.org/html/rfc4559, which gets its credentials from a provided CredentialSource... usually JAAS.
- object Status extends Serializable
- object TlsFilter
- object TooLongMessageException extends Serializable
- object Uri
- object Version extends Serializable
- object defaultClientProtocol extends GlobalFlag[Protocol]
GlobalFlag that can be used to configure the default protocol used when creating a new com.twitter.finagle.Http.Client.
- object defaultServerProtocol extends GlobalFlag[Protocol]
GlobalFlag that can be used to configure the default protocol used when creating a new com.twitter.finagle.Http.Server.
- object serverErrorsAsFailures extends GlobalFlag[Boolean]