ttrpc – github.com/containerd/ttrpc Index | Files | Directories

package ttrpc

import "github.com/containerd/ttrpc"

package ttrpc defines and implements a low level simple transfer protocol optimized for low latency and reliable connections between processes on the same host. The protocol uses simple framing for sending requests, responses, and data using multiple streams.

Index

Variables

var (
	// ErrProtocol is a general error in the handling the protocol.
	ErrProtocol = errors.New("protocol error")

	// ErrClosed is returned by client methods when the underlying connection is
	// closed.
	ErrClosed = errors.New("ttrpc: closed")

	// ErrServerClosed is returned when the Server has closed its connection.
	ErrServerClosed = errors.New("ttrpc: server closed")

	// ErrStreamClosed is when the streaming connection is closed.
	ErrStreamClosed = errors.New("ttrpc: stream closed")
)
var File_github_com_containerd_ttrpc_request_proto protoreflect.FileDescriptor

Functions

func GetMetadataValue

func GetMetadataValue(ctx context.Context, name string) (string, bool)

GetMetadataValue gets a specific metadata value by name from context.Context

func WithMetadata

func WithMetadata(ctx context.Context, md MD) context.Context

WithMetadata attaches metadata map to a context.Context

Types

type Client

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

Client for a ttrpc server

func NewClient

func NewClient(conn net.Conn, opts ...ClientOpts) *Client

NewClient creates a new ttrpc client using the given connection

func (*Client) Call

func (c *Client) Call(ctx context.Context, service, method string, req, resp interface{}) error

Call makes a unary request and returns with response

func (*Client) Close

func (c *Client) Close() error

Close closes the ttrpc connection and underlying connection

func (*Client) NewStream

func (c *Client) NewStream(ctx context.Context, desc *StreamDesc, service, method string, req interface{}) (ClientStream, error)

NewStream creates a new stream with the given stream descriptor to the specified service and method. If not a streaming client, the request object may be provided.

func (*Client) UserOnCloseWait

func (c *Client) UserOnCloseWait(ctx context.Context) error

UserOnCloseWait is used to blocks untils the user's on-close callback finishes.

type ClientOpts

type ClientOpts func(c *Client)

ClientOpts configures a client

func WithOnClose

func WithOnClose(onClose func()) ClientOpts

WithOnClose sets the close func whenever the client's Close() method is called

func WithUnaryClientInterceptor

func WithUnaryClientInterceptor(i UnaryClientInterceptor) ClientOpts

WithUnaryClientInterceptor sets the provided client interceptor

type ClientStream

type ClientStream interface {
	CloseSend() error
	SendMsg(m interface{}) error
	RecvMsg(m interface{}) error
}

ClientStream is used to send or recv messages on the underlying stream

type Handshaker

type Handshaker interface {
	// Handshake should confirm or decorate a connection that may be incoming
	// to a server or outgoing from a client.
	//
	// If this returns without an error, the caller should use the connection
	// in place of the original connection.
	//
	// The second return value can contain credential specific data, such as
	// unix socket credentials or TLS information.
	//
	// While we currently only have implementations on the server-side, this
	// interface should be sufficient to implement similar handshakes on the
	// client-side.
	Handshake(ctx context.Context, conn net.Conn) (net.Conn, interface{}, error)
}

Handshaker defines the interface for connection handshakes performed on the server or client when first connecting.

type Invoker

type Invoker func(context.Context, *Request, *Response) error

Invoker invokes the client's request and response from the ttrpc server

type KeyValue

