atcclient

Documentation

Overview

Package atcclient implements a client for the Roxy Air Traffic Control protocol.

Index

• Constants
• func Spend(cost uint)
• type ATCClient
  • func New(cc *grpc.ClientConn, tlsConfig *tls.Config) (*ATCClient, error)
  • func (c *ATCClient) ClientAssign(ctx context.Context, first *roxy_v0.ClientAssignRequest_First) (context.CancelFunc, <-chan []*roxy_v0.Event, <-chan error, error)
  • func (c *ATCClient) Close() error
  • func (c *ATCClient) Dial(ctx context.Context, addr *net.TCPAddr) (*grpc.ClientConn, roxy_v0.AirTrafficControlClient, error)
  • func (c *ATCClient) Find(ctx context.Context, serviceName string, shardID uint32, useCache bool) (*net.TCPAddr, error)
  • func (c *ATCClient) Lookup(ctx context.Context, serviceName string) (*roxy_v0.LookupResponse, error)
  • func (c *ATCClient) ServerAnnounce(ctx context.Context, first *roxy_v0.ServerAnnounceRequest_First) (context.CancelFunc, <-chan error, error)
• type CostData
  • func GetCostData() CostData
• type InterceptorAdjustFunc
• type InterceptorFactory
  • func (factory InterceptorFactory) Cost(method string) (costPerQuery, costPerReq, costPerResp uint32, adjustFn InterceptorAdjustFunc)
  • func (factory InterceptorFactory) DialOptions(more ...grpc.DialOption) []grpc.DialOption
  • func (factory InterceptorFactory) Handler(inner http.Handler) http.Handler
  • func (factory InterceptorFactory) RoundTripper(inner http.RoundTripper) http.RoundTripper
  • func (factory InterceptorFactory) ServerOptions(more ...grpc.ServerOption) []grpc.ServerOption
  • func (factory InterceptorFactory) StreamClientInterceptor() grpc.StreamClientInterceptor
  • func (factory InterceptorFactory) StreamServerInterceptor() grpc.StreamServerInterceptor
  • func (factory InterceptorFactory) UnaryClientInterceptor() grpc.UnaryClientInterceptor
  • func (factory InterceptorFactory) UnaryServerInterceptor() grpc.UnaryServerInterceptor
• type InterceptorPerMethod

Constants

const CostInterval = 60 * time.Second

CostInterval is the span of time over which the average cost-per-second is computed, for estimating future cost spend.

const ReportInterval = 10 * time.Second

ReportInterval is the time interval between reports sent within ServerAnnounce and ClientAssign.

Functions

func Spend

func Spend(cost uint)

Spend records that a query just happened and the cost value of that query.

(For clients, this represents demand created by outgoing requests. For servers, this represents supply consumed by incoming requests.)

The cost must be a number between 0 and 65536, inclusive.

Types

type ATCClient

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

ATCClient is a client for communicating with the Roxy Air Traffic Controller service.

Each ATC tower is responsible for a set of (ServiceName, ShardID) tuples, which are exclusive to that tower. The client automatically determines which tower it needs to speak with, by asking any tower within the service to provide instructions.

func New

func New(cc *grpc.ClientConn, tlsConfig *tls.Config) (*ATCClient, error)

New constructs and returns a new ATCClient. The cc argument is a gRPC ClientConn configured to speak to any/all ATC towers. The tlsConfig argument specifies the TLS client configuration to use when speaking to individual ATC towers, or nil for gRPC with no TLS.

func (*ATCClient) ClientAssign

func (c *ATCClient) ClientAssign(ctx context.Context, first *roxy_v0.ClientAssignRequest_First) (context.CancelFunc, <-chan []*roxy_v0.Event, <-chan error, error)

ClientAssign starts a subscription for assignment Events. If the method returns with no error, then the caller must call the returned CancelFunc when it is no longer interested in receiving Events, and the caller is also responsible for draining both channels in a timely manner.

func (*ATCClient) Close

func (c *ATCClient) Close() error

Close closes all gRPC channels and blocks until all resources are freed.

func (*ATCClient) Dial

func (c *ATCClient) Dial(ctx context.Context, addr *net.TCPAddr) (*grpc.ClientConn, roxy_v0.AirTrafficControlClient, error)

Dial returns a gRPC ClientConn connected directly to the given ATC tower.

The caller should _not_ call Close() on it. It is owned by the ATCClient and will be re-used until the ATCClient itself is Close()'d.

func (*ATCClient) Find

func (c *ATCClient) Find(ctx context.Context, serviceName string, shardID uint32, useCache bool) (*net.TCPAddr, error)

