package finagle

Finagle is an extensible RPC system.

Services are represented by class Service. Clients make use of Service objects while servers implement them.

Finagle contains a number of protocol implementations; each of these implement Client and/or Server. For example, finagle's HTTP implementation, Http (in package finagle-http), exposes both.

Thus a simple HTTP server is built like this:

import com.twitter.finagle.{Http, Service}
import org.jboss.netty.handler.codec.http.{
  HttpRequest, HttpResponse, DefaultHttpResponse}
import org.jboss.netty.handler.codec.http.HttpVersion._
import org.jboss.netty.handler.codec.http.HttpResponseStatus._
import com.twitter.util.{Future, Await}

val service = new Service[HttpRequest, HttpResponse] {
  def apply(req: HttpRequest) =
    Future.value(new DefaultHttpResponse(HTTP_1_1, OK))
val server = Http.serve(":8080", service)

We first define a service to which requests are dispatched. In this case, the service returns immediately with a HTTP 200 OK response, and with no content.

This service is then served via the Http protocol on TCP port 8080. Finally we wait for the server to stop serving.

We can now query our web server:

% curl -D - localhost:8080
HTTP/1.1 200 OK


Building an HTTP client is also simple. (Note that type annotations are added for illustration.)

import com.twitter.finagle.{Http, Service}
import org.jboss.netty.handler.codec.http.{
  HttpRequest, HttpResponse, DefaultHttpRequest}
import org.jboss.netty.handler.codec.http.HttpVersion._
import org.jboss.netty.handler.codec.http.HttpMethod._
import com.twitter.util.{Future, Await, Future, Return, Throw}

val client: Service[HttpRequest, HttpResponse] =
val f: Future[HttpResponse] =
  client(new DefaultHttpRequest(HTTP_1_1, GET, "/"))
f respond {
  case Return(res) =>
    printf("Got HTTP response %s\n", res)
  case Throw(exc) =>
    printf("Got error %s\n", exc)

Http.newService("localhost:8080") constructs a new Service instance connected to localhost TCP port 8080. We then issue a HTTP/1.1 GET request to URI "/". The service returns a com.twitter.util.Future representing the result of the operation. We listen to this future, printing an appropriate message when the response arrives.

The Finagle homepage contains useful documentation and resources for using Finagle.

Linear Supertypes
AnyRef, Any
  1. Alphabetic
  2. By inheritance
  1. finagle
  2. AnyRef
  3. Any
  1. Hide All
  2. Show all
Learn more about member selection
  1. Public
  2. All

Type Members

  1. abstract class AbstractCodec[Req, Rep] extends Codec[Req, Rep]

    An abstract class version of the above for java compatibility.

  2. sealed trait Addr extends AnyRef

    An address identifies the location of an object--it is a bound name.

  3. trait Announcement extends Closable

  4. trait Announcer extends AnyRef

  5. class AnnouncerForumInvalid extends Exception

  6. class AnnouncerNotFoundException extends Exception

  7. class ApiException extends Exception

  8. class ApplicationException extends Exception

  9. class CancelledConnectionException extends RequestException

  10. class CancelledReadException extends TransportException

  11. class CancelledRequestException extends RequestException

  12. class CancelledWriteException extends TransportException

  13. class ChannelBufferUsageException extends Exception

  14. class ChannelClosedException extends ChannelException with NoStacktrace

  15. class ChannelException extends Exception with SourcedException

  16. case class ChannelWriteException(underlying: Throwable) extends ChannelException with WriteException with NoStacktrace with Product with Serializable

    Default implementation for WriteException that wraps an underlying exception.

  17. trait Client[Req, Rep] extends AnyRef

    RPC clients with Req-typed requests and Rep typed replies.

  18. case class ClientCodecConfig(serviceName: String) extends Product with Serializable


  19. trait ClientConnection extends Closable

    Information about a client, passed to a Service factory for each new connection.

  20. trait Codec[Req, Rep] extends AnyRef

    Superclass for all codecs.

  21. class CodecException extends Exception

  22. trait CodecFactory[Req, Rep] extends AnyRef

    A combined codec factory provides both client and server codec factories in one (when available).

  23. class ConnectionFailedException extends ChannelException with NoStacktrace

  24. case class ConnectionRefusedException(remoteAddress: SocketAddress) extends ChannelException with Product with Serializable

  25. trait ContextHandler extends AnyRef

    A ContextHandler is responsible for maintaining a context.

  26. class FactoryToService[Req, Rep] extends Service[Req, Rep]

  27. case class FailFastException() extends ChannelException with Product with Serializable

  28. class FailedFastException extends RequestException

  29. abstract class Filter[-ReqIn, +RepOut, +ReqOut, -RepIn] extends (ReqIn, Service[ReqOut, RepIn]) ⇒ Future[RepOut]

    A Filter acts as a decorator/transformer of a service.

  30. class GlobalRequestTimeoutException extends RequestTimeoutException

  31. class InconsistentStateException extends ChannelException

  32. class IndividualRequestTimeoutException extends RequestTimeoutException

  33. class InvalidPipelineException extends ApiException

  34. trait ListeningServer extends Closable with Awaitable[Unit] with Group[SocketAddress]

    Trait ListeningServer represents a bound and listening server.

  35. class MultipleAnnouncersPerSchemeException extends Exception with NoStacktrace

  36. class MultipleResolversPerSchemeException extends Exception with NoStacktrace

  37. trait MutableGroup[T] extends Group[T]

  38. trait Name extends AnyRef

    A name identifies an object.

  39. trait NamedGroup extends AnyRef

    A mixin trait to assign a name to the group.

  40. class NoBrokersAvailableException extends RequestException

  41. trait NoStacktrace extends Exception

  42. class NotServableException extends RequestException

  43. class NotShardableException extends NotServableException

  44. class NotYetConnectedException extends ApiException

  45. trait ProxyAnnouncement extends Announcement with Proxy

  46. trait ProxyServiceFactory[-Req, +Rep] extends ServiceFactory[Req, Rep] with Proxy

  47. case class RefusedByRateLimiter() extends ChannelException with Product with Serializable

  48. class ReplyCastException extends RequestException

  49. class RequestException extends Exception with NoStacktrace with SourcedException

    Request failures (eg.

  50. class RequestTimeoutException extends RequestException with TimeoutException

  51. trait Resolver extends AnyRef

    A resolver binds a name, represented by a string, to a variable address.

  52. class ResolverAddressInvalid extends Exception

  53. class ResolverNotFoundException extends Exception

  54. class RetryFailureException extends RequestException

  55. trait Server[Req, Rep] extends AnyRef

    Servers implement RPC servers with Req-typed requests and Rep-typed responses.

  56. case class ServerCodecConfig(serviceName: String, boundAddress: SocketAddress) extends Product with Serializable


  57. abstract class Service[-Req, +Rep] extends (Req) ⇒ Future[Rep] with Closable

    A Service is an asynchronous function from Request to Future[Response].

  58. class ServiceClosedException extends Exception with ServiceException

  59. trait ServiceException extends Exception with SourcedException

  60. abstract class ServiceFactory[-Req, +Rep] extends (ClientConnection) ⇒ Future[Service[Req, Rep]] with Closable

  61. abstract class ServiceFactoryProxy[-Req, +Rep] extends ServiceFactory[Req, Rep] with ProxyServiceFactory[Req, Rep]

    A simple proxy ServiceFactory that forwards all calls to another ServiceFactory.

  62. trait ServiceFactoryWrapper extends AnyRef

    A ServiceFactoryWrapper adds behavior to an underlying ServiceFactory.

  63. class ServiceNotAvailableException extends Exception with ServiceException

  64. abstract class ServiceProxy[-Req, +Rep] extends Service[Req, Rep] with Proxy

    A simple proxy Service that forwards all calls to another Service.

  65. class ServiceTimeoutException extends Exception with WriteException with ServiceException with TimeoutException

    Indicates that the connection was not established within the timeouts.

  66. class ShardNotAvailableException extends NotServableException

  67. abstract class SimpleFilter[Req, Rep] extends Filter[Req, Rep, Req, Rep]

  68. trait SourcedException extends Exception

  69. case class SslHandshakeException(underlying: Throwable, remoteAddress: SocketAddress) extends ChannelException with Product with Serializable

  70. case class SslHostVerificationException(principal: String) extends ChannelException with Product with Serializable

  71. trait TimeoutException extends Exception with SourcedException

  72. class TooManyConcurrentRequestsException extends ApiException

  73. class TooManyWaitersException extends RequestException

  74. class TransportException extends Exception with SourcedException

  75. case class UnknownChannelException(underlying: Throwable, remoteAddress: SocketAddress) extends ChannelException with Product with Serializable

  76. trait WriteException extends Exception with SourcedException

    Marker trait to indicate there was an exception while writing the request.

  77. class WriteTimedOutException extends ChannelException

  78. trait Group[T] extends AnyRef

    A group is a dynamic set of T-typed values.

Value Members

  1. object Addr

  2. object Announcer

  3. object BackupRequestLost extends Exception with NoStacktrace

  4. object ChannelException extends Serializable

  5. object ClientConnection

  6. object Codec

  7. object Context

    A context is a piece of serializable metadata managed by a registered handler.

  8. object Filter

  9. object Group

  10. object InetResolver extends Resolver

  11. object Name

  12. object NamedGroup

  13. object NullServer extends ListeningServer with CloseAwaitably

    An empty ListeningServer that can be used as a placeholder.

  14. object Resolver

  15. object Service

  16. object ServiceFactory

  17. object ServiceFactoryWrapper

  18. object WriteException extends Serializable

  19. package builder

  20. package channel

  21. package client

  22. package core

  23. package dispatch

  24. package factory

  25. package filter

  26. package group

  27. package httpproxy

  28. package loadbalancer

  29. package netty3

    Package netty3 implements the bottom finagle primitives: {{com.

  30. package pool

  31. package server

  32. package service

  33. package socks

  34. package ssl

  35. package stats

  36. package tracing

  37. package transport

  38. package util

Inherited from AnyRef

Inherited from Any