Investigate Metro

[vRallev]

Investigate Metro as alternative to kotlin-inject. It provides a similar feature set and much improved build times. It's unclear if all features and platforms needed are supported and how our custom extensions can be built on top.

[vRallev]

I have a prototype ready and Metro is working well. It's conceptional very similar to kotlin-inject, but much better supported. The slow development speed of kotlin-inject with many bugs open is a real concern, e.g. version 0.8.0 released that introduced regressions. Since April no new version was released that would address these regressions. Therefore, App Platform should at least support kotlin-inject and Metro simultaneously and perhaps migrate to Metro long term entirely.

Adding Metro support within App Platform

Adopting Metro within App Platform requires a few refactorings, but mostly new additions. The setup for kotlin-inject will not break and using Metro is opt-in.

1. Extract shared annotations #105
   Extract shared annotations: The current setup is a little unfortunate. Annotations like @ContributesRenderer and qualifiers like @IoCoroutineDispatcher are part of the kotlin-inject modules. But these annotation can and should be shared to make a migration from kotlin-inject to Metro easier. A new module :di-common:public will be introduced and shared annotation will be moved there.
   
   Note that other types like @Inject, @SingleIn(AppScope::class) and @ContributesBinding are truly kotlin-inject specific and Metro ships with their own annotations. During the adoption of Metro imports of these classes need to be updated, e.g. import software.amazon.lastmile.kotlin.inject.anvil.ContributesTo changes to import dev.zacsweers.metro.ContributesTo.
2. Deprecate Scope.diComponent() and add Scope.kotlinInjectComponent() #106
   Change the name of Scope.diComponent() to Scope.kotlinInjectComponent(). The existing function will be deprecated, but still work. This makes it clear that the function is specific to kotlin-inject and later we can introduce Scope.metroDependencyGraph().
3. Metro Gradle DSL #109
   Add a new Gradle DSL to enable Metro enableMetro true, which is the equivalent to enableKotlinInject true. This DSL sets up Metro, but also KSP for our custom code generators.
4. Support Metro for shared DI qualifiers #110
   Update shared qualifiers like @IoCoroutineDispatcher to support Metro and kotlin-inject.
5. Introduce metroDependencyGraph() #113
   This new extension is the equivalent to kotlinInjectComponent() for kotlin-inject. It makes it easier to add and retrieve a Metro dependency graph from a Scope instance.
6. Custom code generators #115
   Create new custom code generators for shared APIs like @ContributesRenderer to support Metro. The output will be similar to the versions like kotlin-inject. Note that Metro recommends using KSP for custom extensions. Long term we should consider making them compiler plugins for performance reasons, but KSP will be fine for now.
7. Add Metro bindings for scopes and dispatchers #119
   We provide default bindings for coroutine dispatchers and coroutine scopes for kotlin-inject. We need to provide the same bindings for Metro.
8. Introduce @ContributesScoped for Metro #132
   Metro doesn't allow overriding the @ContributesBinding annotation similar to kotlin-inject-anvil. Therefore, we need to introduce @ContributesScoped for Metro.
9. Adopt Metro in the :sample app #127
   Move the :samples app from kotlin-inject to Metro. The :recipes app will keep using kotlin-inject for now.

Contributing Scoped

We have convenient setup to support Scoped with kotlin-inject. By default, the @ContributesBinding annotation only allows a single super type. If there are multiple super types, then you must declare the binding explicitly:

// That's fine
@ContributesBinding(AppScope::class)
class Abc : Def

// That will produce an error
@ContributesBinding(AppScope::class)
class Abc : Def, Ghj

// This is the fix
@ContributesBinding(AppScope::class, boundType = Def::class)
@ContributesBinding(AppScope::class, boundType = Ghj::class)
class Abc : Def, Ghj

Since Scoped is used so commonly, we're disabling the default code generator for @ContributesBinding and use our own version, that will not complain about the Scoped interface. Otherwise the logic is identical:

