Merge #4050 #4051

4050: Internal Endpoints Disclaimer r=KtorZ a=KtorZ

## Description

<!--- A brief description of this PR and the problem is trying to solve -->

As a follow-up from the discussion in cardano-foundation/cardano-wallet#151 (comment), we will add a proper disclaimer in the documentation about the internal endpoints. 

## Linked issue

<!--- Put here the relevant issue from YouTrack -->

cardano-foundation/cardano-wallet#228



4051: Disable node monitoring API by default r=KtorZ a=KtorZ

## Description

<!--- A brief description of this PR and the problem is trying to solve -->

Instead of using default arguments pointing to files that may or may not be present.
It's better to simply not have it by default, and activate it only when needed

## Linked issue

<!--- Put here the relevant issue from YouTrack -->



Co-authored-by: KtorZ <[email protected]>

Author: iohk-bors[bot]

lib/src/Pos/Client/CLI/NodeOptions.hs

@@ -25,15 +25,14 @@ import           Data.Version (showVersion)
 import           NeatInterpolation (text)
 import           Options.Applicative (Parser, auto, execParser, footerDoc,
                      fullDesc, header, help, helper, info, infoOption, long,
-                     metavar, option, progDesc, showDefault, strOption, switch,
-                     value)
+                     metavar, option, progDesc, strOption, switch, value)
 import           Text.PrettyPrint.ANSI.Leijen (Doc)
 
 import           Paths_cardano_sl (version)
 
 import           Pos.Client.CLI.Options (CommonArgs (..), commonArgsParser,
                      optionalJSONPath, templateParser)
-import           Pos.Core.NetworkAddress (NetworkAddress, addrParser, localhost)
+import           Pos.Core.NetworkAddress (NetworkAddress, addrParser)
 import           Pos.Infra.HealthCheck.Route53 (route53HealthCheckOption)
 import           Pos.Infra.InjectFail (FInjectsSpec, parseFInjectsSpec)
 import           Pos.Infra.Network.CLI (NetworkConfigOpts, networkConfigOption)
@@ -162,7 +161,7 @@ nodeArgsParser = NodeArgs <$> behaviorParser
             metavar "FILE" <>
             help "Path to the behavior config"
 
-data NodeWithApiArgs = NodeWithApiArgs CommonNodeArgs NodeArgs NodeApiArgs
+data NodeWithApiArgs = NodeWithApiArgs CommonNodeArgs NodeArgs (Maybe NodeApiArgs)
 
 nodeWithApiArgsParser :: Parser NodeWithApiArgs
 nodeWithApiArgsParser =
@@ -171,22 +170,19 @@ nodeWithApiArgsParser =
         <*> nodeArgsParser
         <*> nodeApiArgsParser
 
-nodeApiArgsParser :: Parser NodeApiArgs
-nodeApiArgsParser =
-    NodeApiArgs
-        <$> addressParser "node-api-address" (localhost, 8080)
-        <*> tlsParamsParser
-        <*> debugModeParser
-        <*> addressParser "node-doc-address" (localhost, 8180)
+nodeApiArgsParser :: Parser (Maybe NodeApiArgs)
+nodeApiArgsParser = optional $ NodeApiArgs
+    <$> addressParser "node-api-address"
+    <*> tlsParamsParser
+    <*> debugModeParser
+    <*> addressParser "node-doc-address"
   where
-    addressParser flagName defValue =
+    addressParser :: String -> Parser NetworkAddress
+    addressParser flagName =
         option (fromParsec addrParser) $
             long flagName
          <> metavar "IP:PORT"
-         <> help helpMsg
-         <> showDefault
-         <> value defValue
-    helpMsg = "IP and port for backend node API."
+         <> help "IP and port for backend node API."
     debugModeParser :: Parser Bool
     debugModeParser =
         switch (long "wallet-debug" <>
@@ -216,23 +212,20 @@ tlsParamsParser = constructTlsParams <$> certPathParser
                                 "tlscert"
                                 "FILEPATH"
                                 "Path to file with TLS certificate"
-                                <> value "scripts/tls-files/server.crt"
                                )
 
     keyPathParser :: Parser FilePath
     keyPathParser = strOption (templateParser
                                "tlskey"
                                "FILEPATH"
                                "Path to file with TLS key"
-                               <> value "scripts/tls-files/server.key"
                               )
 
     caPathParser :: Parser FilePath
     caPathParser = strOption (templateParser
                               "tlsca"
                               "FILEPATH"
                               "Path to file with TLS certificate authority"
-                              <> value "scripts/tls-files/ca.crt"
                              )
 
     noClientAuthParser :: Parser Bool

