Document the generic diagnostic-headers mechanism

[sascha-egerer]

No description provided.

[Copilot]

Pull request overview

Documents the new generic “diagnostic headers” mechanism (matcher-provided headers carried via MatchResult metadata) and updates existing OWASP CRS/debugging docs to reference the new enableDiagnosticsHeaders() API (with enableOwaspDiagnosticsHeader() noted as a deprecated alias).

Changes:

• Replace OWASP-specific diagnostics-header documentation/examples with the generic enableDiagnosticsHeaders() mechanism.
• Explain how matchers declare diagnostic headers via diagnostic_headers metadata and how this applies beyond blocklists (e.g., Fail2Ban filters).
• Expand observability/notifications/architecture docs to highlight MatchResult availability on matcher-carried events and how listeners can read matcher metadata.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/features/owasp-crs.md	Updates OWASP CRS docs to the generic diagnostics headers API and explains diagnostic_headers metadata behavior.
docs/faq.md	Updates debugging guidance to enableDiagnosticsHeaders() and documents matcher-provided diagnostic headers.
docs/advanced/track-notifications.md	Notes that matcher-carried events expose MatchResult for consumers.
docs/advanced/portable-config.md	Updates portable-config option list to the new diagnostics headers API and clarifies the deprecated alias.
docs/advanced/observability.md	Adds a summary explaining MatchResult exposure on matcher-carried events and metadata access.
docs/advanced/architecture.md	Updates architecture docs to the new diagnostics headers flag and explains response copying behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

docs/features/owasp-crs.md:285

• This sentence implies enableResponseHeaders() is required to see which OWASP rule matched, but the info box below says X-Phirewall-Owasp-Rule is controlled independently by enableDiagnosticsHeaders(). Consider rephrasing to make enableResponseHeaders() clearly optional (only needed for X-Phirewall / X-Phirewall-Matched).

Enable response and diagnostic headers to see which OWASP rule matched:

docs/advanced/portable-config.md:91

• “on fromArray() deserialize” reads like a verb phrase; using “during fromArray() deserialization” is grammatically clearer.

`filterHeaderEquals`, `filterHeaderPresent`, and `filterHeaderRegex` are rejected on `safelist()` (and on `fromArray()` deserialize): a client-controlled header value would be a forgeable bypass token (anyone presenting it skips every downstream rule). They remain valid on blocklists, throttles, Fail2Ban, Allow2Ban, and track rules.