Add OnBeforeExecute and OnAfterExecute to the client

Both live in TRALClientHTTP.BeforeSendUrl, the single funnel every engine
already goes through, so one implementation serves all six engines on Delphi
and FPC without touching an engine unit.

They report an attempt, not a call: the BaseURL failover and the 401 resend
fire the pair again with Attempt one higher, which is the only way a handler
can see the failover and time the right thing.

OnBeforeExecute runs after the URL and its TLS policy are settled and before
any network work, the token fetch included, and may refuse the attempt through
ACancel/ACancelReason - failing it with the new rteCancelled, appended so every
existing TRALTransportError value keeps its ordinal and CanSwitchURL's else
already declines to resend it. OnAfterExecute always pairs with it, the refusal
included, so a handler may count in one and discount in the other.

Author: tempraturbo

.agents/PROJECT_MAP.md

@@ -253,6 +253,18 @@ Lazarus
    única — evento, senão pin, senão o veredito do próprio engine. Sem pin e sem evento
    nada muda, inclusive o fato de Indy e fpHTTP não validarem certificado por padrão.
    Ver `CLAUDE.md`, "Which server certificate a client accepts".
+7. `OnBeforeExecute` e `OnAfterExecute` também moram no `TRALClient` e também rodam
+   dentro do `BeforeSendUrl`, então valem para os seis engines em Delphi e FPC sem
+   tocar em unit de engine nenhuma. Eles dão à aplicação a palavra sobre **cada
+   tentativa**: o primeiro roda depois da URL e da política de TLS dela decididas e
+   antes de qualquer trabalho de rede (inclusive a busca de token), pode acrescentar
+   header ou param no `ARequest` e pode recusar a tentativa com `ACancel` +
+   `ACancelReason`, que falha com `rteCancelled`; o segundo roda quando a tentativa
+   termina, seja como for que ela termine, e sempre pareado com o primeiro.
+   `TRALExecInfo` leva URL, método, tentativa (1-based), engine, `Elapsed` em ms,
+   `StatusCode`, `TransportError` e `ErrorMessage`. Tentativa não é chamada: o failover
+   e o reenvio do 401 disparam o par de novo, com `Attempt` maior. Ver `CLAUDE.md`,
+   "The application's own say over each attempt".
 
 ### 4.3) DBWare
 

CLAUDE.md

@@ -161,6 +161,20 @@ Two engine traps live under this:
 
 Verified with `testes_ral_matriz/timeout` (repro `tmout.dpr`, verifier `tmfix.dpr` + `fpc/tmfixfpc.lpr`), across Indy, mORMot2, netHTTP and fpHTTP.
 
