gRFC A4: Header Extraction

[Mark D. Roth]

I've created a gRFC for the header extraction mechanism we're working on:

https://github.com/grpc/proposal/pull/9

As per the gRFC process, please keep all design discussion on this thread.  All comments welcome.

Carl, can you please provide content for the Java implementation?  Thanks!

Please let me know if you have any questions or comments.

--

Mark D. Roth <ro...@google.com>
Software Engineer
Google, Inc.

[Alfred Fuller]

Thanks!

+Ed Davisson  +Louis Ryan 

[Alfred Fuller]

"When protocol buffers are used for the payload, this must refer to a non-repeated string field."

Datastore needs support for a 'bytes' field for the transaction identifier.

for the user example, you would almost want to split on the @ and keep the second segment (the domain name).

[Mark D. Roth]

On Mon, Jan 30, 2017 at 9:05 PM, Alfred Fuller <arfu...@google.com> wrote:

"When protocol buffers are used for the payload, this must refer to a non-repeated string field."

Datastore needs support for a 'bytes' field for the transaction identifier.

What character encoding do they use for that field, UTF-8?  How can we tell what character encoding is in use?  I think we'd need some way to figure this out in order to support it.

 

for the user example, you would almost want to split on the @ and keep the second segment (the domain name).

That would require adding yet another field to the header extraction spec for the number of leading fields to skip.  Do we actually have a use-case for that?  If not, I don't want to add unnecessary complexity.

The example in the doc was just meant to illustrate that the delimiter character can be anything; it wasn't meant to be a realistic example.

 

On Mon, Jan 30, 2017 at 3:28 PM Alfred Fuller <arfu...@google.com> wrote:

Thanks!

+Ed Davisson  +Louis Ryan 

On Mon, Jan 30, 2017 at 2:14 PM Mark D. Roth <ro...@google.com> wrote:

I've created a gRFC for the header extraction mechanism we're working on:

https://github.com/grpc/proposal/pull/9

As per the gRFC process, please keep all design discussion on this thread.  All comments welcome.

Carl, can you please provide content for the Java implementation?  Thanks!

Please let me know if you have any questions or comments.

--

Mark D. Roth <ro...@google.com>
Software Engineer
Google, Inc.

[Alfred Fuller]

On Tue, Jan 31, 2017 at 8:32 AM Mark D. Roth <ro...@google.com> wrote:

On Mon, Jan 30, 2017 at 9:05 PM, Alfred Fuller <arfu...@google.com> wrote:

"When protocol buffers are used for the payload, this must refer to a non-repeated string field."

Datastore needs support for a 'bytes' field for the transaction identifier.

What character encoding do they use for that field, UTF-8?  How can we tell what character encoding is in use?  I think we'd need some way to figure this out in order to support it.

it is raw bytes, so no encoding (it is a serialized internal protobuf)

It does not require splitting (in fact any modification would be harmful)

Maybe make the delimiter optional? (and when it is set, the field must be a string).

 

for the user example, you would almost want to split on the @ and keep the second segment (the domain name).

That would require adding yet another field to the header extraction spec for the number of leading fields to skip.  Do we actually have a use-case for that?  If not, I don't want to add unnecessary complexity.

The example in the doc was just meant to illustrate that the delimiter character can be anything; it wasn't meant to be a realistic example.

If it is not a real example no point in complicating the API at this moment (I could see it being a real use case to someone), though maybe the field names should use slicing nomenclature incase this ever changes.

[Mark D. Roth]

On Tue, Jan 31, 2017 at 9:44 AM, Alfred Fuller <arfu...@google.com> wrote:

On Tue, Jan 31, 2017 at 8:32 AM Mark D. Roth <ro...@google.com> wrote:

On Mon, Jan 30, 2017 at 9:05 PM, Alfred Fuller <arfu...@google.com> wrote:

"When protocol buffers are used for the payload, this must refer to a non-repeated string field."

Datastore needs support for a 'bytes' field for the transaction identifier.

What character encoding do they use for that field, UTF-8?  How can we tell what character encoding is in use?  I think we'd need some way to figure this out in order to support it.

it is raw bytes, so no encoding (it is a serialized internal protobuf)

It does not require splitting (in fact any modification would be harmful)

Maybe make the delimiter optional? (and when it is set, the field must be a string).

Actually, I think there's a more fundamental problem here.  HTTP2 headers are limited to ASCII characters (see https://tools.ietf.org/html/rfc7540#section-10.3).  Given that, the only way we could support this would be to encode it somehow in the header value.

gRPC does have a pre-existing convention that when a header name ends in "-bin", then the value is automatically base64-encoded and huffman-compressed.  We could presumably use this mechanism in this case (with the restriction that the header name must end in "-bin"), but would we be able to do the required request routing based on the encoded value?

 

 

