[CBR-306] Akegalj/co 319/swagger account index #3086

akegalj · 2018-06-13T20:37:10Z

Description

The example accountId from the API doc isn't much relevant and reflects an invalid value

Linked issue

https://iohk.myjetbrains.com/youtrack/issue/CO-319

Type of change

🐞 Bug fix (non-breaking change which fixes an issue)
🛠 New feature (non-breaking change which adds functionality)
⚠️ Breaking change (fix or feature that would cause existing functionality to change)
🏭 Refactoring that does not change existing functionality but does improve things like code readability, structure etc
🔨 New or improved tests for existing code
⛑ git-flow chore (backport, hotfix, etc)

Developer checklist

I have read the style guide document, and my code follows the code style of this project.
If my code deals with exceptions, it follows the guidelines.
I have updated any documentation accordingly, if needed. Documentation changes can be reflected in opening a PR on cardanodocs.com, amending the inline Haddock comments, any relevant README file or one of the document listed in the docs directory.

Testing checklist

I have added tests to cover my changes.
All new and existing tests passed.

QA Steps

Run a cardano-node
Visit https://localhost:8091/docs/v1/index/ - you will see changes showed bellow
Roundtrip tests pass (the screenshot bellow)

Screenshots (if available)

accountIndex in request body shows correct value range

accountIndex on description on the right picks correct value (not bellow the minimum)

accountId (same thing as accountIndex) in request params shows correct value range

roundtrip tests

@KtorZ I wonder why did we ended up with accountId and accountIndex json keys for the same thing. Is it still too late to unify it? (it would be a breaking change for exchanges)

akegalj · 2018-06-14T07:56:26Z

wallet-new/src/Cardano/Wallet/API/V1/Types.hs

+mkAccountIndex :: Word32 -> Either Text AccountIndex
+mkAccountIndex index | index >= getAccIndex minBound = Right $ AccountIndex index
+                     | otherwise = Left $ sformat
+                            ("mkAccountIndex: Account index should be in range ["%int%".."%int%"]")


do we think it make sense to add additional constructor to WalletError which would capture this failure?

There are other places in this module where I can do this refactoring (possibly as part of https://iohk.myjetbrains.com/youtrack/issue/CBR-26 )

Oui :)
IMO, we should always favor explicit and typed error when we can. Especially when the error is a well-identified scenario that is reachable.

KtorZ · 2018-06-18T07:57:08Z

wallet-new/src/Cardano/Wallet/API/V1/Swagger.hs

@@ -186,17 +186,13 @@ instance (HasSwagger subApi) => HasSwagger (WalletRequestParams :> subApi) where

 instance ToParamSchema WalletId

-instance ToSchema Core.Address where
-    declareNamedSchema = pure . paramSchemaToNamedSchema defaultSchemaOptions
-
 instance ToParamSchema Core.Address where


😶 Why exactly? Is this not used?

:/ good catch, looks like a mistake

KtorZ · 2018-06-18T07:59:27Z

wallet-new/src/Cardano/Wallet/API/V1/Types.hs

+mkAccountIndex :: Word32 -> Either Text AccountIndex
+mkAccountIndex index | index >= getAccIndex minBound = Right $ AccountIndex index
+                     | otherwise = Left $ sformat
+                            ("mkAccountIndex: Account index should be in range ["%int%".."%int%"]")


Oui :)
IMO, we should always favor explicit and typed error when we can. Especially when the error is a well-identified scenario that is reachable.

KtorZ · 2018-06-18T08:00:59Z

wallet-new/src/Cardano/Wallet/API/V1/Types.hs

+
+instance FromJSON AccountIndex where
+    parseJSON =
+        either (fail . toString) pure . mkAccountIndex <=< parseJSON


Note that if we define an explicit WalletError for mkAccountIndex, it'd be better to use sformat instead of toString to leverage a Buildable instance and have a proper diagnostic!

KtorZ · 2018-06-18T08:02:02Z

wallet-new/src/Cardano/Wallet/API/V1/Types.hs

+deriveSafeBuildable ''AccountIndex
+-- Nothing secret to redact for a AccountIndex.
+instance BuildableSafeGen AccountIndex where
+    buildSafeGen _ = bprint build


Hmmm... isn't that a bit too recursive ^^" ?

