eqgrpc

Documentation

Overview

Package eqgrpc provides a gRPC backend for EntroQ. This is the backend that is commonly used by clients of an EntroQ task service, set up thus:

Server:
	qsvc -> entroq library -> some backend (e.g., pg)

Client:
	entroq library -> grpc backend

You can start, for example, a postgres-backed QSvc like this (or just use pg/svc):

ctx := context.Background()
svc, err := qsvc.New(ctx, pg.Opener(dbHostPort)) // Other options available, too.
if err != nil {
	log.Fatalf("Can't open PG backend: %v",e rr)
}
defer svc.Close()

lis, err := net.Listen("tcp", fmt.Sprintf(":%d", thisPort))
if err != nil {
	log.Fatalf("Can't start this service")
}

s := eqgrpc.NewServer()
pb.RegisterEntroQServer(s, svc)
s.Serve(lis)

With the server set up this way, the client simply uses the EntroQ library, hands it the eqgrpc Opener, and they're off:

client, err := entroq.New(ctx, eqgrpc.Opener("myhost:54321", eqgrpc.WithInsecure()))

That creates a client library that uses a gRPC connection to do its work. Note that Claim will block on the *client* side doing this instead of holding the *server* connection hostage while a claim fails to go through. That is actually what we want; rather than hold connections open, we allow the client to poll with exponential backoff. In large-scale systems, this is better behavior.

Index

• Constants
• func New(conn *grpc.ClientConn, opts ...Option) (*backend, error)
• func Opener(addr string, opts ...Option) entroq.BackendOpener
• type BearerCredentials
  • func NewBearerCredentials(tok string) *BearerCredentials
  • func (c *BearerCredentials) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)
  • func (*BearerCredentials) RequireTransportSecurity() bool
• type Option
  • func WithBearerToken(tok string) Option
  • func WithBlock() Option
  • func WithDialOpts(d ...grpc.DialOption) Option
  • func WithDialer(f func(string, time.Duration) (net.Conn, error)) Option
  • func WithInsecure() Option
  • func WithMaxSize(maxMB int) Option
  • func WithNiladicDialer(f func() (net.Conn, error)) Option

Constants

const (
	// DefaultAddr is the default listening address for gRPC services.
	DefaultAddr = ":37706"

	// ClaimRetryInterval is how long a grpc client holds a claim request open
	// before dropping it and trying again.
	ClaimRetryInterval = 2 * time.Minute

	// MB helps with conversion to and from megabytes.
	MB = 1024 * 1024
)

Functions

func New

func New(conn *grpc.ClientConn, opts ...Option) (*backend, error)

New creates a new gRPC backend that attaches to the task service via gRPC.

func Opener

func Opener(addr string, opts ...Option) entroq.BackendOpener

Opener creates an opener function to be used to get a gRPC backend. If the address string is empty, it defaults to the DefaultAddr, the default value for the memory-backed gRPC server.

Types

type BearerCredentials

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

BearerCredentials implements the RPC Credentials interface, and provides a bearer token for gRPC communication.

func NewBearerCredentials

func NewBearerCredentials(tok string) *BearerCredentials

NewBearerCredentials creates credentials for a bearer token.

func (*BearerCredentials) GetRequestMetadata

func (c *BearerCredentials) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)

GetRequestMetadata provides an authorization header for a bearer token.

func (*BearerCredentials) RequireTransportSecurity

func (*BearerCredentials) RequireTransportSecurity() bool

RequireTransportSecurity is always false, tread carefully! If not on localhost, ensure security is on.

type Option

type Option func(*backendOptions)

Option allows grpc-opener-specific options to be sent in Opener.

func WithBearerToken

func WithBearerToken(tok string) Option

WithBearerToken sets a bearer token to use for all requests.

func WithBlock

func WithBlock() Option

WithBlock is a common gRPC dial option, here for convenience.

func WithDialOpts

func WithDialOpts(d ...grpc.DialOption) Option

WithDialOpts sets grpc dial options. Can be called multiple times. Only valid in call to Opener.

func WithDialer

func WithDialer(f func(string, time.Duration) (net.Conn, error)) Option

WithDialer is a common gRPC dial option, here for convenience.

func WithInsecure

func WithInsecure() Option

WithInsecure is a common gRPC dial option, here for convenience.

func WithMaxSize

func WithMaxSize(maxMB int) Option

WithMaxSize is a convenience method for setting WithDialOptions(grpc.WithDefaultCallOptions(grpc.MaxCallRecvSize(...), grpc.MaxCallSendSize(...))). Default is 4MB.

func WithNiladicDialer

func WithNiladicDialer(f func() (net.Conn, error)) Option

WithNiladicDialer uses a niladic dial function such as that returned by bufconn.Listen. Useful for testing.