Package Usage: go: github.com/fullstorydev/grpchan
Package grpchan provides an abstraction for a gRPC transport, called a
Channel. The channel is more general than the concrete *grpc.ClientConn
and *grpc.Server types provided by gRPC. It allows gRPC over alternate
substrates and includes sub-packages that provide two such alternatives:
in-process and HTTP 1.1.
The key type in this package is an alternate implementation of
grpc.ServiceRegistrar interface that allows you to accumulate service
registrations, for use with an implementation other than *grpc.Server.
This repo also includes a deprecated protoc plugin. This is no longer
needed now that the standard protoc-gen-go-grpc plugin generates code that
uses interfaces: grpc.ClientConnInterface and grpc.ServiceRegistrar. In
older versions, the generated code only supported concrete types
(*grpc.ClientConn and *grpc.Server) so this repo's protoc plugin would
generate alternate code that used interfaces (and thus supported other
concrete implementations).
Continued use of the plugin is only to continue supporting code that
uses the functions generated by it.
To use the protoc plugin, you need to first build it and make sure its
location is in your PATH.
When you invoke protoc, include a --grpchan_out parameter that indicates
the same output directory as used for your --go_out parameter. Alongside
the *.pb.go files generated, the grpchan plugin will also create
*.pb.grpchan.go files.
In older versions of the Go plugin (when emitting gRPC code), a server
registration function for each RPC service defined in the proto source files
was generated that looked like so:
The grpchan plugin produces a similarly named method that accepts the
ServiceRegistry interface:
A new transport can then be implemented by just implementing two interfaces:
grpc.ClientConnInterface for the client side and grpchan.ServiceRegistry for
the server side.
The alternate method also works just fine with *grpc.Server as it implements
the ServiceRegistry interface.
NOTE: If your have code relying on New<ServiceName>ChannelClient methods that
earlier versions of this package produced, they can still be generated by passing
a "legacy_stubs" option to the plugin. Example:
The client-side implementation of a transport is done with just the two
methods in grpc.ClientConnInterface: one for unary RPCs and the other for
streaming RPCs.
Note that when a unary interceptor is invoked for an RPC on a channel that
is *not* a *grpc.ClientConn, the parameter of that type will be nil.
Not all client call options will make sense for all transports. This repo
chooses to ignore call options that do not apply (as opposed to failing
the RPC or panicking). However, several call options are likely important
to support: those for accessing header and trailer metadata. The peer,
per-RPC credentials, and message size limits are other options that are
reasonably straight-forward to apply to other transports. But the other
options (dealing with on-the-wire encoding, compression, etc) may not be
applicable.
The server-side implementation of a transport must be able to invoke
method and stream handlers for a given service implementation. This is done
by implementing the grpc.ServiceRegistrar interface. When a service is
registered, a service description is provided that includes access to method
and stream handlers. When the transport receives requests for RPC operations,
it in turn invokes these handlers. For streaming operations, it must also
supply a grpc.ServerStream implementation, for exchanging messages on the
stream.
Note that the server stream's context will need a custom implementation of
the grpc.ServerTransportStream in it, too. Sadly, this interface is just
different enough from grpc.ServerStream that they cannot be implemented by
the same type. This is particularly necessary for unary calls since this is
how a unary handler indicates what headers and trailers to send back to the
client.
4 versions
Latest release: over 3 years ago
36 dependent packages
View more package details: https://packages.ecosystem.code.gouv.fr/registries/proxy.golang.org/packages/github.com/fullstorydev/grpchan