README
¶
Documentation
¶
Index ¶
- type BridgeOption
- type Forwarder
- type ForwarderOption
- type GRPCProxy
- type Option
- type ProxyOption
- type ReflectionRouter
- func (r *ReflectionRouter) Add(name string, target string, opts ...RouterOption) (bool, error)
- func (r *ReflectionRouter) Remove(name string) bool
- func (r *ReflectionRouter) RouteGRPC(ctx context.Context) (grpcadapter.ClientConn, routing.GRPCRoute, error)
- func (r *ReflectionRouter) RouteHTTP(req *http.Request) (grpcadapter.ClientConn, routing.HTTPRoute, error)
- type Router
- type RouterOption
- type WebBridge
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BridgeOption ¶
type BridgeOption interface {
// contains filtered or unexported methods
}
BridgeOption configures the various bridging handlers used by WebBridge.
func WithDefaultMarshaler ¶
func WithDefaultMarshaler(m transcoding.Marshaler) BridgeOption
WithDefaultMarshaler allows setting a custom default marshaler for transcoding-based handlers, which will be used for requests which do not specify the Content-Type header. By default, transcoding.DefaultJSONMarshaler is used.
func WithMarshalers ¶
func WithMarshalers(marshalers []transcoding.Marshaler) BridgeOption
WithMarshalers allows using custom marshalers for transcoding-based handlers, which will be picked according to the content types they support. By default, transcoding.DefaultJSONMarshaler is used.
type Forwarder ¶ added in v0.1.0
type Forwarder struct {
// contains filtered or unexported fields
}
func NewForwarder ¶ added in v0.1.0
func NewForwarder(opts ...ForwarderOption) *Forwarder
func (*Forwarder) Forward ¶ added in v0.1.0
func (f *Forwarder) Forward(ctx context.Context, params grpcadapter.ForwardParams) error
type ForwarderOption ¶ added in v0.1.0
type ForwarderOption interface {
// contains filtered or unexported methods
}
type GRPCProxy ¶
type GRPCProxy struct {
// contains filtered or unexported fields
}
GRPCProxy is a basic gRPC proxy implementation which uses a routing.GRPCRouter to route incoming gRPC requests to the proper target services. It should be registered with a grpc.Server as a grpc.UnknownServiceHandler, which is precisely what the GRPCProxy.AsServerOption helper method returns.
This way of routing is used instead of relying on the grpc.ServiceRegistrar interface because GRPCProxy supports dynamic routing, which is not possible with a classic gRPC service, since it expects all gRPC services to be registered before launch.
Actual forwarding of routed calls is performed using a Forwarder, which is a separate entity so that it can be easily shared between the both GRPCProxy and WebBridge.
func NewGRPCProxy ¶
func NewGRPCProxy(router routing.GRPCRouter, opts ...ProxyOption) *GRPCProxy
NewGRPCProxy constructs a new *GRPCProxy with the given router and options. When no options are provided, sane defaults are used. The router is the only required parameter because without it there is no way to figure out over which gRPC connection requests must be proxied. By default, a new Forwarder is created with default options, but WithForwarder can be used to specify a custom call forwarder.
func (*GRPCProxy) AsServerOption ¶
func (s *GRPCProxy) AsServerOption() grpc.ServerOption
AsServerOption returns a grpc.ServerOption which can be used to register this proxy with a gRPC server as the handler to be used for all unknown services.
func (*GRPCProxy) StreamHandler ¶
func (s *GRPCProxy) StreamHandler(_ any, incoming grpc.ServerStream) error
StreamHandler allows proxying any incoming gRPC streams. It uses the router's RouteGRPC method with the incoming context to get a connection to the target and the description of the method. The actual forwarding is performed using the generic grpcadapter.ForwardServerToClient function.
type Option ¶
type Option interface {
RouterOption
ForwarderOption
ProxyOption
BridgeOption
}
Option configures common grpcbridge options, such as the logger.
func WithForwarder ¶ added in v0.1.0
func WithForwarder(forwarder grpcadapter.Forwarder) Option
WithForwarder configures the gRPC call forwarder to be used by GRPCProxy or WebBridge. By default each of these components would create their own Forwarder with default options.
The default grpcbridge Forwarder can be customized using [ForwarderOption]s, and passed using this option to NewGRPCProxy or NewWebBridge.
func WithLogger ¶
WithLogger configures the logger to be used by grpcbridge components. By default all logs are discarded.
Taking the full Logger interface allows you to configure all functionality however you want, however you can also use bridgelog.WrapPlainLogger to wrap a basic logger such as slog.Logger.
type ProxyOption ¶
type ProxyOption interface {
// contains filtered or unexported methods
}
ProxyOption configures gRPC proxying options.
type ReflectionRouter ¶
type ReflectionRouter struct {
// contains filtered or unexported fields
}
ReflectionRouter provides the default Router implementation used by grpcbridge. It uses the gRPC reflection Protocol to retrieve Protobuf contracts of target gRPC services added via the ReflectionRouter.Add method, which launches a new reflection.Resolver to perform polling for contract updates, represented as bridgedesc.Target structures, in the background.
Routing is performed using routing.ServiceRouter for gRPC requests based on the requested gRPC service name, and routing.PatternRouter for HTTP requests, supporting familiar pattern-based routing defined by Google's HTTP to gRPC Transcoding spec.
grpcadapter.AdaptedClientPool is used by the various components as a centralized gRPC client pool, providing support for features such as gRPC stream receiving/sending cancelation, waiting for client liveness and reconnections, and more.
func NewReflectionRouter ¶
func NewReflectionRouter(opts ...RouterOption) *ReflectionRouter
NewReflectionRouter constructs a new *ReflectionRouter with the given options. When no options are provided, the respective components are initialized with their default options.
func (*ReflectionRouter) Add ¶
func (r *ReflectionRouter) Add(name string, target string, opts ...RouterOption) (bool, error)
Add adds a new target by an arbitrary name and its gRPC target to the router with the possibility to override the default options. It returns true if a new target was added, and false if the target was already present, in which case all the components are updated to use the new options. Unless a custom connection constructor was specified using WithConnFunc, the target name syntax must adhere to standard gRPC rules defined in https://github.com/grpc/grpc/blob/master/doc/naming.md.
When add returns, it means that the target was added to the router components, but no guarantees are made as to when the target can actually be returned by the router. For example, the initial resolution of the target's Protobuf contracts can fail, in which case the routers will have no information available regarding the target's routes.
TODO(renbou): support option overriding. TODO(renbou): support modifications to existing targets. TODO(renbou): support using ServiceRouter for HTTP routing when simplified reflection resolving is enabled.
func (*ReflectionRouter) Remove ¶
func (r *ReflectionRouter) Remove(name string) bool
Remove removes a target by its name, stopping the reflection polling and closing the gRPC client, returning true if the target was present. No more requests will be routed to the target after this call returns, meaning it will block until all the components acknowledge the removal.
func (*ReflectionRouter) RouteGRPC ¶
func (r *ReflectionRouter) RouteGRPC(ctx context.Context) (grpcadapter.ClientConn, routing.GRPCRoute, error)
RouteGRPC uses the router's routing.ServiceRouter instance to perform service-based routing for gRPC-like requests. This routing method is used for gRPC proxying, as well as gRPC-Web bridging of HTTP and WebSockets.
func (*ReflectionRouter) RouteHTTP ¶
func (r *ReflectionRouter) RouteHTTP(req *http.Request) (grpcadapter.ClientConn, routing.HTTPRoute, error)
RouteHTTP uses the router's routing.PatternRouter instance to perform pattern-based routing for HTTP-originating requests, such as simple REST-like HTTP requests, WebSocket streams, and Server-Sent Event streams.
type Router ¶
type Router interface {
routing.GRPCRouter
routing.HTTPRouter
}
Router unifies the routing.GRPCRouter and routing.HTTPRouter interfaces, providing routing support for both GRPCProxy and WebBridge for all kinds of incoming calls. It is implemented by ReflectionRouter, which is the default routing component used by grpcbridge itself.
type RouterOption ¶
type RouterOption interface {
// contains filtered or unexported methods
}
RouterOption configures all the components needed to set up grpcbridge routing - gRPC reflection, client pools, logging.
func WithConnFunc ¶
func WithConnFunc(f func(target string, opts ...grpc.DialOption) (*grpc.ClientConn, error)) RouterOption
WithConnFunc returns a RouterOption that sets the function that will be used by grpcadapter.AdaptedClientPool for establishing new connections instead of grpc.NewClient.
func WithDialOpts ¶
func WithDialOpts(opts ...grpc.DialOption) RouterOption
WithDialOpts returns a RouterOption that sets the default gRPC dial options used by grpcadapter.AdaptedClientPool for establishing new connections. Multiple WithDialOpts calls can be chained together, and they will be aggregated into a single list of options.
func WithDisabledReflectionPolling ¶
func WithDisabledReflectionPolling() RouterOption
WithDisabledReflectionPolling returns a RouterOption that disables polling for proto changes, meaning that reflection.Resolver will retrieve the proto descriptors of target servers only once. For more granular control over when re-resolving happens, reflection.ResolverBuilder should be used to manually create resolvers.
func WithReflectionPollInterval ¶
func WithReflectionPollInterval(interval time.Duration) RouterOption
WithReflectionPollInterval returns a RouterOption that sets the interval at which reflection.Resolver will poll target gRPC servers for proto changes, by default equal to 5 minutes.
type WebBridge ¶
type WebBridge struct {
// contains filtered or unexported fields
}
WebBridge provides a single entrypoint for all web-originating requests which are bridged to target gRPC services with various applied transformations. It uses a Router which combines gRPC and HTTP routing to support both typical REST-like API (HTTP, WebSockets, Server-Sent Events), and modern gRPC-Web APIs. Meanwhile, forwarding of all incoming requests is performed using a Forwarder, which can be shared with GRPCProxy in order to unify how all outgoing gRPC streams are run.
WebBridge itself is no more than a thin wrapper around various handlers from the webbridge package, multiplexing incoming requests to the appropriate router based on headers such as Content-Type, Connection, and Upgrade. For more info, see the WebBridge.ServeHTTP method.
func NewWebBridge ¶
func NewWebBridge(router Router, opts ...BridgeOption) *WebBridge
NewWebBridge constructs a new *WebBridge with the given router and options. When no options are provided, the transcoding.StandardTranscoder and the underlying bridge handlers from webbridge will be initialized with their default options.
func (*WebBridge) ServeHTTP ¶
func (b *WebBridge) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements net/http.Handler and routes the request to the appropriate bridging handler according to these rules:
- WebSocket upgrades (Connection: Upgrade and Upgrade: WebSocket) are handled by webbridge.TranscodedWebSocketBridge.
- WebSocket upgrades with the Sec-WebSocket-Protocol header containing grpc-websockets are handled by webbridge.GRPCWebSocketBridge.
- HTTP gRPC-Web (Content-Type: application/grpc-web) requests are handled by webbridge.GRPCWebBridge.
- All other requests are handled by webbridge.TranscodedHTTPBridge.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
bench
Package bench is a reverse proxy.
|
Package bench is a reverse proxy. |
|
Package reflection provides a way to receive complete service descriptions via gRPC reflection suitable for use with grpcbridge's routers.
|
Package reflection provides a way to receive complete service descriptions via gRPC reflection suitable for use with grpcbridge's routers. |
|
Package routing provides routers for handling gRPC and HTTP requests in grpcbridge.
|
Package routing provides routers for handling gRPC and HTTP requests in grpcbridge. |
|
Package transcoding implements standard methods for transcoding between non-gRPC and gRPC request and response messages.
|
Package transcoding implements standard methods for transcoding between non-gRPC and gRPC request and response messages. |
|
Package webbridge contains implementations of various handlers for bridging web-originated requests to gRPC.
|
Package webbridge contains implementations of various handlers for bridging web-originated requests to gRPC. |