Wrap up feature

src/Database/Bloodhound/Client.hs

@@ -343,6 +343,7 @@ deleteSnapshotRepo (SnapshotRepoName n) = delete =<< url
     url = joinPath ["_snapshot", n]
 
 
+-- | Create and start a snapshot
 createSnapshot
     :: (MonadBH m)
     => SnapshotRepoName
@@ -370,14 +371,14 @@ renderIndices (i :| is) = T.intercalate "," (renderIndex <$> (i:is))
     renderIndex (IndexName n) = n
 
 
+-- | Get info about known snapshots given a pattern and repo name.
 getSnapshots
     :: ( MonadBH m
        , MonadThrow m
        )
     => SnapshotRepoName
     -> SnapshotSelection
-    -> m (Either EsError
-     [SnapshotInfo])
+    -> m (Either EsError [SnapshotInfo])
 getSnapshots (SnapshotRepoName repoName) sel =
   fmap (fmap unSIs) . parseEsResponse =<< get =<< url
   where
@@ -398,6 +399,7 @@ instance FromJSON SIs where
       parse o = SIs <$> o .: "snapshots"
 
 
+-- | Delete a snapshot. Cancels if it is running.
 deleteSnapshot :: MonadBH m => SnapshotRepoName -> SnapshotName -> m Reply
 deleteSnapshot (SnapshotRepoName repoName) (SnapshotName snapName) =
   delete =<< url

src/Database/Bloodhound/Types.hs

@@ -258,6 +258,8 @@ module Database.Bloodhound.Types
        , SnapshotSelection(..)
        , SnapshotPattern(..)
        , SnapshotInfo(..)
+       , SnapshotShardFailure(..)
+       , ShardId(..)
        , SnapshotName(..)
        , SnapshotState(..)
        , SnapshotRestoreSettings(..)
@@ -3687,7 +3689,7 @@ data SnapshotRepoSelection = SnapshotRepoList (NonEmpty SnapshotRepoPattern)
 
 
 -- | Either specifies an exact repo name or one with globs in it,
--- e.g. @RepoPattern "foo*"@ __NOTE__:@ Patterns are not supported on ES < 1.7
+-- e.g. @RepoPattern "foo*"@ __NOTE__: Patterns are not supported on ES < 1.7
 data SnapshotRepoPattern = ExactRepo SnapshotRepoName
                          | RepoPattern Text
                          deriving (Eq, Generic, Show, Typeable)
@@ -3746,6 +3748,7 @@ instance FromJSON SnapshotVerification where
         SnapshotNodeVerification (FullNodeId rawFullId) <$> o .: "name"
 
 
