Finagle 6.26.0

Deprecations

• finagle-memcached: Deprecated in favor of finagle-memcachedx and now removed.

New Features

• finagle-httpx: Support nacks between Finagle Http clients and servers. When a server fails
  with retryable exceptions (exceptions wrapped by Failure.rejected), it sends back a "Nack"
  response, i.e. 503 Response code with a new "finagle-http-nack" header. This allows clients
  to safely retry failed requests, and keep connections open. RB_ID=670046

Breaking API Changes

• finagle-core: Moved netty3 specific things into a netty3 namespace. For
  these symbols, the namespace translation follows this pattern:
  c.t.f.$MODULE._ => c.t.f.netty3.$MODULE._. RB_ID=691746
• finagle-core: Define WeightedSocketAddress as a case class. Add
  WeightedSocketAddress.extract method to extract weight. RB_ID=614228
• finagle-core: Constructing a new Balancer that can be injected into a Finagle client
  was unnecessarily complex and non-uniform. We removed the legacy constructors around
  defining the collection of endpoints and simplified the interface to LoadBalancerFactory.
  Now, com.twitter.finagle.loadbalancer.Balancers defines the collection of balancer
  constructors. RB_ID=660730
• finagle-core: Aperture can no longer be enabled via command line flags. Configuring
  per-client settings globally is generally not a good idea and we're working to remove
  these flags from Finagle. Use the constructors in com.twitter.finagle.loadbalancer.Balancers
  to create an instance that can be injected into a client. RB_ID=663194
• finagle-core: The default load balancer has changed to p2c from heap. RB_ID=693450
• finagle-core: Service.isAvailable and ServiceFactory.isAvailable is finalized.
  Service.status and ServiceFactory.status supersedes isAvailable usage since 6.24.0 release.
  RB_ID=678588
• finagle-core: ClientBuilder.failureAccrual method is removed. Use ClientBuilder.failureAccrualFactory
  instead. RB_ID=689076
• finagle-core: Stack param ClientBuilder.ClientConfig.FailureAccrualFac is removed.
  Use ClientBuilder.failureAccrualFactory instead. RB_ID=689076
• finagle-exception: com.twitter.finagle.exception.ExceptionReporter is no longer used
  as the default com.twitter.finagle.util.ReporterFactory. RB_ID=674646
• finagle-kestrel: Replace deprecated finagle-kestrel package with finagle-kestrelx.
  RB_ID=667920
• finagle-core: Add new method noFailureAccrual on ClientBuilder that completely disables
  FailureAccrualFactory in the underlying stack. RB_ID=689076

New Features

• finagle-thrift: Support for finagle Services per thrift method.

Finagle 6.25.0

Breaking API Changes

• finagle-core: c.t.f.builder.Server now implements c.t.f.ListeningServer.
• finagle-core: c.t.f.Server.serveAndAnnounce with a ServiceFactory had
  its first argument renamed to name from forum.
• finagle-core: Add an attribute map to c.t.f.Addr.Bound.
• finagle-core: c.t.f.builder.ClientConfig.FailFast has moved to
  c.t.f.FailFastFactory.FailFast.
• finagle-core: NoBrokersAvailableException now has two Dtab constructor
  arguments, both the base and local Dtabs.
• finagle-core: c.t.f.Failure convenience constructors (e.g., Failure.Cause,
  Failure.Rejected) were removed in favor of uniform flag treatment, and clean
  separation of attributes from interpretation of those attributes.
• finagle-core: ExitGuard usage is now private to finagle.
• finagle-core: c.t.f.service.TimeoutFilter.module is now split into
  TimeoutFilter.clientModule and TimeoutFilter.serverModule.
• finagle-core: remove deprecated c.t.f.builder.ClientBuilder.stack taking a
  Stack.Params => Client[Req1, Rep1].
• finagle-core: StackRegistry.Entry takes different constructor arguments, and the
  name has been bundled in with the Stack.Params. StackRegistry.Entry is only used
  internally, so this should be relatively inexpensive. Similarly, StackRegister#register
  has also had a small change to its method signature along the same lines.
