[👷] Road to v2 🚀

[samber]

Hi there 👋,

Over the past 18 months, many of you reported bugs or provided valuable feedback on various aspects of this project, such as error handling, debugging, invocation API, documentation, and more... Thanks for your contributions! 🙌

Work on this library has provided me with significant learning opportunities and now I believe it's time to advance this project further.

Most of the work for v2 has been done already. I'm targeting the end of January for a release. It will depend on additional requirements.

go get -u github.com/samber/do/[email protected]

Scope

This milestone will lead to major improvement: Scope.

A Scope was previously referred to as an Injector and can be viewed as a module of an application, with restricted visibility. I advocate for each project possessing a RootScope for common code, and shifting business logic to dedicated Scopes.

The Scopes are structured with a parent (RootScope or other Scope), numerous Services, and potentially a few children Scopes as well.

RootScope owns options and is the only Scope that supports cloning.

Services from a Scope can invoke Services available locally or in parent Scopes. Therefore, a single Service can be instantiated many times in different branches of the Scope tree, without conflict.

Scope will be almost invisible to developers: services will keep using Injector API without awareness of the underlying implementation, whether it's a RootScope, Scope or VirtualScope.

A chain of Service invocation will instantiate many VirtualScope, in order to track dependency cycles.

A debugging toolchain has been added to illustrate the service dependency chain and Scope tree.

Checklist

The library has been almost entirely recoded, but most of do@v1 API has been preserved (see breaking changes below).

