Add fx.Decorate

[sywhang]

This adds fx.Decorate, which lets you specify decorators to an fx app. A decorator can take in one or more dependencies that have already been Provided to the app, and produce one or more values that will be used as replacements in the object graph.

For example, suppose there is a simple app like this:

fx.New(
  fx.Provide(func() *Logger {
    return &Logger{Name: "logger"}
  }),
  fx.Invoke(func(l *Logger) {
    fmt.Println(l.Name)
  }),
)

Running this app will print "logger" on the console.

Now let us suppose a decorator was provided:

fx.New(
  fx.Provide(...), // Provide same function as above
  fx.Decorate(func(l *Logger) *Logger {
    return &Logger{Name: "decorated " + l.Name}
  }),
  fx.Invoke(...), // Invoke same function as above
)

The decorator here will take in the provided Logger and replace it with another logger whose Name is decorated logger. The Invoked function is then executed with this replacement value, so running this app will print "decorated logger" on the console.

In terms of implementation, a decorator is represented by the target decorator function and the call stack it was provided from, similar to a provider. module contains a list of decorators that were specified within its scope.

The dig dependency had to be updated to the latest master branch of Dig to ensure the fix for uber-go/dig#316 is in.

Following this PR, there are two additional pieces I will be adding:

1. An eventing system for fx.Decorate.
2. fx.Replace, which takes in a value instead of a function to replace a value in the object graph. This is similar to what fx.Supply is to fx.Provide.

This PR along with the two PRs above should make the long-awaited feature of graph modifications in fx finally possible.

---

Refs #653, #649, #825, uber-go/dig#230, GO-1203, GO-736

[codecov]

Codecov Report

Merging #833 (5a386a0) into master (d2c3431) will increase coverage by 0.04%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #833      +/-   ##
==========================================
+ Coverage   98.32%   98.36%   +0.04%     
==========================================
  Files          28       29       +1     
  Lines        1012     1041      +29     
==========================================
+ Hits          995     1024      +29     
  Misses         11       11              
  Partials        6        6              

Impacted Files	Coverage Δ
app.go	94.95% <100.00%> (+0.07%)	⬆️
decorate.go	100.00% <100.00%> (ø)
module.go	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d2c3431...5a386a0. Read the comment docs.

[abhinav]

Surprisingly simple after all of the other changes. No major concerns.
Minus the couple missing untested corner cases, I think this is good to go.

Please get a review from someone else on the team as well.

---

As an aside: 🎉 🎉 🎉

[abhinav]

This is fine as a test, but in the real world, I expect we will not nest "redis" under "testredis".

[abhinav]

nice

[abhinav]

😆

[akshayjshah]

Heck yeah! Nice work :)

[Ardagan]

Great work!
Is there any rough estimation when this will end up in released version of fx?

[sywhang]

Thanks @Ardagan! Our current estimate is to ship this by end of the month. We have some more work to do to integrate this with the fxevent package, and add fx.Replace (though there's already a PR out for that - #837). We also need to verify this doesn't break any Go services here at Uber.

After all those have been done, we should be good to go!

[sywhang]

@Ardagan it's been released now: https://github.com/uber-go/fx/releases/tag/v1.17.0