callback

README

Why?

NSM need a server to call client via GRPC, for this purpuse in native way it required to have client serve a GRPC server on unix socket or TCP. But to simplify communication between client and server a better way is to have only one connection between client and server.

And this grpc.callback library is intended to perform required functionality using grpc bi-directional streams.

How?

A Server declared as usual except:

server := grpc.NewServer()
...
// register normal APIs on server
...
// Register callback GRPC endpoint and callback.Server will hold callback clients to be callable.
callbackServer := callback.NewServer(callback.IdentityByAuthority)
//
callback.RegisterCallbackServiceServer(server, callbackServer)
...
_ = server.Serve(listener)

And then require to call client.

target := "callback:{client-authority}"
// If target is not in a list of callback server targets, 
// it will perform grpc.DialContext to connect to passed target
nsmClientGRPC, err := grpc.DialContext(context.Background(), target, callbackServer.WithCallbackDialer(), grpc.WithInsecure())
nsmClient := networkservice.NewNetworkServiceClient(nsmClientGRPC)

resp, _ := nsmClient.Request(context.Background(), &networkservice.NetworkServiceRequest{
    Connection: &networkservice.Connection{
        Id: "qwe",
    },
})

Client identification.

Server could identify clients from passed metadata values, clients could define how to extract identification from context. Servers adds "callback:" to identity, so then dial with callback it is required to add "callback:{client-id}".

// IdentityByAuthority - return identity by :authority
func IdentityByPeerCertificate(ctx context.Context) (string, error) {
	p, ok := peer.FromContext(ctx)
	if !ok {
		err := errors.New("No peer is provided")
		logrus.Error(err)
		return "", err
	}
	tlsInfo, tlsOk := p.AuthInfo.(credentials.TLSInfo)
	if !tlsOk {
		err := errors.New("No TLS info is provided")
		logrus.Error(err)
		return "", err
	}
	commonName := tlsInfo.State.PeerCertificates[0].Subject.CommonName
	return commonName, nil
}

Documentation

Overview

Package callback - provide GRPC API to perform client callbacks.

Package callback - provide GRPC API to perform client callbacks.

Index

• Variables
• func IdentityByAuthority(ctx context.Context) (string, error)
• func RegisterCallbackServiceServer(s *grpc.Server, srv CallbackServiceServer)
• type CallbackData
  • func (*CallbackData) Descriptor() ([]byte, []int)
  • func (x *CallbackData) GetData() []byte
  • func (x *CallbackData) GetKind() DataKind
  • func (*CallbackData) ProtoMessage()
  • func (x *CallbackData) ProtoReflect() protoreflect.Message
  • func (x *CallbackData) Reset()
  • func (x *CallbackData) String() string
• type CallbackServiceClient
  • func NewCallbackServiceClient(cc grpc.ClientConnInterface) CallbackServiceClient
• type CallbackServiceServer
• type CallbackService_HandleCallbacksClient
• type CallbackService_HandleCallbacksServer
• type Client
  • func NewClient(clientConnInterface grpc.ClientConnInterface, clientServer *grpc.Server) Client
• type ClientListener
• type DataKind
  • func (DataKind) Descriptor() protoreflect.EnumDescriptor
  • func (x DataKind) Enum() *DataKind
  • func (DataKind) EnumDescriptor() ([]byte, []int)
  • func (x DataKind) Number() protoreflect.EnumNumber
  • func (x DataKind) String() string
  • func (DataKind) Type() protoreflect.EnumType
• type IdentityProvider
• type Server
  • func NewServer(provider IdentityProvider) Server
• type UnimplementedCallbackServiceServer
  • func (*UnimplementedCallbackServiceServer) HandleCallbacks(CallbackService_HandleCallbacksServer) error

Variables

var (
	DataKind_name = map[int32]string{
		0: "Data",
		1: "Close",
	}
	DataKind_value = map[string]int32{
		"Data":  0,
		"Close": 1,
	}
)

Enum value maps for DataKind.

var File_callback_proto protoreflect.FileDescriptor

Functions

func IdentityByAuthority

func IdentityByAuthority(ctx context.Context) (string, error)

IdentityByAuthority - return identity by :authority

func RegisterCallbackServiceServer

func RegisterCallbackServiceServer(s *grpc.Server, srv CallbackServiceServer)

