Finagle Serial supports the creation of Finagle servers and clients that use Scala (or Java) libraries for serialization instead of IDL-based systems like Apache Thrift or Google's Protobuf. It's designed to make it easy to construct Finagle services that take arbitrary Scala types as inputs and outputs, with minimal boilerplate.
Finagle Serial uses Mux as its session-layer protocol, with object serialization (the presentation layer, to use the terminology of the OSI model) supplied by a pluggable wrapper for the serialization library of your choice. We currently provide support for Scodec.
Let's start with some simple case classes:
case class User(name: String)
case class Greeting(u: User) {
override def toString = s"Hello, ${u.name}!"
}Now we can write a Finagle service that greets a user:
import com.twitter.finagle.Service
import com.twitter.util.Future
object GreetUser extends Service[User, Greeting] {
def apply(u: User) = Future.value(Greeting(u))
}Now suppose we want to make this greeting service available on the network. All
we need to do is pick a serialization backend (we'll use Scodec here),
and provide codecs for our input and output types (see the Scodec
documentation for an explanation of the use of variableSizeBits,
uint24, and utf8 here):
import io.github.finagle.serial.scodec.ScodecSerial
import java.net.InetSocketAddress
import scodec.Codec
import scodec.codecs._
implicit val userCodec: Codec[User] = variableSizeBits(uint24, utf8).as[User]
implicit val greetingCodec: Codec[Greeting] = userCodec.as[Greeting]
val protocol = ScodecSerial[User, Greeting]
val server = protocol.serve(new InetSocketAddress(8123), GreetUser)
val client = protocol.newService("localhost:8123")And now we can call our server from our client:
client(User("Mary")).onSuccess { greeting =>
println(greeting)
}That's all! No plugins, no IDLs, no code generation, and very little boilerplate.
Serial is brand new and is not published to Maven Central at the moment (it will
be soon), but for now you can check out this repository, run
sbt +publish-local, and then add the following dependency to your project:
libraryDependencies += "io.github.finagle" %% "finagle-serial-scodec" % "0.0.1"The most straightforward way to take care of application error handling is simply to represent the possibility of error in your service's return type, and then provide the appropriate codecs. For example, a simple integer parsing service might have the following implementation:
object IntParser extends Service[String, Either[NumberFormatException, Int]] {
def apply(s: String) = Future(
try Right(s.toInt) catch {
case e: NumberFormatException => Left(e)
}
)
}Now you just need to tell your serialization backend how to encode String and
Either[NumberFormatException, Int] and you're done.
It's also possible (and sometimes more convenient) to use the service's Future
to represent the possibility of error. This allows you to write the following:
object IntParser extends Service[String, Int] {
def apply(s: String) = Future(s.toInt)
}Now depending on the serialization backend you choose, one of two things will
happen when you call this service with invalid input. If that backend supports
serializing NumberFormatException, you'll get back a NumberFormatException
(wrapped in a Try, of course). If the backend doesn't know how to serialize
the exception, you'll get a io.github.finagle.serial.ApplicationError instead
(also wrapped in a Try).
Consult your serialization backend to see which exceptions it can serialize—it may support adding your own, as well. For example, the default Scodec backend knows how to serialize a few commonly-used exceptions from the Java standard library, and you can easily add user-defined exceptions, or other exceptions it doesn't know about.
There are three more exceptional kinds of exceptions that may be returned from a Serial service:
- A
io.github.finagle.serial.CodecErrorrepresents an encoding error at the presentation layer. This probably indicates a problem with one of your codecs, and a well-behaved serialization backend should provide an error message that clearly indicates the source of the issue. - A
com.twitter.finagle.mux.ServerErrorindicates an encoding error at the session layer. This almost certainly isn't something you're responsible for (whether you're implementing a service or a serialization backend). - A
com.twitter.finagle.mux.ServerApplicationErrorindicates an unhandled application error. A well-behaved serialization backend implementation shouldn't return these, but instead should return aCodecErrororApplicationError(assuming it can't return the exception thrown by your service).
We provide a SerialIntegrationTest that makes it easy to use ScalaCheck
to help verify that your serialization backend implementation is working
correctly. For example, the following is a simplified (but complete) version of
part of the integration testing for the Scodec backend:
import _root_.scodec._
import _root_.scodec.codecs._
import com.twitter.util.Await
import io.github.finagle.serial.test.SerialIntegrationTest
import org.scalacheck.{Arbitrary, Gen}
import org.scalatest.FunSuite
class ScodecIntegrationTest extends FunSuite with ScodecSerial with SerialIntegrationTest {
implicit val intCodec: Codec[Int] = int32
implicit val stringCodec: Codec[String] = variableSizeBits(uint24, utf8)
case class Foo(i: Int, s: String)
implicit val fooCodec: Codec[Foo] = (uint8 :: stringCodec).as[Foo]
implicit val fooArbitrary: Arbitrary[Foo] = Arbitrary(
for {
i <- Gen.choose(0, 255)
s <- Gen.alphaStr
} yield Foo(i, s)
)
test("A service that doubles an integer should work on all integers") {
testFunctionService[Int, Int](_ * 2)
}
test("A service that returns the length of a string should work on all strings") {
testFunctionService[String, Int](s => s.length)
}
test("A service that changes a case class should work on all instances") {
testFunctionService[Foo, Foo] {
case Foo(i, s) => Foo(i % 128, s * 2)
}
}
}Check the test project documentation for more information about these tools.
We also provide a very preliminary benchmark project that uses JMH to
compare the performance of the Scodec backend to a similar Finagle Thrift
service. In our initial testing, the Scodec backend manages about 46% of the
throughput of the Thrift implementation:
i.g.f.s.RoundTripThriftSmallBenchmark.test thrpt 20 22422.923 ± 1098.352 ops/s
i.g.f.s.ScodecSmallRTBenchmark.test thrpt 20 10335.675 ± 190.058 ops/s
These benchmarks (even more than most benchmarks) should be taken with a grain of salt, but will be refined as the project matures.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent