lhotari commented on code in PR #24704:
URL: https://github.com/apache/pulsar/pull/24704#discussion_r2324991297
##########
pip/pip-439.md:
##########
@@ -0,0 +1,573 @@
+# PIP-439: Adding Transaction Support to Pulsar Functions Through
Auto-Transaction Wrapping
+
+# Background knowledge
+
+Apache Pulsar transactions enable atomic operations across multiple topics,
allowing producers to send messages and consumers to acknowledge messages as a
single unit
+of work. This provides the foundation for exactly-once processing semantics in
streaming applications.
+
+## Transaction Architecture
+
+Pulsar's transaction system consists of four key components:
+
+1. **Transaction Coordinator (TC)**: A broker module that manages transaction
lifecycles, allocates transaction IDs, and orchestrates the commit/abort
process.
+
+2. **Transaction Log**: A persistent topic storing transaction metadata and
state changes, enabling recovery after failures.
+
+3. **Transaction Buffer**: Temporarily stores messages produced within
transactions, making them visible to consumers only after commit.
+
+4. **Pending Acknowledge State**: Tracks message acknowledgments within
transactions, preventing conflicts between competing transactions.
+
+## Transaction Lifecycle
+
+Transactions follow a defined lifecycle:
+
+1. **OPEN**: Client obtains a transaction ID from the Transaction Coordinator.
+2. **PRODUCING/ACKNOWLEDGING**: Client registers topic
partitions/subscriptions with the TC, then produces/acknowledges messages
within the transaction.
+3. **COMMITTING/ABORTING**: Client requests to end the transaction, TC begins
two-phase commit.
+4. **COMMITTED/ABORTED**: After processing all partitions, TC finalizes the
transaction state.
+5. **TIMED_OUT**: Transactions exceeding their timeout are automatically
aborted.
+
+## Transaction Guarantees
+
+Pulsar transactions provide:
+- Atomic writes across multiple topics
+- Conditional acknowledgment to prevent duplicate processing by "zombie"
instances
+- Visibility control ensuring consumers only see committed transaction messages
+- Support for exactly-once processing in consume-transform-produce patterns
+
+# Motivation
+
+Currently, Pulsar Functions cannot publish to multiple topics transactionally,
which is a significant limitation for use cases requiring atomic multi-topic
+publishing. For instance, if a function processes an input message and needs
to publish related updates to several output topics, there's no guarantee that
all
+operations will succeed atomically.
+
+This limitation prevents building robust stream processing applications that
require exactly-once semantics across multiple input and output topics. Without
+transaction support in Functions, developers must implement their own error
handling and retry mechanisms, which can be complex and error-prone.
+
+Adding transaction support to Pulsar Functions would finally ensure message
processing atomicity.
+
+# Goals
+
+## In Scope
+
+1. Enable automatic transaction support for Pulsar Functions through
configuration
+2. Allow Functions to publish messages to multiple topics within a single
transaction
+3. Support transactional acknowledgment of input messages
+4. Ensure transactions are committed only if message processing completes
successfully
+5. Provide transaction timeout configuration for Functions
+
+## Out of Scope
+
+1. Exposing explicit transaction management APIs in the Functions interface
+2. Supporting multi-function transactions (transactions spanning multiple
function invocations)
+3. Adding transaction support to Pulsar IO connectors
+4. Changes to the Function interface itself
+
+# High Level Design
+
+The proposed solution introduces automatic transaction wrapping for Pulsar
Functions through configuration settings. When enabled, each function execution
will be
+automatically wrapped in a transaction without requiring code changes to the
function implementation.
+
+The general flow will be:
+1. Function is configured with `autoTransactionsEnabled: true`
+2. When a message arrives, the function runtime creates a new transaction
+3. The function processes the message with an enhanced Context that uses the
transaction
+4. Any output messages are published using the transaction
+5. Input message acknowledgment is performed within the transaction
+6. If the function completes successfully, the transaction is committed
+7. If the function throws an exception, the transaction is aborted
+
+This approach provides transaction support in a way that is transparent to
function implementers, requiring only configuration changes rather than code
changes.
+
+# Detailed Design
+
+## Design & Implementation Details
+
+### Configuration Classes
+
+First, we need to extend `FunctionConfig` to include transaction-related
settings:
+
+```java
+public class FunctionConfig {
+ // Whether to automatically wrap each function call in a transaction
+ private boolean autoTransactionsEnabled = false;
+
+ // Default transaction timeout in milliseconds
+ private long transactionTimeoutMs = 60000;
+
+ // Getters and setters
+ public boolean isAutoTransactionsEnabled() {
+ return autoTransactionsEnabled;
+ }
+
+ public void setAutoTransactionsEnabled(boolean autoTransactionsEnabled) {
+ this.autoTransactionsEnabled = autoTransactionsEnabled;
+ }
+
+ public long getTransactionTimeoutMs() {
+ return transactionTimeoutMs;
+ }
+
+ public void setTransactionTimeoutMs(long transactionTimeoutMs) {
+ this.transactionTimeoutMs = transactionTimeoutMs;
+ }
+}
+```
+
+We also need to update the protobuf definition for FunctionDetails to include
these fields:
+
+```java
+message FunctionDetails {
+ // Other existing fields...
+
+ // Whether to automatically wrap function execution in a transaction
+ bool autoTransactionsEnabled = X;
+
+ // Default transaction timeout in milliseconds
+ int64 transactionTimeoutMs = Y;
Review Comment:
In protobuf, the above `TransactionConfig` would map to `TransactionSpec`
message included in `FunctionDetails`.
```protobuf
message FunctionDetails {
// Other existing fields...
TransactionSpec transaction = 24;
}
message TransactionSpec {
enum TransactionMode {
OFF = 0;
MANAGED = 1;
}
TransactionMode transactionMode = 1;
int64 transactionTimeoutMs = 2;
}
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscr...@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