Types

type CallbackData

type CallbackData struct {
	Data []byte   `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
	Kind DataKind `protobuf:"varint,2,opt,name=kind,proto3,enum=callback.DataKind" json:"kind,omitempty"`
	// contains filtered or unexported fields
}

Callback binary stream

func (*CallbackData) Descriptor

func (*CallbackData) Descriptor() ([]byte, []int)

Deprecated: Use CallbackData.ProtoReflect.Descriptor instead.

func (*CallbackData) GetData

func (x *CallbackData) GetData() []byte

func (*CallbackData) GetKind

func (x *CallbackData) GetKind() DataKind

func (*CallbackData) ProtoMessage

func (*CallbackData) ProtoMessage()

func (*CallbackData) ProtoReflect

func (x *CallbackData) ProtoReflect() protoreflect.Message

func (*CallbackData) Reset

func (x *CallbackData) Reset()

func (*CallbackData) String

func (x *CallbackData) String() string

type CallbackServiceClient

type CallbackServiceClient interface {
	HandleCallbacks(ctx context.Context, opts ...grpc.CallOption) (CallbackService_HandleCallbacksClient, error)
}

CallbackServiceClient is the client API for CallbackService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.

func NewCallbackServiceClient

func NewCallbackServiceClient(cc grpc.ClientConnInterface) CallbackServiceClient

type CallbackServiceServer

type CallbackServiceServer interface {
	HandleCallbacks(CallbackService_HandleCallbacksServer) error
}

CallbackServiceServer is the server API for CallbackService service.

type CallbackService_HandleCallbacksClient

type CallbackService_HandleCallbacksClient interface {
	Send(*CallbackData) error
	Recv() (*CallbackData, error)
	grpc.ClientStream
}

type CallbackService_HandleCallbacksServer

type CallbackService_HandleCallbacksServer interface {
	Send(*CallbackData) error
	Recv() (*CallbackData, error)
	grpc.ServerStream
}

type Client

type Client interface {
	// Context - return context
	Context() context.Context
	// Stop - stop all operations
	Stop()
	// Server - perform opertaions on local GRPC server and call for remote server.
	Serve(ctx context.Context)
	// ErrChan - return error stream
	ErrChan() chan error
}

Client - a callback server client, main functionality is to serve local grpc and perform operations on it.

func NewClient

func NewClient(clientConnInterface grpc.ClientConnInterface, clientServer *grpc.Server) Client

NewClient - construct a new callback client. It is used to connect server and transfer all call back to client.

type ClientListener

type ClientListener interface {
	ClientConnected(id string)
	ClientDisconnected(id string)
}

ClientListener - inform server about new client is arrived or disconnected.

type DataKind

type DataKind int32

const (
	DataKind_Data  DataKind = 0
	DataKind_Close DataKind = 1
)

func (DataKind) Descriptor

func (DataKind) Descriptor() protoreflect.EnumDescriptor

func (DataKind) Enum

func (x DataKind) Enum() *DataKind

func (DataKind) EnumDescriptor

func (DataKind) EnumDescriptor() ([]byte, []int)

Deprecated: Use DataKind.Descriptor instead.

func (DataKind) Number

func (x DataKind) Number() protoreflect.EnumNumber

func (DataKind) String

func (x DataKind) String() string

func (DataKind) Type

func (DataKind) Type() protoreflect.EnumType

type IdentityProvider

type IdentityProvider func(ctx context.Context) (string, error)

IdentityProvider - A function to retrieve identity from grpc connection context and create clients based on it.

type Server

type Server interface {
	AddListener(listener ClientListener)
	WithCallbackDialer() grpc.DialOption
	CallbackServiceServer
}

Server - a callback server, hold client callback connections and allow to provide client

func NewServer

func NewServer(provider IdentityProvider) Server

NewServer - creates a new callback server to handle clients, should be used to create client connections back to client.

type UnimplementedCallbackServiceServer

type UnimplementedCallbackServiceServer struct {
}

UnimplementedCallbackServiceServer can be embedded to have forward compatible implementations.

func (*UnimplementedCallbackServiceServer) HandleCallbacks

func (*UnimplementedCallbackServiceServer) HandleCallbacks(CallbackService_HandleCallbacksServer) error