ywxzm03 commented on code in PR #921:
URL: https://github.com/apache/dubbo-go-pixiu/pull/921#discussion_r3200677617
##########
skills/pixiu-filter-author/references/filter-interface.md:
##########
@@ -0,0 +1,144 @@
+# The Four (Plus Two) HTTP Filter Interfaces
+
+Source of truth: `pkg/common/extension/filter/filter.go`. Read that file
+first; this reference exists to annotate the shape and the "why".
+
+## Interfaces, in implementation order
+
+### 1. `HttpFilterPlugin`
+
+```go
+type HttpFilterPlugin interface {
+ Kind() string // unique identifier, e.g.
"dgp.filter.http.cors"
+ CreateFilterFactory() (HttpFilterFactory, error)
+}
+```
+
+Every package has exactly one `Plugin` struct that implements this. It
+is what gets registered in `init()` via `filter.RegisterHttpFilter`.
+`Kind()` returns a package-level `const Kind = "..."` — define it once
+at the top of the file and reuse everywhere.
+
+### 2. `HttpFilterFactory`
+
+```go
+type HttpFilterFactory interface {
+ Config() any
+ Apply() error
+ PrepareFilterChain(ctx *http.HttpContext, chain FilterChain) error
+}
+```
+
+Factories are **listener-scoped singletons** (one per listener into
+which the filter is wired). `Config()` returns a pointer so that
+pixiu's config manager can deserialize yaml into it. `Apply()` runs
+**after** deserialization — this is where you validate fields and set
+defaults. `PrepareFilterChain` is called **per request**: construct a
+fresh `Filter` instance, append it to the chain.
+
+Two correctness rules that bit many contributors:
+
+- `Config()` must return a **pointer**, not the struct by value. Yaml
+ binding silently no-ops on a non-pointer.
+- Do not share `factory.cfg` pointer with the per-request `Filter`.
+ Copy out the fields you need so a hot-reload of the factory config
+ does not race with in-flight requests.
+
+### 3. `HttpDecodeFilter`
+
+```go
+type HttpDecodeFilter interface {
+ Decode(ctx *http.HttpContext) FilterStatus
+}
+```
+
+Invoked in **declaration order** as the request travels inbound. Return
+`filter.Continue` to move on or `filter.Stop` to short-circuit. Common
+decode work: authentication, rate limiting, path rewriting, enriching
+`ctx.Params`, emitting request-size metrics.
+
+### 4. `HttpEncodeFilter`
+
+```go
+type HttpEncodeFilter interface {
+ Encode(ctx *http.HttpContext) FilterStatus
+}
+```
+
+Invoked in **reverse declaration order** on the response path. Common
+encode work: response header rewriting, body transformation, masking
+PII, emitting response-size metrics.
+
+A single filter package may implement either, neither (rare), or both.
+If both, `PrepareFilterChain` calls both `chain.AppendDecodeFilters`
+and `chain.AppendEncodeFilters`.
+
+### 5. `NetworkFilterPlugin` (L4)
Review Comment:
这是OSI Layer 4缩写，但在这里完全没有必要，我的疏忽
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
