Lore

This page is a narrative timeline of the Envoy codebase, derived from git history. It is the "what happened here and when" view; for the current snapshot of stats see by the numbers, and for technical rationale see background.

Eras

Aug 2016 — The original Lyft commit

Envoy's first commit, a714b9c2b0a2 "Initial commit", landed on 2016-08-08 from Matt Klein. The next commit, "Initial import (#2)" two days later, dropped the bulk of the Lyft-internal codebase as a single import. By the end of August 2016 the repository already had network filters, an HTTP/2 codec, the cluster manager, and statsd integration — Envoy was born close to feature-complete by today's "L4/L7 proxy" yardstick.

The proxy was open-sourced as part of Lyft's announcement that September. Envoy joined the CNCF the same month.

2017 — Outside Lyft

Envoy crossed the boundary from "Lyft's proxy" to "industry data plane" through 2017. Istio shipped its first public release in May 2017 with Envoy as its data plane, and the api/ directory was carved out as a standalone protobuf surface so other projects could speak xDS. The blog series Matt Klein wrote that year — on the threading model, hot restart, and stats architecture — became the closest thing the project has to design documents. They are still cited in code comments today.

2018 — Extensions and tracing (Nov 2018)

The source/extensions/ directory was introduced and the existing in-tree filters were migrated into it. The first non-Zipkin tracer (Datadog) landed in source/extensions/tracers/datadog on 2018-11-06, marking the start of the tracer extension family. The Datadog C++ Opentracing client this used would be the first of many third-party C/C++ libraries Envoy would gain Bazel bindings for.

2019–2020 — xDS v3 and gRPC (2019, 2020)

The xDS API was rewritten as v3 and the api/API_VERSIONING.md policy was formalised. The v2 API would be deleted in 2021. WASM support landed on 2020-11-16, with the first runtime in source/extensions/wasm_runtime/. HTTP/3 / QUIC plumbing followed — the first commits to source/extensions/quic/ were on 2021-06-10.

2021 — Contrib (Aug 2021)

The contrib model — extensions held to a looser bar, in a separate binary — was introduced on 2021-08-12 with the contrib/ directory and the extension policy. It allowed niche or experimental code (Postgres proxy, MySQL proxy, SIP proxy, hyperscan, etc.) to live in-tree without raising the maintenance ceiling for the core binary.

Late 2022 — Envoy Mobile merges in (Nov 2022)

Envoy Mobile started life in a separate repo (envoyproxy/envoy-mobile). It was merged into the main repo on 2022-11-02 as the mobile/ directory. From that point one repo housed both the server binary and the Android/iOS/C library. The mobile tree carries its own WORKSPACE, its own MODULE.bazel, its own pre-commit config, and its own Kotlin/Swift lints.

2023–2024 — Universal extensibility

Three orthogonal extensibility mechanisms exist now:

• Compiled C++ extensions (the original model).
• WASM plugins via source/extensions/wasm_runtime/.
• Dynamic modules via source/extensions/dynamic_modules/ — a stable C ABI so Rust, Go, and C extensions can be loaded at runtime without recompiling Envoy. Dynamic module support exists for HTTP filters, network filters, clusters, load balancing policies, access loggers, tracers, and stat sinks, all added in the 2024–2025 window. The wip (work-in-progress) annotation on the dynamic-modules API was removed on 2025-08-19.

2025 — Steady state, AI plumbing (2025–2026)

Recent additions to source/extensions/filters/http/ reveal what's currently being built:

• mcp/, mcp_json_rest_bridge/, mcp_router/ — Model Context Protocol bridge filters.
• a2a/, proto_api_scrubber/, transform/ — newer transformation/policy filters.
• proto_message_extraction/ — gRPC message-level extraction.

The 2025-2026 cadence is steady: ~270 commits/month, ~10/day. The latest commit at the time this wiki was generated is ff9e47a3ad74f6b4daf00bcdc502ad86200c3a10 "envoy_log: allows Envoy version embedding (#44337)" on 2026-04-29. PR numbers in the 44k range tell you something about the volume.

