Thrift-To-Metadata Filter (proto)

This extension has the qualified name envoy.filters.http.thrift_to_metadata

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.filters.http

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.filters.http.thrift_to_metadata.v3.ThriftToMetadata

The Thrift to Metadata filter serves for thrift over HTTP traffic, expecting serialized Thrift request and response bodies in the HTTP payload. It extracts thrift metadata from the HTTP body and put them into the filter metadata. This is useful for matching load balancer subsets, logging, etc.

Thrift to Metadata configuration overview.

extensions.filters.http.thrift_to_metadata.v3.KeyValuePair

[extensions.filters.http.thrift_to_metadata.v3.KeyValuePair proto]

{
  "metadata_namespace": ...,
  "key": ...,
  "value": {...}
}

metadata_namespace: (string) The namespace — if this is empty, the filter’s namespace will be used.

key: (string, REQUIRED) The key to use within the namespace.

value

(Value) When used for on_present case, if value is non-empty it’ll be used instead of the field value.

When used for on_missing case, a non-empty value must be provided.

extensions.filters.http.thrift_to_metadata.v3.FieldSelector

[extensions.filters.http.thrift_to_metadata.v3.FieldSelector proto]

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

{
  "name": ...,
  "id": ...,
  "child": {...}
}

name: (string, REQUIRED) field name to log

id: (int32) field id to match

child: (extensions.filters.http.thrift_to_metadata.v3.FieldSelector) next node of the field selector

extensions.filters.http.thrift_to_metadata.v3.Rule

[extensions.filters.http.thrift_to_metadata.v3.Rule proto]

{
  "field": ...,
  "field_selector": {...},
  "method_name": ...,
  "on_present": {...},
  "on_missing": {...}
}

field: (extensions.filters.http.thrift_to_metadata.v3.Field) The field to match on. If set, takes precedence over field_selector.

field_selector

(extensions.filters.http.thrift_to_metadata.v3.FieldSelector) Specifies that a match will be performed on the value of a field in the thrift body. If set, the whole http body will be buffered to extract the field value, which may have performance implications.

It’s a thrift over http version of field_selector.

See also payload-to-metadata for more reference.

Example:

method_name: foo
field_selector:
  name: info
  id: 2
  child:
    name: version
    id: 1

The above yaml will match on value of info.version in the below thrift schema as input of on_present or on_missing while we are processing foo method. This rule won’t be applied to bar method.

struct Info {
  1: required string version;
}
service Server {
  bool foo(1: i32 id, 2: Info info);
  bool bar(1: i32 id, 2: Info info);
}

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

method_name: (string) If specified, field_selector will be used to extract the field value only on the thrift message with method name.

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

on_present

(extensions.filters.http.thrift_to_metadata.v3.KeyValuePair) The key-value pair to set in the filter metadata if the field is present in thrift metadata.

If the value in the KeyValuePair is non-empty, it’ll be used instead of field value.

on_missing

(extensions.filters.http.thrift_to_metadata.v3.KeyValuePair) The key-value pair to set in the filter metadata if the field is missing in thrift metadata.

The value in the KeyValuePair must be set, since it’ll be used in lieu of the missing field value.

extensions.filters.http.thrift_to_metadata.v3.ThriftToMetadata

[extensions.filters.http.thrift_to_metadata.v3.ThriftToMetadata proto]

The configuration for transforming thrift metadata into filter metadata.

{
  "request_rules": [],
  "response_rules": [],
  "transport": ...,
  "protocol": ...,
  "allow_content_types": [],
  "allow_empty_content_type": ...
}

request_rules: (repeated extensions.filters.http.thrift_to_metadata.v3.Rule) The list of rules to apply to http request body to extract thrift metadata.

response_rules: (repeated extensions.filters.http.thrift_to_metadata.v3.Rule) The list of rules to apply to http response body to extract thrift metadata.

transport: (extensions.filters.network.thrift_proxy.v3.TransportType) Supplies the type of transport that the Thrift proxy should use. Defaults to AUTO_TRANSPORT.

protocol: (extensions.filters.network.thrift_proxy.v3.ProtocolType) Supplies the type of protocol that the Thrift proxy should use. Defaults to AUTO_PROTOCOL. Note that LAX_BINARY is not distinguished by AUTO_PROTOCOL, which is the same with thrift_proxy network filter. Note that TWITTER is not supported due to deprecation in envoy.

allow_content_types

(repeated string) Allowed content-type for thrift payload to filter metadata transformation. Default to {"application/x-thrift"}.

Set allow_empty_content_type if empty/missing content-type header is allowed.

allow_empty_content_type: (bool) Allowed empty content-type for thrift payload to filter metadata transformation. Default to false.

extensions.filters.http.thrift_to_metadata.v3.ThriftToMetadataPerRoute

[extensions.filters.http.thrift_to_metadata.v3.ThriftToMetadataPerRoute proto]

Thrift to metadata configuration on a per-route basis, which overrides the global configuration for request rules and responses rules.

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

{
  "request_rules": [],
  "response_rules": []
}

request_rules: (repeated extensions.filters.http.thrift_to_metadata.v3.Rule) The list of rules to apply to http request body to extract thrift metadata.

response_rules: (repeated extensions.filters.http.thrift_to_metadata.v3.Rule) The list of rules to apply to http response body to extract thrift metadata.

Enum extensions.filters.http.thrift_to_metadata.v3.Field

[extensions.filters.http.thrift_to_metadata.v3.Field proto]

METHOD_NAME: (DEFAULT) ⁣The Thrift method name, string value.

PROTOCOL: ⁣The Thrift protocol name, string value. Values are “binary”, “binary/non-strict”, and “compact”, with “(auto)” suffix if protocol is set to AUTO_PROTOCOL

TRANSPORT: ⁣The Thrift transport name, string value. Values are “framed”, “header”, and “unframed”, with “(auto)” suffix if transport is set to AUTO_TRANSPORT

HEADER_FLAGS: ⁣The Thrift message type, singed 16-bit integer value.

SEQUENCE_ID: ⁣The Thrift sequence ID, singed 32-bit integer value.

MESSAGE_TYPE: ⁣The Thrift message type, string value. Values in request are “call” and “oneway”, and in response are “reply” and “exception”.

REPLY_TYPE: ⁣The Thrift reply type, string value. This is only valid for response rules. Values are “success” and “error”.