tunnel

Documentation

Index

• func TunnelMetadataFromIncomingContext(ctx context.Context) (metadata.MD, bool)
• func TunnelMetadataFromOutgoingContext(ctx context.Context) (metadata.MD, bool)
• func WithTunnelChannel(ch *TunnelChannel) grpc.CallOption
• type ReverseClientConnInterface
• type ReverseTunnelServer
  • func NewReverseTunnel(conn *grpc.ClientConn) *ReverseTunnelServer
  • func NewReverseTunnelServer(stub rpc2.TunnelServiceClient) *ReverseTunnelServer
  • func (s *ReverseTunnelServer) GracefulStop()
  • func (s *ReverseTunnelServer) RegisterService(desc *grpc.ServiceDesc, srv interface{})
  • func (s *ReverseTunnelServer) Serve(ctx context.Context, opts ...grpc.CallOption) (started bool, err error)
  • func (s *ReverseTunnelServer) Stop()
• type TunnelChannel
  • func NewChannel(stream rpc2.TunnelService_ConnectClient) TunnelChannel
  • func TunnelChannelFromContext(ctx context.Context) TunnelChannel
• type TunnelServiceHandler
  • func NewTunnelServiceHandler(options TunnelServiceHandlerOptions) *TunnelServiceHandler
  • func (s *TunnelServiceHandler) AllReverseTunnels() []TunnelChannel
  • func (s *TunnelServiceHandler) AsChannel() ReverseClientConnInterface
  • func (s *TunnelServiceHandler) InitiateShutdown()
  • func (s *TunnelServiceHandler) KeyAsChannel(key interface{}) ReverseClientConnInterface
  • func (s *TunnelServiceHandler) RegisterService(desc *grpc.ServiceDesc, srv interface{})
  • func (s *TunnelServiceHandler) Service() rpc.TunnelServiceServer
• type TunnelServiceHandlerOptions

Functions

func TunnelMetadataFromIncomingContext

func TunnelMetadataFromIncomingContext(ctx context.Context) (metadata.MD, bool)

TunnelMetadataFromIncomingContext provides server-side access to the request metadata used to open a tunnel. This can be used from server interceptors or handlers that are handling tunneled requests in a tunnel.

func TunnelMetadataFromOutgoingContext

func TunnelMetadataFromOutgoingContext(ctx context.Context) (metadata.MD, bool)

TunnelMetadataFromOutgoingContext provides client-side access to the request metadata used to open a forward tunnel. This can be used from client interceptors that are processing tunneled requests in a forward tunnel.

For client interceptors in a reverse tunnel, you can use metadata.FromOutgoingContext with the context passed to the interceptor or handler.

func WithTunnelChannel

func WithTunnelChannel(ch *TunnelChannel) grpc.CallOption

WithTunnelChannel provides the caller access to the specific TunnelChanel that was used to send a tunneled RPC. This is similar to using TunnelChannelFromContext except it can be used with unary RPCs, where the invoker never has access to values added to the request context. When the RPC completes, the given location will be updated with the channel that handled the request. If the channel that handled the request was not a tunnel, the location is left unchanged.

The pointer must point to an allocated location. Passing a nil pointer will result in a panic when an RPC is invoked with the returned option.

Types

type ReverseClientConnInterface

type ReverseClientConnInterface interface {
	grpc.ClientConnInterface
	// Ready returns true if this channel is backed by at least one reverse
	// tunnel. Returns false if there are no active, matching reverse tunnels.
	Ready() bool
	// WaitForReady blocks until either this channel is ready or the given
	// context is cancelled or times out. If the latter, the context error is
	// returned. Otherwise, nil is returned. If the channel is immediately
	// ready, this will not block and will immediately return nil.
	WaitForReady(context.Context) error
}

ReverseClientConnInterface is an RPC channel that reports if there are any active reverse tunnels. If there are no available tunnels, the channel will not be ready. When tunnels are ready, RPCs will be balanced across all such tunnels in a round-robin fashion.

type ReverseTunnelServer

type ReverseTunnelServer struct {
	// contains filtered or unexported fields
}

func NewReverseTunnel

func NewReverseTunnel(conn *grpc.ClientConn) *ReverseTunnelServer

func NewReverseTunnelServer

func NewReverseTunnelServer(stub rpc2.TunnelServiceClient) *ReverseTunnelServer

func (*ReverseTunnelServer) GracefulStop

