envoyproxy/envoy

filters: improve docs & protections around callbacks

Open

#13,737 opened on Oct 23, 2020

View on GitHub
 (11 comments) (0 reactions) (0 assignees)C++ (5,373 forks)batch import
area/httphelp wantedtech debt

Repository metrics

Stars
 (27,997 stars)
PR merge metrics
 (Avg merge 8d) (378 merged PRs in 30d)

Description

We recently ran into an internal problem where an in-house filter was returning a local reply and immediately after returning FilterHeaderStatus::Continue, which ends up confusing the Router filter machinery.

A few things can be done to improve the experience for filter developers:

  1. improve docs around the contract with filters (e.g.: #13678, I'll send another one for docs/root/faq/extensions/contract.rst as well)

  2. enforce more checks to ensure callbacks cannot be called after a local reply has been sent

  3. more assertions around the filter chain state machine

cc: @alyssawilk @mattklein123

Contributor guide

Research direction
Study the existing documentation on filter callbacks and the contract in the Envoy source code. Identify where local replies and callbacks intersect and propose documentation improvements and code checks.
Tech stack
cpp
Domain
backend
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
C++Envoy filter development
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65