taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

payment-poll-crashes-when-the-session-ends.md (5445B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # The terminal dies one second after the session ends on the payment screen
     18 
     19 The payment screen polls the backend once a second to see whether the customer
     20 has paid. If the merchant's session ends while it is doing that -- the token
     21 expires, or the back office revokes it -- the next poll kills the app:
     22 
     23 ```
     24 11-08 23:11:08.191 D taler-pos: Network error: Error 2015 (401): The merchant
     25     refused the request due to lack of authorization.
     26     - Check credentials in 'Authorization' header
     27 --------- beginning of crash
     28 11-08 23:11:09.060 E AndroidRuntime: FATAL EXCEPTION: main
     29 11-08 23:11:09.060 E AndroidRuntime: java.lang.NullPointerException
     30     at net.taler.merchantpos.payment.PaymentManager$checkPayment$1.invokeSuspend(PaymentManager.kt:238)
     31     at net.taler.merchantpos.payment.PaymentManager.checkPayment(PaymentManager.kt:237)
     32     at net.taler.merchantpos.payment.PaymentManager$checkTimer$1.onTick(PaymentManager.kt:79)
     33     at android.os.CountDownTimer$1.handleMessage(CountDownTimer.java:145)
     34 ```
     35 
     36 869 milliseconds between the 401 and the fatal exception -- exactly one tick of
     37 the poll timer. The process is killed, the activity is force-finished, and the
     38 cashier is back at the launcher with a customer halfway through paying.
     39 
     40 The session-expiry handling itself is fine and the message is written and
     41 translated. With the crash fixed, the same scenario shows
     42 
     43 ```
     44 'Taler POS': 'Session expired – please re-enter your credentials' ['OK']
     45 ```
     46 
     47 which is exactly right. The dialog never gets a chance on an unpatched build.
     48 
     49 ## Why it happens
     50 
     51 `merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt:238`:
     52 
     53 ```kotlin
     54 private fun checkPayment(orderId: String) =
     55     scope.launch {
     56         val merchantConfig = configManager.merchantConfig!!    // <- line 238
     57         api.checkOrder(merchantConfig, orderId).handle(…)
     58     }
     59 ```
     60 
     61 `ConfigManager.merchantConfig` is a `var MerchantConfig?` that is set to null
     62 the moment a request comes back 401 -- that is what ends the session. The
     63 payment screen's `CountDownTimer` ticks every `CHECK_INTERVAL` regardless, and
     64 the tick after the 401 dereferences a field that has just been emptied.
     65 
     66 It is not one line. `configManager.merchantConfig!!` appears five times in this
     67 file, and every one of them is reachable after the session has gone:
     68 
     69 | line | method | reached by |
     70 | --- | --- | --- |
     71 | 94 | `createPayment` | charging an order |
     72 | 238 | `checkPayment` | **the poll timer, once a second** |
     73 | 372 | `cancelPayment` | the Cancel button *and* the payment timeout |
     74 | 401 | `tryDeleteOrder` | the Delete button |
     75 | 422 | `forceDeleteOrder` | force-deleting a claimed order |
     76 
     77 Line 238 is the one that fires by itself, which is why it is the one that was
     78 caught; 372 is the next most likely, because a cashier whose screen has just
     79 stopped responding presses Cancel.
     80 
     81 ## How it was found
     82 
     83 `driver/suite.py`, scenario `token_revoked_mid_payment`: bill an order, wait
     84 for the payment screen to start polling, revoke the terminal's own access
     85 token through the merchant API, and watch. The harness mints a token of its
     86 own for this, so nothing else's session is touched.
     87 
     88 Reproduced twice, on two different emulators, with the same stack both times.
     89 
     90 ## Severity
     91 
     92 High. It is a crash, it needs no unusual input, and it happens at the worst
     93 moment in the app's whole life -- mid-payment, in front of a customer. A token
     94 with a finite lifetime reaches it on its own, without anybody doing anything
     95 wrong.
     96 
     97 ## Suggested fix
     98 
     99 `payment-poll-crashes-when-the-session-ends.diff`, verified: the scenario goes
    100 from a fatal exception to a clean "Session expired" dialog.
    101 
    102 One helper, and all five call sites through it:
    103 
    104 ```kotlin
    105 /**
    106  * The merchant configuration, or null once the session has ended.
    107  *
    108  * `ConfigManager` clears it the moment a request comes back 401, and the
    109  * payment screen polls once a second -- so between two ticks of [checkTimer]
    110  * the field can go from a configuration to nothing …
    111  */
    112 private fun liveConfig(): MerchantConfig?
    113 {
    114     val merchantConfig = configManager.merchantConfig
    115     if (merchantConfig == null)
    116     {
    117         Log.d(TAG, "no merchant configuration left; stopping payment checks")
    118         stopPaymentChecks()
    119     }
    120     return merchantConfig
    121 }
    122 ```
    123 
    124 `cancelPayment` is the one exception: it does not take the helper, because
    125 cancelling has to keep working when the session is the thing that ended. It
    126 reads the field directly and skips only the "delete the abandoned order" step,
    127 so the error still reaches `mPayment` and the cashier still sees why.
    128 
    129 `:merchant-terminal:testSimUnitTest` passes with the patch.
    130 
    131 ## Reproducer
    132 
    133 ```bash
    134 cd /tmp/taler-pos-sim/driver && . ../env.sh
    135 python3 suite.py token_revoked_mid_payment
    136 ```