Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FAQ for implementing a conformance client or server #827

Open
jhump opened this issue Mar 13, 2024 · 3 comments
Open

FAQ for implementing a conformance client or server #827

jhump opened this issue Mar 13, 2024 · 3 comments

Comments

@jhump
Copy link
Member

jhump commented Mar 13, 2024

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 see 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
Copy link
Member Author

jhump commented Mar 13, 2024

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
Copy link
Member

smaye81 commented Mar 13, 2024

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

@drice-buf
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants