Documentation: clarify the threading model

[chibenwa]

Issue description

CF linagora/tmail-backend#1247

Got my ass kicked today diagnoising an unresponsive Apisix plugin when the underlying Redis is down.

By instinct I pushed the team to use a non blocking apprach as it leads to better resource management.

But digging more I discovered the code actually runs directly on the netty event loop. This means that any blocking IOs would cause the plugin to stop progress.

While I'm very happy the plugin runs directly Netty (performance!) this should be better documented, and also I do believe the examples should include an asynchronous example. Most of the devs around do not have the culture to understand the danger and need strong guidance. Busy tech leaders need a clear succinct statement to orientate code review and catch defects early.

I would happily propose myself to write this doc!

Environment

• your apisix-java-plugin-runner version : 4.0

Minimal test code / Steps to reproduce the issue

Code snippet: https://github.com/linagora/tmail-backend/tree/master/demo/apisix/tmail-apisix-plugin-runner

Reactified version: linagora/tmail-backend#1412

What's the expected result?

Doc and example being clear enough so that no other team ever do the mistakes mine did!

[chibenwa]

Merged on master