FAQ for implementing a conformance client or server

[jhump]

We now have detailed docs for testing a client or server implementation.

But there are some issues that we've hit when implementing these that warrant a Frequently Asked Questions page.

Here are the issues I'm thinking we could seed the FAQ with:

• Why do I see an "invalid error" for every request from my conformance client?
  • We need to review a little further how exactly this manifests, but this would likely be about not passing request headers from the client under test. The reference server requires one of the headers to always be present (a header that identifies the particular test case for the request), and rejects requests that don't have it. So if someone is trying out a client implementation to test, but haven't yet implemented passing request headers, nothing will actually work.
• Why do I keep getting "timed out waiting for result from client"?
  • Something about flushing the output and making sure the client process cleanly exits at the end and responds to SIGTERM by exiting.
  • Probably also mention troubleshooting with --v and how to safely log from the program under test by writing to stderr.
• Why am I seeing encoding errors?
  • Something here about incorrectly supporting "deflate" compression (using RFC 1951 instead of RFC 1950, which is a trivial and common mistake to make that even we made in earlier release candidates -- see Fix deflate algorithm to adhere to RFC 1950 #824 for more context).
  • Maybe something here also about making sure that client disables support for all compression algorithms other than the one indicated in the ClientCompatRequest (need more info the client docs for this, too).

@smaye81, @srikrsna-buf, @rebello95, @drice-buf, @jchadwick-buf: I'd love for all of you to add anything else you can think of regarding issues you encountered working with this stuff. Some of the FAQ items will likely also warrant some extra info in some of the other doc pages, too.

[jhump]

We probably also want content about accidentally writing stuff to stdout, which could confuse the test runner and likely be misinterpreted as a very large 32-bit number. This would be a source of the tests hanging or generating the "timed out waiting for result from client" issue. We could also improve the test runner here by requiring that client results be 16mb or smaller and than server results be 1mb or smaller (which should both be reasonable limits for the expected contents of these response messages). This would require the most siginificant byte(s) of the 32-bit length prefix to be zero, which is unlikely to be the case for text that is mistakenly printed to stdout.

[smaye81]

Accidentally writing to stdout burned me a few times, so I would definitely recommend adding that.

[drice-buf]

FYI using Java remote debugging can trigger the issue with writing to stdout. The fix is to include quiet=y in the debugger flags.