Scrooge Changelog

Below is a list of changes for each Scrooge release



  • scrooge-adaptive: Add support for adaptive decoding, that learns from field access patterns and optimizes the decoder to cheaply skip over unused fields. RB_ID=908416
  • scrooge-generator: Scala code generation support for annotations on enums RB_ID=917467


  • scrooge-core: To reduce object allocations, c.t.s.TFieldBlob now uses, and add c.t.s.TReusableBuffer for providing thread-safe reusable buffer. RB_ID=914874
  • scrooge-core: Add dependency on util-core. RB_ID=914874


No Changes


  • scrooge-core: c.t.s.ThriftUnion adds methods containedValue and unionStructFieldInfo. These were already a part of the generated Scala implementations for unions, but now it is defined on the trait. RB_ID=909576
  • scrooge-core: Removed c.t.s.ThriftStructCodec deprecated encoder and decoder methods. Use encode and decode instead. RB_ID=
  • scrooge-core: Remove deprecated encoder and decoder methods from c.t.s.ThriftStructCodec. Use encode and decode instead. RB_ID=909714
  • scrooge-generator: Add parsing, AST, and Scala code generation support for annotations on enums, enum fields, services, and service methods. RB_ID=908556
  • scrooge-generator: Fix default values for collections in scala bindings RB_ID=908152
  • scrooge-generator: MethodIfaceBuilder#newMethodIface now returns a MethodIface. RB_ID=907700
  • scrooge-generator: Scala’s types for ServiceIfaces are now a Service from ThriftMethod.Args to ThriftMethod.SuccessType, instead of ThriftMethod.Args to ThriftMethod.Result. This is a breaking API change though it should generally be easy to adapt existing code to it. RB_ID=908846


No Changes


  • scrooge-linter: Add thrift definition linter warnings if generated thrift will exceed JVM HotSpot ClipInlining check. RB_ID=896379


  • scrooge-generator: Remove check for 22 args when generating scala ServiceIface. Now that we no longer support Scala 2.10 we can always generate a case class for the generated scala ServiceIface. RB_ID=882203
  • scrooge-generator: Don’t allow Structs and Typedefs with the same identifier. Structs and typedefs should not have the same name. This makes it difficult to properly support self-referencing types. RB_ID=881684
  • scrooge-generator: Fix pathological case for self-referencing types with Java generation. RB_ID=880813



No Changes


No Changes

  • scrooge-core: c.t.scrooge.TReusableMemoryTransport now uses TUnboundedByteArrayOutputStream instead of TByteArrayOutputStream to avoid buffer reallocation on reset.