for the user example, you would almost want to split on the @ and keep the second segment (the domain name).

That would require adding yet another field to the header extraction spec for the number of leading fields to skip.  Do we actually have a use-case for that?  If not, I don't want to add unnecessary complexity.

The example in the doc was just meant to illustrate that the delimiter character can be anything; it wasn't meant to be a realistic example.

If it is not a real example no point in complicating the API at this moment (I could see it being a real use case to someone), though maybe the field names should use slicing nomenclature incase this ever changes.

If and when we actually run into this case, we can add new parameters for slice notation.

 

 

On Mon, Jan 30, 2017 at 3:28 PM Alfred Fuller <arfu...@google.com> wrote:

Thanks!

+Ed Davisson  +Louis Ryan 

On Mon, Jan 30, 2017 at 2:14 PM Mark D. Roth <ro...@google.com> wrote:

I've created a gRFC for the header extraction mechanism we're working on:

https://github.com/grpc/proposal/pull/9

As per the gRFC process, please keep all design discussion on this thread.  All comments welcome.

Carl, can you please provide content for the Java implementation?  Thanks!

Please let me know if you have any questions or comments.

--

Mark D. Roth <ro...@google.com>
Software Engineer
Google, Inc.

--

Mark D. Roth <ro...@google.com>
Software Engineer
Google, Inc.

[Eric Anderson]

I'd feel better if there was an example that did not use delimiterCharacter (the value of the field referenced by payloadFieldName is not mutated).

Note that for streaming RPCs, we extract headers only from the first request message on the stream.

This seems to imply a change in the semantics for streaming RPCs, since streaming RPCs may not have any messages. Today, we have to send the headers immediately, without waiting for the first message. In the past we've disallowed such things instead of changing the semantics (like with safe).

[Eric Anderson]

On Wednesday, February 1, 2017 at 8:52:57 AM UTC-8, Mark D. Roth wrote:

What character encoding do they use for that field, UTF-8?  How can we tell what character encoding is in use?  I think we'd need some way to figure this out in order to support it.

it is raw bytes, so no encoding (it is a serialized internal protobuf)

It does not require splitting (in fact any modification would be harmful)

Maybe make the delimiter optional? (and when it is set, the field must be a string).

Actually, I think there's a more fundamental problem here.  HTTP2 headers are limited to ASCII characters (see https://tools.ietf.org/html/rfc7540#section-10.3).  Given that, the only way we could support this would be to encode it somehow in the header value.

Isn't this a problem for strings as well, as currently defined in the gRFC? How are strings containing non-ASCII or illegal characters handled?

[Mark D. Roth]

On Wed, Feb 1, 2017 at 9:12 AM, 'Eric Anderson' via grpc.io <grp...@googlegroups.com> wrote:

I'd feel better if there was an example that did not use delimiterCharacter (the value of the field referenced by payloadFieldName is not mutated).

Good point.  Added.

 

Note that for streaming RPCs, we extract headers only from the first request message on the stream.

This seems to imply a change in the semantics for streaming RPCs, since streaming RPCs may not have any messages. Today, we have to send the headers immediately, without waiting for the first message. In the past we've disallowed such things instead of changing the semantics (like with safe).

Right.  The doc already explicitly called out this change in the C-core implementation section, but you're right that it should be mentioned here too.  I've added a note about it.

 

--
You received this message because you are subscribed to the Google Groups "grpc.io" group.
To unsubscribe from this group and stop receiving emails from it, send an email to grpc-io+unsubscribe@googlegroups.com.
To post to this group, send email to grp...@googlegroups.com.
Visit this group at https://groups.google.com/group/grpc-io.
To view this discussion on the web visit https://groups.google.com/d/msgid/grpc-io/368277cc-6a5b-4a56-95e0-3c191ae5743a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mark D. Roth]

That's a really good point.  I guess the only real difference between string fields and bytes fields is that the former may be less likely to have non-ASCII characters, but we still have to handle other characters somehow when they do occur.

Right off the cuff, I can think of a few possible options here:

1. Always base64-encode the extracted values.

2. Do base64 encoding only when non-ASCII characters are actually present.

3. Simply strip out non-ASCII characters.

Option 1 seems like it would be easiest to implement, although it might make things a bit harder to debug.  Also, we would probably need to automatically append a "-bin" suffix to header field names.

Option 2 is slightly more complex, because we would have two different encodings, depending on what we find in the request, and the server would need to know to check for both of them (i.e., check for both "${header}" and "${header}-bin", the latter with base64 encoding).  This might make debugging a bit easier in the common case (no non-ASCII characters), but it would leave a potentially rare edge case that might be harder for people to remember to think about.

I suspect that option 3 won't work, because anyone using those characters in the relevant fields presumably needs them as part of their key.

