Binding Decorators

[chrisbanes]

Description

We had this feature in our custom DI framework at Twitter, and it was super handy for large codebases.

Here's the use case that I'm thinking, but I'm 100% sure that there's more. We have a Logger with takes a tag, and in every class we either:

• Create a copy of the logger: val classLogger = logger.withTag("MyClassName")
• Or just pass it in at the calls logger.d(TAG)

It would be nice if we could attach some kind of decorator so that the injected logger is pre-decorated with the class name as tag.

The API could be something like the following:

annotation class BindingDecorator(val type: KClass<Any>)

interface Decorator<T> {
  fun decorate(context: BindingContext, value: T): T
}

Then to create and attach a decorator:

annotation class LoggerDecoration

@Inject
@BindingDecorator(LoggerDecoration::class)
class LoggerDecorator : Decorator<Logger> {
  override fun decorate(context: BindingContext, source: Logger): Logger {
    return logger.withTag(context.callee.simpleName)
  }
}

Then, every Logger injected into a class would be automatically decorated with the class name.

This is just one example. Others could include:

• Tracing. A tracing decorator which automatics add Trace sections around binding functions
• I'll think of more 😄

[efemoney]

Spring (framework) has a slightly different concept called InjectionPoint that solves much of the same problems but without the downsides (if any?) and it ties into familiar DI concepts. Spring uses reflection but metro being a compiler plugin makes the concept OP.

The way it works is that at a types "injection point" ie where the type is requested/injected, you add a "virtual" / "intrinsic" dependency that gives basic information about where/how that type is being injected & the type can use that information within itself.

The information could be whether or not its a value parameter or property injection? What is its enclosing class? And maybe any annotations on the injection.

Here's an example from one of my services. In my case I allow my users to annotate the injected parameter or field with a custom LogName or if they dont, I just use whatever class the logger is being injected in.

@Provides 
// OR @Inject on Logger constructor ... also, cannot have scoping
fun logger(injectionPoint: InjectionPoint): Logger {
  val name = injectionPoint.getAnnotation(LogName::class.java)
  return if (name != null) getLogger(name.value) else {
    getLogger(
      injectionPoint.methodParameter?.containingClass
        ?: injectionPoint.field?.declaringClass
    )
  }
}

As an example, assuming we have the above provision declared:

// Logger is injected with: 
// InjectionPoint [
//   type=value-parameter, 
//   name=logger,
//   method=<init>,
//   enclosingCls=MyClass, ...
// ]
@Inject
MyClass constructor(val logger: Logger)

and another case:

// Logger is injected with 
// InjectionPoint [
//   type=value-parameter, 
//   name=log,
//   method=providesOther
//   enclosingCls=MyProvisions, ...
// ]

MyOtherClass(val logger: Logger)

@Module
interface MyProvisions {
  @Provides
  fun provideOther(log: Logger) = MyOtherClass(logger)
}

It goes without saying that for any usage of InjectionPoint, that particular binding can not be scoped (and the provision method/constructor will be called everytime)

Just sharing as an alternative to discuss/consider.

[ZacSweers]

re: scoping, @chrisbanes these could never be scoped in your case either right? Or would you envision the scoped instance to be decorated too? Or the injected instance to be a decorated instance around some scoped source instance?

[chrisbanes]

For simplicity's sake I'd say to stay consistent with Spring, and make it so that the decorator/binding can not be scoped, but the receiver (MyClass in the example above) can be scoped.

[ZacSweers]

Few other questions that popped up

• What is LoggerDecoration used for?
• Can you have multiple decorators for the same type? If so, how does that behavior work?
  • Run all in a chain? If so, what determines order
  • Take first? If so, what determines priority?
• What's in BindingContext?
• Can you request it directly from the graph?

[mrmans0n]

Can you have multiple decorators for the same type? If so, how does that behavior work?

Yes. You'd annotate the "real" binding with the annotations linked to the decorator definitions. Order would be defined by the order in which you put the annotations on the binding.

As to how the decorators could be contributed to the graph, it could look similar to @Multibinds contributions (when in a separate contributing interface), or even like @ContributesToSet/Map annotations if done in-place in the decorator itself.

Like for example:

interface Logger { 
  fun log(text: String)
  fun withTag(tag: String)
}

annotation class WithTag // Maybe useful to also allow for simple params in the annotations?

@Inject
@BindingDecorator(WithTag::class) // associates the decorator annotation with the decorator 
class LoggerTagDecorator(private val myTag: Tag) : Decorator<Logger> {
  override fun decorate(source: Logger, ...): Logger = source.withTag(myTag)
}

annotation class WhateverTrace

@Inject
@BindingDecorator(WhateverTrace::class)
class TraceDecorator<T> : Decorator<T> { 
  override fun decorate(source: T, ...): T = whateverTrace { source )
}

Priority would be dictated by the order in which the annotations are used.

@ContributesTo(AppScope::class)
interface LoggerSubgraph {
  @WhateverTrace
  @WithTag
  @Provides
  fun myLogger(): Logger = LoggerImpl(...)
}

When instantiating the logger via the provider, it'd be like:

fun myLogger() {
  val loggerA = LoggerImpl(...) // original binding code 
  val loggerB = LoggerTagDecorator#decorate(loggerA)
  val loggerC = TraceDecorator#decorate(loggerB)
  return loggerC
}

And the binding used for Logger elsewhere would be loggerC.

We used this pattern all the time in twitter for android back in the day, with Scythe. Real usages examples were logging, tracing, analytics and view binding. It was really, really useful. Miss it dearly 😢

Can you request it directly from the graph?

Ambivalent on this, really. They'd be defined in the graph, and it'd be useful for the decorators themselves to be able to inject stuff from the graph as well. The aim for them is to annotate a binding transparently to the consumers of said binding. But as per if they could be consumed by another binding directly, I could see a case for disallowing that. But maybe there's some use case for that I'm missing?