Better error message for query utxo without oops

[newhoggy]

This makes the checking of node to client versions less manual. It replaces a earlier PRs:

• Better error message for query utxo #2957
• Better error message for query utxo plucky poc #3390
• Better error message for query utxo 2 #3358
• Better error message for query utxo #2957

This PR improves on the earlier version by making it so that the monadic expressions no longer need to know what version each query requires. If the node that is connected to does not support the query being made, then the query expression returns UnsupportedNtcVersionError which can be handled in a convenient top-level location.

The PR uses the new functions onLeft and onNothing from transformers-except-0.1.3 to improve the way we structure code.

[Jimbo4350]

I was always suspect about using ConT here to get monadic local state query expressions. Can we not write our own Monad instance for which will potentially make it more pleasant to use?

e.g result <- ExceptT . fmap (join . first ShelleyQueryCmdAcquireFailure) $ ... does not compose well.

Can we avoid the fmap (join ... by writing our own Monad instance? The type errors I experienced trying to get the expression to compile resulted in me abandoning trying to using it. Adding ReaderT here as things are now only serves to make this less usable imo.

[newhoggy]

The need for fmap (join ... doesn't come from ContT and writing our own monad instance wouldn't fix it.

It comes from the fact that we are returning multiple error types. It's one of my motivations for using oops which makes returning multiple error types seamless.

What that code is doing is converting Either ShelleyQueryCmdError (Either AcquireError a) to Either ShelleyQueryCmdError (Either ShelleyQueryCmdError a) and then the join squishes it to Either ShelleyQueryCmdError a.

Before this PR the code had to squish AcquireError into ShelleyQueryCmdError.

In this code, the PR has to squish AcquireError and UnsupportedNtcVersionError into ShelleyQueryCmdError, which means more hoops to jump.

Then when you're done jumping all the hoops to make the code compile you find out later the code is brittle because ordering of errors in stacked Eithers matters.

Either a (Either b (Either c)) is different to Either c (Either b (Either a))

Different code that stacks the Eithers differently are incompatible so can't call those functions one after the other without reordering the Either stack and adding removing error types is painful.

It's also difficult to see when looking at the code how the Eithers are stacked in each sub-expression and you have to know in order to successfully connected bits of code together.

As for ContT I originally wrote this code without ContT back in 2021 but someone commented that I should use ContT which allows me to lean on all the code that ContT provides rather than rewriting it all from scratch which would have been near duplications.

[newhoggy]

How runQueryStakePools is implemented without oops.

[newhoggy]

For comparison: https://github.com/input-output-hk/cardano-node/pull/4777/files#r1071975815

[newhoggy]

Without oops:

runQueryStakePools
  :: AnyConsensusModeParams
  -> NetworkId
  -> Maybe OutputFile
  -> ExceptT ShelleyQueryCmdError IO ()
runQueryStakePools (AnyConsensusModeParams cModeParams)
                          network mOutFile = do
  SocketPath sockPath <- firstExceptT ShelleyQueryCmdEnvVarSocketErr
                           $ newExceptT readEnvSocketPath
  let localNodeConnInfo = LocalNodeConnectInfo cModeParams network sockPath


  result <- ExceptT . fmap (join . first ShelleyQueryCmdAcquireFailure) $
    executeLocalStateQueryExpr localNodeConnInfo Nothing $ runExceptT @ShelleyQueryCmdError $ do
      anyE@(AnyCardanoEra era) <- case consensusModeOnly cModeParams of
        ByronMode -> return $ AnyCardanoEra ByronEra
        ShelleyMode -> return $ AnyCardanoEra ShelleyEra
        CardanoMode -> ExceptT $ fmap (first ShelleyQueryCmdUnsupportedNtcVersion) $ queryExpr $ QueryCurrentEra CardanoModeIsMultiEra

      let cMode = consensusModeOnly cModeParams

      case toEraInMode era cMode of
        Just eInMode -> do
          sbe <- getSbe $ cardanoEraStyle era

          r <- ExceptT $ fmap (first ShelleyQueryCmdUnsupportedNtcVersion) $ queryExpr $
            QueryInEra eInMode $ QueryInShelleyBasedEra sbe $ QueryStakePools

          case r of
            Right a -> pure a
            Left e -> throwE (ShelleyQueryCmdEraMismatch e)

        Nothing -> left $ ShelleyQueryCmdEraConsensusModeMismatch (AnyConsensusMode cMode) anyE

  writeStakePools mOutFile result

[newhoggy]

This can also be written as:

        eInMode <- pure (toEraInMode era cMode)
          & onNothing (throwE $ ShelleyQueryCmdEraConsensusModeMismatch (AnyConsensusMode cMode) anyE)

This shows the versatility of the on* combinators.

[Jimbo4350]

Some comments

[Jimbo4350]

I really don't like the name throwE because it implies we are throwing an exception, which we're not. There is the function left that is exposed in Control.Monad.Trans.Except.Extra that I think is better named. What are your thoughts here? Do you feel strongly about throwE?

[newhoggy]

I was worried about confusion between Left in Either and the Left in ExceptT. The onLeft extracts the Left of Either and the throwE or left puts the value in the Left of the ExceptT.

Writing & onLeft (left . ShelleyQueryCmdUnsupportedNtcVersion) makes it look like we are leaving the structure unchanged, but that is not the case. The structure changes from ExceptT x (Either e a) to ExceptT x.

I don't think of throwE as "throw exception". I think of it as "throw except" or "throw error".

However, I am happy to switch to left for this PR, which I've done.

Comments addressed