type KeyValue struct {
	Key   string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
	Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

func (*KeyValue) Descriptor

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

Deprecated: Use KeyValue.ProtoReflect.Descriptor instead.

func (*KeyValue) GetKey

func (x *KeyValue) GetKey() string

func (*KeyValue) GetValue

func (x *KeyValue) GetValue() string

func (*KeyValue) ProtoMessage

func (*KeyValue) ProtoMessage()

func (*KeyValue) ProtoReflect

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

func (*KeyValue) Reset

func (x *KeyValue) Reset()

func (*KeyValue) String

func (x *KeyValue) String() string

type MD

type MD map[string][]string

MD is the user type for ttrpc metadata

func GetMetadata

func GetMetadata(ctx context.Context) (MD, bool)

GetMetadata retrieves metadata from context.Context (previously attached with WithMetadata)

func (MD) Append

func (m MD) Append(key string, values ...string)

Append appends additional values to the given key.

func (MD) Get

func (m MD) Get(key string) ([]string, bool)

Get returns the metadata for a given key when they exist. If there is no metadata, a nil slice and false are returned.

func (MD) Set

func (m MD) Set(key string, values ...string)

Set sets the provided values for a given key. The values will overwrite any existing values. If no values provided, a key will be deleted.

type Method

type Method func(ctx context.Context, unmarshal func(interface{}) error) (interface{}, error)

type Request

type Request struct {
	Service     string      `protobuf:"bytes,1,opt,name=service,proto3" json:"service,omitempty"`
	Method      string      `protobuf:"bytes,2,opt,name=method,proto3" json:"method,omitempty"`
	Payload     []byte      `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
	TimeoutNano int64       `protobuf:"varint,4,opt,name=timeout_nano,json=timeoutNano,proto3" json:"timeout_nano,omitempty"`
	Metadata    []*KeyValue `protobuf:"bytes,5,rep,name=metadata,proto3" json:"metadata,omitempty"`
	// contains filtered or unexported fields
}

func (*Request) Descriptor

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

Deprecated: Use Request.ProtoReflect.Descriptor instead.

func (*Request) GetMetadata

func (x *Request) GetMetadata() []*KeyValue

func (*Request) GetMethod

func (x *Request) GetMethod() string

func (*Request) GetPayload

func (x *Request) GetPayload() []byte

func (*Request) GetService

func (x *Request) GetService() string

func (*Request) GetTimeoutNano

func (x *Request) GetTimeoutNano() int64

func (*Request) ProtoMessage

func (*Request) ProtoMessage()

func (*Request) ProtoReflect

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

func (*Request) Reset

func (x *Request) Reset()

func (*Request) String

func (x *Request) String() string

type Response

type Response struct {
	Status  *status.Status `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"`
	Payload []byte         `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
	// contains filtered or unexported fields
}

func (*Response) Descriptor

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

Deprecated: Use Response.ProtoReflect.Descriptor instead.

func (*Response) GetPayload

func (x *Response) GetPayload() []byte

func (*Response) GetStatus

func (x *Response) GetStatus() *status.Status

func (*Response) ProtoMessage

func (*Response) ProtoMessage()

func (*Response) ProtoReflect

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

func (*Response) Reset

func (x *Response) Reset()

func (*Response) String

func (x *Response) String() string

type Server

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

func NewServer

func NewServer(opts ...ServerOpt) (*Server, error)

func (*Server) Close

func (s *Server) Close() error

Close the server without waiting for active connections.

func (*Server) Register

func (s *Server) Register(name string, methods map[string]Method)

Register registers a map of methods to method handlers TODO: Remove in 2.0, does not support streams

func (*Server) RegisterService

func (s *Server) RegisterService(name string, desc *ServiceDesc)

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, l net.Listener) error

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

type ServerOpt

type ServerOpt func(*serverConfig) error

ServerOpt for configuring a ttrpc server

func WithServerHandshaker

func WithServerHandshaker(handshaker Handshaker) ServerOpt

WithServerHandshaker can be passed to NewServer to ensure that the handshaker is called before every connection attempt.

Only one handshaker is allowed per server.

func WithUnaryServerInterceptor

func WithUnaryServerInterceptor(i UnaryServerInterceptor) ServerOpt

WithUnaryServerInterceptor sets the provided interceptor on the server

type ServiceDesc

type ServiceDesc struct {
	Methods map[string]Method
	Streams map[string]Stream
}

type Stream

type Stream struct {
	Handler         StreamHandler
	StreamingClient bool
	StreamingServer bool
}

type StreamClientInterceptor

type StreamClientInterceptor func(context.Context)

type StreamDesc

type StreamDesc struct {
	StreamingClient bool
	StreamingServer bool
}

StreamDesc describes the stream properties, whether the stream has a streaming client, a streaming server, or both

type StreamHandler

type StreamHandler func(context.Context, StreamServer) (interface{}, error)

type StreamServer

type StreamServer interface {
	SendMsg(m interface{}) error
	RecvMsg(m interface{}) error
}

type StreamServerInfo

type StreamServerInfo struct {
	FullMethod      string
	StreamingClient bool
	StreamingServer bool
}

StreamServerInfo provides information about the server request

type StreamServerInterceptor

type StreamServerInterceptor func(context.Context, StreamServer, *StreamServerInfo, StreamHandler) (interface{}, error)

type StringList

type StringList struct {
	List []string `protobuf:"bytes,1,rep,name=list,proto3" json:"list,omitempty"`
	// contains filtered or unexported fields
}

func (*StringList) Descriptor

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

Deprecated: Use StringList.ProtoReflect.Descriptor instead.

func (*StringList) GetList

func (x *StringList) GetList() []string

func (*StringList) ProtoMessage

func (*StringList) ProtoMessage()

func (*StringList) ProtoReflect

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

func (*StringList) Reset

func (x *StringList) Reset()

func (*StringList) String

func (x *StringList) String() string

type UnaryClientInfo

type UnaryClientInfo struct {
	FullMethod string
}

UnaryClientInfo provides information about the client request

type UnaryClientInterceptor

type UnaryClientInterceptor func(context.Context, *Request, *Response, *UnaryClientInfo, Invoker) error

UnaryClientInterceptor specifies the interceptor function for client request/response

type UnaryServerInfo

type UnaryServerInfo struct {
	FullMethod string
}

UnaryServerInfo provides information about the server request

type UnaryServerInterceptor

type UnaryServerInterceptor func(context.Context, Unmarshaler, *UnaryServerInfo, Method) (interface{}, error)

UnaryServerInterceptor specifies the interceptor function for server request/response

type UnixCredentialsFunc

type UnixCredentialsFunc func(*unix.Ucred) error

func UnixSocketRequireRoot

func UnixSocketRequireRoot() UnixCredentialsFunc

func UnixSocketRequireSameUser

func UnixSocketRequireSameUser() UnixCredentialsFunc

UnixSocketRequireSameUser resolves the current effective unix user and returns a UnixCredentialsFunc that will validate incoming unix connections against the current credentials.

This is useful when using abstract sockets that are accessible by all users.

func UnixSocketRequireUidGid

func UnixSocketRequireUidGid(uid, gid int) UnixCredentialsFunc

UnixSocketRequireUidGid requires specific *effective* UID/GID, rather than the real UID/GID.

For example, if a daemon binary is owned by the root (UID 0) with SUID bit but running as an unprivileged user (UID 1001), the effective UID becomes 0, and the real UID becomes 1001. So calling this function with uid=0 allows a connection from effective UID 0 but rejects a connection from effective UID 1001.

See socket(7), SO_PEERCRED: "The returned credentials are those that were in effect at the time of the call to connect(2) or socketpair(2)."

func (UnixCredentialsFunc) Handshake

func (fn UnixCredentialsFunc) Handshake(_ context.Context, conn net.Conn) (net.Conn, interface{}, error)

type Unmarshaler

type Unmarshaler func(interface{}) error

Unmarshaler contains the server request data and allows it to be unmarshaled into a concrete type

Source Files

channel.go client.go codec.go config.go doc.go errors.go handshake.go interceptor.go metadata.go request.pb.go server.go services.go stream.go stream_server.go unixcreds_linux.go

Directories

PathSynopsis
cmd
cmd/protoc-gen-gogottrpc
cmd/protoc-gen-go-ttrpc
examplePackage example demonstrates a lightweight protobuf service.
example/cmd
integration
integration/streamingCode generated by protoc-gen-go-ttrpc.
internal
plugin
Version
v1.2.1
Published
Mar 8, 2023
Platform
linux/amd64
Imports
25 packages
Last checked
17 minutes ago

Tools for package owners.