lib/src/Pos/Node/API.hs

@@ -19,7 +19,7 @@ import           Data.Aeson.Types (toJSONKeyText)
 import qualified Data.ByteArray as ByteArray
 import qualified Data.Char as C
 import qualified Data.Map.Strict as Map
-import           Data.Swagger hiding (Example, example)
+import           Data.Swagger hiding (Example, Tag, example)
 import qualified Data.Swagger as S
 import           Data.Swagger.Declare (Declare, look)
 import           Data.Swagger.Internal.Schema (GToSchema)
@@ -46,7 +46,8 @@ import           Pos.Infra.Util.LogSafe (BuildableSafeGen (..), SecureLog (..),
                      deriveSafeBuildable)
 import           Pos.Util.Example
 import           Pos.Util.Servant (APIResponse, CustomQueryFlag, Flaggable (..),
-                     HasCustomQueryFlagDescription (..), Tags, ValidJSON)
+                     HasCustomQueryFlagDescription (..), Tag,
+                     TagDescription (..), ValidJSON)
 import           Pos.Util.UnitsOfMeasure
 import           Serokell.Util.Text
 
@@ -665,13 +666,13 @@ instance BuildableSafeGen NodeSettings where
 
 
 type SettingsAPI =
-    Tags '["Settings"]
+    Tag "Settings" 'NoTagDescription
         :> "node-settings"
         :> Summary "Retrieves the static settings for this node."
         :> Get '[ValidJSON] (APIResponse NodeSettings)
 
 type InfoAPI =
-        Tags '["Info"]
+        Tag "Info" 'NoTagDescription
             :> "node-info"
             :> Summary "Retrieves the dynamic information for this node."
             :> CustomQueryFlag "force_ntp_check" ForceNtpCheck

lib/src/Pos/Util/Servant.hs

@@ -69,7 +69,8 @@ module Pos.Util.Servant
     , applicationJson
     , applyLoggingToHandler
     , ValidJSON
-    , Tags
+    , Tag
+    , TagDescription(..)
     , mapRouter
     , APIResponse(..)
     , single
@@ -93,8 +94,14 @@ import           Data.Constraint.Forall (Forall, inst)
 import           Data.Default (Default (..))
 import           Data.List (lookup)
 import           Data.Reflection (Reifies (..), reflect)
-import qualified Data.Set as Set
-import           Data.Swagger as S hiding (Example, Header, example, info)
+import           Data.Swagger (NamedSchema (..), ParamAnySchema (..),
+                     ParamLocation (..), SwaggerType (..), ToSchema (..),
+                     allowEmptyValue, applyTagsFor, declareSchemaRef,
+                     defaultSchemaOptions, default_, description,
+                     genericDeclareNamedSchema, in_, name, operationsOf,
+                     paramSchema, properties, required, schema, toParamSchema,
+                     type_)
+import qualified Data.Swagger as S
 import qualified Data.Text as T
 import           Data.Time.Clock.POSIX (getPOSIXTime)
 import           Data.Typeable (typeOf, typeRep)