Of course, both options 1 and 2 rest on the assumption that the server can handle the base64 decoding.  Alfred, I'd like your feedback on that.

 

--
You received this message because you are subscribed to the Google Groups "grpc.io" group.
To unsubscribe from this group and stop receiving emails from it, send an email to grpc-io+unsubscribe@googlegroups.com.
To post to this group, send email to grp...@googlegroups.com.
Visit this group at https://groups.google.com/group/grpc-io.

To view this discussion on the web visit https://groups.google.com/d/msgid/grpc-io/1403c8d6-4535-46ee-9174-c0c0ed4addc7%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Eric Anderson]

On Wed, Feb 1, 2017 at 9:38 AM, Mark D. Roth <ro...@google.com> wrote:

Right off the cuff, I can think of a few possible options here:

1. Always base64-encode the extracted values.

2. Do base64 encoding only when non-ASCII characters are actually present.

3. Simply strip out non-ASCII characters.

There's also the option of encoding the special characters. Say, with %-encoding. We're doing this for status messages. I think we are sad each time we have to do this, but it frequently seems to be the least-bad solution.

Note this would get pretty strange (from a parsing perspective) when values are binary, not text. So we may want a different solution for binary.

[Mark D. Roth]

You're right, that is another viable option.  And I do like the fact that it makes things easier to debug in the common case, where the string is mostly ASCII but may have a small number of non-ASCII characters.

The down-side of this approach is that, as you pointed out, we would probably want a separate solution for binary data.  That would mean two different code-paths and probably some way to indicate which one we want to use for each header extraction spec.

Alfred, what are you thoughts on all of this?

[Alfred Fuller]

+Trevor Schroeder what is easiest for the GFE and friends? Base64 decoding a header, url unescaping a header or something else?

(I like the idea of %encoding for strings and base64 encoding bytes, though if I had to pick only one it would probably be base64, as the blowup from that is fixed and known)

[Louis Ryan]

I'm a little confused by this spec. Given that protobuf is backed by a significant amount of code-generation and expression handling machinery why is the spec putting responsibility for the extraction and formatting of these headers on the GRPC runtime? 

Is there some requirement to be able to configure the field extraction behavior dynamically for APIs that did not anticipate the need for it when they were launched? If so it seems like that responsibility should rest entirely on the protobuf runtime and the spec for GRPC should just talk about how to talk to it to get something extracted. The same would be true for other encoding runtimes.

Given that protobuf has (or will have) a standard expression language it seems like that is what should be passed up to the protobuf runtime

[Alfred Fuller]

I think this type of config is very service centric, not interface centric. For example, look at the LRO API. Different services use the same protobuf, but have different resource name formats. If the requirement was copy a field verbatim it 'might' work to define the same extraction for all services that implement LRO, but the requirement here is that the client is able to uniquely identify an 'affinity key', so the protocol must be able to extract the exact substring needed.

I can also see some services implementing a routing layer that is happy to inspect everything, and in those cases, no extraction is needed even though the same interface is exposed.

Also, this eliminates the problems of clients using old configuration with new infrastructure.

So I would say this is not interface configuration, so it should not be in the interface definition (i.e. the proto files).

[Alfred Fuller]

Interestingly, most of the time, the extracted fields are also bound to the url for REST, in which case the strings are URL encoded, and the bytes are base64 encoded. So it would seem to make sense to follow suit.

[Craig Tiller]

I'm very wary about the delimiter character: it seems like it opens the door to adding a whole host of renormalization filters to this spec, and such will eventually lead to mutually inconsistent implementations. I'd strongly prefer that we drop any massaging of the fields client side and instead leave it as a problem for the server.

[Louis Ryan]

On Thu, Feb 2, 2017 at 1:19 PM, Alfred Fuller <arfu...@google.com> wrote:

I think this type of config is very service centric, not interface centric. For example, look at the LRO API. Different services use the same protobuf, but have different resource name formats. If the requirement was copy a field verbatim it 'might' work to define the same extraction for all services that implement LRO, but the requirement here is that the client is able to uniquely identify an 'affinity key', so the protocol must be able to extract the exact substring needed.

I'm not necessarily saying it has to be codegen though that might be a reasonable option for a wide variety of folks where interface and service are not decoupled.

My primary concern is how much GRPC has to know about whats happening. GRPC shouldn't have to know anything more than 

'higher layer please provide me a header value for this opaque rule that I don't understand'

perhaps with an indication of whether the provided value is binary or not.

[Alfred Fuller]

To support client-side demultiplexing needed by much of the upcoming routing technologies, the client needs to be able to extract the exact piece of information that is relevant. 

