# pgbytes/go-grpc-middleware architecture

> Architecture diagram of the GitHub repository pgbytes/go-grpc-middleware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pgbytes/go-grpc-middleware
- Repository: https://github.com/pgbytes/go-grpc-middleware

## Overview

##### Main Components

a. Core Middleware Chain
- Central ChainUnaryServer and ChainStreamServer components
- How multiple interceptors can be chained together

b. Interceptor Categories (group these visually)
- Authentication (auth/)
- Logging (logging/)
- Logrus integration
- Zap integration
- Kit integration
- Monitoring/Tracing (tracing/)
- OpenTracing implementation
- Validation (validator/)
- Recovery (recovery/)
- Rate Limiting (ratelimit/)
- Retry Mechanism (retry/)
- Tags (tags/)

**┌─────────────────────────────────────────────┐**
- gRPC Server                 │
- ┤
- Middleware Chain Layer            │
- ┬───────┬───────┬───────┬───────┬────┤
- Auth  │ Log   │ Trace │ Valid │ Retry │... │
- ┴───────┴───────┴───────┴───────┴────┘

##### Key Relationships

a. Request Flow:
**Client Request → Client Interceptors → gRPC Server → Server Interceptors → Handler**

b. Interceptor Chain:
How multiple interceptors can be composed using the middleware chain

##### Important Details

a. Middleware Types:
- Unary Interceptors
- Stream Interceptors

b. Context Propagation:
- How context and metadata flow through the system

c. Integration Points:
- How the middleware integrates with external logging systems
- OpenTracing integration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CR[Client Request]
    end

    subgraph "Middleware Chain"
        direction TB
        MC["Chain Constructor"]:::core
        click MC "https://github.com/pgbytes/go-grpc-middleware/blob/master/chain.go"
        MW["Middleware Wrappers"]:::core
        click MW "https://github.com/pgbytes/go-grpc-middleware/blob/master/wrappers.go"
    end

    subgraph "Server-Side Interceptors"
        direction TB
        
        subgraph "Authentication"
            AUTH["Auth Interceptor"]:::interceptor
            META["Metadata Handler"]:::interceptor
            click AUTH "https://github.com/pgbytes/go-grpc-middleware/blob/master/auth/auth.go"
            click META "https://github.com/pgbytes/go-grpc-middleware/blob/master/auth/metadata.go"
        end

        subgraph "Logging Systems"
            LOGRUS["Logrus Integration"]:::logger
            ZAP["Zap Integration"]:::logger
            KIT["Kit Integration"]:::logger
            click LOGRUS "https://github.com/pgbytes/go-grpc-middleware/tree/master/logging/logrus/"
            click ZAP "https://github.com/pgbytes/go-grpc-middleware/tree/master/logging/zap/"
            click KIT "https://github.com/pgbytes/go-grpc-middleware/tree/master/logging/kit/"
        end

        subgraph "Monitoring"
            TRACE["OpenTracing"]:::monitor
            click TRACE "https://github.com/pgbytes/go-grpc-middleware/tree/master/tracing/opentracing/"
        end

        subgraph "Safety & Control"
            VAL["Validator"]:::safety
            REC["Recovery Handler"]:::safety
            RATE["Rate Limiter"]:::safety
            click VAL "https://github.com/pgbytes/go-grpc-middleware/blob/master/validator/validator.go"
            click REC "https://github.com/pgbytes/go-grpc-middleware/blob/master/recovery/interceptors.go"
            click RATE "https://github.com/pgbytes/go-grpc-middleware/blob/master/ratelimit/ratelimit.go"
        end

        subgraph "Request Management"
            RETRY["Retry Handler"]:::management
            BACKOFF["Backoff Controller"]:::management
            click RETRY "https://github.com/pgbytes/go-grpc-middleware/blob/master/retry/retry.go"
            click BACKOFF "https://github.com/pgbytes/go-grpc-middleware/blob/master/retry/backoff.go"
        end

        subgraph "Metadata Management"
            TAGS["Tags System"]:::meta
            FIELD["Field Extractor"]:::meta
            CTX["Context Handler"]:::meta
            click TAGS "https://github.com/pgbytes/go-grpc-middleware/blob/master/tags/interceptors.go"
            click FIELD "https://github.com/pgbytes/go-grpc-middleware/blob/master/tags/fieldextractor.go"
            click CTX "https://github.com/pgbytes/go-grpc-middleware/blob/master/tags/context.go"
        end
    end

    subgraph "Utility Layer"
        METAUTIL["Metadata Utils"]:::util
        BACKUTIL["Backoff Utils"]:::util
        click METAUTIL "https://github.com/pgbytes/go-grpc-middleware/tree/master/util/metautils/"
        click BACKUTIL "https://github.com/pgbytes/go-grpc-middleware/tree/master/util/backoffutils/"
    end

    subgraph "Context Propagation"
        CTXLOG["Logrus Context"]:::context
        CTXZAP["Zap Context"]:::context
        CTXKIT["Kit Context"]:::context
        click CTXLOG "https://github.com/pgbytes/go-grpc-middleware/blob/master/logging/logrus/ctxlogrus/context.go"
        click CTXZAP "https://github.com/pgbytes/go-grpc-middleware/blob/master/logging/zap/ctxzap/context.go"
        click CTXKIT "https://github.com/pgbytes/go-grpc-middleware/blob/master/logging/kit/ctxkit/context.go"
    end

    CR --> MC
    MC --> MW
    MW --> AUTH
    AUTH --> META
    META --> LOGRUS & ZAP & KIT
    LOGRUS & ZAP & KIT --> TRACE
    TRACE --> VAL
    VAL --> REC
    REC --> RATE
    RATE --> RETRY
    RETRY --> BACKOFF
    BACKOFF --> TAGS
    TAGS --> FIELD
    FIELD --> CTX

    METAUTIL -.-> META
    BACKUTIL -.-> BACKOFF
    CTXLOG -.-> LOGRUS
    CTXZAP -.-> ZAP
    CTXKIT -.-> KIT

    classDef core fill:#2374ab
    classDef interceptor fill:#48a9a6
    classDef logger fill:#4ad7d1
    classDef monitor fill:#c1666b
    classDef safety fill:#d4b483
    classDef management fill:#e4dfda
    classDef meta fill:#c17767
    classDef util fill:#8d8741
    classDef context fill:#659dbd

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Interceptors]:::interceptor
        L3[Logging]:::logger
        L4[Monitoring]:::monitor
        L5[Safety]:::safety
        L6[Management]:::management
        L7[Metadata]:::meta
        L8[Utilities]:::util
        L9[Context]:::context
    end
```
