---

Overview

GRIP is a production-ready Go library that adds resilience, intelligent error handling, and stream ordering guarantees to gRPC. It eliminates boilerplate while providing sophisticated patterns for correctness and performance.

Instead of writing repetitive error handling, retry logic, and stream management code, GRIP provides:

• Automatic Error Classification - Consistent gRPC code mapping across all RPC types
• Built-in Retry & Deadline Management - Configurable supervisor policies
• Smart Stream Ordering - Per-key sequential ordering with cross-key parallelism
• Unified Execution Pipeline - Admission control → execution → supervision
• Production Observability - OpenTelemetry and Prometheus metrics
• Zero Boilerplate - Interceptor-based integration with your gRPC services

Features

Error Handling

Priority-based error classification ensuring consistent gRPC codes:
├── ResourceExhausted (admission rejected)
├── Unavailable (server shutdown)
├── Canceled (context cancelled)
└── Unknown (handler errors/panics)

All RPC Types Supported

• Unary RPC - Request-response with supervision
• Server Streaming - Server sends multiple messages
• Client Streaming - Client sends multiple messages
• Bidirectional Streaming - Full-duplex communication

Stream Ordering Modes

Mode	Throughput	Ordering	Use Case
OrderingNone	Maximum	None	Immutable events
OrderingFIFO	Low	Global Sequential	Strict sequencing
OrderingKeyedFIFO	High	Per-Key Sequential	RECOMMENDED

Integrated Metrics

• OpenTelemetry (OTEL) support
• Prometheus metrics
• Pluggable metrics sink

Production Ready

• 295+ unit and integration tests
• Chaos and fuzz testing
• Zero resource leaks
• Race-free implementation (verified with go test -race)
• Comprehensive error handling

Quick Start

Installation

go get github.com/abhipray-cpu/grip

Minimal Example - Unary RPC

package main

import (
    "context"
    "fmt"
    "github.com/abhipray-cpu/grip/unary"
)

func main() {
    // Create unary interceptor with default settings
    u := unary.New()

    // Use in your gRPC server
    server := grpc.NewServer(
        grpc.UnaryInterceptor(u.UnaryServerInterceptor()),
    )

    // Your handler (automatic error mapping, panic recovery)
    // Handler signature: func(ctx context.Context, req any) (any, error)
}

With Retry Policy

u := unary.New(
    unary.WithSupervisorPolicy(supervisor.SupervisorPolicy{
        Retry: &supervisor.RetryPolicy{
            MaxAttempts: 3,
            Backoff:     time.Second,
        },
    }),
)

Server Streaming

// Create engine with sensible defaults (no internal imports needed)
engine := serverstream.New(
    serverstream.WithAdmissionLimit(100), // max 100 concurrent streams
    serverstream.WithSupervisorPolicy(supervisor.SupervisorPolicy{}),
)

stream := serverstream.NewStream(ctx, grpcStream)
err := engine.Run(ctx, stream, core.AdmissionSoftAllow, handler)

Customization

All configuration is available through public packages — no internal/ imports needed:

import (
    "github.com/abhipray-cpu/grip/unary"
    "github.com/abhipray-cpu/grip/admission"       // admission control
    "github.com/abhipray-cpu/grip/lifecycle"        // shutdown coordination
    "github.com/abhipray-cpu/grip/metrics"          // metrics interface
    "github.com/abhipray-cpu/grip/metrics/prommetrics"  // Prometheus sink
    "github.com/abhipray-cpu/grip/metrics/otelmetrics"  // OpenTelemetry sink
    "github.com/abhipray-cpu/grip/streaming"        // streaming types (Handler, Message, OrderingPolicy)
)

// Simple: use convenience options (no extra imports)
u := unary.New(
    unary.WithAdmissionLimit(100),
)

// Advanced: use public packages for full control
sd := lifecycle.NewShutdown()
u := unary.New(
    unary.WithAdmissionLimiter(admission.NewLimiter(100)),
    unary.WithShutdown(sd),
    unary.WithMetricsSink(prommetrics.New(prommetrics.DefaultOptions())),
)

Examples

All examples are fully working and documented:

Unary RPC

• Basic - Simple request-response
• With Retry - Automatic retry policy
• Error Handling - gRPC code mapping

Streaming

• Server Streaming - Server sends multiple messages
• Client Streaming - Client sends multiple messages
• Bidirectional - Full-duplex communication

Advanced Patterns

• Keyed Ordering - Production pattern for correctness + performance

Run any example:

cd examples/unary/basic
go run main.go

Documentation

Document	Purpose
Architecture	System design, error flow, execution pipeline
Usage Guide	Complete API reference with patterns
Contributing	How to contribute to GRIP