Breaking API Changes

  • scrooge-sbt-plugin: Allow scrooge to build bindings for more than one language. To reflect this, ScroogeSBT.autoImport.scroogeLanguage has been renamed to scroogeLanguages and is now a SettingKey[Seq[String]] instead of a SettingKey[String]. RB_ID=846198
  • Builds are now only for Java 8 and Scala 2.11. See the blog post for details. RB_ID=828898


  • scrooge-core, scrooge-generator: c.t.scrooge.ThriftEnum now includes an originalName method which represents the name as defined in the Thrift IDL file. RB_ID=820075


  • scrooge-ostrich: Removed scrooge-ostrich module
  • scrooge-runtime: Deleted unnecessary scrooge-runtime module
  • scrooge-generator: Remove broken experimental-java generator.


  • scrooge: Improve implementation of service#FunctionType




  • scrooge: Rename __ServiceIface to BaseServiceIface
  • scrooge: Add methods for converting between function and service implementations of ThriftMethods.


  • bump finagle version to 6.30


  • bump finagle version to 6.29


  • scrooge: Scrooge 4.0.0 includes backward compatibility patches for Finagle service per endpoint generation. This allows using Thrift endpoints as Finagle Services and combining them with Filters.



  • scrooge: Generate a finagle Service per thrift method (Service interface)


  • scrooge: Performance improvements and bug fixes.
  • scrooge-sbt-plugin: Add output language support in scrooge-sbt-plugin.


  • scrooge-maven-plugin: Fix bug with plugin parameters.


  • scrooge: Support ignoring unknown enum ids.
  • scrooge: Output full exception chain in client stats.
  • scrooge: Add union metadata to generated scala code.
  • scrooge-maven-plugin: Resolve IDLs transitively; deprecate the dependencyIncludes option.
  • scrooge-sbt-plugin: Add thrift files to published artifact in sbt-plugin.
  • scrooge-sbt-plugin: Upgrade to autoPlugin.


  • scrooge: add is required to ThriftStructFieldInfo.
  • scrooge minor docs update: add logo and short description.
  • scrooge-serializer: Remove dependency on scrooge-runtime.
  • scrooge: Cache mustache resources to improve generation performance.
  • scrooge: Disallow identifiers that are thrift keywords.
  • scrooge: Remove SafeVarargs for JDK 6 compatibility.


  • scrooge-core: Added scala 2.11 support
  • scrooge-core: scrooge: add .withoutPassthrough method that recursively removes passthrough fields
  • scrooge-doc: Fix formatting in the CLI help page.
  • scrooge-linter: Cleaner logging and options.
  • scrooge-linter: remove invalid CONFIG.ini.
  • scrooge: prefer Protocols.binaryFactory over TBinaryProtocol.Factory


  • scrooge-core: Add union metadata for reflection
  • scrooge-doc: Clarify docs on CLI usage
  • scrooge-generator: Fix error message for missing required field
  • scrooge-generator: Modify compiler to accept a Scaladoc comment at the end of Thrift file
  • scrooge-generator: Normalize scalatest versions between poms and 3rdparty
  • scrooge-generator: Stricter checks for invalid Thrift filenames
  • scrooge-ostrich: Default to using Protocols.binaryFactory


  • release finagle v6.18.0
  • release util v6.18.0
  • scrooge-linter: Fix multiple arguments to linter + pants/mvn fixes
  • scrooge: Separate flow for linter
  • scrooge: Skip includes when linting


  • Upgrade dependencies to latest versions
  • scrooge: Move scrooge-linter into scrooge
  • scrooge: Add SimpleID.originalName for enum fields.


  • scrooge: Bumping finagle to 6.16.0
  • scrooge: Bump util to 6.16.1-SNAPSHOT


  • scrooge-generator: Allow union field names to match struct names


  • scrooge: Use scala.Option in all com.twitter.scrooge files to avoid conflict with com.twitter.scrooge.Option
  • scrooge: Allow for Longs as const values
  • scrooge: Make mustache parser threadsafe
  • scrooge: Removing scrooge-generated null checks for primitive Scala types
  • scrooge-ostrich: Add a flag for enabling ThriftMux


scrooge: bump finagle + util versions


