taler-docs

wait-transaction-state.rst (5372B)

---

 .. ts:op:: waitTransactionState
   :read-only:
 
   Wait until a transaction is in a particular state.  The operation
   blocks until the transaction reaches the requested state, an
   error occurs, or the timeout expires.
 
   **Request:**
 
     The request ``args`` must be a `WaitTransactionStateRequest`
     object.
 
   **Response:**
 
     On success, the result is a `WaitTransactionStateResponse`
     object.
 
   **Details:**
 
     This is a long-polling operation: it returns once the
     transaction's state matches ``txState``, matches one of the
     ``bailStates``, or (with ``bailOnError``) an error is recorded
     for the transaction.  The response's ``matched`` field says which
     of the two sets of states ended the wait.
 
     The ``txState`` and ``bailStates`` fields are
     `TestingWaitTxStateSpec` values: a `TransactionStatePattern` or a
     list of patterns (matching when any pattern matches), a
     wallet-internal numeric state ID, or one of the shorthands
     ``nonpending`` (any major state other than ``pending``) and
     ``final`` (any final major state).  In a pattern, ``major``,
     ``minor`` and ``working`` accept the wildcard ``*``; a pattern
     without ``minor`` only matches states that have no minor state,
     while a pattern without ``working`` matches regardless of the
     flag.
 
     Without ``bailStates`` or ``bailOnError``, a transaction that
     reaches a state it will never leave keeps the caller waiting
     until the ``timeout`` expires; the wait then fails with
     ``GENERIC_TIMEOUT``.
 
     If no transaction with the given ``transactionId`` exists, the
     wait fails with ``WALLET_TRANSACTION_NOT_FOUND`` instead of
     waiting.
 
     When ``progressToken`` is set, the wait reports request
     progress notifications (including recorded transaction errors
     with their retry counter and remaining retry delay) and can be
     cancelled with :ts:op:`cancelProgressToken` or nudged with
     :ts:op:`retryProgressTokenNow`.  Cancellation fails the wait
     with ``WALLET_CORE_REQUEST_CANCELLED``; it stops only the wait,
     not the transaction.
 
 .. ts:def:: WaitTransactionStateRequest
 
   interface WaitTransactionStateRequest {
     transactionId: TransactionIdStr;
 
     // Receive request progress notifications and control this wait
     // via ``cancelProgressToken``/``retryProgressTokenNow``.
     // Cancellation stops only the wait.  Retry-now retries the
     // transaction if its current state allows it, without
     // restarting the wait or extending its timeout.  Transaction
     // errors are reported with their recorded retry counter and
     // remaining delay; without a recorded error retry, the counter
     // is zero and the delay is "forever".
     progressToken?: string;
 
     // Additional identifier that is used in the logs to easily
     // find the status of the particular wait request.
     logId?: string;
 
     // After the timeout has passed, give up on waiting for the
     // desired state and raise an error instead.
     timeout?: DurationUnitSpec;
 
     // If set to true, wait until the desired state is reached
     // with an error.
     requireError?: boolean;
 
     // State(s) to wait for.
     txState: TestingWaitTxStateSpec;
 
     // States that end the wait even though they are not the state
     // that was waited for.  The response says which of the two
     // sets matched.  Without this, a transaction that ends up in
     // a state it will never leave keeps the caller waiting until
     // the timeout.
     bailStates?: TestingWaitTxStateSpec;
 
     // End the wait as soon as an error is recorded for the
     // transaction.  Beware that this includes transient errors of
     // retried operations, which are cleared again once the
     // operation succeeds.
     bailOnError?: boolean;
   }
 
 .. ts:def:: WaitTransactionStateResponse
 
   interface WaitTransactionStateResponse {
     // Which set of states ended the wait: the requested state or
     // one of the bail states.
     matched: "target" | "bail";
 
     // State that ended the wait.
     txState: TransactionState;
 
     // Wallet-internal state ID, only used for debugging and
     // testing.
     stId: number;
   }
 
 .. ts:def:: TestingWaitTxStateSpec
 
   // State(s) to wait for: a plain pattern or a list of patterns
   // (matching any of them), a wallet-internal numeric state ID, or
   // one of the shorthands for a category of states.
   type TestingWaitTxStateSpec =
     | TransactionStatePattern
     | TransactionStatePattern[]
     | number
     | "nonpending"
     | "final";
 
 .. ts:def:: TransactionStatePattern
 
   interface TransactionStatePattern {
     major: TransactionMajorState | TransactionStateWildcard;
 
     minor?: TransactionMinorState | TransactionStateWildcard;
 
     // Required value of the "working" flag of the transaction
     // state.  A transaction state without the flag counts as
     // false.  If left undefined, the flag is not taken into
     // account when matching, i.e. it behaves like a wildcard.
     working?: boolean | TransactionStateWildcard;
   }
 
 .. ts:def:: TransactionStateWildcard
 
   type TransactionStateWildcard = "*";
 
 .. ts:def:: DurationUnitSpec
 
   // A duration given as a sum of the specified units; used for
   // timeouts.
   interface DurationUnitSpec {
     seconds?: number;
 
     minutes?: number;
 
     hours?: number;
 
     days?: number;
 
     months?: number;
 
     years?: number;
   }