// That's fine
@ContributesBinding(AppScope::class)
class Abc : Def

// That's fine too
@ContributesBinding(AppScope::class)
class Abc : Def, Scoped

Metro doesn't provide this kind of integration and it's required to create a graph interface:

@Inject
@SingleIn(AppScope::class)
class Abc : Def, Scoped

@ContributesTo(AppScope::class)
interface AbcGraph {
  @Binds
  val Abc.bindDef: Def

  @Binds @IntoSet @ForScope(AppScope::class)
  val Abc.bindScoped: Scoped
}

That's a lot more code and it's probably best to introduce the custom annotation @ContributesScoped for Metro to restore the same functionality like before:

@Inject
@SingleIn(AppScope::class)
@ContributesScoped(AppScope::class)
class Abc : Def, Scoped

Note that, during a migration from from kotlin-inject to Metro, when you forget to change the annotation from @ContributesBinding to @ContributesScoped, then Metro will complain at compile time about the two super types, which makes the introduction of @ContributesScoped rather safe.

Metro and kotlin-inject on the classpath

App Platform modules like :renderer:public must import Metro and kotlin-inject at the same time to support both. This means even though an app only uses Metro or only used kotlin-inject, the other DI framework will be part of the runtime classpath, but not part of the compile classpath. This is safe, because annotations at compile time cannot be mixed up. Code minification tools like R8 can remove the dead code.

Metro problems

• There seem to be incremental compilation issues with other targets than JVM/Android: https://youtrack.jetbrains.com/issue/KT-75865
• I ran into incremental compilation issues even for JVM/Android: https://scans.gradle.com/s/xv2abmesyk2yc/console-log?page=1#L519 A reproducible sample is here: https://github.com/amzn/app-platform/tree/rwo/metro-ic-bug

Migrating from kotlin-inject to Metro

Once all changes are implemented and there's a need to migrate consuming projects from kotlin-inject to Metro, then I'd recommend to migrate the DI setup in one go rather than breaking it down into incremental steps. The migration is mostly mechanical and therefore safe. Errors will mostly happen at compile time and not runtime. Integration / QA tests should catch any regressions.

• It's strongly recommended to use the latest Kotlin and Metro version. Metro is a compiler plugin and tied to the compiler to a certain degree.
• Enable Metro in the Gradle DSL:

appPlatform {
    enableMetro true
}

• Change kotlin-inject specific imports to Metro:

me.tatarka.inject.annotations.IntoSet -> dev.zacsweers.metro.IntoSet
me.tatarka.inject.annotations.Provides -> dev.zacsweers.metro.Provides
software.amazon.lastmile.kotlin.inject.anvil.AppScope -> dev.zacsweers.metro.AppScope
software.amazon.lastmile.kotlin.inject.anvil.ContributesTo -> dev.zacsweers.metro.ContributesTo
software.amazon.lastmile.kotlin.inject.anvil.ForScope -> dev.zacsweers.metro.ForScope
software.amazon.lastmile.kotlin.inject.anvil.SingleIn -> dev.zacsweers.metro.SingleIn

• Update the final kotlin-inject components to Metro. The Metro docs explain the API very well. E.g. this component had to adopt a factory:

// Old:
@Component
@MergeComponent(AppScope::class)
@SingleIn(AppScope::class)
abstract class DesktopAppComponent(@get:Provides val rootScopeProvider: RootScopeProvider) :
  DesktopAppComponentMerged

// New:
@DependencyGraph(scope = AppScope::class)
@SingleIn(AppScope::class)
interface DesktopAppComponent {
  @DependencyGraph.Factory
  fun interface Factory {
    fun create(@Provides rootScopeProvider: RootScopeProvider): DesktopAppComponent
  }
}

• Change usages of addKotlinInjectComponent() (or the deprecated addDiComponent()) to addMetroDependencyGraph() and usages of kotlinInjectComponent() (or the deprecated diComponent()) to metroDependencyGraph().