oimcommon

Documentation

Index

• Constants
• func ChooseDialOpts(endpoint string, opts ...grpc.DialOption) []grpc.DialOption
• func CompletePCIAddress(addr, def oim.PCIAddress) oim.PCIAddress
• func GRPCDialer(endpoint string, t time.Duration) (net.Conn, error)
• func GetBlkSize64(file *os.File) (int64, error)
• func HexToU32(hex string) uint32
• func InitTracer(component string) (io.Closer, error)
• func JoinRegistryPath(elements []string) string
• func LoadTLS(caFile, key, peerName string) (credentials.TransportCredentials, error)
• func LoadTLSConfig(caFile, key, peerName string) (*tls.Config, error)
• func LogGRPCClient(formatter PayloadFormatter) grpc.UnaryClientInterceptor
• func LogGRPCServer(logger log.Logger, formatter PayloadFormatter) grpc.UnaryServerInterceptor
• func LogWriter(logger log.Logger) io.WriteCloser
• func ParseBDFString(dev string) (*oim.PCIAddress, error)
• func ParseEndpoint(ep string) (string, string, error)
• func PrettyPCIAddress(p *oim.PCIAddress) string
• func SplitRegistryPath(path string) ([]string, error)
• type CmdMonitor
  • func AddCmdMonitor(cmd *exec.Cmd) (CmdMonitor, error)
  • func (cm CmdMonitor) Watch() <-chan interface{}
• type CompletePayloadFormatter
  • func (c CompletePayloadFormatter) Sprint(payload interface{}) string
• type NonBlockingGRPCServer
  • func (s *NonBlockingGRPCServer) Addr() net.Addr
  • func (s *NonBlockingGRPCServer) ForceStop(ctx context.Context)
  • func (s *NonBlockingGRPCServer) Run(ctx context.Context, services ...RegisterService) error
  • func (s *NonBlockingGRPCServer) Start(ctx context.Context, services ...RegisterService) error
  • func (s *NonBlockingGRPCServer) Stop(ctx context.Context)
  • func (s *NonBlockingGRPCServer) Wait(ctx context.Context)
• type NullPayloadFormatter
  • func (n NullPayloadFormatter) Sprint(payload interface{}) string
• type PayloadFormatter
• type RegisterService
• type StripSecretsFormatter
  • func (s StripSecretsFormatter) Sprint(payload interface{}) string

Constants

const (
	// RegistryAddress is the special registry path element for the gRPC target value.
	RegistryAddress = "address"

	// RegistryPCI is the special registry path element with the PCI address of an accelerator card.
	RegistryPCI = "pci"
)

Functions

func ChooseDialOpts

func ChooseDialOpts(endpoint string, opts ...grpc.DialOption) []grpc.DialOption

ChooseDialOpts sets certain default options for the given endpoint, then adds the ones given as additional parameters. For unix:// endpoints it activates the custom dialer and disables security.

func CompletePCIAddress

func CompletePCIAddress(addr, def oim.PCIAddress) oim.PCIAddress

CompletePCIAddress merges two PCI addresses, filling in unknown fields from the default.

func GRPCDialer

func GRPCDialer(endpoint string, t time.Duration) (net.Conn, error)

GRPCDialer can be used with grpc.WithDialer. It supports addresses of the format defined for ParseEndpoint. Necessary because of https://github.com/grpc/grpc-go/issues/1741.

func GetBlkSize64

func GetBlkSize64(file *os.File) (int64, error)

GetBlkSize64 returns the size of a block device, referred to with an open read/write or read-only file handle.

func HexToU32

func HexToU32(hex string) uint32

HexToU32 takes 0 to 4 hex digits and turns them into an uint32. It panics on invalid content, so the caller must check for valid input in advance. 0xFFFF is the default if the string is empty.

func InitTracer

func InitTracer(component string) (io.Closer, error)

InitTracer initializes the global OpenTracing tracer, using Jaeger and the provided name for the current process. Must be called at the start of main(). The result is a function which should be called at the end of main() to clean up.

func JoinRegistryPath

func JoinRegistryPath(elements []string) string

JoinRegistryPath combines different path elements into a full path.

func LoadTLS

func LoadTLS(caFile, key, peerName string) (credentials.TransportCredentials, error)

LoadTLS is identical to LoadTLSConfig except that it returns the TransportCredentials for a gRPC client or server.

func LoadTLSConfig

func LoadTLSConfig(caFile, key, peerName string) (*tls.Config, error)

LoadTLSConfig sets up the necessary TLS configuration for a client or server. The peer name must be set when expecting the peer to offer a certificate with that common name, otherwise it can be left empty.

caFile must be the full file name. keyFile can either be the .crt file (foo.crt, implies foo.key) or the base name (foo for foo.crt and foo.key).

func LogGRPCClient

func LogGRPCClient(formatter PayloadFormatter) grpc.UnaryClientInterceptor

LogGRPCClient does the same as LogGRPCServer, only on the client side. There is no need for a logger because that gets passed in.