func (s *ReverseTunnelServer) GracefulStop()

func (*ReverseTunnelServer) RegisterService

func (s *ReverseTunnelServer) RegisterService(desc *grpc.ServiceDesc, srv interface{})

func (*ReverseTunnelServer) Serve

func (s *ReverseTunnelServer) Serve(ctx context.Context, opts ...grpc.CallOption) (started bool, err error)

func (*ReverseTunnelServer) Stop

func (s *ReverseTunnelServer) Stop()

type TunnelChannel

type TunnelChannel interface {
	grpc.ClientConnInterface

	// Close shuts down the channel, cancelling any outstanding operations and
	// making it unavailable for subsequent operations. For forward tunnels,
	// this also closes the underlying stream.
	//
	// Channels for forward tunnels are implicitly closed if the context used
	// to create the underlying stream is cancelled or times out.
	Close()
	// Context returns the context for this channel. This context is derived
	// from the context associated with the underlying stream.
	//
	// For forward tunnels, this is a client context. So it will include
	// outgoing metadata for the request headers that were used to open the
	// tunnel. For reverse tunnels, this is a server context.  So that request
	// metadata will be available as incoming metadata.
	Context() context.Context
	// Done returns a channel that can be used to await the channel closing.
	Done() <-chan struct{}
	// Err returns the error that caused the channel to close. If the channel
	// is not yet closed, this will return nil.
	Err() error
}

func NewChannel

func NewChannel(stream rpc2.TunnelService_ConnectClient) TunnelChannel

func TunnelChannelFromContext

func TunnelChannelFromContext(ctx context.Context) TunnelChannel

TunnelChannelFromContext returns the TunnelChannel that is handling the given request context. If the given context is not a client-side request context, or if the channel for the request is not a tunnel, this will return nil.

type TunnelServiceHandler

type TunnelServiceHandler struct {
	// contains filtered or unexported fields
}

func NewTunnelServiceHandler

func NewTunnelServiceHandler(options TunnelServiceHandlerOptions) *TunnelServiceHandler

func (*TunnelServiceHandler) AllReverseTunnels

func (s *TunnelServiceHandler) AllReverseTunnels() []TunnelChannel

AllReverseTunnels returns the set of all currently active reverse tunnels.

func (*TunnelServiceHandler) AsChannel

func (s *TunnelServiceHandler) AsChannel() ReverseClientConnInterface

func (*TunnelServiceHandler) InitiateShutdown

func (s *TunnelServiceHandler) InitiateShutdown()

func (*TunnelServiceHandler) KeyAsChannel

func (s *TunnelServiceHandler) KeyAsChannel(key interface{}) ReverseClientConnInterface

KeyAsChannel returns a channel that can be used for issuing RPCs back to clients over reverse tunnels whose affinity key matches the given value. If no reverse tunnels that match are established, RPCs will fail with "Unavailable" errors. If no affinity key function was provided when the handler was created, the only key available will be the nil interface.

The returned channel will use a round-robin strategy to select from matching reverse tunnels for any given RPC.

This method panics if the handler was created with an option to disallow the use of reverse tunnels.

func (*TunnelServiceHandler) RegisterService

func (s *TunnelServiceHandler) RegisterService(desc *grpc.ServiceDesc, srv interface{})

func (*TunnelServiceHandler) Service

func (s *TunnelServiceHandler) Service() rpc.TunnelServiceServer

type TunnelServiceHandlerOptions

type TunnelServiceHandlerOptions struct {
	// If reverse tunnels are allowed, this callback may be configured to
	// receive information when clients open a reverse tunnel.
	OnReverseTunnelOpen func(TunnelChannel) error
	// If reverse tunnels are allowed, this callback may be configured to
	// receive information when reverse tunnels are torn down.
	OnReverseTunnelClose func(TunnelChannel)
	// Optional function that accepts a reverse tunnel and returns an affinity
	// key. The affinity key values can be used to look up outbound channels,
	// for targeting calls to particular clients or groups of clients.
	//
	// The given TunnelChannel has a context which can be used to query for the
	// identity of the remote peer. Functions like peer.FromContext will return
	// the peer that opened the reverse tunnel, and metadata.FromIncomingContext
	// will return the request headers used to open the reverse tunnel. If any
	// server interceptors ran when the tunnel was opened, then any values they
	// store in the context is also available.
	AffinityKey func(TunnelChannel) any
}