doc.go

// 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.
//
// # Protoc Plugin
//
// 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.
//
//	go install github.com/fullstorydev/grpchan/cmd/protoc-gen-grpchan
//	# If necessary, make sure its location is on your path like so:
//	#   export PATH=$PATH:$GOPATH/bin
//
// 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:
//
//	// A function with this signature is generated, for registering
//	// server handlers with the given server.
//	func Register<ServiceName>Server(s *grpc.Server, srv <ServiceName>Server) {
//	    s.RegisterService(&_<ServiceName>_serviceDesc, srv)
//	}
//
// The grpchan plugin produces a similarly named method that accepts the
// ServiceRegistry interface:
//
//	func RegisterHandler<ServiceName>(sr grpchan.ServiceRegistry, srv <ServiceName>Server) {
//	    s.RegisterService(&_<ServiceName>_serviceDesc, srv)
//	}
//
// 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:
//
//	protoc foo.proto --grpchan_out=legacy_stubs:./output/dir
//
// # Client-Side Channels
//
// 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.
//
// # Server-Side Service Registries
//
// 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.
package grpchan