Find queries any ATC tower for information about which ATC tower is responsible for the given (ServiceName, ShardID) tuple. If useCache is false, then the local cache will not be consulted.

func (*ATCClient) Lookup

func (c *ATCClient) Lookup(ctx context.Context, serviceName string) (*roxy_v0.LookupResponse, error)

Lookup queries any ATC tower for information about the given service.

func (*ATCClient) ServerAnnounce

func (c *ATCClient) ServerAnnounce(ctx context.Context, first *roxy_v0.ServerAnnounceRequest_First) (context.CancelFunc, <-chan error, error)

ServerAnnounce starts announcing that a new server is available for the given (ServiceName, ShardID) tuple. If the method returns with no error, then the caller must call the returned CancelFunc when the announcement should be withdrawn, and the caller must also ensure that the returned error channel is drained in a timely manner. The error channel will be closed once all goroutines and other internal resources have been released.

type CostData

type CostData struct {
	Counter   uint64
	PerSecond float64
}

CostData represents a snapshot of this Go process's cost expenditures.

(For clients, this represents demand created by outgoing requests. For servers, this represents supply consumed by incoming requests.)

func GetCostData

func GetCostData() CostData

GetCostData captures a CostData snapshot.

type InterceptorAdjustFunc

type InterceptorAdjustFunc func(oldCost uint32, request interface{}) uint32

InterceptorAdjustFunc is a closure that is permitted to peek at the contents of the gRPC request body.

type InterceptorFactory

type InterceptorFactory struct {
	DefaultCostPerQuery    uint32
	DefaultCostPerRequest  uint32
	DefaultCostPerResponse uint32
	ByFullMethod           map[string]InterceptorPerMethod
}

InterceptorFactory creates gRPC Interceptors (and other wrapper types) for capturing cost-adjusted query-per-second data.

func (InterceptorFactory) Cost

func (factory InterceptorFactory) Cost(method string) (costPerQuery, costPerReq, costPerResp uint32, adjustFn InterceptorAdjustFunc)

Cost returns the cost factors for the named method.

The method should be in gRPC "full method" syntax, i.e. a URL path like "/package.of.Service/Method".

func (InterceptorFactory) DialOptions

func (factory InterceptorFactory) DialOptions(more ...grpc.DialOption) []grpc.DialOption

DialOptions returns the DialOptions for installing client-side gRPC interceptors.

func (InterceptorFactory) Handler

func (factory InterceptorFactory) Handler(inner http.Handler) http.Handler

Handler wraps an http.Handler to install server-side HTTP cost instrumentation.

See RoundTripper for details of how HTTP requests are mapped to gRPC calls.

func (InterceptorFactory) RoundTripper

func (factory InterceptorFactory) RoundTripper(inner http.RoundTripper) http.RoundTripper

RoundTripper wraps an http.RoundTripper to install client-side HTTP cost instrumentation.

The HTTP requests are treated as if they are unitary gRPC calls, with a "full method" name of "/your/url/here@VERB" for HTTP method "VERB", and a request type of *http.Request.

(The query string is not included in the "full method" name.)

func (InterceptorFactory) ServerOptions

func (factory InterceptorFactory) ServerOptions(more ...grpc.ServerOption) []grpc.ServerOption

ServerOptions returns the ServerOptions for installing server-side gRPC interceptors.

func (InterceptorFactory) StreamClientInterceptor

func (factory InterceptorFactory) StreamClientInterceptor() grpc.StreamClientInterceptor

StreamClientInterceptor returns a gRPC StreamClientInterceptor.

func (InterceptorFactory) StreamServerInterceptor

func (factory InterceptorFactory) StreamServerInterceptor() grpc.StreamServerInterceptor

StreamServerInterceptor returns a gRPC StreamServerInterceptor.

func (InterceptorFactory) UnaryClientInterceptor

func (factory InterceptorFactory) UnaryClientInterceptor() grpc.UnaryClientInterceptor

UnaryClientInterceptor returns a gRPC UnaryClientInterceptor.

func (InterceptorFactory) UnaryServerInterceptor

func (factory InterceptorFactory) UnaryServerInterceptor() grpc.UnaryServerInterceptor

UnaryServerInterceptor returns a gRPC UnaryServerInterceptor.

type InterceptorPerMethod

type InterceptorPerMethod struct {
	CostPerQuery    uint32
	CostPerRequest  uint32
	CostPerResponse uint32
	AdjustFunc      InterceptorAdjustFunc
}

InterceptorPerMethod is the cost adjustments for a specific gRPC method. Client-side SendMsg and server-side RecvMsg events will be routed through AdjustFunc, if non-nil.