The current proposal is the minimal amount of extraction support needed for the the use cases we are targeting.  Any future expansion should be relegated to standard extraction/transform methods, for example RE2 or CEL. (I personally would be fine with using RE2 now, though that adds a dependency on the RE2 lib, where this simple form likely doesn't add any deps).

Note that the interpretation of the extracted contents are still opaque to GRPC. GRPC just needs to be able to test for equality. 

[Craig Tiller]

Any proposal that adds a dependency to a regex library is an absolute non-starter in my mind.

I'd really encourage solutions that can take the proto data at face value: if client side demuxing needs a more precise view of some data, then perhaps a better solution is to change the proto.

[Alfred Fuller]

I am also against any use-case specific feature creep. No regex is fine with me (sorry I brought it up, I suspect CEL will be a real alternative at some point, but let's not go there now). 

Unfortunately we can't change the proto. Sanjay decided that paths were a well enough understood concept that it is acceptable to standardize on it for resource names. The minimum requirement for this feature is the ability to grabbing a specific parent from a path. However you want to accomplish that works for me.

[Alfred Fuller]

Why not make the headerName a key to an outer map, instead of using a list. That would enforce uniqueness.

[Craig Tiller]

Can you describe your actual use case for this, and why it can't be accomplished server side? (that seems to be completely missing here, or I've missed it somewhere).

Also, what is CEL?

[Craig Tiller]

Alfred linked me to some docs explaining.

FTR this seems like very use-case specific bloat being piled onto gRPC, with a clearly stated aim to pile more bloat onto the mechanism in the future.

My recommendation would be to drop the delimiter and find some other solution for these use-cases.

[Craig Tiller]

Alternative proposal:

- this mechanism only allows single field extraction, with no string processing

- when we do the affinity based load balancing design, we allow some level of string manipulation there

Advantages:

- this feature becomes universal (if we need to provide a smaller binary, we can drop load balancers, but keep support for dos protection via this mechanism)

- we minimize the blast radius of possible implementations in wrapped languages

[Alfred Fuller]

That sounds great to me. I only need the value extraction for client-side demultiplexing. It solves another issue as well. Specifically that only some of the fields are needed for load balancing/routing. When we have the GRPC LB, we will only want to send the extracted values from fields. The original proposal had a boolean that decides if something is needed for routing. If we move the affinity key extraction to the LB config, it removes the need for that boolean (it is implicitly defined by what fields are referenced in the LB config).

[Alfred Fuller]

(which means I only need value extraction this feature in stacks that support
GRPC LB)

[Louis Ryan]

On Thu, Feb 2, 2017 at 3:34 PM, Craig Tiller <cti...@google.com> wrote:

Alternative proposal:

- this mechanism only allows single field extraction, with no string processing

This seems like a very reasonable restriction if we're allowing more than one header value to be produced. Given that this allows allows the extraction rule to be opaque to GRPC (if not to real implementations) then it can evolve over time as CEL or other datatype expression languages allow

[Mark D. Roth]

(+dgq, who is working on the grpclb affinity design)

FYI, Abhishek told me yesterday that he's gotten some push-back from Sanjay on this approach and is now exploring alternatives, such as possibly pushing the problem up to the layer above gRPC and handling it in VTK.  I think there are some drawbacks to that proposal (most notably the fact that there would not be a centralized way to change the configuration for all clients), but I'm going to hold off on further work on this design until we see what that investigation yields.

That having been said, here are a few comments related to some of the recent discussion.

First, the reason for not pushing the parameters for modifying the field value up into the protobuf layer is that we wanted this mechanism to be agnostic to the serialization mechanism used for the payload.  If, for example, a user was using thrift instead of protobuf, they should be able to use the same mechanism.  And really, modifying the resulting value does not have anything to do with what data structure the value originally came from, so there's no reason that we need to link the two.

That having been said, I am fine with the idea of restricting this mechanism to only extract the full field value and making other mechanisms (e.g., grpclb affinity code or server-side request routing code such as that in the GFEs) responsible for modifying the field value as needed.  I like the fact that this makes it more obvious that extracting the payload field and modifying the resulting value are two separate operations.  This does mean that both the grpclb affinity mechanism and the server-side request routing mechanism would each have to implement their own code to modify the value, but that also adds flexibility, since it would let each of them implement it differently if needed.  And making the server do the value modification probably doesn't add a lot of overhead there, since we're still avoiding the need for the server to deserialize the request payload in order to figure out how to route the request.

The only catch I can think of is that we would probably need to make sure that we apply some sort of length limitation, so that we don't wind up sending a huge amount of data when the server only needs a small prefix.  But that doesn't seem like a problem.

If we do wind up going forward with this proposal, I will change the doc accordingly.  I will update this thread once I know more.

[Mark D. Roth]

It looks like we're going to be pursuing a different approach for this, in which the header field is set in the VTK layer based on static configuration.  As a result, I am withdrawing this gRFC.

Abhishek is driving forward the VTK proposal, so I presume that he will publish something once there are more details to share on that.