scrooge-generator: Use OutputSreamWriter to write non ascii characters correctly.


  • scrooge: add sbt 0.13 variant of scrooge-sbt-plugin
  • scrooge: Add scrooge/scrooge-generator/BUILD
  • scrooge: enable structs for the RHS of consts in scala
  • scrooge: handle all shapes of RHS structs
  • scrooge: scrooge: expose IDL annotations in generated structs
  • scrooge: scrooge: throw an error when reading a field with the wrong type
  • scrooge: Test uses of scala.Product are fully qualified
  • scrooge: Thrift structs with fields named “n” can’t use productElement to get that field
  • scrooge: upgrade finagle to 6.13.1
  • scrooge: upgrade util to 6.13.2


  • scrooge: add the thrift root to the list of includes for scrooge
  • scrooge: Automatically whitelist all idl jar dependencies
  • scrooge: fixed issue when default value is enum from other namespace where namespace is missing in generated code
  • scrooge: Update mustache to 0.8.13
  • scrooge: update util to 6.12.0
  • scrooge: update finagle to 6.12.1
  • scrooge: update util to 6.12.1
  • scrooge: add extra fields to generated companion object for reflection use
  • scrooge: capture unknown union values as its own value (THRIFT-99)
  • scrooge: Update scrooge to remove date from Generated annotation so generated code is reproducible.


  • scrooge: Added missing writeFieldEnd() for passthrough fields
  • scrooge: Bump finagle to 6.11.1
  • scrooge: Bump util to 6.11.1
  • scrooge: WriteFieldStop during transfer


  • scrooge: properly handle field annotations


  • scrooge: use a TReusableMemoryTransport in finagle services
  • Bump guava to 15.0
  • scrooge-generator: trim some allocations from generated scala code
  • scrooge: use scalatest, remove specs
  • added scala namespace to demo
  • Rm all imports of scala.Some


  • scrooge-*: bump finagle to 6.10.1-SNAPSHOT, util to 6.10.1-SNAPSHOT
  • scrooge-generator: Attach thrift annotations to generated AST
  • scrooge-generator: Ensure enums with values of the same name will compile
  • scrooge-maven-plugin: Overwrite and warn if the current file is older


  • scrooge: bump finagle version to 6.8.0
  • scrooge: bump util version to 6.8.0
  • scrooge: secondary struct class constructors without _passthroughFields for backwards compatibility
  • scrooge-generator: fixed comment parsing bug


  • scrooge-generator: simplify synthesized structs For synthesized service method arg and results structs
  • scrooge-generator: special, scrooge-only syntax for scala namespace
  • scrooge-generator: don’t backquote scala identifiers in Enum.valueOf string constants


  • scrooge-generator: produce slimmer code, remove _passthroughFields from object apply method


  • scrooge-generator: default passthrough value, valid method names.


  • scrooge-serializer: simpler BinaryThriftStructSerializer builder
  • scrooge-maven-plugin: check for null from Artifact.getDependencyTrail


  • scrooge: support larger structs
  • scrooge: allow oneway
  • scrooge: always generate passthrough code


  • scrooge-generator: remove deprecation warnings removed deprecation warnings for FutureIface, FinagledClient, and FinagledServer. Since Jeff is working on finagle-free code generation, there is no good reason to push people off of these classes onto the replacements I added, only to deprecate those classes in the near future.
  • scrooge-generator: fixed imports for union


  • scrooge use scala option in metadata
  • provide type parameters in metadata
  • automatically whitelist all idl jar dependencies
  • fix scrooge build properties
  • bump finagle to 6.6.3-SNAPSHOT
  • scrooge: support backslash escapes
  • bump poms to finagle 6.6.1-SNAPSHOT
  • bump util to 6.5.1-SNAPSHOT


  • scrooge: passthrough field improvements
  • Scrooge doesn’t title case extended services properly
  • update scrooge demo
  • fix test breakage on sbt


  • scrooge-serializer: tighten up dependencies scrooge-serializer only needs to depend on scrooge-core, not scrooge-runtime (the pants BUILD file already did this).
  • We think that mustache actually handles the escaping so that this additional escaping is not needed.
  • bump util to 6.4.1-SNAPSHOT
  • scrooge-runtime => scrooge-core
  • properly qualify service parents
  • scrooge-ostrich: add thriftProtocolFactory as val The generated ThriftServer class has a thriftProtocolFactory field that some subclasses use.
  • scrooge: removed ostrich generation.
  • remove use of deprecated generated ostrich ThriftServer


  • scrooge-generator: fixed whitespace eating in strings ThriftParser extends RegexParsers.
  • scrooge-generator: Fixup java codegen issues surfaced by converting ads:ad-review-tests in science to scrooge.
  • scrooge-generator: add support for scala namepsace
  • scrooge-generator: Need to filter out items that are not set when rendering default struct values.
  • scrooge-maven-plugin: Make scrooge plugin find thrift files in idls when run only with reactor projects in a clean env
  • scrooge-generator: Allow default struct values in the java generator.
  • scrooge-ostrich: search harder for FutureIface
  • scrooge-generator: rename Service$ThriftServer to Service$OstrichThriftServer - fixes breakage under scala 2.10 - also removed which wasn’t used
  • scrooge-generator: allow trailing comma at the end of a map


  • scrooge: breaking out finagle, higher-kinded-type interface
  • use apply instead of cons for enum list all
  • Cleanup around the TypeResolver
  • update ostrich related docs
  • scrooge-ostrich This review introduces a new, temporary scrooge subproject, which is intended to help in the migration away from generating ostrich code in scrooge.


  • BREAKING: remove list generation from enums (was causing compile errors. will revisit)
  • move TypeResolver and ParseException into the frontend package
  • create scrooge-core leaving legacy finagle code in scrooge-runtime. (scrooge-runtime will be deprecated soon)
  • treat non-letters as case-less
  • update docs and release process for twitter-server, scrooge
  • BREAKING: move serializer into its own project
  • keep the order of the values in the constant map in the parser. Should be a no-op for scala that converts it to a map in the generator
  • Remove the tracerFactory usage and use tracer instead.
  • create scrooge documentation site
  • tiny fix for oneway support


  • bugfix: collections of enums now identify as i32 on the wire


  • provide a mechanism for dynamicallly pluggable backends
  • make enum list of values lazy
  • remove the include mapping hack
  • fix maven plugin references includes


  • Documenation fixes
  • fix ThriftStructMetaData use camelCase method names to match generated

