taldir-protocol-version-mismatch.md (4168B)
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 wallet and the Taler directory disagree on the protocol version 18 19 Found while deploying a real directory beside the simulator's stack 20 (`git://git.taler.net/taldir` at `3dca5c1b`, master of 2026-10-18): the wallet 21 refuses to talk to it at all, before any alias is registered. 22 23 **Severity: low-moderate, and it is an integration fact rather than a bug in 24 either side.** Both are in development; the point is that today's heads do not 25 interoperate, and the failure is reported as a generic error. 26 27 ## What happens 28 29 The directory's configuration endpoint answers: 30 31 ```json 32 {"version":"0:0:0","name":"taler-directory", 33 "alias_types":[{"name":"email","challenge_fee":"EUR:0"}],"monthly_fee":"EUR:0"} 34 ``` 35 36 and that version is a literal in the service: 37 38 ```go 39 // taldir, pkg/taldir/taldir.go:694 40 cfg := VersionResponse{ 41 Version: "0:0:0", 42 Name: "taler-directory", 43 ``` 44 45 The wallet's client declares `1:0:0` and checks compatibility before using the 46 service: 47 48 ```ts 49 // taler-util/src/http-client/taldir.ts:53 50 public static readonly PROTOCOL_VERSION = "1:0:0"; 51 ``` 52 53 ```ts 54 // taler-util/src/operation.ts:166, in carefullyParseConfig 55 if (!LibtoolVersion.isCompatible(clientVersion, minBody.version)) { 56 throw TalerError.fromUncheckedDetail({ 57 code: TalerErrorCode.GENERIC_CLIENT_UNSUPPORTED_PROTOCOL_VERSION, 58 … 59 detail: `Unsupported protocol version, client supports ${clientVersion}, server supports ${minBody.version}`, 60 }); 61 } 62 ``` 63 64 `1:0:0` against `0:0:0` is incompatible in libtool terms, so `lookupAlias`, 65 `registerAlias` and `completeRegisterAlias` all fail at the first step. What 66 reaches the caller is not the version detail but 67 `WALLET_ALIAS_REGISTRATION_FAILED` with the hint "could not read the 68 configuration of the directory service" — the specific reason is thrown away 69 by `taldir.ts`'s own `default:` branch. 70 71 For contrast, the mailbox service gets this right: `taler-mailbox`'s 72 `Makefile.in` carries `LT_VERSION="1:1:0"` and passes it in at build time, and 73 `1:0:0` against `1:1:0` is compatible. 74 75 ## How it was established 76 77 Deploy the directory and ask it: 78 79 ```bash 80 git clone git://git.taler.net/taldir && cd taldir 81 GOFLAGS=-mod=vendor go build -o taldir-server ./cmd/taldir-server 82 ./taldir-dbinit -c sim.conf && ./taldir-server -c sim.conf & 83 curl -s http://127.0.0.1:11001/config 84 ``` 85 86 Then point wallet-core at it (the app cannot be pointed anywhere, see 87 [`alias-registration-hardcodes-the-directory.md`](alias-registration-hardcodes-the-directory.md)): 88 89 ```bash 90 taler-wallet-cli --wallet-db /tmp/w.sqlite3 advanced api lookupAlias \ 91 '{"alias":"sim@example.com","aliasType":"email","taldirBaseUrl":"http://127.0.0.1:11001/"}' 92 ``` 93 94 With the service as it ships, that fails. With one character changed in 95 `taldir.go` (`0:0:0` → `1:0:0`) the whole flow — register, challenge, 96 complete, look up — works on the first attempt. 97 98 ## Suggested fix 99 100 Whichever side is wrong about the number, two things would have helped: 101 102 * taldir should take its protocol version from `LT_VERSION` at build time, the 103 way `taler-mailbox` does, rather than hard-coding it in the handler; 104 * `taldir.ts` should pass the configuration error through instead of replacing 105 it: its `default:` branch turns a precise 106 `GENERIC_CLIENT_UNSUPPORTED_PROTOCOL_VERSION` ("client supports 1:0:0, 107 server supports 0:0:0") into "could not read the configuration of the 108 directory service", which is what an operator would have to debug from.