It is recommended to improve the SDK thread safety mechanism

[w2534073922]

Background

When developing a Dify plugin, I encountered a thread-related issue that is extremely difficult to troubleshoot:

• In the current SDK, under the Remote (full-duplex) mode, the underlying reader/writer channels are not thread-safe.
• When the main thread and sub-threads concurrently access the SDK session (for example, the main thread (endpoint) quickly responds to HTTP requests, and sub-threads asynchronously call reverse invocations such as self.session.app.chat.invoke), phenomena like "long waits, eventual network errors, or timeouts" occur.
• After adjusting the code structure (such as moving external HTTP requests into sub-threads), this issue manifests as follows: when the main thread no longer performs network operations, reverse invocations in sub-threads get blocked.

Problem Analysis

• The SDK's full-duplex implementation relies on a controlled read/write loop, which typically works stably only under specific threads/contexts.
• When multiple threads concurrently access the same session, competition or deadlocks occur for underlying resources (sockets, readers/writers, event loops), resulting in callbacks failing to receive responses.
• The phenomenon is extremely difficult to troubleshoot and is easily mistaken for network/business issues. In fact, it is caused by the opacity of the SDK's thread model.

Suggestions

• It is hoped that the official SDK team:
  1. Can clearly specify the requirements and limitations for thread usage in the SDK in the documentation.
  2. Provide thread-safe invocation methods to prevent developers from encountering inexplicable issues due to thread problems.

Reproduction Method

• Have the main thread of the plugin quickly return an HTTP response, and call self.session.app.chat.invoke in a sub-thread.
• Or place all network operations in sub-threads, leaving the main thread idle. In this case, reverse invocations are likely to be blocked.

Expectations

• The SDK can better support asynchronous/multi-threaded scenarios, or at the very least, prevent developers from falling into pitfalls.
• Improve the usability and robustness of the SDK, and reduce hidden thread traps.