code - maven-plugin: skip file copy from references if existing file is the same - POTENTIALLY BREAKING CHANGES: - Identify enum fields as TType.ENUM but maintain backward compatibility by identifying them as I32 on the wire - maven-plugin - do not extract dependencies into their own subdirectories


  • add list method to enums that lists all values
  • bugfix: ThriftUtil was not being imported for services
  • add ability to attach additional passthrough fields



Make java gen experimental. There are changes coming down the pipe that will dramatically refactor java’s codegen.


  • do not use an intermedial val for passthroughs. Eliminates the possibility

of a name collision - eliminate the possibility of namespace collision for “runtime” - revert identification of Enums and TType.ENUM (back to I32) - eliminate all use of ThriftUtil unless it’s needed


  • bump to util-6.3.6 / finagle-6.5.0
  • [EXPERIMENTAL] add ability to pass through additional fields

enable with –enable-passthrough - Create the ability to map includes to directories to bridge scrooge2 and scrooge3 maven layouts - show the filename of the file being parsed in error messages - identify enums as TType.ENUM


  • generator: thrift idl containing UTF-8 produces

java.nio.charset.UnmappableCharacterException - generator: Replace backslash with forward slash in file URI - sbt-plugin: Include (and optionally compile) external thrift files. - generator: remove unnecessary apply method for decode (causes issues with named args)


  • Use explicit version numbers


  • Depend on the latest patch version of util/finagle


  • add back the –import-path flag as a deprecation step
  • add sbt-plugin
  • use maven as the build system for the maven plugin



In the maven plugin: change the dependentConfigs param to dependentIncludes

  • optimize empty collections on deserialization
  • upgrade to finagle 6.4.0 and util 6.3.4



We finally made scrooge-runtime to be backward with Scrooge 2. This requires a name change for the ThriftStructCodec. From now on, all objects generated by Scrooge 3 will use ThriftStructCodec3. This will affect you only if your code is using ThriftStructCodec directly, which is not common. - scrooge now releases jar-with-dependencies - add language option tag to scrooge-maven-plugin, thanks to @eirslett - some directory reorganization of the demos


  • Dependency changes: now on util/finagle 6.3.0
  • demo project now shows how to construct finagle server and client using

generated code - –ostrich flag implies –finagle flag


  • Remove “provided” scope of finagle in scrooge-runtime. So it brings Finagle

6.1.0 as transit dependency to your project - Make the generated Scala code backward compatible with Finagle 5. The impact to users on Finagle 6 is that you will see a lot of warnings saying that tracerFactory is deprecated.


  • When scrooge-maven-plugin extracts Thrift files from a dependency artifact, it

now puts them in a sub folder named after the artifact id. This way, the user project can use same-named Thrift files from different artifacts. - Title case and camel case more consistent with previous version before 3.0.7 We still preserve consecutive upper cases but not in an all-up-case string, eg:

TBird (original) -> tBird (camel case) -> TBird (title case) HTML (original) -> html (camel case) -> Html (title case)

Thanks to @erikvanoosten - Finagle client can throw exception on void function. Thanks to @brancek - Support documentation on enum values. Thanks to @erikvanoosten - Reorganizing test folder, and add Apache standard test


  • All on-wire names in the Thrift messages are now consistent with

