Documentation
¶
Index ¶
- Constants
- func GracefulStopWithTimeout(srv *grpc.Server, d time.Duration) bool
- func NewGRPCServer(tel *telemetry.Client, opts ...ServerOption) *grpc.Server
- func NewStatsWrapper(statsHandler stats.Handler) stats.Handler
- func ObserveConnection(ctx context.Context, conn *grpc.ClientConn, target string)
- func RegisterChannelzTarget(conn *grpc.ClientConn, clientType string)
- func SetSandboxHeader(header http.Header, hostname string, sandboxID string) error
- func SetUserHeader(header http.Header, user string)
- func StartChannelzSampler(ctx context.Context)
- func StreamToChannel[Res any](ctx context.Context, stream *connect.ServerStreamForClient[Res]) (<-chan *Res, <-chan error)
- func WithSandboxClientMetricAttributes() otelgrpc.Option
- type ServerOption
- func WithMaxConnectionAge(age, grace time.Duration) ServerOption
- func WithMaxMessageSize(size int) ServerOption
- func WithRecoveryHandler(handler recovery.RecoveryHandlerFunc) ServerOption
- func WithSandboxMetricAttributes() ServerOption
- func WithStreamInterceptors(interceptors ...grpc.StreamServerInterceptor) ServerOption
- func WithTransportCredentials(creds credentials.TransportCredentials) ServerOption
- func WithUnaryDeadline(timeout time.Duration) ServerOption
- func WithUnaryInterceptors(interceptors ...grpc.UnaryServerInterceptor) ServerOption
- func WithWaitForHandlers() ServerOption
Constants ¶
const ( DefaultMaxConnectionAge = 5 * time.Minute DefaultMaxConnectionAgeGrace = 5 * time.Minute )
The connection age applied when WithMaxConnectionAge is not passed.
Every connection rotates, so a client finds replicas added after it connected and a transport-security change reaches long-lived connections within minutes. The grace exceeds every unary deadline in use, so a call in flight at rotation completes; a stream still open when age plus grace elapses is cut. A server whose streams may outlive that, or that must never rotate, passes WithMaxConnectionAge(0, 0).
const IsResumeMetadataKey = "x-sandbox-resume"
IsResumeMetadataKey is the gRPC metadata key used to pass the is_resume/snapshot value from the API client to the orchestrator server. This allows the server-side otelgrpc stats handler to include sandbox.resume in metric attributes during TagRPC, before the request payload is available.
const TeamIDMetadataKey = "x-team-id"
TeamIDMetadataKey carries the sandbox's team ID for the same reason IsResumeMetadataKey does: so the server's otelgrpc metrics can be split by team before the request payload is decoded.
Variables ¶
This section is empty.
Functions ¶
func GracefulStopWithTimeout ¶
GracefulStopWithTimeout invokes srv.GracefulStop and falls back to Stop() if it does not return within d. Returns true if graceful stop completed before the deadline.
grpc.Server.GracefulStop blocks until all pending RPCs finish, with no built-in deadline. A stuck stream would otherwise block process shutdown past Nomad's kill_timeout and result in SIGKILL.
Stop() force-closes transports
func NewGRPCServer ¶
func NewGRPCServer(tel *telemetry.Client, opts ...ServerOption) *grpc.Server
func NewStatsWrapper ¶
NewStatsWrapper wraps grpc stats.Handler and removes healthchecks from tracing.
func ObserveConnection ¶
func ObserveConnection(ctx context.Context, conn *grpc.ClientConn, target string)
func RegisterChannelzTarget ¶
func RegisterChannelzTarget(conn *grpc.ClientConn, clientType string)
func SetSandboxHeader ¶
func SetUserHeader ¶
func StartChannelzSampler ¶
func StreamToChannel ¶
func StreamToChannel[Res any](ctx context.Context, stream *connect.ServerStreamForClient[Res]) (<-chan *Res, <-chan error)
StreamToChannel pumps messages from stream into the returned message channel. The error channel holds the terminal status of the stream (stream error or ctx cancellation), if any, before the message channel is closed: after observing the closed message channel, callers must drain the error channel to learn how the stream ended.
func WithSandboxClientMetricAttributes ¶
WithSandboxClientMetricAttributes labels a client's otelgrpc metrics with the sandbox.resume and team.id values the caller put on the outgoing metadata, the same values the orchestrator's server metrics carry. The caller's side of every sandbox RPC then splits by team on its own deploy, and it also counts the calls that never reached a server.
Types ¶
type ServerOption ¶
type ServerOption func(*serverOptions)
ServerOption configures NewGRPCServer.
func WithMaxConnectionAge ¶
func WithMaxConnectionAge(age, grace time.Duration) ServerOption
WithMaxConnectionAge gracefully closes every connection after about age, which gRPC jitters by up to 10%, and forcibly closes it grace later. A client that resolves its target again when a connection closes uses the rotation to find servers added after it connected. Calls in flight at rotation keep running on the old connection until they finish or grace ends. Without this option DefaultMaxConnectionAge and DefaultMaxConnectionAgeGrace apply; zero for both removes the age limit.
func WithMaxMessageSize ¶
func WithMaxMessageSize(size int) ServerOption
WithMaxMessageSize sets both send and receive message limits in bytes.
func WithRecoveryHandler ¶
func WithRecoveryHandler(handler recovery.RecoveryHandlerFunc) ServerOption
WithRecoveryHandler configures the unary panic recovery handler.
func WithSandboxMetricAttributes ¶
func WithSandboxMetricAttributes() ServerOption
WithSandboxMetricAttributes adds the sandbox.resume and team.id attributes to otelgrpc metrics, read from incoming gRPC metadata.
func WithStreamInterceptors ¶
func WithStreamInterceptors(interceptors ...grpc.StreamServerInterceptor) ServerOption
WithStreamInterceptors appends interceptors after the logging interceptor, so streams see the ordering WithUnaryInterceptors promises for unary calls.
func WithTransportCredentials ¶
func WithTransportCredentials(creds credentials.TransportCredentials) ServerOption
WithTransportCredentials sets the server's transport credentials. Without it the server speaks plaintext, as before.
func WithUnaryDeadline ¶
func WithUnaryDeadline(timeout time.Duration) ServerOption
WithUnaryDeadline bounds unary requests while preserving an earlier caller deadline.
func WithUnaryInterceptors ¶
func WithUnaryInterceptors(interceptors ...grpc.UnaryServerInterceptor) ServerOption
WithUnaryInterceptors appends interceptors after logging, recovery, and the unary deadline, so they run with a bounded context and inside the recovery.
func WithWaitForHandlers ¶
func WithWaitForHandlers() ServerOption
WithWaitForHandlers makes Stop, including the forced fallback of GracefulStopWithTimeout, return only after every method handler has returned. Stop still closes connections and cancels handler contexts first. Without it, Stop can return while handlers run, so a caller that closes their dependencies afterwards races them.