uh, you might be right!

I saw a similar definition for SyncProgress in the same module

cardano-sl/wallet-new/src/Cardano/Wallet/API/V1/Types.hs

Line 694 in 3acda87

buildSafeGen _ sp = bprint build sp

. Let me have a look at how BuildableSafeGen is defined...

EDIT: Good catch. In fact, SyncProgress will also recurse.

KtorZ · 2018-06-18T08:02:21Z

wallet-new/test/MarshallingSpec.hs

+        httpApiDataRoundtripProp @(V1 Core.Address) Proxy
+        httpApiDataRoundtripProp @PerPage Proxy
+        httpApiDataRoundtripProp @Page Proxy
+        httpApiDataRoundtripProp @Core.Coin Proxy


KtorZ · 2018-06-18T09:07:42Z

@KtorZ I wonder why did we ended up with accountId and accountIndex json keys for the same thing. Is it still too late to unify it? (it would be a breaking change for exchanges)

Erf :/ ... Not sure introducing a breaking change will be well-advised here. Especially for a JSON-key which can be hard to chase in exchange integrations. Yet, we can perhaps have a backward compatible fix making a slightly hacky parser accepting both accountId and accountIndex keys with a clear comment about it.

akegalj · 2018-06-18T20:11:07Z

wallet-new/src/Cardano/Wallet/API/V1/Types.hs

@@ -688,7 +707,14 @@ instance ToSchema SyncProgress where
 deriveSafeBuildable ''SyncProgress
 -- Nothing secret to redact for a SyncProgress.
 instance BuildableSafeGen SyncProgress where