Longest-standing features

Some pieces of the codebase have survived from the Lyft import in 2016 essentially in place:

• The HTTP connection manager (source/extensions/filters/network/http_connection_manager/) — the L7 dispatcher that turns a TCP connection into an HTTP filter chain. The shape and semantics described in Matt's 2017 threading-model post still match the file you read today.
• The router filter (source/extensions/filters/http/router/). It has gained retries, hedging, shadowing, and HTTP/3 support, but the surface has not been rewritten.
• The threading model in source/server/worker_impl.cc and source/common/thread_local/thread_local_impl.cc. Lock-free per-worker, copy-on-write for config — same design as 2016.
• Hot restart (source/server/hot_restart_impl.cc). Still uses the same shared-memory + Unix-domain-socket protocol it started with.
• The stats system built around the symbol table in source/common/stats/symbol_table.cc — predates SymbolTable as a public concept; the original design memo is the stats blog post.

Major rewrites and migrations

• xDS v2 → v3 (2019–2021). All proto messages duplicated under v3, then v2 removed across the tree. Versioning rules in api/API_VERSIONING.md.
• Buffer rewrite (2019). The legacy LibEvent buffer was replaced with the slice-based source/common/buffer/ implementation. The performance and lifetime semantics changed enough that several filters needed to be rewritten.
• HTTP/2 codec migration to oghttp2 (2022–2023). The original nghttp2 wrapper still exists for compatibility but the new path is the default.
• HTTP/3 / QUIC (2021–present). Built on the QUICHE library. The QUIC-related code is now larger than many older subsystems put together.
• Filter manager refactor (2023). source/common/http/filter_manager.cc at ~88k lines is the result of unifying decoder, encoder, and async filter execution into a single state machine.
• Bazel module migration (2024). The repo gained MODULE.bazel alongside the legacy WORKSPACE. Both still exist; the WORKSPACE will be retired once the bzlmod migration is complete.
• Exception-free data plane (ongoing, 2024–2026). The style guide bans new exceptions on the data plane and discourages them on the control plane. Existing exception sites are being replaced with absl::StatusOr returns.

Deprecated features

• The xDS v2 API. Removed entirely in 2021.
• OpenCensus tracer. Replaced by the OpenTelemetry tracer (source/extensions/tracers/opentelemetry/).
• Envoy proprietary tracer config schemas. Per-tracer typed config replaced the legacy Bootstrap.tracing schema; the deprecation policy in CONTRIBUTING.md walks the field through warning → fatal → removed.
• The original lua filter implementation is still around but the Wasm + dynamic modules combination has subsumed most of its motivating use-cases.
• The legacy source/extensions/filters/http/cache/ is being superseded by source/extensions/filters/http/cache_v2/ — the directories live side by side during the transition.

The DEPRECATED.md file at the repo root tracks user-visible deprecations between releases. For the API specifically, docs/root/version_history/ has a per-release changelog generated from the per-PR changelog YAMLs in changelogs/.

Growth trajectory

• 2016 Q3: ~30k lines of C++, no extensions, single binary.
• 2018: the extension model lands; source/extensions/ is created.
• 2020: Wasm runtimes, the start of QUIC plumbing; ~5k commits/year.
• 2021: contrib/ introduced.
• 2022: Envoy Mobile merged in; the repo nearly doubles its reachable surface.
• 2024: dynamic modules ABI stabilises; the repo crosses ~25k commits.
• 2026 Q2: ~27k commits, ~1.6k unique authors, ~270 commits/month, three flavours of extensibility (C++, Wasm, dynamic modules), three transports (HTTP/1, HTTP/2, HTTP/3), one mobile fork in-tree. Same threading model.

What survives the longest

If you read the codebase looking for what hasn't changed: the threading model, the stats symbol table, the hot restart protocol, the public-interface vs *_impl.cc split, the per-extension factory registration pattern, and the bias toward unique-pointer ownership in the style guide. Almost everything else has been rewritten or replaced at least once.