README
¶
ttrpc
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.
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.
- No support for streams yet.
Status
Very new. YMMV.
TODO:
- Plumb error codes and GRPC status
- Remove use of any type and dependency on typeurl package
- Ensure that protocol can support streaming in the future
- Document protocol layout
- 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
¶
Index ¶
- Variables
- func GetMetadataValue(ctx context.Context, name string) (string, bool)
- func WithMetadata(ctx context.Context, md MD) context.Context
- type Client
- type ClientOpts
- type Handshaker
- type Invoker
- type KeyValue
- type MD
- type Method
- type Request
- type Response
- type Server
- type ServerOpt
- type ServiceDesc
- type StringList
- type UnaryClientInfo
- type UnaryClientInterceptor
- type UnaryServerInfo
- type UnaryServerInterceptor
- type UnixCredentialsFunc
- type Unmarshaler
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("ttrpc: closed")
ErrClosed is returned by client methods when the underlying connection is closed.
var (
ErrServerClosed = errors.New("ttrpc: server closed")
)
Functions ¶
func GetMetadataValue ¶
GetMetadataValue gets a specific metadata value by name from context.Context
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client for a ttrpc server
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 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 KeyValue ¶
type KeyValue struct {
Key string `protobuf:"bytes,1,opt,name=key,proto3"`
Value string `protobuf:"bytes,2,opt,name=value,proto3"`
}
func (*KeyValue) ProtoMessage ¶
func (*KeyValue) ProtoMessage()
type MD ¶
MD is the user type for ttrpc metadata
func GetMetadata ¶
GetMetadata retrieves metadata from context.Context (previously attached with WithMetadata)
type Request ¶
type Request struct {
Service string `protobuf:"bytes,1,opt,name=service,proto3"`
Method string `protobuf:"bytes,2,opt,name=method,proto3"`
Payload []byte `protobuf:"bytes,3,opt,name=payload,proto3"`
TimeoutNano int64 `protobuf:"varint,4,opt,name=timeout_nano,proto3"`
Metadata []*KeyValue `protobuf:"bytes,5,rep,name=metadata,proto3"`
}
func (*Request) ProtoMessage ¶
func (r *Request) ProtoMessage()
type Response ¶
type Response struct {
Status *spb.Status `protobuf:"bytes,1,opt,name=status,proto3"`
Payload []byte `protobuf:"bytes,2,opt,name=payload,proto3"`
}
func (*Response) ProtoMessage ¶
func (r *Response) ProtoMessage()
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
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 StringList ¶
type StringList struct {
List []string `protobuf:"bytes,1,rep,name=list,proto3"`
}
func (*StringList) ProtoMessage ¶
func (r *StringList) ProtoMessage()
func (*StringList) Reset ¶
func (r *StringList) Reset()
func (*StringList) String ¶
func (r *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 ¶
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)."
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
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
Package example demonstrates a lightweight protobuf service.
|
Package example demonstrates a lightweight protobuf service. |