• finagle-http: deprecated methods in c.t.f.http.HttpMessageProxy have been removed.
• finagle-memcached / finagle-memcachedx: move TwitterCacheResolver
  and related objects to new finagle-cacheresolver package.
• finagle-memcached / finagle-memcachedx: failureAccrual param in ReplicationClient
  is changed from type (Int, Duration) to (Int, () => Duration), to allow flexibility
  to config duration. Also see markDeadFor change in finagle-core in the "New Features"
  section below.
• finagle-memcached / finagle-memcachedx: MigrationClientTest now uses
  ServerCnxnFactory from com.twitter.zk rather than NIOServerCnxn.Factory from
  org.apache.zookeeper.server.
• finagle-mux: c.t.f.mux.RequestNackedException is removed in favor of a standard
  Failure (c.t.f.Failure.Rejected).
• finagle-ostrich4: Switched dependency to finagle-httpx from finagle-http.
• finagle-serversets: ZkInstance in tests now uses ServerCnxnFactory from
  com.twitter.zk rather than NIOServerCnxn.Factory from
  org.apache.zookeeper.server.
• finagle-stats: Switched dependency to finagle-httpx from finagle-http.
• finagle-mysql: PreparedStatements are now more type-safe! The type signature of
  PreparedStatements has changed from Seq[Any] => Future[Result] to Seq[Parameter] =>
  Future[Result]. Parameter represents objects that are serializable by finagle-mysql.
  In most cases, scalac should transparently wrap your arguments in Parameter when
  applying a PreparedStatement. However, in cases where this doesn't happen you
  can explicitly wrap them using Parameter.wrap.

Runtime Behavior Changes

• finagle-core: com.twitter.finagle.service.StatsFilter no longer requires a
  com.twitter.finagle.stats.RollupStatsReceiver for correct behaviour, and
  providing one will double count failures.
• finagle-core: com.twitter.finagle.factory.TimeoutFactory will fail with
  a retryable com.twitter.finagle.Failure when it times out.
• finagle-core: com.twitter.finagle.pool.WatermarkPool will fail with
  an interrupted com.twitter.finagle.Failure when it is interrupted while
  waiting or trying to establish a connection. It has previously failed with
  a com.twitter.finagle.WriteException when trying to establish a
  connection, but it's incorrect to retry on an interruption.
• finagle-core: com.twitter.fiangle.RetryPolicy's RetryableWriteException
  and WriteExceptionsOnly will not retry on com.twitter.finagle.Failures
  that are marked InterruptedBy, even if they are Retryable.
• finagle-core: The error message provided by c.t.f.NoBrokersAvailableException
  prints both the base and local Dtabs.
• finagle-core: Stats produced by com.twitter.finagle.factory.BindingFactory
  are now scoped with the "namer" prefix rather than "interpreter". The total
  latency associated with Name binding is now recorded in the "bind_latency_ms"
  stat.
• finagle-core: The "service_creation/service_acquisition_latency_ms" stat
  produced by com.twitter.finagle.factory.StatsFactoryWrapper no longer
  includes time spent in name resolution, which is now covered by
  "namer/bind_latency_us" as discussed above.
• finagle-core: added transit_latency_ms and deadline_budget_ms stats.
• finagle-core: Automatic retries (requeues) are now credited as a ratio of
  requests over a window of time, instead of a fixed limit. The stats scope
  has also changed from "automatic" to "requeues".

Deprecations

• finagle-core: c.t.f.builder.Server.localAddress is deprecated in favor of
  c.t.f.ListeningServer.boundAddress.

New Features

• finagle-core: Fail fast <https://twitter.github.io/finagle/guide/FAQ.html#why-do-clients-see-com-twitter-finagle-failedfastexception-s>_
  is now configurable <https://twitter.github.io/finagle/guide/FAQ.html#configuring-finagle6>_
  on Stack-based clients via the com.twitter.finagle.FailFastFactory.FailFast param.