-    buildSafeGen _ sp = bprint build sp
+    buildSafeGen sl SyncProgress {..} = bprint ("{"


es Util WalletSpecs Data.Text.Buildable Test.QuickCheck> sp :: SyncProgress <- generate arbitrary es Util WalletSpecs Data.Text.Buildable Test.QuickCheck> sp SyncProgress {spEstimatedCompletionTime = EstimatedCompletionTime (MeasuredIn 2894754), spThroughput = SyncThroughput (MeasuredIn (SyncThroughput (BlockCount {getBlockCount = 12610705}))), spPercentage = SyncPercentage (MeasuredIn 42)} es Util WalletSpecs Data.Text.Buildable Test.QuickCheck> build sp "{ estimatedCompletionTime={ quantity=2894754 unit=milliseconds } throughput={ quantity=12610705 unit=blocksPerSecond } percentage=42% }"

it was recursive before

akegalj · 2018-06-18T20:12:00Z

wallet-new/src/Cardano/Wallet/API/V1/Types.hs

+deriveSafeBuildable ''AccountIndex
+-- Nothing secret to redact for a AccountIndex.
+instance BuildableSafeGen AccountIndex where
+    buildSafeGen _ = bprint build . getAccIndex


fixed recursive buildable. Thanks for catching that!

es Util WalletSpecs Data.Text.Buildable Test.QuickCheck> let ac = fromRight (error "bla") (mkAccountIndex 2147483649) es Util WalletSpecs Data.Text.Buildable Test.QuickCheck> ac AccountIndex {getAccIndex = 2147483649} es Util WalletSpecs Data.Text.Buildable Test.QuickCheck> build ac "2147483649"

parsonsmatt · 2018-06-21T19:47:19Z

@KtorZ I've implemented the ADT-error-type; care to re-review?

KtorZ · 2018-06-22T09:38:30Z

LGTM 👍

KtorZ · 2018-06-22T14:25:06Z

Some second thoughts, @parsonsmatt What's the rational behind a new AccountIndexError data-type vs a new constructor in the WalletError type?

akegalj · 2018-06-22T14:44:18Z

wallet-new/src/Cardano/Wallet/API/V1/Migration/Types.hs

@@ -195,7 +195,7 @@ instance Migrate V0.AccountId (V1.WalletId, V1.AccountIndex) where
        (,)
            <$> eitherMigrate (V0.aiWId accId)
            <*> first
-                    Errors.MigrationFailed
+                    (Errors.MigrationFailed . sformat build)


do you think it makes sense to introduce new constructor in WalletError to capture exact underying issue (instead of wrapping it under MigrationFailed). I wonder does it makes sense to have this pattern in general.

This would make it possible to have more detailed error handling if it is needed. Now we mask underlying errors under higher level error (which is MigrationFailed in this case).

I wonder do we have some opinion/rules about this?

akegalj · 2018-06-22T14:48:12Z

@KtorZ

Some second thoughts, @parsonsmatt What's the rational behind a new AccountIndexError data-type vs a new constructor in the WalletError type?

problem is with cyclic imports. V1.Errors module is importing V1.Types so we are unable to import and use WalletError inside V1.Types. We would have to factor out mkAccountIndex constructor out of V1.Types. I wonder would this be something preferable? Also I am curious about #3086 (comment) approach ?

akegalj · 2018-06-25T14:59:21Z

wallet-new/src/Cardano/Wallet/API/Response.hs

+--
+-- Error from parsing / validating JSON inputs
+--
+


@KtorZ I see you have made MigrationFailed an instance of Expcetion , but JSONValidationError doesn't have the same instance. Is there a reason for the separation?

Hmmm. No. That's an oversight 👍

parsonsmatt · 2018-06-25T20:29:52Z

@KtorZ Clarity. If I say:

mkAccountIndex :: Int -> Either AnyApplicationError AccountIndex

then you lose all type-safety around what exceptions you should be throwing, and you lose type-safety in handling the appropriate exceptions.

This makes it now possible to import V1/Errors from the V1/Types module and leverage errors from this module. One thing is still unclear to me: Why Errors isn't defined in V1/Types already? There's a circular dependency between V1/Response and V1/Types if we go this way, as well as between V1/Migration and V1/Types. Nevertheless, it would make sense to have three data-types here: - WalletError (defined in V1/Types) - MigrationError (defined in V1/Types) - JSONParsingError (defined in Response) This way, we could remove the conflicting constructor from WalletError and remove the need for an extra module here. It will also makes thing clearer

To realize this, we had to extract JSONValidationFailed and MigrationFailed constructor from WalletError. They're now defined as constructor in different data-types (resp. JSONValidationError and MigrationError).

This is rather ugly and could probably be achieved nicely with a better understanding of the Generics.SOP library. As far as I could tell, there's no easy way to retrieve 'Tag' for single constructor (cf: 'For a datatype with a single constructor we do not need to tag values with their constructor; but for a datatype with multiple constructors we do. ')

akegalj

@KtorZ @parsonsmatt thanks for jumping in. LGTM

* [CO-319] Fix account index swagger example * [CO-319] Add roundtrip tests * [CO-319] Fix recursive buildable instances * [CO-319] Use strongly typed error * [CO-319] Remove duplication in 'renderAccountIndexError' * [CO-319] Distangle V1/Errors This makes it now possible to import V1/Errors from the V1/Types module and leverage errors from this module. One thing is still unclear to me: Why Errors isn't defined in V1/Types already? There's a circular dependency between V1/Response and V1/Types if we go this way, as well as between V1/Migration and V1/Types. Nevertheless, it would make sense to have three data-types here: - WalletError (defined in V1/Types) - MigrationError (defined in V1/Types) - JSONParsingError (defined in Response) This way, we could remove the conflicting constructor from WalletError and remove the need for an extra module here. It will also makes thing clearer * [CO-319] Make V1/Error part of V1/Types To realize this, we had to extract JSONValidationFailed and MigrationFailed constructor from WalletError. They're now defined as constructor in different data-types (resp. JSONValidationError and MigrationError). * [CO-319] Solve rebase conflicts * [CO-319] Correctly format (jsend) newtype errors This is rather ugly and could probably be achieved nicely with a better understanding of the Generics.SOP library. As far as I could tell, there's no easy way to retrieve 'Tag' for single constructor (cf: 'For a datatype with a single constructor we do not need to tag values with their constructor; but for a datatype with multiple constructors we do. ')

akegalj requested review from adinapoli-iohk, denisshevchenko and parsonsmatt as code owners June 13, 2018 20:37

akegalj requested a review from KtorZ June 13, 2018 20:39

akegalj commented Jun 14, 2018

View reviewed changes

KtorZ suggested changes Jun 18, 2018

View reviewed changes

akegalj commented Jun 18, 2018

View reviewed changes

akegalj added the wip label Jun 18, 2018

akegalj commented Jun 22, 2018

View reviewed changes

akegalj commented Jun 25, 2018

View reviewed changes

KtorZ force-pushed the akegalj/CO-319/swagger-account-index branch from 21598f4 to 6161cb7 Compare June 25, 2018 16:01

akegalj requested a review from vincenthz as a code owner June 25, 2018 16:01

KtorZ changed the base branch from Squad1/CO-309/misleading-example-for-account-id to Squad1/CBR-26/improve-error-handling June 26, 2018 08:32

KtorZ force-pushed the akegalj/CO-319/swagger-account-index branch 2 times, most recently from d93784b to 2924c46 Compare June 27, 2018 12:58

akegalj and others added 8 commits June 27, 2018 16:48

[CO-319] Fix account index swagger example

15ee1d5

[CO-319] Add roundtrip tests

1208dcb

[CO-319] Fix recursive buildable instances

a06bb85

[CO-319] Use strongly typed error

76aedf8

[CO-319] Remove duplication in 'renderAccountIndexError'

43e6faa

[CO-319] Make V1/Error part of V1/Types

2813d97

To realize this, we had to extract JSONValidationFailed and MigrationFailed constructor from WalletError. They're now defined as constructor in different data-types (resp. JSONValidationError and MigrationError).

[CO-319] Solve rebase conflicts

fd801a7

KtorZ force-pushed the akegalj/CO-319/swagger-account-index branch from 2924c46 to 808f00b Compare June 27, 2018 15:08

KtorZ approved these changes Jun 28, 2018

View reviewed changes

akegalj commented Jun 28, 2018

View reviewed changes

akegalj merged commit 8899c1f into Squad1/CBR-26/improve-error-handling Jun 28, 2018

akegalj removed the wip label Jun 28, 2018

KtorZ deleted the akegalj/CO-319/swagger-account-index branch June 28, 2018 12:54

akegalj changed the title ~~Akegalj/co 319/swagger account index~~ [CBR-319] Akegalj/co 319/swagger account index Jul 2, 2018

akegalj changed the title ~~[CBR-319] Akegalj/co 319/swagger account index~~ [CBR-306] Akegalj/co 319/swagger account index Jul 2, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CBR-306] Akegalj/co 319/swagger account index #3086