@@ -128,7 +135,6 @@ import           Pos.Infra.Util.LogSafe (BuildableSafe, SecuredText, buildSafe,
 import           Pos.Util.Example (Example (..))
 import           Pos.Util.Jsend (HasDiagnostic (..), ResponseStatus (..),
                      jsendErrorGenericParseJSON, jsendErrorGenericToJSON)
-import           Pos.Util.KnownSymbols
 import           Pos.Util.Pagination
 import           Pos.Util.Wlog (LoggerName, LoggerNameBox, usingLoggerName)
 
@@ -894,31 +900,54 @@ instance HasDiagnostic JSONValidationError where
 
 -- | An empty type which can be used to inject Swagger tags at the type level,
 -- directly in the Servant API.
-data Tags (tags :: [Symbol])
+data Tag (tagName :: Symbol) (tagDescription :: TagDescription)
 
--- | Instance of `HasServer` which erases the `Tags` from its routing,
+data TagDescription
+    = NoTagDescription
+    | TagDescription Symbol
+
+-- | Instance of `HasServer` which erases the `Tag` from its routing,
 -- as the latter is needed only for Swagger.
-instance (HasServer subApi context) => HasServer (Tags tags :> subApi) context where
-    type ServerT (Tags tags :> subApi) m = ServerT subApi m
+instance (HasServer subApi context) => HasServer (Tag name desc :> subApi) context where
+    type ServerT (Tag name desc :> subApi) m = ServerT subApi m
     route _ = route (Proxy @subApi)
     hoistServerWithContext _ = hoistServerWithContext (Proxy @subApi)
 
-instance (HasClient m subApi) => HasClient m (Tags tags :> subApi) where
-    type Client m (Tags tags :> subApi) = Client m subApi
+instance (HasClient m subApi) => HasClient m (Tag name desc :> subApi) where
+    type Client m (Tag name desc :> subApi) = Client m subApi
     clientWithRoute pm _ = clientWithRoute pm (Proxy @subApi)
     hoistClientMonad pm _ f cl =
       hoistClientMonad pm (Proxy @subApi) f cl
 
 -- | Similar to 'instance HasServer', just skips 'Tags'.
 instance HasLoggingServer config subApi context =>
-    HasLoggingServer config (Tags tags :> subApi) context where
-    routeWithLog = mapRouter @(Tags tags :> LoggingApiRec config subApi) route identity
+    HasLoggingServer config (Tag name desc :> subApi) context where
+    routeWithLog = mapRouter @(Tag name desc :> LoggingApiRec config subApi) route identity
+
 
-instance (KnownSymbols tags, HasSwagger subApi) => HasSwagger (Tags tags :> subApi) where
+instance
+       (KnownSymbol name, KnownSymbol desc, HasSwagger subApi)
+    => HasSwagger (Tag name ('TagDescription desc) :> subApi) where
+    toSwagger _ =
+        let
+            subApi  = toSwagger (Proxy @subApi)
+            tag = S.Tag
+                (toText $ symbolVal $ Proxy @name)
+                (Just $ toText $ symbolVal $ Proxy @desc)
+                Nothing
+        in
+            subApi & applyTagsFor (operationsOf subApi) [tag]
+
+instance (KnownSymbol name, HasSwagger subApi) => HasSwagger (Tag name 'NoTagDescription :> subApi) where
     toSwagger _ =
-        let newTags    = map toText (symbolVals (Proxy @tags))
-            swgr       = toSwagger (Proxy @subApi)
-        in swgr & over (operationsOf swgr . tags) (mappend (Set.fromList newTags))
+        let
+            subApi  = toSwagger (Proxy @subApi)
+            tag = S.Tag
+                (toText $ symbolVal $ Proxy @name)
+                Nothing
+                Nothing
+        in
+            subApi & applyTagsFor (operationsOf subApi) [tag]
 
 -- | `mapRouter` is helper function used in order to transform one `HasServer`
 -- instance to another. It can be used to introduce custom request params type.

node/app/Main.hs

@@ -10,20 +10,22 @@ import           Pos.Client.CLI (NodeWithApiArgs (..), getNodeApiOptions,
                      loggingParams)
 import           Pos.Launcher (actionWithCoreNode, launchNode)
 import           Pos.Util.CompileInfo (compileInfo, withCompileInfo)
+import           Pos.Util.Wlog (logInfo)
 
 main :: IO ()
 main = withCompileInfo $ do
-    NodeWithApiArgs cArgs nArgs apiArgs <- getNodeApiOptions
+    NodeWithApiArgs cArgs nArgs mApiArgs <- getNodeApiOptions
     let lArgs = loggingParams "node" cArgs
+
+    let nodeServer = case mApiArgs of
+            Nothing ->
+                \_ _ _ _ _ _ -> logInfo "Monitoring API is disabled."
+            Just apiArgs ->
+                launchNodeServer apiArgs
+
     launchNode nArgs cArgs lArgs
         $ \genConfig walConfig txpConfig ntpConfig nodeParams sscParams nodeResources ->
             actionWithCoreNode
-                (launchNodeServer
-                    apiArgs
-                    ntpConfig
-                    nodeResources
-                    updateConfiguration
-                    compileInfo
-                    genConfig)
+                (nodeServer ntpConfig nodeResources updateConfiguration compileInfo genConfig)
                 genConfig walConfig txpConfig
                 ntpConfig nodeParams sscParams nodeResources

wallet/integration/QuickCheckSpecs.hs

@@ -16,7 +16,7 @@ import           Test.Hspec
 import           Test.QuickCheck
 
 import           Cardano.Wallet.API.Request (FilterBy, SortBy)
-import           Cardano.Wallet.API.Types (Tags, WithDefaultApiArg)
+import           Cardano.Wallet.API.Types (Tag, WithDefaultApiArg)
 import qualified Cardano.Wallet.API.V1 as V0
 import qualified Cardano.Wallet.API.V1 as V1
 import           Cardano.Wallet.API.V1.Parameters (WalletRequestParams,
@@ -63,7 +63,7 @@ instance HasGenRequest sub => HasGenRequest (SortBy syms res :> sub) where
 instance HasGenRequest sub => HasGenRequest (FilterBy syms res :> sub) where
     genRequest _ = genRequest (Proxy @sub)
 
-instance HasGenRequest sub => HasGenRequest (Tags tags :> sub) where
+instance HasGenRequest sub => HasGenRequest (Tag tag desc :> sub) where
     genRequest _ = genRequest (Proxy :: Proxy sub)
 
 instance HasGenRequest (sub :: *) => HasGenRequest (WalletRequestParams :> sub) where

wallet/src/Cardano/Wallet/API/Internal.hs

@@ -8,10 +8,16 @@ import           Pos.Chain.Update (SoftwareVersion)
 import           Servant
 
 import           Cardano.Wallet.API.Response (APIResponse, ValidJSON)
-import           Cardano.Wallet.API.Types (Tags)
+import           Cardano.Wallet.API.Types
 import           Cardano.Wallet.API.V1.Types (V1, Wallet, WalletImport)
 
-type API = Tags '["Internal"] :>
+type API = Tag "Internal" ('TagDescription
+    "This section contains endpoints so-called 'Internal'. They are only\
+    \ expected to be used by advanced users of the API (e.g. Daedalus) with\
+    \ which there's a privileged communication channel. Backward-compatibility\
+    \ or existence of these endpoints between versions is not guaranteed and\
+    \ won't be enforced. Use at your own risks.")
+    :>
     (    "next-update"
         :> Summary "Version of the next update (404 if none)"
         :> Get '[ValidJSON] (APIResponse (V1 SoftwareVersion))

wallet/src/Cardano/Wallet/API/Types.hs

@@ -9,7 +9,8 @@ module Cardano.Wallet.API.Types
     , DHeader
     , mapRouter
     , WithDefaultApiArg
-    , Tags
+    , Tag
+    , TagDescription(..)
     , WalletLoggingConfig
     ) where
 
@@ -20,7 +21,7 @@ import           Servant
 import qualified Servant.Server.Internal as SI
 
 import           Pos.Util.Servant (ApiLoggingConfig (..), DHeader, DQueryParam,
-                     Tags, WithDefaultApiArg)
+                     Tag, TagDescription (..), WithDefaultApiArg)
 
 -- | `mapRouter` is helper function used in order to transform one `HasServer`
 -- instance to another. It can be used to introduce custom request params type.

wallet/src/Cardano/Wallet/API/V1/Accounts.hs

@@ -12,7 +12,7 @@ import qualified Pos.Core as Core
 
 
 type API
-    = Tags '["Accounts"] :>
+    = Tag "Accounts" 'NoTagDescription :>
     (    "wallets" :> CaptureWalletId :> "accounts"
           :> CaptureAccountId
           :> Summary "Deletes an Account."

wallet/src/Cardano/Wallet/API/V1/Addresses.hs

@@ -9,7 +9,7 @@ import           Cardano.Wallet.API.V1.Parameters
 import           Cardano.Wallet.API.V1.Types
 
 
-type API = Tags '["Addresses"] :>
+type API = Tag "Addresses" 'NoTagDescription :>
       (    "addresses" :> WalletRequestParams
                        :> Summary "Returns a list of the addresses."
                        :> Get '[ValidJSON] (APIResponse [WalletAddress])

wallet/src/Cardano/Wallet/API/V1/Settings.hs

@@ -6,7 +6,7 @@ import           Cardano.Wallet.API.V1.Types
 
 import           Servant
 
-type API = Tags '["Settings"] :>
+type API = Tag "Settings" 'NoTagDescription :>
          ( "node-settings"  :> Summary "Retrieves the static settings for this node."
                             :> Get '[ValidJSON] (APIResponse NodeSettings)
          )

wallet/src/Cardano/Wallet/API/V1/Transactions.hs

@@ -10,7 +10,7 @@ import qualified Pos.Core as Core
 
 import           Servant
 
-type API = Tags '["Transactions"] :>
+type API = Tag "Transactions" 'NoTagDescription :>
     (    "transactions" :> Summary "Generates a new transaction from the source to one or multiple target addresses."
                         :> ReqBody '[ValidJSON] Payment
                         :> Post '[ValidJSON] (APIResponse Transaction)

wallet/src/Cardano/Wallet/API/V1/Wallets.hs

@@ -9,7 +9,7 @@ import           Pos.Core as Core
 
 import           Servant
 
-type API = Tags '["Wallets"] :>
+type API = Tag "Wallets" 'NoTagDescription :>
     (    "wallets" :> Summary "Creates a new or restores an existing Wallet."
                    :> ReqBody '[ValidJSON] (New Wallet)
                    :> PostCreated '[ValidJSON] (APIResponse Wallet)