backend

Documentation

Overview

Package backend implements backends satisfying proxy.Backend interface

Index

• Constants
• type APID
  • func NewAPID(target string, tlsConfigProvider func() (*tls.Config, error)) (*APID, error)
  • func (a *APID) AppendInfo(streaming bool, resp []byte) ([]byte, error)
  • func (a *APID) BuildError(streaming bool, err error) ([]byte, error)
  • func (a *APID) Close()
  • func (a *APID) GetConnection(ctx context.Context, fullMethodName string) (context.Context, *grpc.ClientConn, error)
  • func (a *APID) String() string
• type APIDFactory
  • func NewAPIDFactory(provider TLSConfigProvider) *APIDFactory
  • func (factory *APIDFactory) Flush()
  • func (factory *APIDFactory) Get(target string) (proxy.Backend, error)
• type TLSConfigProvider

Constants

const GracefulShutdownTimeout = 30 * time.Minute

GracefulShutdownTimeout is the timeout for graceful shutdown of the backend connection.

Talos has a few long-running API calls, so we need to give the backend some time to finish them.

The connection will enter IDLE time after GracefulShutdownTimeout/2, if no RPC is running.

Types

type APID

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

APID backend performs proxying to another apid instance.

Backend authenticates itself using given grpc credentials.

func NewAPID

func NewAPID(target string, tlsConfigProvider func() (*tls.Config, error)) (*APID, error)

NewAPID creates new instance of APID backend.

func (*APID) AppendInfo

func (a *APID) AppendInfo(streaming bool, resp []byte) ([]byte, error)

AppendInfo is called to enhance response from the backend with additional data.

AppendInfo enhances upstream response with node metadata (target).

This method depends on grpc protobuf response structure, each response should look like:

  message SomeResponse {
    repeated SomeReply messages = 1; // please note field ID == 1
  }

  message SomeReply {
	   common.Metadata metadata = 1;
    <other fields go here ...>
  }

As 'SomeReply' is repeated in 'SomeResponse', if we concatenate protobuf representation of several 'SomeResponse' messages, we still get valid 'SomeResponse' representation but with more entries (feature of protobuf binary representation).

If we look at binary representation of any unary 'SomeResponse' message, it will always contain one protobuf field with field ID 1 (see above) and type 2 (embedded message SomeReply is encoded as string with length). So if we want to add fields to 'SomeReply', we can simply read field header, adjust length for new 'SomeReply' representation, and prepend new field header.

At the same time, we can add 'common.Metadata' structure to 'SomeReply' by simply appending or prepending 'common.Metadata' as a single field. This requires 'metadata' field to be not defined in original response. (This is due to the fact that protobuf message representation is concatenation of each field representation).

To build only single field (Metadata) we use helper message which contains exactly this field with same field ID as in every other 'SomeReply':

  message Empty {
    common.Metadata metadata = 1;
	}

As streaming replies are not wrapped into 'SomeResponse' with 'repeated', handling is simpler: we just need to append Empty with details.

So AppendInfo does the following: validates that response contains field ID 1 encoded as string, cuts field header, rest is representation of some reply. Marshal 'Empty' as protobuf, which builds 'common.Metadata' field, append it to original response message, build new header for new length of some response, and add back new field header.

func (*APID) BuildError

func (a *APID) BuildError(streaming bool, err error) ([]byte, error)

BuildError is called to convert error from upstream into response field.

BuildError converts upstream error into message from upstream, so that multiple successful and failure responses might be returned.

This simply relies on the fact that any response contains 'Empty' message. So if 'Empty' is unmarshalled into any other reply message, all the fields are undefined but 'Metadata':

  message Empty {
   common.Metadata metadata = 1;
	}

 message EmptyResponse {
   repeated Empty messages = 1;
}

Streaming responses are not wrapped into Empty, so we simply marshall EmptyResponse message.

func (*APID) Close

func (a *APID) Close()

Close connection.

func (*APID) GetConnection

func (a *APID) GetConnection(ctx context.Context, fullMethodName string) (context.Context, *grpc.ClientConn, error)

GetConnection returns a grpc connection to the backend.

func (*APID) String

func (a *APID) String() string

type APIDFactory

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

APIDFactory caches connection to apid instances by target.

TODO: need to clean up idle connections from time to time.

func NewAPIDFactory

func NewAPIDFactory(provider TLSConfigProvider) *APIDFactory

NewAPIDFactory creates new APIDFactory with given tls.Config.

Client TLS config is used to connect to other apid instances.

func (*APIDFactory) Flush

func (factory *APIDFactory) Flush()

Flush all cached backends.

This ensures that all connections are closed.

func (*APIDFactory) Get

func (factory *APIDFactory) Get(target string) (proxy.Backend, error)

Get backend by target.

Get performs caching of backends.

type TLSConfigProvider

type TLSConfigProvider interface {
	ClientConfig() (*tls.Config, error)
}

TLSConfigProvider provides tls.Config for client connections.