• finagle-core: com.twitter.finagle.service.StatsFilter is now configurable with an
  com.twitter.finagle.stats.ExceptionStatsHandler to customize how failures are recorded.

• finagle-core: It should be safe to match on com.twitter.finagle.Failure.InterruptedBy
  to tell if a com.twitter.util.Future failed due to being interrupted.

• finagle-core: markDeadFor in c.t.f.service.FailureAccrualFactory.Param is changed from
  Duration type to () => Duration. So it's flexible for clients to pass in a function that
  specifies Duration. For example, c.t.f.service.FailureAccrualFactory provides a function
  that adds perturbation in durations. Stack-based API and c.t.f.builder.ClientBuilder
  support both types for client configuration. For example,

  Thrift.client.configured(FailureAccrualFactory(5, () => 1.seconds))
  // or
  Thrift.client.configured(new FailureAccrualFactory(5, 1.seconds)).
  

  c.t.f.client.DefaultClient does not support Duration type in failureAccrual anymore.

• finagle-core: improved Java compatiblity for c.t.f.Stack.Params / c.t.f.Stack.Parameterized.

• finagle-core: Introduce the ability to add metadata to bound com.twitter.finagle.Addr\s.

• finagle-core: Introduce per-address latency compensation. Clients may be configured with
  a 'Compensator' function that uses the client's address metadata to adjust connection and
  request timeouts. This can be used, for instance, to account for speed-of-light latency
  between physical regions.

• finagle-core: Introduce per-address stats scoping. Clients may be configured with
  a com.twitter.finagle.client.StatsScoping.Scoper function that uses the client's
  address metadata to adjust the scope of client stats. This can be used, for instance,
  to properly scope client stats for a Name that resolves to a Union of distinct clusters.

• finagle-core: A convenient method Client.newService(dest: String, label: String) was added.

• finagle-core: ExitGuard now has an 'explainGuards' method to provide a human-readable
  description of exit guards that are still active.

• finagle-http(x): Two missing params were added: Decompression and CompressionLevel. Both
  client and server may be configured with either configured method or withDecompression/
  withCompressionLevel.

• finagle-mysql: Add support for MySQL transactions.

• finagle-stats: A new HostStatsReceiver type is added and used for per host stats.
  It is loaded through LoadService and used by the Stack-based API as a default
  param. Per host stats can be turned on through com.twitter.finagle.loadbalancer.perHostStats
  flag, and is exported to the "/admin/per_host_metrics.json" route in twitter-server.

• finagle-stats: Improved compatibility when migrating from
  Ostrich stats via two flags:
  com.twitter.finagle.stats.useCounterDeltas=true and
  com.twitter.finagle.stats.format=ostrich. If these flags are both set,
  HTTP requests to /admin/stats.json with the period=60 query string
  parameter will replicate Ostrich's behavior by computing deltas on counters
  every minute and formatting histograms with the same labels Ostrich uses.

• finagle-memcached(x): Add c.t.f.memcached.Memcached which provides a Stack
  based Memcache client that uses pipelining.

Bug Fixes

• finagle-core: c.t.f.Server.serveAndAnnounce for a Service had its usage
  of name and addr transposed.

Miscellaneous Cleanup

