ttrpc

package module
v1.2.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2024 License: Apache-2.0 Imports: 25 Imported by: 1,024

README

ttrpc

Build Status

GRPC for low-memory environments.

The existing grpc-go project requires a lot of memory overhead for importing packages and at runtime. While this is great for many services with low density requirements, this can be a problem when running a large number of services on a single machine or on a machine with a small amount of memory.

Using the same GRPC definitions, this project reduces the binary size and protocol overhead required. We do this by eliding the net/http, net/http2 and grpc package used by grpc replacing it with a lightweight framing protocol. The result are smaller binaries that use less resident memory with the same ease of use as GRPC.

Please note that while this project supports generating either end of the protocol, the generated service definitions will be incompatible with regular GRPC services, as they do not speak the same protocol.

Protocol

See the protocol specification.

Usage

Create a gogo vanity binary (see cmd/protoc-gen-gogottrpc/main.go for an example with the ttrpc plugin enabled.

It's recommended to use protobuild to build the protobufs for this project, but this will work with protoc directly, if required.

Differences from GRPC

  • The protocol stack has been replaced with a lighter protocol that doesn't require http, http2 and tls.
  • The client and server interface are identical whereas in GRPC there is a client and server interface that are different.
  • The Go stdlib context package is used instead.

Status

TODO:

  • Add testing under concurrent load to ensure
  • Verify connection error handling

Project details

ttrpc is a containerd sub-project, licensed under the Apache 2.0 license. As a containerd sub-project, you will find the:

information in our containerd/project repository.

Documentation

Overview

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

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
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 OversizedMessageError added in v1.2.6 

func OversizedMessageError(messageLength int) error

OversizedMessageError returns an OversizedMessageErr error for the given message length if it exceeds the allowed maximum. Otherwise a nil error is returned.

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 added in v1.2.0 

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 added in v1.0.2 

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

UserOnCloseWait is used to block until the user's on-close callback finishes.

type ClientOpts 

type ClientOpts func(c *Client)

ClientOpts configures a client

func WithChainUnaryClientInterceptor added in v1.2.3 

func WithChainUnaryClientInterceptor(interceptors ...UnaryClientInterceptor) ClientOpts

WithChainUnaryClientInterceptor sets the provided chain of client interceptors

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 added in v1.2.0 

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 deprecated added in v1.2.0 

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

Deprecated: Use KeyValue.ProtoReflect.Descriptor instead.

func (*KeyValue) GetKey added in v1.2.0 

func (x *KeyValue) GetKey() string

func (*KeyValue) GetValue added in v1.2.0 

func (x *KeyValue) GetValue() string

func (*KeyValue) ProtoMessage 

func (*KeyValue) ProtoMessage()

func (*KeyValue) ProtoReflect added in v1.2.0 

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) Clone added in v1.2.7 

func (m MD) Clone() MD

Clone returns a copy of MD or nil if it's nil. It's copied from golang's `http.Header.Clone` implementation: https://cs.opensource.google/go/go/+/refs/tags/go1.23.4:src/net/http/header.go;l=94

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 OversizedMessageErr added in v1.2.6 

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

OversizedMessageErr is used to indicate refusal to send an oversized message. It wraps a ResourceExhausted grpc Status together with the offending message length.

func (*OversizedMessageErr) Error added in v1.2.6 

func (e *OversizedMessageErr) Error() string

Error returns the error message for the corresponding grpc Status for the error.

func (*OversizedMessageErr) MaximumLength added in v1.2.6 

func (*OversizedMessageErr) MaximumLength() int

MaximumLength retrieves the maximum allowed message length that triggered the error.

func (*OversizedMessageErr) RejectedLength added in v1.2.6 

func (e *OversizedMessageErr) RejectedLength() int

RejectedLength retrieves the rejected message length which triggered the error.

func (*OversizedMessageErr) Unwrap added in v1.2.6 

func (e *OversizedMessageErr) Unwrap() error

Unwrap returns the corresponding error with our grpc status code.

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 deprecated added in v1.2.0 

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

Deprecated: Use Request.ProtoReflect.Descriptor instead.

func (*Request) GetMetadata added in v1.2.0 

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

func (*Request) GetMethod added in v1.2.0 

func (x *Request) GetMethod() string

func (*Request) GetPayload added in v1.2.0 

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

func (*Request) GetService added in v1.2.0 

func (x *Request) GetService() string

func (*Request) GetTimeoutNano added in v1.2.0 

func (x *Request) GetTimeoutNano() int64

func (*Request) ProtoMessage 

func (*Request) ProtoMessage()

func (*Request) ProtoReflect added in v1.2.0 

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 deprecated added in v1.2.0 

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

Deprecated: Use Response.ProtoReflect.Descriptor instead.

func (*Response) GetPayload added in v1.2.0 

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

func (*Response) GetStatus added in v1.2.0 

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

func (*Response) ProtoMessage 

func (*Response) ProtoMessage()

func (*Response) ProtoReflect added in v1.2.0 

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 added in v1.2.0 

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 WithChainUnaryServerInterceptor added in v1.2.3 

func WithChainUnaryServerInterceptor(interceptors ...UnaryServerInterceptor) ServerOpt

WithChainUnaryServerInterceptor sets the provided chain of server interceptors

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 added in v1.2.0 

type Stream struct {
	Handler         StreamHandler
	StreamingClient bool
	StreamingServer bool
}

type StreamClientInterceptor added in v1.2.0 

type StreamClientInterceptor func(context.Context)

type StreamDesc added in v1.2.0 

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 added in v1.2.0 

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

type StreamServer added in v1.2.0 

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

type StreamServerInfo added in v1.2.0 

type StreamServerInfo struct {
	FullMethod      string
	StreamingClient bool
	StreamingServer bool
}

StreamServerInfo provides information about the server request

type StreamServerInterceptor added in v1.2.0 

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 deprecated added in v1.2.0 

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

Deprecated: Use StringList.ProtoReflect.Descriptor instead.

func (*StringList) GetList added in v1.2.0 

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

func (*StringList) ProtoMessage 

func (*StringList) ProtoMessage()

func (*StringList) ProtoReflect added in v1.2.0 

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

View all Source files

Directories

Path Synopsis
cmd
protoc-gen-go-ttrpc
protoc-gen-gogottrpc
Package example demonstrates a lightweight protobuf service.
 Package example demonstrates a lightweight protobuf service.
cmd
integration
streaming
Code generated by protoc-gen-go-ttrpc.
 Code generated by protoc-gen-go-ttrpc.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.