|
| 1 | +syntax = "proto3"; |
| 2 | + |
| 3 | +package envoy.extensions.filters.http.sse_to_metadata.v3; |
| 4 | + |
| 5 | +import "envoy/config/core/v3/extension.proto"; |
| 6 | + |
| 7 | +import "google/protobuf/wrappers.proto"; |
| 8 | + |
| 9 | +import "xds/annotations/v3/status.proto"; |
| 10 | + |
| 11 | +import "udpa/annotations/status.proto"; |
| 12 | +import "validate/validate.proto"; |
| 13 | + |
| 14 | +option java_package = "io.envoyproxy.envoy.extensions.filters.http.sse_to_metadata.v3"; |
| 15 | +option java_outer_classname = "SseToMetadataProto"; |
| 16 | +option java_multiple_files = true; |
| 17 | +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/sse_to_metadata/v3;sse_to_metadatav3"; |
| 18 | +option (udpa.annotations.file_status).package_version_status = ACTIVE; |
| 19 | +option (xds.annotations.v3.file_status).work_in_progress = true; |
| 20 | + |
| 21 | +// [#protodoc-title: SSE-To-Metadata Filter] |
| 22 | +// |
| 23 | +// The SSE-To-Metadata filter extracts values from Server-Sent Events (SSE) HTTP response bodies |
| 24 | +// and writes them to dynamic metadata. This is useful for LLM token usage tracking, |
| 25 | +// logging, and other observability use cases. |
| 26 | +// |
| 27 | +// The filter specifically handles SSE format (text/event-stream) and uses pluggable content |
| 28 | +// parsers to extract values from the SSE data fields. The content parser is a typed extension |
| 29 | +// that can be configured to handle different content types (JSON, plaintext, XML, etc.). |
| 30 | +// |
| 31 | +// The filter only processes responses with Content-Type "text/event-stream" |
| 32 | +// (the standard SSE content type). Content-Type parameters such as charset are ignored. |
| 33 | +// |
| 34 | +// See SSE-To-Metadata :ref:`configuration overview <config_http_filters_sse_to_metadata>` for more details. |
| 35 | +// [#extension: envoy.filters.http.sse_to_metadata] |
| 36 | + |
| 37 | +message SseToMetadata { |
| 38 | + // Rules for processing SSE streams and extracting metadata. |
| 39 | + // |
| 40 | + // The filter parses the SSE protocol (events delimited by blank lines), then delegates |
| 41 | + // to a content parser to parse event content and extract metadata. The content parser |
| 42 | + // determines which values to extract and how to write them to metadata. |
| 43 | + message ProcessingRules { |
| 44 | + // Content parser configuration for parsing event content and extracting metadata. |
| 45 | + // |
| 46 | + // The content parser specifies: |
| 47 | + // - How to parse the event data (e.g., JSON, XML, plaintext) |
| 48 | + // - Which values to extract from the parsed content (e.g., JSON paths like usage.total_tokens) |
| 49 | + // - How to map extracted values to metadata (namespace, key, type conversions) |
| 50 | + // - When to write metadata (on_present, on_missing, on_error actions) |
| 51 | + // [#extension-category: envoy.content_parsers] |
| 52 | + config.core.v3.TypedExtensionConfig content_parser = 1 |
| 53 | + [(validate.rules).message = {required: true}]; |
| 54 | + |
| 55 | + // Maximum size in bytes for a single SSE event before it's considered invalid |
| 56 | + // and discarded. This protects against unbounded memory growth from malicious |
| 57 | + // or malformed streams that never send event delimiters (blank lines). |
| 58 | + // |
| 59 | + // Default is 8192 bytes (8KB), which is sufficient for most legitimate events. |
| 60 | + // Set to 0 to disable the limit (not recommended for production). |
| 61 | + // Maximum allowed value is 10485760 bytes (10MB). |
| 62 | + google.protobuf.UInt32Value max_event_size = 2 [(validate.rules).uint32 = {lte: 10485760}]; |
| 63 | + } |
| 64 | + |
| 65 | + // Rules for processing SSE response streams. |
| 66 | + ProcessingRules response_rules = 1 [(validate.rules).message = {required: true}]; |
| 67 | +} |
0 commit comments