github.com/hashicorp/go-plugin@v1.6.0/internal/grpcmux/grpc_muxer.go (about)

     1  // Copyright (c) HashiCorp, Inc.
     2  // SPDX-License-Identifier: MPL-2.0
     3  
     4  package grpcmux
     5  
     6  import (
     7  	"net"
     8  )
     9  
    10  // GRPCMuxer enables multiple implementations of net.Listener to accept
    11  // connections over a single "main" multiplexed net.Conn, and dial multiple
    12  // client connections over the same multiplexed net.Conn.
    13  //
    14  // The first multiplexed connection is used to serve the gRPC broker's own
    15  // control services: plugin.GRPCBroker, plugin.GRPCController, plugin.GRPCStdio.
    16  //
    17  // Clients must "knock" before dialling, to tell the server side that the
    18  // next net.Conn should be accepted onto a specific stream ID. The knock is a
    19  // bidirectional streaming message on the plugin.GRPCBroker service.
    20  type GRPCMuxer interface {
    21  	// Enabled determines whether multiplexing should be used. It saves users
    22  	// of the interface from having to compare an interface with nil, which
    23  	// is a bit awkward to do correctly.
    24  	Enabled() bool
    25  
    26  	// Listener returns a multiplexed listener that will wait until AcceptKnock
    27  	// is called with a matching ID before its Accept function returns.
    28  	Listener(id uint32, doneCh <-chan struct{}) (net.Listener, error)
    29  
    30  	// AcceptKnock unblocks the listener with the matching ID, and returns an
    31  	// error if it hasn't been created yet.
    32  	AcceptKnock(id uint32) error
    33  
    34  	// Dial makes a new multiplexed client connection. To dial a specific ID,
    35  	// a knock must be sent first.
    36  	Dial() (net.Conn, error)
    37  
    38  	// Close closes connections and releases any resources associated with the
    39  	// muxer.
    40  	Close() error
    41  }