Pass headers when fetching next links

[jkarneges]

With HTTP streaming, it's possible to set a "next link". Next links are followed without passing along extra headers, such as the original client request headers. This means authenticating a request of a next link requires authentication material to be included in the link itself, for example by include an auth token as a query parameter. It might be nice if there were a way for requests of next links to use headers for auth.

Note that next links are intended to be shared by multiple clients to enable request collapsing, so a headers-based solution should have a way to provide special shared creds generated by the origin server, rather than only simply passing the original client request headers which would likely include client-specific creds.

[jkarneges]

Proposal: a set-header param on Grip-Link specifying a request header using the form name:value.

For example:

HTTP/1.1 200 OK
Grip-Hold: stream
Grip-Channel: foo; prev-id=1
Grip-Link: </stream>; rel=next; set-header="Authorization:Bearer {token}"

When such set headers are used for authentication, the origin could set client-specific or shared creds at its option. If the URIs and set headers are identical for more than one client, then request collapsing could be performed.

For convenience we could also have a way to tell Pushpin to simply pass along a certain request header, with a pass-header param:

HTTP/1.1 200 OK
Grip-Hold: stream
Grip-Channel: foo; prev-id=1
Grip-Link: </stream>; rel=next; pass-header=Authorization

In the case of client-specific auth creds, this would avoid needing to duplicate the creds again in the Grip-Link response header. The specified header would need to be one used in the most recent request from Pushpin (either the initial one triggered by the client, or a subsequent next fetch). If the specified header wasn't used in the prior request then this param would have no effect, or perhaps we error out the connection.

Multiple instances of set-header and pass-header could be supported.

[jkarneges]

While we're at it, consider adding a generic header to indicate whenever a request originated from the proxy. This could be useful for trusting the request URI, as well as for trusting any headers set by the above extension (which the client could otherwise set on its own and the backend wouldn't be able to tell the difference). E.g.:

HTTP/1.1 200 OK
Trusted-Header: foo
Grip-Proxy-Originated: true
Grip-Link: </path?trusted_param>; rel=next

This could be used when following next links, as well as when retrying response holds.

Of course, to fully trust a request from the proxy, the backend also needs to validate Grip-Sig. But another header is needed to differentiate client-initiated vs proxy-initiated, as Grip-Sig is included in both cases.