+### The application's own say over each attempt (`OnBeforeExecute`/`OnAfterExecute`)
+
+`TRALClient.OnBeforeExecute` and `OnAfterExecute` live in `TRALClientHTTP.BeforeSendUrl` — the same single funnel as the resend above — so **one implementation serves every engine on both compilers**: no engine unit knows they exist, and `ExecuteThread`, `ExecuteSingle` and `TRALThreadClient` all pass through them.
+
+They report an **attempt, not a call**, and that is deliberate: `BeforeSendUrl` rotates `BaseURL` on a transport failure and repeats once on a 401, so one `Post` can be three attempts. Each reports itself with `TRALExecInfo.Attempt` one higher; collapsing them would hide the failover and time the wrong thing. Whoever wants the call rather than the attempt ignores `Attempt > 1`. Fields the client cannot know yet come back empty, never invented — the same rule as `TRALCertInfo`.
+
+`OnBeforeExecute` runs **after** the URL is settled and the TLS policy for it enforced, and **before any network work at all** — the `AutoGetToken` fetch included, since that one is a request of its own: whoever refuses for lack of connectivity should not pay for a token round trip first. `AInfo` is `const` on purpose (rewriting the URL there would slip past the pin decided just above), while `ARequest` is not — adding a header or a param is the point of the hook.
+
+Setting `ACancel` fails the attempt with `TransportError = rteCancelled` and raises, instead of the application having to raise from inside the engine's stack. `rteCancelled` is **appended** to `TRALTransportError`, so every existing value keeps its ordinal and `CanSwitchURL`'s `else` already declines to resend it — nothing went out, so there is nothing to resend anywhere. `ACancelReason`, when given, *becomes* the message verbatim; left empty, RAL uses `emRequestCancelled` with the URL.
+
+`OnAfterExecute` **always pairs with `OnBeforeExecute`** — including when the attempt raised, and including when the application itself refused it, which is why the refusal is raised from *inside* the `try` whose `finally` calls it. A handler may therefore count in one and discount in the other without ever losing a pair. `TRALExecInfo.ErrorMessage` comes from `ExceptObject`, not from `AResponse`: an exception that never reached `SetTransportError` would otherwise arrive indistinguishable from success. Both hooks run on the **calling** thread with no `Synchronize`, so under the default `ebMultiThread` they run on the `TRALThreadClient` and not on the main thread — reaching the UI from there is the handler's own business.
+
+`CopyProperties` carries both, next to `SSL` and `OnValidateServerCert`: the DAO clones its client, and a clone that lost the hooks would stop reporting.
+
 ### A published `default` that disagrees with the constructor silently wins
 
 `TRALClient.ConnectTimeout` declared `default 5000` while the constructor set 30000, and `RequestTimeout` declared `default 30000` while the constructor set 10000 — the two were swapped. The directive is not decoration: streaming skips writing a property whose value equals it, so typing exactly `5000` into the Object Inspector produced a `.dfm` with no `ConnectTimeout` at all and a component that ran with 30000. It never showed up in code-driven tests, where `default` has no effect whatsoever — only in the normal use, dropping the component on a form.

src/base/RALClient.pas

@@ -3,7 +3,7 @@
 interface
 
 uses
-  Classes, SysUtils, SyncObjs,
+  Classes, SysUtils, SyncObjs, DateUtils,
   RALCustomObjects, RALTypes, RALAuthentication, RALRequest, RALResponse,
   RALCompress, RALCripto, RALConsts, RALTools, RALToken, RALJSON, RALParams,
   RALMimeTypes;
@@ -45,6 +45,62 @@   TRALCertInfo = record
   TRALOnValidateCert = function(ASender: TObject;
                                 const ACert: TRALCertInfo): boolean of object;
 
+  { TRALExecInfo }
+
+  /// One ATTEMPT of one request - what the client is about to do, or has just
+  /// done. An attempt is not a call: BeforeSendUrl rotates BaseURL on a
+  /// transport failure and repeats once on a 401, and each pass reports itself
+  /// with Attempt one higher. Collapsing them would hide the failover and
+  /// report the wrong latency, so they come as they happen, and whoever wants
+  /// the call instead of the attempt ignores Attempt > 1.
+  /// Fields the client cannot know yet come back empty, never invented - the
+  /// same rule as TRALCertInfo.
+  TRALExecInfo = record
+    /// the URL of THIS attempt, already after the BaseURL rotation
+    URL: StringRAL;
+    Method: TRALMethod;
+    /// 1-based
+    Attempt: IntegerRAL;
+    /// which engine carried it, for an application that mixes engines
+    Engine: StringRAL;
+    /// milliseconds the attempt took - OnAfterExecute only, zero on Before
+    Elapsed: Int64RAL;
+    /// OnAfterExecute only; zero when no HTTP response happened
+    StatusCode: IntegerRAL;
+    /// OnAfterExecute only
+    TransportError: TRALTransportError;
+    /// OnAfterExecute only: the message of whatever ended the attempt, empty
+    /// when nothing did. It is not AResponse.ResponseText: an exception that
+    /// never reached SetTransportError would otherwise arrive indistinguishable
+    /// from success
+    ErrorMessage: StringRAL;
+  end;
+
+  /// Called before each attempt goes out - after RAL settled the URL and
+  /// enforced the TLS policy for it, and BEFORE any network work, the token
+  /// fetch included, since that one is a request of its own.
+  /// - set ACancel to refuse the attempt: RAL fails it with rteCancelled, the
+  ///   same way it fails a refused pin, instead of the application having to
+  ///   raise through the engine's stack
+  /// - ACancelReason, when given, BECOMES the message, verbatim; left empty,
+  ///   RAL uses its own text with the URL. Only read when ACancel is True
+  /// - AInfo is read-only on purpose: rewriting the URL here would slip past
+  ///   the pin and the TLS check decided just above. ARequest is not - adding a
+  ///   header or a param is the point of the hook
+  TRALOnBeforeExecute = procedure(ASender: TObject; ARequest: TRALRequest;
+                                  const AInfo: TRALExecInfo;
+                                  var ACancel: boolean;
+                                  var ACancelReason: StringRAL) of object;
+
+  /// Called when the attempt ends, whatever ended it - a response, a transport
+  /// failure, an exception, or OnBeforeExecute refusing it. It ALWAYS pairs
+  /// with OnBeforeExecute, so a handler may count in one and discount in the
+  /// other. It runs on the calling thread, with no Synchronize: reaching the UI
+  /// from here is the handler's own business.
+  TRALOnAfterExecute = procedure(ASender: TObject; ARequest: TRALRequest;
+                                 AResponse: TRALResponse;
+                                 const AInfo: TRALExecInfo) of object;
+
   /// What the ENGINE itself does about the server certificate - the pin and
   /// OnValidateServerCert are a separate question, and when either is set it is
   /// the one that decides
