...

1. We should have a clear distinguishment between fatal and abortable errors. Today they are all wrapped as KafkaExceptions and hence users cannot really tell the difference, so they have to just treat them all as fatal. One idea is to wrap them differently: we use KafkaException to wrap fatal errors, while use AbortableException to wrap abortable errors.
2. We should have consistent mechanisms on wrapping errors. More specifically:
   1. All exceptions should be wrapped at most once.
   2. We should not have a nested wrapping like KE(KE(e)). Instead we should just have KE(e).
   3. For IllegalState / Runtime errors which indicate a bug, we should not wrap but directly throw.
3. For errors that can be thrown from both scenario 1) and 2) above, we should have a clear guidance on how EOS users should handle them. More specifically:
   1. Users should be safely ignore the returned future since all errors that should be set inside the TransactionManager as well and hence users should just capture the function itself.
   2. The only error that's thrown only in 2) is TransactionAbortedException, and it could just be ignored since the user asked the producer to close.
4. From EOS-related exceptions thrown directly from the call, we would just check if they are abortable or fatal:
   1. For abortable exception, re-throw them as TxnCorruptedException which will be handled by aborting the txns.
   2. For fatal exception, re-throw them as TaskMigratedException which will cause us to lose all tasks and re-join the group.

Proposed Changes

We are proposing a new transactional API usage template which makes EOS processing safer from handling a mix of fatal and non-fatal exceptions:

...