Expansion of "how" section for Payload Processing

proposals/7-payload-processing.md

@@ -165,18 +165,101 @@ Requirements:
 
 ### Implementation Details
 
-TODO: in a later PR.
-
-> This should be left blank until the "What?" and "Why?" are agreed upon,
-> as defining "How?" the goals are accomplished is not important unless we can
-> first even agree on what the problem is, and why we want to solve it.
->
-> This section is fairly freeform, because (again) these proposals will
-> eventually find there way into any number of different final proposal formats
-> in other projects. However, the general guidance is to break things down into
-> highly focused sections as much as possible to help make things easier to
-> read and review. Long, unbroken walls of code and YAML in this document are
-> not advisable as that may increase the time it takes to review.
+
+
+### Operational Requirements and Assumptions
+
+* Gateway MUST provide Processors with plaintext traffic. Any decryption and (re-)encryption MUST happen in Gateway implementation.
+* Gateway MUST support Processors running as workloads on the cluster, as well as remote endpoints. (We should probably focus on cluster-local Services for the first phase)
+* Topology-Aware Routing (or similar constraints) are highly desirable when configuring Gateway consumption of Processors (both due to latency
+concerns, and also since cross-node/cross-AZ traffic may have cloud-networking costs associated with it).
+* Processor MAY support scale based on operational metrics from Gateway.
+* Processor MAY present indications of its capacity (or lack thereof) to Gateway. Gateway MAY support reducing the traffic 
+load on the Processor if such indications are presented. In some scenarios, the user MAY prefer degrading payload processing
+over significant impact on data plane performance.
+
+## Resource Model
+
+
+### Payload Processor Custom Resource
+
+
+`HTTPRoute` **rules** are the most specific level where we wish to prescribe Payload Processors.
+The amount of details and settings we need to support at the processor level is greater than what we can comfortable inline within a sub-object
+of `HTTPRoute` (See also how long `spec.rules.filters` can become on its own, today).
+
+The approach below creates a new custom resource kind for Payload Processing Pipelines.
+A minimal `HTTPRoute` that references a processor pipeline is shown below.
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: example-httproute
+spec:
+  parentRefs:
+  - name: example-gateway
+  hostnames:
+  - "www.example.com"
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /query
+    backendRefs:
+    - name: example-svc
+      port: 8080
+    processing:
+    - name: prompt-injection-guardrails
+      pipelineRef:
+        name: prompt-injection-protection
+---
+apiVersion: gateway.networking.k8s.io/v1alpha1
+kind: PayloadProcessingPipeline
+metadata:
+  name: prompt-injection-protection
+spec:
+  # Sequence of processors
+  rules:
+  - name: malicious-prompt-prevention
+    # Indicates if this processor rule can mutate passed data
+    mutating: true
+    # Determines which parts of the request/response pair is of interest to the processor
+    phases: ["request-headers", "request-body", "response-headers", "response-body"]
+    # Defines the callout type, in this case it is backed by a service hosted on the cluster
+    endpointRef:
+      kind: Service
+      name: bad-prompt-detector
+    # Configuration for the callout itself
+    remoteConfig:
+      timeout: "250ms"
+      fail: open | closed
+      # Context to send in gRPC Metadata
+      context: 
+        tenant_id: "customer-a"
+```
+
+## Open Design Questions
+
+* Payload Processors MUST implement a custom (gRPC?) protocol (specifics TBD, part of a future PR). This protocol allows them to receive phases of the request lifecycle and emit one of several signals, such as:
+    * "give me the next part"
+    * "this request is approved"
+    * rejection of the request/response
+    * "this response is approved"
+    * "change this part I received to be as follows: ..."
+* Payload Processors MAY receive additional context as part of their configuration... Is this a real use case?
+* We need to figure out whether to allow conceptual "processing loops" between `spec.rules.matches` and **mutating** payload processors.
+    * Would an approach that avoids processing loops between `spec.rules.matches` and Payload Processors be making any use case impossible to implement?
+* There is potential overlap between `spec.rules.filters` and `spec.rules.processors`:
+    * Do we avoid it for now?
+    * Processers can supplant filters, but should they?
+    * If we retain both, should Processors be invoked before or after any filters? (Do we want to support both approaches?)
+* How do Gateway-level Processors and HTTPRoute-level Processors co-exist?
+    * Do we allow defining both? (current assumption is that it is allowed)
+    * How do we co-prioritize them?
+* Expressibility of concurrency between Pipeline `.spec.rules` list items (perhaps as second-level list)
+
+
 
 # Relevant Links