+-- | A node that has verified a snapshot
 data SnapshotNodeVerification = SnapshotNodeVerification {
       snvFullId   :: FullNodeId
     , snvNodeName :: NodeName
@@ -3758,6 +3761,8 @@ newtype FullNodeId = FullNodeId { fullNodeId :: Text }
                    deriving (Eq, Ord, Generic, Show, Typeable, FromJSON)
 
 
+-- | A human-readable node name that is supplied by the user in the
+-- node config or automatically generated by ElasticSearch.
 newtype NodeName = NodeName { nodeName :: Text }
                  deriving (Eq, Ord, Generic, Show, Typeable, FromJSON)
 
@@ -3778,14 +3783,19 @@ defaultSnapshotRepoUpdateSettings :: SnapshotRepoUpdateSettings
 defaultSnapshotRepoUpdateSettings = SnapshotRepoUpdateSettings True
 
 
--- | A filesystem-based snapshot repo that ships with elasticsearch.
+-- | A filesystem-based snapshot repo that ships with
+-- ElasticSearch. This is an instance of 'SnapshotRepo' so it can be
+-- used with 'updateSnapshotRepo'
 data FsSnapshotRepo = FsSnapshotRepo {
       fsrName                   :: SnapshotRepoName
     , fsrLocation               :: FilePath
     , fsrCompressMetadata       :: Bool
     , fsrChunkSize              :: Maybe Bytes
+    -- ^ Size by which to split large files during snapshotting.
     , fsrMaxRestoreBytesPerSec  :: Maybe Bytes
+    -- ^ Throttle node restore rate. If not supplied, defaults to 40mb/sec
     , fsrMaxSnapshotBytesPerSec :: Maybe Bytes
+    -- ^ Throttle node snapshot rate. If not supplied, defaults to 40mb/sec
     } deriving (Eq, Generic, Show, Typeable)
 
 
@@ -3827,10 +3837,8 @@ class SnapshotRepo r where
   fromGSnapshotRepo :: GenericSnapshotRepo -> Either SnapshotRepoConversionError r
 
 
-data SnapshotRepoConversionError = RepoTypeMismatch SnapshotRepoType
-                                                    -- ^ Expected type
-                                                    SnapshotRepoType
-                                                    -- ^ Actual type
+data SnapshotRepoConversionError = RepoTypeMismatch SnapshotRepoType SnapshotRepoType
+                                 -- ^ Expected type and actual type
                                  | OtherRepoConversionError Text
                                  deriving (Show, Eq, Generic, Typeable)
 
@@ -3891,7 +3899,7 @@ data SnapshotPattern = ExactSnap SnapshotName
 -- redundancies with 'SnapshotStatus'
 data SnapshotInfo = SnapshotInfo {
       snapInfoShards    :: ShardResult
-      --TODO: what does failures produce? list of what?
+    , snapInfoFailures  :: [SnapshotShardFailure]
     , snapInfoDuration  :: NominalDiffTime
     , snapInfoEndTime   :: UTCTime
     , snapInfoStartTime :: UTCTime
@@ -3905,6 +3913,7 @@ instance FromJSON SnapshotInfo where
   parseJSON = withObject "SnapshotInfo" parse
     where
       parse o = SnapshotInfo <$> o .: "shards"
+                             <*> o .: "failures"
                              <*> (unMS <$> o .: "duration_in_millis")
                              <*> (posixMS <$> o .: "end_time_in_millis")
                              <*> (posixMS <$> o .: "start_time_in_millis")
@@ -3912,6 +3921,26 @@ instance FromJSON SnapshotInfo where
                              <*> o .: "indices"
                              <*> o .: "snapshot"
 
+data SnapshotShardFailure = SnapshotShardFailure {
+      snapShardFailureIndex :: IndexName
+    , snapShardFailureNodeId :: Maybe NodeName -- I'm not 100% sure this isn't actually 'FullNodeId'
+    , snapShardFailureReason :: Text
+    , snapShardFailureShardId :: ShardId
+    } deriving (Eq, Show, Generic, Typeable)
+
+
+instance FromJSON SnapshotShardFailure where
+  parseJSON = withObject "SnapshotShardFailure" parse
+    where
+      parse o = SnapshotShardFailure <$> o .: "index"
+                                     <*> o .:? "node_id"
+                                     <*> o .: "reason"
+                                     <*> o .: "shard_id"
+
+
+newtype ShardId = ShardId { shardId :: Int }
+                deriving (Eq, Show, Generic, Typeable, FromJSON)
+
 -- | Milliseconds
 newtype MS = MS NominalDiffTime
 
@@ -3999,8 +4028,7 @@ newtype RestoreRenamePattern = RestoreRenamePattern { rrPattern :: Text }
 -- | A single token in a index renaming scheme for a restore. These
 -- are concatenated into a string before being sent to
 -- ElasticSearch. Check out these Java
--- <https://docs.oracle.com/javase/7/docs/api/java/util/regex/Matcher.html
--- docs> to find out more if you're into that sort of thing.
+-- <https://docs.oracle.com/javase/7/docs/api/java/util/regex/Matcher.html docs> to find out more if you're into that sort of thing.
 data RestoreRenameToken = RRTLit Text
                         -- ^ Just a literal string of characters
                         | RRSubWholeMatch
@@ -4011,7 +4039,7 @@ data RestoreRenameToken = RRTLit Text
 
 
 -- | A group number for regex matching. Only values from 1-9 are
--- supported. Construct with mkRRGroupRefNum
+-- supported. Construct with 'mkRRGroupRefNum'
 newtype RRGroupRefNum = RRGroupRefNum { rrGroupRefNum :: Int }
                       deriving (Show, Eq, Generic, Typeable, Ord)
 
@@ -4020,8 +4048,7 @@ instance Bounded RRGroupRefNum where
   maxBound = RRGroupRefNum 9
 
 
-
--- | Only allows valid group number references (0-9).
+-- | Only allows valid group number references (1-9).
 mkRRGroupRefNum :: Int -> Maybe RRGroupRefNum
 mkRRGroupRefNum i
   | i >= (rrGroupRefNum minBound) && i <= (rrGroupRefNum maxBound) =