docs/protocol: define headers for tchannel language and version

[jcorbin]

This defines three new init headers:

• tchannel_language to identify the implementation language
• tchannel_language_version to identify the version of the implementation language
• tchannel_version to identify the version of the implementation

r @breerly @prashantv @mranney @ShanniLi

[jcorbin]

The plan is that a central authority, such as hyperbahn, can collect and report on these things... and eventually enforce cut off versions.

[ShanniLi]

:+1:

[ShanniLi]

@jcorbin So, if Hyperbahn decides to cut off a version. What init res message should it send?

[prashantv]

lgtm

[jcorbin]

@ShanniLi probably:

• the init res would be no different
• however we'd follow up the init res with an immediate null-id'd Declined error frame
• close the connection immediately.

Basically, an even harder form of our current draining mechanism.

[jcorbin]

Oh furthermore @ShanniLi, these fields would be required of both init req and init res, since when hyperbahn connects to you, it cares about the versions sent in your init res to its init req.

[ShanniLi]

@jcorbin Thanks, makes sense. :)

[willsalz]

Why are these needed at all? Why does tchannel/hyperbahn care about implementation language? And what is tchannel_language_version? Is that a SemVer of the library implementing hyperbahn/tchannel? Are you planning on cutting off older versions of libraries? That seems crazy.

[jcorbin]

Great questions @willsalz , we're adding this primarily to get visibility in production so that we can help eliminate version skew. It may be possible to get similar benefit by auditing repositories and build artifacts internally, but the reality of what's being used in production is likely to be much more reliable than any such integration.

the tchannel_language_version is the version of "language", whatever that means for the language:

• for node it would simple be the runtime version of node
• for python or pypy or others, it's again pretty clear
• for java it'll likely be the runtime version (irrespective of how it was built)
• for go it'll be the version of go that built the binary, since there is no dynamic runtime

Eventually we may decide to cut off old versions, but only based on clear auditing of what versions are being used and weighed against whatever the reason is for that enforcement.

We'll first have to track getting everyone upgraded to libraries which send this new field, including e.g. a backported version to tchannel-node's 2.x series.

[HelloGrayson]

:ship:

[willsalz]

OK why not have people put this in headers or something?

[jcorbin]

This is in the headers, of the connection init message @willsalz ; we'd like to avoid transmitting it as overhead on every single call message.