[CBR-306] Akegalj/co 319/swagger account index #3086

akegalj commented Jun 13, 2018 •

edited

Loading

akegalj Jun 14, 2018

KtorZ Jun 18, 2018

KtorZ Jun 18, 2018

akegalj Jun 18, 2018

KtorZ Jun 18, 2018

KtorZ Jun 18, 2018

KtorZ Jun 18, 2018

akegalj Jun 18, 2018 •

edited

Loading

KtorZ Jun 18, 2018

KtorZ commented Jun 18, 2018

akegalj Jun 18, 2018

akegalj Jun 18, 2018

parsonsmatt commented Jun 21, 2018

KtorZ commented Jun 22, 2018

KtorZ commented Jun 22, 2018

akegalj Jun 22, 2018 •

edited

Loading

akegalj commented Jun 22, 2018

akegalj Jun 25, 2018 •

edited

Loading

KtorZ Jun 25, 2018

parsonsmatt commented Jun 25, 2018

akegalj left a comment

[CBR-306] Akegalj/co 319/swagger account index #3086

[CBR-306] Akegalj/co 319/swagger account index #3086

Conversation

akegalj commented Jun 13, 2018 • edited Loading

Description

Linked issue

Type of change

Developer checklist

Testing checklist

QA Steps

Screenshots (if available)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akegalj Jun 18, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KtorZ commented Jun 18, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

parsonsmatt commented Jun 21, 2018

KtorZ commented Jun 22, 2018

KtorZ commented Jun 22, 2018

akegalj Jun 22, 2018 • edited Loading

Choose a reason for hiding this comment

akegalj commented Jun 22, 2018

akegalj Jun 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

parsonsmatt commented Jun 25, 2018

akegalj left a comment

Choose a reason for hiding this comment

akegalj commented Jun 13, 2018 •

edited

Loading

akegalj Jun 18, 2018 •

edited

Loading

akegalj Jun 22, 2018 •

edited

Loading

akegalj Jun 25, 2018 •

edited

Loading