• Scope (see above)
• Circular dependency detection 🔥 (Detect circular dependency and panic #2)
• Easier debugging with DAG representation of service dependencies and Scopes tree 🥵 (Improvements on dependency graph #3)
• Improved implicit service naming and reduced conflict risks (discussed in refactor: including package path in implicit service name #13 - see https://github.com/samber/go-type-to-string)
• Transient services: new instantiation on each invocation. (proposal: Add factory provide mode  #36)
• No more inappropriate panics
• Handling of panics triggered by Providers -> transformed into Go error
• Better consistency in error format
• A stack trace is collected on Service invocation (not visible to developers for now)
• Support more Healthcheck + Shutdown interfaces (with or without error and context)
• Thread-safe service invocation 😩
• Thread-safe service shutdown 😩
• Reduce the number of // @TODO in the code
• Cleanup the dirty code
• Rename package with /v2 suffix (and everywhere in the doc)
• Create a dedicated v1 branch for LTS

To be challenged

• Service invocation based on Go field tags (discussed in [proposal] Auto magically inject services #28)
• Service aliasing (discussed in Is there an equivalent to dig.As() ? #41 & Anonymous Invocation #25)
• Parallel service healthcheck
• Parallel service shutdown
• Healthcheck and shutdown timeout -> pass context.WithTimeout(10*time.Second) instead
• Remove some ShutdownXXX helpers ?
• Add HTTP routes for debugging
• Package registration
• Shutdown time (see Proposal: do.Shutdown returning shutdown time ? #32)
• Shutdown timeout at service level
• slog as logger (breaking change)
• Value groups (discussed in Add support of Value Groups #52)
• Export of service DAG to dot files?
• Flamegraph for easy debugging (discussed in Troubleshooting: flamegraph of service invocation #53)

More existing issues might be added to the v2 milestone.

Documentation

• Revamp README
• Evaluate the need for an external documentation (External website for documentation (starting v2) #46)
• Provide more examples in example directory
• Provide more examples in xxxx_test_examples.go files + playground (Add toy examples in Go playground sandboxes #77)
• Provide more examples in go playground (Add toy examples in Go playground sandboxes #77)
• Add a comment on top of each public method
• Cleanup dead code or old comments
• Add a link to the doc of do@v1
• v2 upgrade instruction
• Create an application templates (Create application templates #47)
• On Vercel, move the main branch from v2-🚀 to master
• Add GenAI search engine? 😁
• Versioning
• Replace glossary page by docusaurus-terminology -> Docusaurus v3 support? grnet/docusaurus-terminology#24

Testing

Code coverage has been improved compared to v1. 😍

• Reach 80% code coverage
• Reach 85% code coverage
• Reach 90% code coverage
• See // @TODO in xxx_test.go files
• More tests on nested scopes (clone, service invocation...)
• More tests on virtual scopes

Coverage:

• 2023-10-23: 83%
• 2023-12-30: 87%
• 2024-05-07: 89%

Breaking changes

• Injector struct turned into an interface 😕
• ListProvidedServices and ListInvokedServices now return 2 do.Edge arrays.
• No more panic propagation on Provider error 😛
• Service implicit names have been changed. BTW, you should never manipulate it! Eg: *mypkg.MyService -> *github.com/samber/example.MyService.
• injector.ShutdownOnSignals and injector.ShutdownOnSIGTERM now return (os.Signal, error)

If you consider the API must be improved, please write a comment on this issue. No breaking change will be done in v2 minor releases. And I hope v2 is going to be the last major version.

[samber]

Debugging

Here is the output of do.ExplainService[*MyService](Injector) 👇

Scope ID: scope-id-123
Scope name: scope-child
Service: SERVICE-E
Service type: lazy
Service build time: 1s
Invoked: /home/samber/project/github.com/samber/do/di_explain_test.go:fakeProvider5:38

Dependencies:
* SERVICE-D from scope scope-child
  * SERVICE-C1 from scope scope-child
    * SERVICE-B from scope [root]
      * SERVICE-A1 from scope [root]
      * SERVICE-A2 from scope [root]
  * SERVICE-C2 from scope scope-child
    * SERVICE-B from scope [root]
      * SERVICE-A1 from scope [root]
      * SERVICE-A2 from scope [root]

Dependents:
* SERVICE-F from scope scope-child
  * SERVICE-G from scope scope-child

Here is the output of do.ExplainInjector(Injector) 👇

Scope ID: scope-id-root
Scope name: [root]

DAG:

\_ [root] (ID: scope-id-root)
    * 😴 SERVICE-A1
    * 😴 SERVICE-A2
    * 😴 SERVICE-B
    |
    |
     \_ scope-0 (ID: scope-id-0)
         |
         |
         |\_ scope-1a (ID: scope-id-1a)
         |    * 😴 SERVICE-C1
         |    * 😴 SERVICE-C2
         |    * 😴 SERVICE-D
         |    * 😴 SERVICE-E
         |    * 🔁 SERVICE-EAGER-VALUE
         |    |
         |    |
         |    |\_ scope-2a (ID: scope-id-2a)
         |    |    * 😴 SERVICE-LAZY-HEALTH 🏥
         |    |    * 🏭 SERVICE-TRANSIANT-SIMPLE
         |    |     
         |    |
         |     \_ scope-2b (ID: scope-id-2b)
         |         * 😴 SERVICE-LAZY-SHUTDOWN 🙅
         |          
         |
          \_ scope-1b (ID: scope-id-1b)
              * 😴 SERVICE-F

The emoji prefix indicates the service is either Lazy, Eager, or Transiant. The EOL emoji indicates the service implements do.HealthChecker and/or do.Shutdowner.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 90.15352% with 186 lines in your changes missing coverage. Please review.

Project coverage is 87.56%. Comparing base (9831445) to head (ec49e08).
Report is 15 commits behind head on master.

Files with missing lines	Patch %	Lines
service_alias.go	63.93%	40 Missing and 4 partials ⚠️
virtual_scope.go	40.47%	25 Missing ⚠️
scope.go	93.44%	17 Missing and 7 partials ⚠️
service_eager.go	75.67%	14 Missing and 4 partials ⚠️
root_scope.go	87.40%	17 Missing ⚠️
invoke.go	94.00%	8 Missing and 4 partials ⚠️
di.go	87.17%	10 Missing ⚠️
stacktrace/stacktrace.go	86.88%	5 Missing and 3 partials ⚠️
service_lazy.go	93.20%	5 Missing and 2 partials ⚠️
di_explain.go	97.73%	5 Missing and 1 partial ⚠️
... and 5 more

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #45      +/-   ##
==========================================
- Coverage   88.83%   87.56%   -1.27%     
==========================================
  Files           6       23      +17     
  Lines         430     2043    +1613     
==========================================
+ Hits          382     1789    +1407     
- Misses         40      225     +185     
- Partials        8       29      +21     

Flag	Coverage Δ
unittests	87.56% <90.15%> (-1.27%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[GreyXor]

Hello, that's a really great news! Thanks a lot.
I can't use the branch directly atm

go get github.com/samber/do@v2-🚀
go: github.com/samber/do@v2-🚀: invalid version: version "v2-🚀" invalid: disallowed version string

workaround:
go get github.com/samber/do@d722cd623c629ebfaf5b2032f998d3ae1b176009

[danilobuerger]

It would be nice to provide context o healthcheck and shutdown.

[samber]

@danilobuerger can you elaborate on your use case?

[danilobuerger]

@danilobuerger can you elaborate on your use case?

Sure, I want to provide a context to be able to use cancellation.

[GreyXor]

My last workaround don't work anymore. I've followed this guide https://github.com/samber/do/blob/v2-%F0%9F%9A%80/MIGRATION-V1-TO-V2.md and also the v2 readme : https://github.com/samber/do/blob/v2-%F0%9F%9A%80/README.md
But I get this error go: github.com/samber/do@v2: no matching versions for query "v2" when I run go get github.com/samber/do@v2

[samber]

I renamed the package samber/do to samber/do/v2, so the latest command is: go get github.com/samber/do/v2@a158d2d9f84b4a1973db49e959e476aca996e04a

Adding an emoji in the branch name was definitely a bad idea 😆

[GreyXor]

I renamed the package samber/do to samber/do/v2, so the latest command is: go get github.com/samber/do/v2@a158d2d9f84b4a1973db49e959e476aca996e04a

Adding an emoji in the branch name was definitely a bad idea 😆

Not your fault, go get should be UTF-8 ready imho.

[GreyXor]

@samber, Since I've designed the ShutdownOnSignals* function to accommodate any signals, we've maintained the *OnSIGTERM for compatibility purposes. However, now that we have the option to revise the API (by breaking it), I believe all the shutdownOnSIGTERMs are unnecessary.

I therefore propose deleting ShutdownOnSIGTERM, ShutdownOnSIGTERMWithContext, ShutdownOnSIGTERMOrInterrupt and ShutdownOnSIGTERMOrInterruptWithContext.

What do you think about ? I feel that they are redundant

[danilobuerger]

One thing I noticed is that the pattern of Accept interfaces, return structs doesnt seem possible:

type EngineService interface{}

func NewEngineService(i *do.Injector) (*engineServiceImplem, error) {
    return &engineServiceImplem{}, nil
}

type engineServiceImplem struct {}

Later this fails:

do.Provide[EngineService](injector, NewEngineService)

[samber]

@danilobuerger v2 will make it possible to respect this pattern:

do.As[*engineServiceImplem, EngineService](injector)
// or
do.InvokeAs[EngineService](injector)

See the function comments for the full explanation.

[samber]

We need to push this PR forward.

I created a list of issues that must be addressed before v2 release:

Design:

• InvokeAs problems #75
• Proposal: do.Shutdown returning shutdown time ? #32
• Add support of Value Groups #52 + Invoke multiple services satisfying the interface #29 + Proposal: allow multiple implementation for the same interface and being able to return all them #33

Bugs:

• V2: Bug in parallel shutdown #76
• InvokeAs problems #75

Tasks/Features:

• Transform hooks into slices of hooks #71
• Proposal: do.Shutdown returning shutdown time ? #32
• Add support of Value Groups #52 + Invoke multiple services satisfying the interface #29 + Proposal: allow multiple implementation for the same interface and being able to return all them #33

Doc:

• Add toy examples in Go playground sandboxes #77
• Create application templates #47

[GreyXor]

Hello @samber,

Healthcheck not working properly when calling do.DefaultRootScope.HealthCheck() from Echo router API.
I have this /healthcheck endpoint that should return the healthcheck errors list. I couldn't make an example code with the problem.
I just lose the Step-by-step debugger thread here: https://github.com/samber/do/blob/v2-%F0%9F%9A%80/scope.go#L189.

Seems to work as expected when it's called from my main thread and not from my API (in my main.go for exemple)

but this, not working

func (a API) GetHealthcheck(_ context.Context, _ openapi.GetHealthcheckRequestObject) (openapi.GetHealthcheckResponseObject, error) {
	err := do.DefaultRootScope.HealthCheck()
	// never reached
	return openapi.GetHealthcheck200JSONResponse{}, nil
}