# ardikabs/gonvoy architecture

> Architecture diagram of the GitHub repository ardikabs/gonvoy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ardikabs/gonvoy
- Repository: https://github.com/ardikabs/gonvoy

## Overview

Gonvoy is a Go framework for implementing Envoy HTTP filter extensions with net/http-style request and response access. A Go extension registers a filter and configuration parser; Envoy then drives filter lifecycle and HTTP phases through Gonvoy’s handler chain and context, which expose request/response mutation and local replies. The README also documents logging, custom metrics, caching, and graceful panic handling. Some lifecycle and integration wiring is inferred from documented roles and the tree; unsampled implementation links are omitted where uncertain.

Main entry points: [`context.go`](https://github.com/ardikabs/gonvoy/blob/main/context.go) (Filter context), [`httpfilter_manager.go`](https://github.com/ardikabs/gonvoy/blob/main/httpfilter_manager.go) (Phase manager), [`pkg/envoy/register.go`](https://github.com/ardikabs/gonvoy/blob/main/pkg/envoy/register.go) (Filter registration), [`context_httpfilter.go`](https://github.com/ardikabs/gonvoy/blob/main/context_httpfilter.go) (Request response access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Envoy integration"]
  node_registration["Filter registration<br/>[register.go]"]
  node_config["Config parsing<br/>[configparser.go]"]
  node_factory["Filter factory<br/>[httpfilter.go]"]
end

subgraph group_filtering["Filter lifecycle"]
  node_lifecycle["Filter lifecycle<br/>[httpfilter.go]"]
  node_manager["Phase manager"]
  node_handlers["Handler chain"]
end

subgraph group_http["HTTP processing"]
  node_context["Filter context<br/>[context.go]"]
  node_httpaccess["Request response access"]
  node_headers["Header access<br/>[header.go]"]
  node_bodies["Body access<br/>[body.go]"]
  node_replies["Errors and replies"]
end

subgraph group_runtime["Runtime services"]
  node_logger["Logging<br/>[logger.go]"]
  node_metrics["Custom metrics<br/>[metrics.go]"]
  node_cache["Runtime cache<br/>[cache.go]"]
end

node_extension(("Go extension"))
node_envoy(("Envoy Proxy"))

node_extension -->|"registers filter"| node_registration
node_registration -->|"registers factory"| node_factory
node_registration -->|"registers parser"| node_config
node_envoy -->|"requests filter"| node_factory
node_factory -->|"creates filter"| node_lifecycle
node_config -->|"provides config"| node_lifecycle
node_envoy -->|"drives phases"| node_manager
node_lifecycle -->|"sets up handlers"| node_manager
node_manager -->|"dispatches phases"| node_handlers
node_manager -->|"provides context"| node_context
node_handlers -->|"uses context"| node_context
node_context -->|"exposes HTTP"| node_httpaccess
node_httpaccess -->|"reads and modifies"| node_headers
node_httpaccess -->|"reads and modifies"| node_bodies
node_context -->|"sends local replies"| node_replies
node_manager -->|"handles failures"| node_replies
node_context -->|"provides logger"| node_logger
node_context -->|"provides metrics"| node_metrics
node_context -->|"provides cache"| node_cache
node_replies -->|"logs errors"| node_logger

click node_registration "https://github.com/ardikabs/gonvoy/blob/main/pkg/envoy/register.go"
click node_config "https://github.com/ardikabs/gonvoy/blob/main/configparser.go"
click node_factory "https://github.com/ardikabs/gonvoy/blob/main/httpfilter.go"
click node_lifecycle "https://github.com/ardikabs/gonvoy/blob/main/httpfilter.go"
click node_manager "https://github.com/ardikabs/gonvoy/blob/main/httpfilter_manager.go"
click node_handlers "https://github.com/ardikabs/gonvoy/blob/main/httpfilter_processor.go"
click node_context "https://github.com/ardikabs/gonvoy/blob/main/context.go"
click node_httpaccess "https://github.com/ardikabs/gonvoy/blob/main/context_httpfilter.go"
click node_headers "https://github.com/ardikabs/gonvoy/blob/main/header.go"
click node_bodies "https://github.com/ardikabs/gonvoy/blob/main/body.go"
click node_replies "https://github.com/ardikabs/gonvoy/blob/main/httpfilter_handler.go"
click node_logger "https://github.com/ardikabs/gonvoy/blob/main/logger.go"
click node_metrics "https://github.com/ardikabs/gonvoy/blob/main/metrics.go"
click node_cache "https://github.com/ardikabs/gonvoy/blob/main/cache.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registration,node_config,node_factory toneBlue
class node_lifecycle,node_manager,node_handlers toneAmber
class node_context,node_httpaccess,node_headers,node_bodies,node_replies toneMint
class node_logger,node_metrics,node_cache toneRose
class node_extension,node_envoy toneIndigo
```

## Components

### Envoy integration

- [Filter registration](https://github.com/ardikabs/gonvoy/blob/main/pkg/envoy/register.go): `pkg/envoy/register.go`
- [Config parsing](https://github.com/ardikabs/gonvoy/blob/main/configparser.go): `configparser.go`
- [Filter factory](https://github.com/ardikabs/gonvoy/blob/main/httpfilter.go): `httpfilter.go`

### Filter lifecycle

- [Filter lifecycle](https://github.com/ardikabs/gonvoy/blob/main/httpfilter.go): `httpfilter.go`
- [Phase manager](https://github.com/ardikabs/gonvoy/blob/main/httpfilter_manager.go): `httpfilter_manager.go`
- [Handler chain](https://github.com/ardikabs/gonvoy/blob/main/httpfilter_processor.go): `httpfilter_processor.go`

### HTTP processing

- [Filter context](https://github.com/ardikabs/gonvoy/blob/main/context.go): `context.go`
- [Request response access](https://github.com/ardikabs/gonvoy/blob/main/context_httpfilter.go): `context_httpfilter.go`
- [Header access](https://github.com/ardikabs/gonvoy/blob/main/header.go): `header.go`
- [Body access](https://github.com/ardikabs/gonvoy/blob/main/body.go): `body.go`
- [Errors and replies](https://github.com/ardikabs/gonvoy/blob/main/httpfilter_handler.go): `httpfilter_handler.go`

### Runtime services

- [Logging](https://github.com/ardikabs/gonvoy/blob/main/logger.go): `logger.go`
- [Custom metrics](https://github.com/ardikabs/gonvoy/blob/main/metrics.go): `metrics.go`
- [Runtime cache](https://github.com/ardikabs/gonvoy/blob/main/cache.go): `cache.go`

### Other components

- **Go extension**
- **Envoy Proxy**

## Connections

- Go extension → Filter registration: registers filter
- Filter registration → Filter factory: registers factory
- Filter registration → Config parsing: registers parser
- Envoy Proxy → Filter factory: requests filter
- Filter factory → Filter lifecycle: creates filter
- Config parsing → Filter lifecycle: provides config
- Envoy Proxy → Phase manager: drives phases
- Filter lifecycle → Phase manager: sets up handlers
- Phase manager → Handler chain: dispatches phases
- Phase manager → Filter context: provides context
- Handler chain → Filter context: uses context
- Filter context → Request response access: exposes HTTP
- Request response access → Header access: reads and modifies
- Request response access → Body access: reads and modifies
- Filter context → Errors and replies: sends local replies
- Phase manager → Errors and replies: handles failures
- Filter context → Logging: provides logger
- Filter context → Custom metrics: provides metrics
- Filter context → Runtime cache: provides cache
- Errors and replies → Logging: logs errors