@@ -247,6 +303,8 @@   TRALClient = class(TRALComponent)
     FIndexUrl: IntegerRAL;
     FKeepAlive: boolean;
     FMaxRedirects: IntegerRAL;
+    FOnAfterExecute: TRALOnAfterExecute;
+    FOnBeforeExecute: TRALOnBeforeExecute;
     FOnResponse: TRALThreadClientResponse;
     FOnValidateServerCert: TRALOnValidateCert;
     FRequestTimeout: IntegerRAL;
@@ -353,6 +411,12 @@   TRALClient = class(TRALComponent)
     /// TLS options - see TRALClientSSL
     property SSL: TRALClientSSL read FSSL write SetSSL;
     property UserAgent: StringRAL read FUserAgent write SetUserAgent;
+    /// Runs before each attempt leaves, and may refuse it - see TRALOnBeforeExecute
+    property OnBeforeExecute: TRALOnBeforeExecute read FOnBeforeExecute
+                                                  write FOnBeforeExecute;
+    /// Runs when each attempt ends, whatever ended it - see TRALOnAfterExecute
+    property OnAfterExecute: TRALOnAfterExecute read FOnAfterExecute
+                                                write FOnAfterExecute;
     property OnResponse: TRALThreadClientResponse read FOnResponse write FOnResponse;
     /// Judges the server certificate yourself. Assigned, it is the last word:
     /// it overrides both SSL.Pin and the engine's own verdict, and receives
@@ -374,6 +438,9 @@   TRALClient = class(TRALComponent)
   /// whatever the stack held. Default(T) would do it, and does not exist on
   /// the older compilers RAL still supports
   function RALEmptyCertInfo: TRALCertInfo;
+  /// A TRALExecInfo with every field zeroed - what the client starts from, so
+  /// no field ever reaches a handler carrying what was on the stack
+  function RALEmptyExecInfo: TRALExecInfo;
   /// Splits "host", "host:port" or "[ipv6]:port" - the very format of the left
   /// side of an SSL.Pins line, published so that whatever writes that config
   /// can read it back the same way. An IPv6 without brackets is all host,
@@ -671,6 +738,11 @@ procedure TRALClient.CopyProperties(ADest: TRALClient);
     of what the pin was set for - and the DAO clones its client }
   ADest.SSL := Self.SSL;
   ADest.OnValidateServerCert := Self.OnValidateServerCert;
+
+  { a clone that lost the hooks would stop reporting, and the DAO clones its
+    client }
+  ADest.OnBeforeExecute := Self.OnBeforeExecute;
+  ADest.OnAfterExecute := Self.OnAfterExecute;
 end;
 
 procedure TRALClient.SetAuthentication(AValue: TRALAuthClient);
