Documentation
¶
Overview ¶
Package unary provides a production-ready execution pipeline for gRPC unary RPCs.
It wraps user handlers with admission control, panic recovery, deadline enforcement, retry/restart supervision, and error classification — all configured through functional options.
Quick Start ¶
handler := unary.New(
unary.WithAdmissionLimit(100),
)
server := grpc.NewServer(
grpc.UnaryInterceptor(handler.UnaryServerInterceptor()),
)
Features ¶
- Automatic panic recovery with stack trace preservation
- Configurable admission control (concurrency limiting)
- Supervisor retry/restart/escalation policies
- Deadline enforcement (before-admission, after-admission, ignore)
- Prometheus and OpenTelemetry metrics via WithMetricsSink
- Graceful shutdown coordination via WithShutdown
- Consistent gRPC error code mapping
Index ¶
- type Option
- func WithAdmissionLimit(n int) Option
- func WithAdmissionLimiter(l *admission.Limiter) Option
- func WithDefaultDeadline(d time.Duration) Option
- func WithMetricsSink(s metrics.Sink) Option
- func WithShutdown(s *lifecycle.Shutdown) Option
- func WithShutdownCoordinator(sc core.ShutdownCoordinator) Option
- func WithSupervisorPolicy(p supervisor.SupervisorPolicy) Option
- type Options
- type Unary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*Options)
func WithAdmissionLimit ¶
WithAdmissionLimit sets the maximum number of concurrent executions.
This is the recommended way to configure admission control. No internal imports required.
unary.New(unary.WithAdmissionLimit(100)) // max 100 concurrent unary.New(unary.WithAdmissionLimit(-1)) // unlimited (default) unary.New(unary.WithAdmissionLimit(0)) // reject all
func WithAdmissionLimiter ¶
WithAdmissionLimiter sets a custom admission limiter.
Prefer WithAdmissionLimit(n) for simple capacity configuration. Use this for advanced cases requiring a pre-built limiter:
import "github.com/abhipray-cpu/grip/admission" unary.WithAdmissionLimiter(admission.NewLimiter(100))
func WithDefaultDeadline ¶
func WithMetricsSink ¶
WithMetricsSink sets a custom metrics sink.
The sink must implement the metrics.Sink interface. Use the public packages for built-in implementations:
import "github.com/abhipray-cpu/grip/metrics" import "github.com/abhipray-cpu/grip/metrics/prommetrics" unary.WithMetricsSink(metrics.Noop()) unary.WithMetricsSink(prommetrics.New(prommetrics.DefaultOptions()))
func WithShutdown ¶
WithShutdown sets a custom shutdown coordinator.
Use the public lifecycle package:
import "github.com/abhipray-cpu/grip/lifecycle" sd := lifecycle.NewShutdown() unary.WithShutdown(sd)
func WithShutdownCoordinator ¶
func WithShutdownCoordinator(sc core.ShutdownCoordinator) Option
WithShutdownCoordinator sets a shutdown coordinator using the public interface.
This accepts core.ShutdownCoordinator, which can be satisfied by lifecycle.NewShutdown() from the public lifecycle package.
Note: internally the coordinator must be a *lifecycle.Shutdown. Use WithShutdown for type-safe usage.
func WithSupervisorPolicy ¶
func WithSupervisorPolicy(p supervisor.SupervisorPolicy) Option
type Options ¶
type Options struct {
// Core
SupervisorPolicy supervisor.SupervisorPolicy
MetricsSink metrics.Sink
Shutdown *lifecycle.Shutdown
// Admission (fast gate)
AdmissionLimiter *admission.Limiter
// Defaults
DefaultDeadline time.Duration
}
Options holds the configuration for a unary handler.
External consumers should use the With* option functions instead of constructing this struct directly, since some fields use internal types.
func DefaultOptions ¶
func DefaultOptions() Options
type Unary ¶
type Unary struct {
// contains filtered or unexported fields
}
func (*Unary) UnaryServerInterceptor ¶
func (u *Unary) UnaryServerInterceptor() grpc.UnaryServerInterceptor
Source Files