• finagle-protobuf: Move entire unused subproject to the `Finagle
  organization on GitHub: https://github.com/finagle/finagle-protobuf.

Finagle 6.24.0

Breaking API Changes

• finagle-core: Remove c.t.f.client.StackClient.Role.loadBalancer, which
  was unused and duplicated by c.t.f.loadbalancer.LoadBalancerFactory.role.

• finagle-core: c.t.f.Namer.orElse was removed; composing Namers
  may be accomplished by constructing an appropriate Dtab.

• finagle-core: removed experimental enum / expand from
  c.t.f.Namer and alt / union from c.t.f.Dtab.

• finagle-http: Remove c.t.f.http.CheckRequestFilter along with
  c.t.f.http.CheckHttpRequestFilter. The functionality has been
  added to c.t.f.http.codec.HttpServerDispatcher. In addition,
  the codecError in c.t.f.http.BadHttpRequest has been replaced
  with the exception thrown by the HttpServerCodec.

• finagle-httpx: Remove deprecated code, limited scope of access on internal
  classes.

• finagle-mux: c.t.f.mux.lease.exp.WindowedByteCounter no longer
  calls Thread.start() in its constructor. This should be now be
  done by the caller.

• finagle-mux: The experimental session API is discontinued.

• finagle-mux: Introduce new Request and Response types for mux services.
  The new mux request includes a destination path so that, which corresponds
  to the destination field in Tdispatch requests. Furthermore, these new
  types expose c.t.io.Buf instead of Netty's ChannelBuffers.

• finagle-thrift,finagle-thriftmux: c.t.f.Thrift.Client, c.t.f.Thrift.Server,
  c.t.f.ThriftMux.Client and c.t.f.ThriftMux.Server have their
  TProtocolFactory configured via a c.t.f.thrift.param.ProtocolFactory
Stack.Param.

• finagle-thriftmux: c.t.f.ThriftMux.Client now has its ClientId
  configured via a c.t.f.thrift.param.ClientId Stack.Param.

• Traces (com.twitter.finagle.tracing.Trace) lose their local-state mutating methods:
  Trace.clear, Trace.pushId, Trace.setId, Trace.setTerminalId, Trace.pushTracer,
  Trace.pushTracerAndSetNextId,
  Trace.state_=, and Trace.unwind.
  Let-bound versions of these are introduced in their stead.
  This makes it simple to ensure that state changes are properly delimited;
  further, these are always guaranteed to be delimited properly by Finagle.

  Trace.setTracer(tracer)
  codeThatUsesTracer()
  
  // Let-bound version:
  Tracer.letTracer(tracer) {
    codeThatUsesTracer()
  }
  

• Context handlers (com.twitter.finagle.Context) are removed.
  They are replaced by the use of marshalled request contexts
  (com.twitter.finagle.context.Contexts.broadcast).
  Marshalled request contexts do not require the use of service loading,
  so their use no longer requires build system coordination.
  We show Finagle's trace context:
  the first version uses the old context handler mechanism;
  the second uses Contexts.broadcast.

  // The old context handler for Finagle's tracing context. Note that this
  // also required the file
  // finagle-core/src/main/resources/META-INF/services/com.twitter.finagle.ContextHandler
  // to contain the fully qualifed class path of the below object.
  class TraceContext extends ContextHandler {
    val key = Buf.Utf8("com.twitter.finagle.tracing.TraceContext")
  
    def handle(body: Buf) {
      // Parse 'body' and mutate the trace state accordingly.
    }
  
    def emit(): Option[Buf] = {
      // Read the trace state and marshal to a Buf.
    }
  }
  
  // New definition. No service loading required.
  private[finagle] val idCtx = new Contexts.broadcast.Key[TraceId] {
    val marshalId = Buf.Utf8("com.twitter.finagle.tracing.TraceContext")
  
    def marshal(id: TraceId): Buf = {
      // Marshal the given trace Id
    }
  
    def tryUnmarshal(body: Buf): Try[TraceId] = {
      // Try to marshal 'body' into a trace id.
    }
  }
  

Runtime Behavior Changes

• finagle-mux: Mark the ServiceFactory available again if the underlying
  Service is no longer available. This permits it to be closed and reused.
• finagle-mux: Rename the "lease_counter" counter to "leased" on mux clients.

Deprecations

• finagle-core: Deprecated the mechanisms of FailureAccrual that use
  factory Transformers. It's better to just use the Params to
  configure the existing FailureAccrualFactory. However, if you've
  actually written your own failure accrual transformer that's
  significantly different, then you can do stack.replace() to swap it
  in.
• finagle-memcached: Have cas() operation return false on NotFound()
  state instead of throw IllegalStateException

New Features

• finagle-core: All Stack.Params used in ClientBuilder and
  ServerBuilder are now publicly exposed for configuration
  parity.
• finagle-mux: Drain mux servers properly, so that shutdowns can be
  graceful.
• finagle-core: Introduce Service.status which supersedes
  Service.isAvailable. Service.status is a fine-grained
  health indicator. The default definition of
  Service.isAvailable is now defined in terms of
  Service.status; this definition will soon be made
  final.
• finagle-mux: Inject bound residual paths into mux requests.
• Request contexts. Request contexts replace the direct use of
  com.twitter.util.Local and of com.twitter.finagle.Context.
  Request contexts are environments of request-local bindings;
  they are guaranteed to be delimited by Finagle,
  and their API admits only properly delimited binding.
  They come in two flavors:
  Contexts.local are always local to handling a single request;
  bindings in Contexts.broadcast may be marshalled and transmitted across process
  boundaries where there is protocol support.
  Currently, both Thrift and Mux (and thus also ThriftMux)
  support marshalled contexts.
  See com.twitter.finagle.contexts.Context for more details.

v6.22.0

Breaking API Changes

• finagle-core: Removed unused com.twitter.finagle.service.ProxyService. It wasn't
  sufficiently general to be used outside of finagle, and was no longer used
  in finagle.

New Features

• finagle-core: BroadcastStatsReceiver, introduce specialized implementation
• finagle-core: Introduce gauges in SummarizingStatsReceiver
• finagle-core: Introduce Transport#copyToWriter
• finagle-core: Make base Dtab used in BindingFactory a Stack.Param
• finagle-core: Proper decay in experimental ewma load metric
• finagle-core: Simplify Stack{Client, Server} and unify around them

Runtime Behavior Changes

• finagle-core: Add support for non-URLClassloaders to LoadService
• finagle-core: clear locals before entering server dispatch loop
• finagle-core: Defer DNS Resolution in InetResolver to FuturePool
• finagle-core: for paths starting with /#/, skip rewrites where prefix is /
• finagle-core: include name resolution in tracing request span
• finagle-core: Properly wrap some IOException into ConnectionFailedException
• finagle-core: Scope InetResolver's stats properly
• finagle-http: Send "Connection: close" header while dispatcher is closing
• finagle-http: Set content length header when appropriate
• finagle-memcached: Use interruptible future for the client request readiness
• finagle-stats: Add content-type response header to JsonExporter
• finagle-thrift: Add back connection_preparation_latency stat in Thrift
• finagle-thriftmux: Record protocol as a gauge rather than a counter

Documentation

• finagle-core: Add Scaladocs for ChannelBufferBuf and BufChannelBuffer
• finagle-core: link to the FAQ in FailedFastException
• finagle-serversets: Defer DNS resolution for endpoints to InetResolver
• finagle-thrift{,mux}: Clarified with* deprecation warning
• Fix minor issues and missing code blocks in Finagle documentation

Optimization

• finagle-core: GlobalFlag isn't caching the property value
• finagle-core: recursive-descent Path / NameTree / Dentry / Dtab parsers to reduce heap allocation

Bug Fixes

• finagle-core: Fix a deadlock in Contexts

• finagle-core: Fix breaking ABI change in SummarizingStatsReceiver

• finagle-core: Fix bug in computing array index in SummarizingStatsReceiver

• finagle-core: Fix build.properties location for maven builds

• finagle-core: Fix synchronization in LeasedFactory

• finagle-core: Fix tracing with Stack{Client, Server}

• finagle-core: Make FailedFastException an instance variable.

• finagle-core: Synchronized access to the Stackable mutable.params map

• finagle-http: Fix CookieMap.rewriteCookieHeaders()

• finagle-http: Fix the memory leak in HttpClientDispatcher

• finagle-mysql: Fix timestamp fractional seconds encoding

• finagle-mysql: Properly heed timezone when extracting TimestampValue

• mux: clear contexts after receive, not in 'finally' clause

  Removed TLSEngine, and replaced it with two, TLSClientEngine, and
  TLSServerEngine, where TLSServerEngine is the same as TLSEngine, and
  TLSClientEngine takes a SocketAddress instead of (). The other changed
  API is the Netty3TransporterTLSConfig now takes a function
  SocketAddress => Engine, instead of () => Engine.