admin/wire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

goose: rename module to provider set

Browse Source 
It is more descriptive of what it is, as well as avoids confusion with
Go modules in the versioning sense.

Reviewed-by: Herbie Ong <herbie@google.com>
This commit is contained in:
Ross Light
2018-03-28 17:31:32 -07:00
parent 26c8618466
commit 4abf804032
2 changed files with 134 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
README.md
View File

@@ -14,10 +14,10 @@ might have hand-written.
The primary mechanism in goose is the **provider**: a function that can
produce a value, annotated with the special `goose:provide` directive. These
functions are ordinary Go code and live in packages.
functions are otherwise ordinary Go code.
```go
package module
package foobarbaz
type Foo int
@@ -29,18 +29,19 @@ func ProvideFoo() Foo {
}
```
Providers are always part of a **module**: if there is no module name specified
on the `//goose:provide` line, then `Module` is used.
Providers are always part of a **provider set**: if there is no provider set
named on the `//goose:provide` line, then the provider is added to the provider
set with the name `Module`.
Providers can specify dependencies with parameters:
```go
package module
// goose:provide SuperModule
package foobarbaz
type Bar int
// goose:provide SuperSet
// ProvideBar returns a Bar: a negative Foo.
func ProvideBar(foo Foo) Bar {
return Bar(-foo)
@@ -50,7 +51,7 @@ func ProvideBar(foo Foo) Bar {
Providers can also return errors:
```go
package module
package foobarbaz
import (
"context"
@@ -59,7 +60,7 @@ import (
type Baz int
// goose:provide SuperModule
// goose:provide SuperSet
// ProvideBaz returns a value if Bar is not zero.
func ProvideBaz(ctx context.Context, bar Bar) (Baz, error) {
@@ -70,20 +71,33 @@ func ProvideBaz(ctx context.Context, bar Bar) (Baz, error) {
}
```
Modules can import other modules. To import `Module` in `SuperModule`:
Provider sets can import other provider sets. To add `Module` in
`SuperSet`:
```go
// goose:import SuperModule Module
// goose:import SuperSet Module
```
You can also import provider sets in another package, provided that you have a
Go import for the package:
```go
// goose:import SuperSet "example.com/some/other/pkg".OtherSet
```
A provider set reference is an optional import qualifier (either a package name
or a quoted import path, as seen above) ending with a dot, followed by the
provider set name.
### Injectors
An application can use these providers by declaring an **injector**: a
generated function that calls providers in dependency order.
An application wires up these providers with an **injector**: a function that
calls providers in dependency order. With goose, you write the injector's
signature, then goose generates the function's body.
An injector is declared by writing a function declaration without a body in a
file guarded by a `gooseinject` build tag. Let's say that the above providers
were defined in a package called `example.com/module`. The following would
were defined in a package called `example.com/foobarbaz`. The following would
declare an injector to obtain a `Baz`:
```go
@@ -94,22 +108,21 @@ package main
import (
"context"
"example.com/module"
"example.com/foobarbaz"
)
// goose:use module.SuperModule
// goose:use foobarbaz.SuperSet
func initializeApp(ctx context.Context) (module.Baz, error)
func initializeApp(ctx context.Context) (foobarbaz.Baz, error)
```
Like providers, injectors can be parameterized on inputs (which then get sent to
providers) and can return errors. The `goose:use` directive specifies the
modules to use in the injection. Both `goose:use` and `goose:import` use the
same syntax for referencing modules: an optional import qualifier (either a
package name or a quoted import path) with a dot, followed by the module name.
For example: `SamePackageModule`, `foo.Bar`, or `"example.com/foo".Bar`.
providers) and can return errors. Each `goose:use` directive specifies a
provider set to use in the injection. An injector can have one or more
`goose:use` directives. `goose:use` directives use the same syntax as
`goose:import` to reference provider sets.
You can generate the injector using goose:
You can generate the injector by invoking goose in the package directory:
```
goose
@@ -125,8 +138,8 @@ go generate
(Adding the line to the injection declaration file will be silently ignored by
`go generate`.)
goose will produce an implementation of the injector that looks something like
this:
goose will produce an implementation of the injector in a file called
`goose_gen.go` that looks something like this:
```go
// Code generated by goose. DO NOT EDIT.
@@ -136,13 +149,13 @@ this:
package main
import (
"example.com/module"
"example.com/foobarbaz"
)
func initializeApp(ctx context.Context) (module.Baz, error) {
foo := module.ProvideFoo()
bar := module.ProvideBar(foo)
baz, err := module.ProvideBaz(ctx, bar)
func initializeApp(ctx context.Context) (foobarbaz.Baz, error) {
foo := foobarbaz.ProvideFoo()
bar := foobarbaz.ProvideBar(foo)
baz, err := foobarbaz.ProvideBaz(ctx, bar)
if err != nil {
return 0, err
}
@@ -159,8 +172,9 @@ written code is just normal Go code, and can be used without goose.
## Best Practices
goose is still not mature yet, but guidance that applies to Dagger generally
applies to goose as well. In particular, when thinking about how to group a
package of providers, follow the same [guidance](https://google.github.io/dagger/testing.html#organize-modules-for-testability) as Dagger:
applies to goose as well. In particular, when thinking about how to group
providers into sets, follow the same [guidance](https://google.github.io/dagger/testing.html#organize-modules-for-testability)
as Dagger (provider sets are called modules in Dagger/Guice):
> Some [...] bindings will have reasonable alternatives, especially for
> testing, and others will not. For example, there are likely to be
@@ -174,30 +188,31 @@ package of providers, follow the same [guidance](https://google.github.io/dagger
>
> Once you’ve classified your bindings into [...] bindings with reasonable
> alternatives [and] bindings without reasonable alternatives, consider
> arranging them into packages like this:
> arranging them into provider sets like this:
>
> - One [package] for each [...] binding with a reasonable alternative. (If
> you are also writing the alternatives, each one gets its own [package].) That
> [package] contains exactly one provider.
> - All [...] bindings with no reasonable alternatives go into [packages]
> - One [provider set] for each [...] binding with a reasonable alternative.
> (If you are also writing the alternatives, each one gets its own [provider
> set].) That [provider set] contains exactly one provider.
> - All [...] bindings with no reasonable alternatives go into [provider sets]
> organized along functional lines.
> - The [packages] should each include the no-reasonable-alternative [packages] that
> require the [...] bindings each provides.
> - The [provider sets] should each include the no-reasonable-alternative
> [provider sets] that require the [...] bindings each provides.
One goose-specific practice though: create one-off types where in Java you
would use a binding annotation.
would use a binding annotation. For example, if you need to pass a string
through the dependency graph, you would create a wrapping type:
```go
type MySQLConnectionString string
```
## Future Work
- The names of imports and provider results in the generated code are not
actually as nice as shown above. I'd like to make them nicer in the
common cases while ensuring uniqueness.
- I'd like to support optional and multiple bindings.
- At the moment, the entire transitive closure of all dependencies are read
for providers. It might be better to have provider imports be opt-in, but
that seems like too many levels of magic.
- Support for map bindings.
- Support for multiple provider outputs.
- Currently, all dependency satisfaction is done using identity. I'd like to
use a limited form of assignability for interface types, but I'm unsure
how well this implicit satisfaction will work in practice.
- Errors emitted by goose are not very good, but it has all the information
it needs to emit better ones.