@@ -1043,6 +1115,18 @@ function RALPinPlace(const ALine: StringRAL; out AHost: StringRAL;
     RALSplitHostPort(Copy(ALine, 1, vIgual - 1), AHost, APort);
 end;
 
+function RALEmptyExecInfo: TRALExecInfo;
+begin
+  Result.URL := '';
+  Result.Method := amGET;
+  Result.Attempt := 0;
+  Result.Engine := '';
+  Result.Elapsed := 0;
+  Result.StatusCode := 0;
+  Result.TransportError := rteNone;
+  Result.ErrorMessage := '';
+end;
+
 function RALEmptyCertInfo: TRALCertInfo;
 begin
   Result.Fingerprint := '';
@@ -1195,8 +1279,10 @@ procedure TRALClientHTTP.BeforeSendUrl(ARoute: StringRAL;
 var
   vConta, vMaxUrls, vResp, vErrorCode: IntegerRAL;
   vParams: TStringList;
-  vURL: StringRAL;
-  vRepeat, vTriedToken: boolean;
+  vURL, vCancelReason: StringRAL;
+  vRepeat, vTriedToken, vCancel: boolean;
+  vInfo: TRALExecInfo;
+  vStart: TDateTime;
 begin
   vConta := 0;
   vTriedToken := False;
@@ -1247,8 +1333,39 @@ procedure TRALClientHTTP.BeforeSendUrl(ARoute: StringRAL;
     // freed pointer - or, when the token already existed and the block did not
     // run at all, an uninitialised variable. Neither Basic nor JWT read this
     // argument, but Digest and OAuth do.
+    { The application's own say over THIS attempt. It runs here, with the URL
+      and the TLS policy for it already settled, and BEFORE any network work -
+      the token fetch below included, since that one is a request of its own:
+      whoever refuses for lack of connectivity should not pay for it. }
+    vCancel := False;
+    vCancelReason := '';
+    vStart := Now;
+
+    if Assigned(FParent.OnBeforeExecute) or Assigned(FParent.OnAfterExecute) then
+    begin
+      vInfo := RALEmptyExecInfo;
+      vInfo.URL := vURL;
+      vInfo.Method := AMethod;
+      vInfo.Attempt := vConta + 1;
+      vInfo.Engine := EngineName;
+    end;
+
+    if Assigned(FParent.OnBeforeExecute) then
+      FParent.OnBeforeExecute(FParent, ARequest, vInfo, vCancel, vCancelReason);
+
     vParams := TStringList.Create;
     try
+      { the refusal lives INSIDE this try so that the OnAfterExecute in the
+        finally below covers it as well - a handler may count in one event and
+        discount in the other without ever losing a pair }
+      if vCancel then
+      begin
+        if vCancelReason = '' then
+          vCancelReason := StringRAL(Format(emRequestCancelled, [vURL]));
+        SetTransportError(AResponse, rteCancelled, 0, vCancelReason);
+        raise Exception.Create(string(vCancelReason));
+      end;
+
       vParams.Sorted := True;
       vParams.Add('method=' + RALMethodToHTTPMethod(AMethod));
       vParams.Add('url=' + vURL);
@@ -1282,6 +1399,22 @@ procedure TRALClientHTTP.BeforeSendUrl(ARoute: StringRAL;
       end;
     finally
       FreeAndNil(vParams);
+
+      { Always paired with OnBeforeExecute - including when the attempt raised,
+        and including when the application refused it. ExceptObject is whatever
+        is unwinding right now, and it is the only way to name the failure here
+        without wrapping the whole attempt in one more try just to catch it and
+        re-raise. }
+      if Assigned(FParent.OnAfterExecute) then
+      begin
+        vInfo.Elapsed := MilliSecondsBetween(Now, vStart);
+        vInfo.StatusCode := AResponse.StatusCode;
+        vInfo.TransportError := AResponse.TransportError;
+        if ExceptObject is Exception then
+          vInfo.ErrorMessage := StringRAL(Exception(ExceptObject).Message);
+
+        FParent.OnAfterExecute(FParent, ARequest, AResponse, vInfo);
+      end;
     end;
 
     vConta := vConta + 1;

src/base/RALTypes.pas

@@ -99,9 +99,13 @@ interface
     rteOther,
     /// the TLS handshake failed over the server certificate - refused by the
     /// engine's own validation, by SSL.Pin or by OnValidateServerCert
-    /// - last on purpose: the four values above keep their ordinal, and
-    /// CanSwitchURL's "else" already declines to resend what it does not know
-    rteCertificate);
+    rteCertificate,
+    /// the application refused the attempt from OnBeforeExecute, so nothing
+    /// went out and there is nothing to resend
+    /// - new values are APPENDED, never inserted: every value above keeps its
+    ///   ordinal, and CanSwitchURL's "else" already declines to resend what it
+    ///   does not know
+    rteCancelled);
 
   {$IF Defined(FPC) or Defined(DELPHIXE3UP)}
   TRALBase64StringHelper = {$IFDEF FPC}type{$ELSE}record{$ENDIF} helper for StringRAL

src/languages/ralconsts_enus.inc

@@ -13,6 +13,7 @@
   emCertNotInspectable = 'The %s engine could not inspect the server certificate on this connection, so SSL.Pins and OnValidateServerCert cannot be applied. Use the Indy engine.';
   emCertPinInvalid = 'Every SSL.Pins line must end in the SHA-256 of the certificate: 64 hex digits, with or without separators.';
   emCertPinUnsupported = 'SSL.Pins is not supported by the %s engine on this platform: it cannot read the certificate fingerprint. Use the Indy engine, or decide in OnValidateServerCert.';
+  emRequestCancelled = 'The request was refused by OnBeforeExecute: %s.';
   emCertRejected = 'Server certificate refused.';
   emCertRequiresTLS = 'SSL.Required is set, or a line of SSL.Pins applies to this host, so plain http is refused: %s.';
   emCompressInvalidFormat = 'Invalid compression Format.';

src/languages/ralconsts_eses.inc

@@ -13,6 +13,7 @@
   emCertNotInspectable = 'El motor %s no pudo inspeccionar el certificado del servidor en esta conexión, por lo que SSL.Pins y OnValidateServerCert no pueden aplicarse. Use el motor Indy.';
   emCertPinInvalid = 'Cada línea de SSL.Pins debe terminar en el SHA-256 del certificado: 64 dígitos hexadecimales, con o sin separadores.';
   emCertPinUnsupported = 'SSL.Pins no es compatible con el motor %s en esta plataforma: no puede leer la huella digital del certificado. Use el motor Indy o decida en OnValidateServerCert.';
+  emRequestCancelled = 'La solicitud fue rechazada por OnBeforeExecute: %s.';
   emCertRejected = 'Certificado del servidor rechazado.';
   emCertRequiresTLS = 'SSL.Required está definido, o una línea de SSL.Pins aplica a este host, por lo que se rechaza http sin cifrar: %s.';
   emCompressInvalidFormat = 'Formato de compressión no és válido.';

src/languages/ralconsts_ptbr.inc

@@ -13,6 +13,7 @@
   emCertNotInspectable = 'O engine %s não conseguiu inspecionar o certificado do servidor nesta conexão, então SSL.Pins e OnValidateServerCert não podem ser aplicados. Use o engine Indy.';
   emCertPinInvalid = 'Toda linha de SSL.Pins deve terminar no SHA-256 do certificado: 64 dígitos hexadecimais, com ou sem separadores.';
   emCertPinUnsupported = 'SSL.Pins não é suportado pelo engine %s nesta plataforma: ele não consegue ler a impressão digital do certificado. Use o engine Indy ou decida no OnValidateServerCert.';
+  emRequestCancelled = 'A requisição foi recusada pelo OnBeforeExecute: %s.';
   emCertRejected = 'Certificado do servidor recusado.';
   emCertRequiresTLS = 'SSL.Required está definido, ou uma linha de SSL.Pins vale para este host, então http puro é recusado: %s.';
   emCompressInvalidFormat = 'Formato de compressão inválido.';