Key Concepts

Error Classification

GRIP maps all errors to gRPC codes using a priority system:

1. Admission Rejected/Signaled → codes.ResourceExhausted
2. Server Shutdown → codes.Unavailable
3. Context Cancelled → codes.Canceled
4. Handler Errors → codes.Unknown

This ensures consistent error handling across your entire service.

Stream Ordering - Keyed FIFO (Recommended)

For partitioned workloads, use OrderingKeyedFIFO:

Per-key sequential:    User A transactions execute in order
                       User B transactions execute in order

Cross-key parallel:    User A and User B process simultaneously
                       Maximum throughput + Correctness

Real-world examples:

• Banking: Transaction ordering per account
• User sessions: Action ordering per user
• Stream processing: Partition ordering (Kafka/Kinesis)
• Event sourcing: Event ordering per aggregate

Supervisor Policies

Control execution behavior:

supervisor.SupervisorPolicy{
    Retry: &supervisor.RetryPolicy{
        MaxAttempts: 3,
        Backoff:     time.Second,
    },
    Deadline: &supervisor.DeadlinePolicy{
        Timeout: 5 * time.Second,
    },
    Admission: &supervisor.AdmissionPolicy{
        MaxConcurrency: 100,
    },
}

Running Tests

# All tests
go test -timeout 10m ./...

# Specific package
go test -v ./serverstream/test

# Fuzz tests (8 packages)
make fuzz

# Coverage
go test -cover ./...

Current Status:

• 295/295 tests passing
• 0 vet issues
• 8/8 fuzz packages covered
• 0 race conditions (go test -race ./... passes all packages)

Architecture

GRIP implements a unified execution pipeline:

Request
  ↓
Admission Controller (capacity check)
  ↓
Executor (panic recovery + deadline enforcement)
  ↓
Supervisor (retry + escalation + hooks)
  ↓
User Handler
  ↓
Response + Error Classification

For detailed architecture diagrams, see Architecture Documentation.

Use Cases

GRIP is ideal for:

• Microservices - Consistent error handling across services
• Stream Processing - Partition-aware ordering (Kafka consumers)
• Banking/Finance - Transaction ordering guarantees
• E-commerce - Order processing with correct sequencing
• Real-time Chat - User session isolation
• Event Sourcing - Aggregate event ordering

Performance

GRIP is designed for minimal overhead. The interceptor-based architecture adds only lightweight admission checks and error classification to the gRPC call path. The core execution pipeline avoids allocations on the hot path.

With OrderingKeyedFIFO, throughput scales linearly with key cardinality — each key gets sequential execution while different keys process in parallel.

Best Practices

DO

• Use OrderingKeyedFIFO for partitioned workloads
• Set appropriate retry policies per endpoint
• Monitor admission limiter rejection rate
• Use OpenTelemetry for observability
• Implement supervisor hooks for custom behavior

DON'T

• Use OrderingFIFO for high-throughput services
• Set unbounded retry attempts
• Ignore error codes in client code
• Skip deadline policies for long operations
• Create multiple engine instances unnecessarily

Contributing

GRIP is open for contributions! See CONTRIBUTING.md for:

• Development setup
• Testing requirements
• Code style guidelines
• PR process
• Issue templates

Contributors Welcome!

• Bug fixes
• Documentation improvements
• New examples
• Performance optimizations
• Integration examples

📋 License

Licensed under the MIT License. See LICENSE for details.

Support

Getting Help

1. Check Usage Guide for API documentation
2. Browse Examples for working code
3. Read Architecture for system design
4. Open an issue with details and error logs

Bug Reports

Please include:

• GRIP version
• Go version
• Minimal reproduction code
• Error logs/stack traces
• Expected vs actual behavior

Roadmap

Current focus areas:

• Integration examples (gRPC service, microservice)
• Additional streaming patterns (chat service, data pipeline)
• Distributed tracing integration
• Custom metrics collectors
• Performance optimization guide

Learning Path

New to GRIP? Follow this path:

1. Start: Read this README
2. Understand: Run examples/unary/basic
3. Learn: Work through examples in order
4. Deep Dive: Read Architecture
5. Reference: Use Usage Guide
6. Implement: Build your service with GRIP

Key Achievements

• Zero Boilerplate - Interceptor pattern, not config objects
• Consistent Errors - Unified gRPC code mapping
• Smart Ordering - Per-key sequential, cross-key parallel
• Production Ready - 295+ tests, chaos testing, fuzz coverage
• Well Documented - 1,400+ lines of docs, 15+ diagrams
• Complete Examples - 7 working examples, all patterns covered

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md

---