func LogGRPCServer

func LogGRPCServer(logger log.Logger, formatter PayloadFormatter) grpc.UnaryServerInterceptor

LogGRPCServer returns a gRPC interceptor for a gRPC server which logs the server-side call information via the provided logger. Method names are printed at the "Debug" level, with detailed request and response information if (and only if!) a formatter for those is provided. That's because sensitive information may be included in those data structures. Failed method calls are printed at the "Error" level.

If this interceptor is invoked after the otgrpc.OpenTracingServerInterceptor, then it will install a logger which adds log events to the span in addition to passing them on to the original logger.

func LogWriter

func LogWriter(logger log.Logger) io.WriteCloser

LogWriter returns a WriteCloser that logs individual lines as they get written through the logger.

func ParseBDFString

func ParseBDFString(dev string) (*oim.PCIAddress, error)

ParseBDFString accepts a PCI address in extended BDF notation.

func ParseEndpoint

func ParseEndpoint(ep string) (string, string, error)

ParseEndpoint splits a string of the format (unix|tcp)://<address> and returns the network and address separately.

func PrettyPCIAddress

func PrettyPCIAddress(p *oim.PCIAddress) string

PrettyPCIAddress formats a PCI address in extended BDF format.

func SplitRegistryPath

func SplitRegistryPath(path string) ([]string, error)

SplitRegistryPath separates the path into elements. It returns an error for invalid paths.

Types

type CmdMonitor

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

CmdMonitor can be used to detect when a command terminates unexpectedly. It works by letting the command inherit the write end of a pipe, then closing that end in the parent process and then watching the read end.

Alternatively one can also block on cmd.Wait() in a goroutine. But that might have unintended side effects, like reaping the child. The advantage of CmdMonitor is that it doesn't interfere with the child lifecycle.

func AddCmdMonitor

func AddCmdMonitor(cmd *exec.Cmd) (CmdMonitor, error)

AddCmdMonitor prepares the command for watching. Must be called before starting the command.

func (CmdMonitor) Watch

func (cm CmdMonitor) Watch() <-chan interface{}

Watch must be called after starting the command. The returned channel is closed once the command terminates.

type CompletePayloadFormatter

type CompletePayloadFormatter struct{}

CompletePayloadFormatter dumps the entire request or response as string. Beware that this may include sensitive information!

func (CompletePayloadFormatter) Sprint

func (c CompletePayloadFormatter) Sprint(payload interface{}) string

Sprint uses fmt.Sprint("%+v") to format the entire payload.

type NonBlockingGRPCServer

type NonBlockingGRPCServer struct {
	Endpoint      string
	ServerOptions []grpc.ServerOption
	// contains filtered or unexported fields
}

NonBlockingGRPCServer provides the common functionatilty for a gRPC server.

func (*NonBlockingGRPCServer) Addr

func (s *NonBlockingGRPCServer) Addr() net.Addr

Addr returns the address on which the server is listening, nil if none. Can be used to find the actual port when using tcp://:0 as endpoint.

func (*NonBlockingGRPCServer) ForceStop

func (s *NonBlockingGRPCServer) ForceStop(ctx context.Context)

ForceStop stops the background server immediately.

func (*NonBlockingGRPCServer) Run

func (s *NonBlockingGRPCServer) Run(ctx context.Context, services ...RegisterService) error

Run combines Start and Wait.

func (*NonBlockingGRPCServer) Start

func (s *NonBlockingGRPCServer) Start(ctx context.Context, services ...RegisterService) error

Start listens on the configured endpoint and runs a gRPC server with the given services in the background.

func (*NonBlockingGRPCServer) Stop

func (s *NonBlockingGRPCServer) Stop(ctx context.Context)

Stop the background server, allowing it to finish current requests.

func (*NonBlockingGRPCServer) Wait

func (s *NonBlockingGRPCServer) Wait(ctx context.Context)

Wait for completion of the background server.

type NullPayloadFormatter

type NullPayloadFormatter struct{}

NullPayloadFormatter just produces "nil" or "<filtered>".

func (NullPayloadFormatter) Sprint

func (n NullPayloadFormatter) Sprint(payload interface{}) string

Sprint just produces "nil" or "<filtered>".

type PayloadFormatter

type PayloadFormatter interface {
	// Sprint serializes the gRPC request or response as string.
	Sprint(payload interface{}) string
}

PayloadFormatter is responsible for turning a gRPC request or response into a string.

type RegisterService

type RegisterService func(*grpc.Server)

RegisterService is a callback that adds a service to the given gRPC server.

type StripSecretsFormatter

type StripSecretsFormatter struct{}

StripSecretsFormatter removes secret fields from a CSI 0.3 or CSI 1.0 message using the protosanitizer package.

func (StripSecretsFormatter) Sprint

func (s StripSecretsFormatter) Sprint(payload interface{}) string

Sprint strips messages for CSI >= 1.0.