Support for embedding types into mocks in the `matryer` template

[frozenbonito]

This issue is a feature proposal based on matryer/moq#226 (implemented in matryer/moq#227).

Some interfaces may have a mechanism to guarantee that a specific type is embedded.

For example, the <ServiceName>Server interface generated by protoc-gen-go-grpc contains an unexported mustEmbedUnimplemented<ServiceName>Server method, which can be implemented by embedding the Unimplemented<ServiceName>Server from the same package.

You can find more information here:
https://github.com/grpc/grpc-go/tree/master/cmd/protoc-gen-go-grpc#future-proofing-services

Real examples can be seen in the helloworld example of grpc-go:

• https://github.com/grpc/grpc-go/blob/941102b7811f/examples/helloworld/helloworld/helloworld_grpc.pb.go#L72-L76
• https://github.com/grpc/grpc-go/blob/941102b7811f/examples/helloworld/helloworld/helloworld_grpc.pb.go#L83-L88

To support this pattern, I propose a feature that allows specified types to be embedded in mocks.

The .mockery.yml would likely look like this:

packages:
  google.golang.org/grpc/examples/helloworld/helloworld:
    interfaces:
      GreeterServer:
        config:
          embed-types:
            - UnimplementedGreeterServer

Since the purpose is to embed types that implement unexported methods, the types used must belong to the same package as the interface.

[LandonTClipp]

Thanks for the issue. I'm not super familiar with protobuf in Go. My question about this particular type embedding thing is that it appears to be some way to implement an abstract base class? Is that correct? It seems to me that the intention is to allow users to add methods to type GreeterServer interface which will cause all real implementations of it to fail to compile since they would not immediately implement the new method.

The technical considerations on how we would implement this would depend on questions like:

• Would the template itself need full typing information? If so, mockery needs to parse the type being embedded.
• If the type does not need to be parsed, should we place this in template-data: to be a configuration parameter specific to the matryer template, or should it be a first-class config parameter?

I'm imagining that if full typing information is needed, we could introduce a separate config parameter that would tell mockery additional packages that need to be parsed, something like:

extra-packages:
  github.com/grpc/grpc-go/examples/helloworld/helloworld:
    types:
      UnimplementedGreeterServer:

This would be stored in a generic parameter provided to templates. Then the matryer template could be configured to use this as an embedded type:

template-data:
  embed-types:
    - github.com/grpc/grpc-go/examples/helloworld/helloworld.UnimplementedGreeterServer

I'm just spitballing some ideas.

[frozenbonito]

@LandonTClipp
Thank you for your detailed comment!

My question about this particular type embedding thing is that it appears to be some way to implement an abstract base class?

Yes, in the case of gRPC (protobuf), it is indeed an implementation of an abstract base class.
UnimplementedGreeterServer implements the GreeterServer interface, and all of its methods simply return an Unimplemented error.
By embedding this struct into their own GreeterServer implementation, users can automatically get default method implementations that return Unimplemented errors, without having to implement all the methods themselves.

It seems to me that the intention is to allow users to add methods to type GreeterServer interface which will cause all real implementations of it to fail to compile since they would not immediately implement the new method.

There seems to be a slight misunderstanding here.
Both GreeterServer and UnimplementedGreeterServer are automatically generated from a .proto file by protoc-gen-go-grpc.
When a new method is added to GreeterServer, the same method is also added to UnimplementedGreeterServer.
As a result, if a user embeds UnimplementedGreeterServer into their own implementation, they will continue to compile successfully even after the interface is updated, without needing to modify their code.
In gRPC, embedding UnimplementedGreeterServer is a recommended practice to ensure forward compatibility when methods are added to the GreeterServer interface.
This practice is enforced by the type system through the presence of an unexported method in the GreeterServer interface.

gRPC is just one example — the more general idea is to define unexported methods in an interface to act as a kind of "type marker."
This way, external packages are forced to embed a specific type in order to implement the interface properly.

Here is an additional example: A technique to distinguish multiple interfaces with the same method signature, based on their role, using a type marker.

package gen

type NameGenerator interface {
	Generate() (string, error)
	isNameGenerator()
}

type NameGeneratorImpl struct{}

func (NameGeneratorImpl) isNameGenerator() {}

type KeyGenerator interface {
	Generate() (string, error)
	isKeyGenerator()
}

type KeyGeneratorImpl struct{}

func (KeyGeneratorImpl) isKeyGenerator() {}

From outside the package, it would be implemented as follows:

var _ gen.NameGenerator = &generator{}

type generator struct {
	gen.NameGeneratorImpl
}

func (generator) Generate() (string, error) {
	return "name", nil
}

The implementation of NameGenerator cannot be used as a KeyGenerator due to the presence of the unexported method.
This ensures type safety.

Would the template itself need full typing information?

In my opinion, this is not necessary.
The type is simply embedded and is not used for any other purpose.
I think my pull request to matryer/moq can serve as a good reference:
matryer/moq#227

If the user specifies an incorrect type, the generated code will simply fail to compile, and the user will immediately notice the issue.

If the type does not need to be parsed, should we place this in template-data: to be a configuration parameter specific to the matryer template, or should it be a first-class config parameter?

I am not very familiar with testify's mock support, but I believe this functionality could likely be added to the testify template as well.
For interfaces like GreeterServer, embedding a type is essential when creating a mock.

While I initially proposed this as a feature specific to the matryer template, it seems valuable enough to consider making it a first-class config parameter.
In any case, it will be necessary to allow specifying different embedded types for each interface.

[LandonTClipp]

What you're saying makes a lot of sense, I'd be comfortable with adding support for something like this. I am more swayed by the fact that protobuf/gRPC are such prolific technologies and it would be good to support their idiosyncracies. I am going to think this over and give you a more thorough proposal at some point soon on the best way to meet your needs here.

[LandonTClipp]

Following up on this, the easiest way to do this is to add specific points in the template that would allow the user to inject arbitrary code at specific points, "plugins" as I'll call it. This would just be a string parameter in the template data.

template-data:
  struct-preamble: "gen.NameGeneratorImpl"

We would need an additional piece of the template that allows adding arbitrary imports:

template-data:
  struct-preamble: "gen.NameGeneratorImpl"
  add-import:
    - pkgPath: github.com/org/gen
      name: gen

This should be flexible enough to account for all scenarios I can image. I'm approving this work if someone wants to take it.