Apache generated code. This allows Scrooge generated services to exchange Thrift messages with Apache generated services. - Title case ids now preserve consecutive upper case letters. Eg:

TBird (original) -> Tbird (old) -> TBird (now)

See test case in scrooge-generator/src/test/scala/com/twitter/scrooge/ASTSpec.scala - scrooge-maven-plugin now enforces an explicit white list in <dependencyConfig>. The old behavior is that if a dependency artifact has a “idl” classifier, we will extract thrift files from it to compile. The new behavior is that the artifact must be explicitly included in <dependencyConfig>. The dependencies here include both direct dependencies(specified in project pom file) and indirect dependencies (everything in the dependency tree). - Now supports “scala” as a namespace scope. It is treated same as “java”. - Now supports “*” as a default namespace scope


  • Released a scrooge-maven-plugin, for maven projects to integrate Scrooge in

their pom files. Also released a demo of how to use scrooge-maven-plugin - scrooge-runtime is now backward compatible with scrooge-runtime 2.X.X. The following classes and methods are deprecated: - FinagleThriftClient - FinagleThriftService - ThriftStructCodec.decoder - ThriftStructCodec.encoder - scrooge-runtime now can introspect generated ThriftStruct. See the new ThriftStructMetaData class. - BREAKING: in scrooge-runtime, com.twitter.ScroogeOption is now renamed to just Option. This is mainly for Java code. But if you need to use it in Scala code, make sure to address ambiguity with scala.Option. - Updated APIs of scrooge-generator. See com.twitter.scrooge.Compiler class - Fix the stats reporting for the java scrooge thrift code generation


Bug fixes

  • Constant definitions now can be of “set” type.
  • Fix letter cases of enum fields(Java uses upper case; Scala uses title case)


  • Remove dependency on org.scalatest, com.twitter.scalatest (not in Maven

Central) - Update dependency of util/finagle/ostrich to 6.1.0 - Project dependencies are all in Maven Central now. You don’t need to have access to Twitter internal repository anymore.



  • add –dry-run option to parse and validate source thrift files, reports any

errors, but does not emit any generated source code. It can be used with –gen-file-mapping to get the file mapping

Bug fixes

  • union types now can contain primitive types.
  • constants defined in the same file now can be referenced.


  • Update dependency of util/finagle/ostrich to 6.0.6


  • Scrooge artifacts now deploys to Maven central via Sonatype
  • Scrooge project builds in Travis CI
  • Features
  • Fully qualifying ids imported by “include” statements. We don’t generate

“import” statements anymore. - Remove unnecessary finagle jar dependencies for vanilla generated code. - Add tests - non-finagle usage; see NonFinagleSpec.scala - struct immutability and deep copying; see ImmutableStructSpec.scala - Bug fixes - move “validate” method from Scala struct trait to object, so that the thrift struct can define a “validate” field without name clashing.


  • Adding a “–gen-file-map <path>” option to Scrooge command line. It tells

what output files each input Thrift files generates, in the following format:

inputPath/input.thrift -> outputPath/Constants.scala inputPath/input.thrift -> outputPath/FooStruct.scala

  • The generated enums now have a common trait ThriftEnum(defined in

scrooge-runtime), that allows you to query the name as well as the value of the enum field. - The generated Scala enums now are Java-serializable. - The generated FinagledClient class takes val arguments to make “service”, “protocol” accessible:

class FinagledClient( val service: ..., val protocol: ..., val serviceName: ... stats: ... )


Features and bug fixes

  • Doc comments are included in the generated code.
  • Generated exception structs now have getMessage() method
  • Generate header that emits Scrooge version
  • You can now import a directory or a Jar/Zip file through command line

argument, which will be stored in a chain of paths maintained by Scrooge. Then refer to a file using relative path in the thrift “include” statement. Scrooge will locate the file in the path chain. - Introduce a “strict” mode that defaults to on. Unfavored syntax throws an exception when “strict” mode is on and prints a warning when it’s off. The strict mode can be disabled by specifying the “–disable-strict” argument. - The “oneway” modifier is treated as an OnewayNotSupportedException in strict mode and a warning in non-strict mode. - Support Union types. Given:

union Point { 1: double x 2: double y 3: Color color = BLUE }

Scrooge generates: sealed trait Point object Point { case class X(x: Double) extends Point case class Y(y: Double) extends Point case class Count(color: Color = Color.Blue) extends Point }

The “required” and “optional” modifiers in a union type will throw exceptions in strict mode and print warnings in non-strict mode. - Have a common trait ThriftException for all the thrift exception structs. - Support cross file service inheritance. Now you can do include “foo.thrift” service MyService extends foo.FooService { ... } - Bug fix: It couldn’t resolve a symbol imported through a relative path and threw an UndefinedSymbolException - Bug fix: namespace aliasing put the parentheses in the wrong place. - Bug fix: services using binary fields wouldn’t compile - Bug fix: cross-file const referencing didn’t work

Implementation updates

  • Project structure:
  • frontend: Importer and ThriftParser
  • mustache: everything related to mustache, including template parser, loader

and handlebar - ast: Thrift AST definition - backend: code generation include various generators and dictionaries to hydrate Mustache templates. - Redefine clear and separate responsibilities of each components: - Move ID manipulation(concatenation, case conversion, keyword rewriting etc) to Generator phase. - Utilizing Scala static type checking to enforce scoping correctness by introducing SimpleID and QualifiedID to AST. - Enforce dictionary key uniqueness for nested Mustache templates. - Scrooge project is now on Maven - Delete obsolete code and tests


  • Upgraded to util 5.3.13, finagle 5.3.30
  • Removed dependency on sbt
  • Add dependency on maven


  • Java code generation is now supported!
  • Scala code now generates a set of classes for each struct:
  • a base trait
  • an immutable case class (used as the default implementation)
  • a proxy trait (to make it easy to build proxy classes)
  • Moved scrooge-runtime into the same repo with scrooge, which is now called

scrooge-generator. Both projects will keep version numbers in sync now. - Changed the way required/optional is treated on fields, and default values, to more closely match the way Apache Thrift works. (This is described in more detail in a new section of the README.) - Fixed constant sets. - Fixed thread safety in finagle ThriftServer. - Fixed the resolution of #include directives that follow relative paths. - Removed the finagle dependency from scrooge-runtime so that code generated with scrooge can be loosely coupled with finagle, or optionally not depend on finagle at all (if you don’t build finagle bindings). - Fixed typedef references that were relative to #included files. - Made various improvements to the internal template system. - Fixed test speed by using scrooge to generate code that the tests build against, avoiding runtime evaluation.


  • Upgraded to thrift 0.8.0, util 4.0, and finagle 4.0.
  • Upgraded to sbt 0.11.2.
  • Upgraded to scala 2.9.2.



  • Addressed an issue where structs with the same name but from different

namespaces/packages would conflict. Now using a package alias to disambiguate.


  • Minor bug fix for serviceName name class with.


  • added support for structs with more than 22 fields, which previously was the

limit as that is the max case-class size in scala. For structs larger than this, instead of using case-classes, normal classes are used but with most of the case-class boilerplate support code also generated, allowing these structs to be used as if they were case-classes. The only exception is that there is no unapply method; but do you really want to unapply 23+ fields in a match statement?


  • thriftProtocolFactory in generated ThriftServer now has

type of TProtocolFactory, so you can override it with other protocol factories.


  • You can now override serverBuilder in ThriftServer to provide

additional server configuration - The protocol factory to the FinagledClient now has a default value of TBinaryProtocol.Factory, which means you don’t have to specify it when using the default.


  • tracerFactory support in ThriftServer.


  • Support for tracing in server.


  • fixes a bug in which namespace mapping was not applied

recursively to included documents.


  • fixes a bug in which qualified service names from imported

thrift files were not resolved properly.


  • fixes a bug with enum in which the first value was wrong.



  • scrooge-runtime-1.0.1
  • Each thrift struct companion object now extends ThriftStructCodec
  • Correctly resolving enum constants and Const values.
  • Title-casing enum value names.
  • Added support for namespace renaming from the command line.