From 24c7db55ab14443785cc16b1ea57397de9bd953b Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Wed, 31 May 2023 16:40:40 -0400
Subject: [PATCH] minor formatting, haddock improvements
---
src/Tahoe/Download.hs | 43 +++++++++++++++++-------
src/Tahoe/Download/Internal/Client.hs | 6 ++++
src/Tahoe/Download/Internal/Immutable.hs | 4 +++
3 files changed, 41 insertions(+), 12 deletions(-)
diff --git a/src/Tahoe/Download.hs b/src/Tahoe/Download.hs
index a7529a8..79cf07d 100644
--- a/src/Tahoe/Download.hs
+++ b/src/Tahoe/Download.hs
@@ -88,17 +88,19 @@ firstStorageServer servers finder = do
responses <- mapM finder servers
pure $ head $ take 1 $ rights responses -- XXX don't do this at home kids, head isn't safe
-{-
- getShareNumbers :: server -> storageIndex -> IO [ShareNumber]
- for mutables, getMutableShareNumbers
- getEncodingParameters :: Capability -> StorageServer -> IO (n,k)
- it's pure for CHK (immutables), but must be requested from the server for mutables
- this returns the FEC encoding values so you know when to stop fetching shares
- getStorageIndex :: Capability -> StorageIndex
- -}
+-- | A capability which confers the ability to locate and verify some stored data.
class Verifiable v where
+ -- | Ask a storage server which share numbers related to this capability it
+ -- is holding. This is an unverified result and the storage server could
+ -- present incorrect information. Even if it correctly reports that it
+ -- holds a share, it could decline to give it out when asked.
getShareNumbers :: MonadIO m => v -> StorageServer -> m (Set.Set ShareNum)
+
+ -- | Get the encoding parameters used for the shares of this capability.
+ -- The information is presented as a tuple of (required, total).
getRequiredTotal :: MonadIO m => v -> StorageServer -> m (Int, Int)
+
+ -- | Get the location information for shares of this capability.
getStorageIndex :: v -> StorageIndex
instance Verifiable CHK.Verifier where
@@ -108,13 +110,23 @@ instance Verifiable CHK.Verifier where
-- CHK is pure, we don't have to ask the StorageServer
getRequiredTotal Verifier{required, total} _ = pure (fromIntegral required, fromIntegral total)
+{- | A capability which confers the ability to interpret some stored data to
+ recover the original plaintext. Additionally, it can be attentuated to a
+ Verifiable.
+-}
class (Verifiable v) => Readable r v | r -> v where
+ -- | Attentuate the capability.
getVerifiable :: r -> v
+
+ -- | Interpret the required number of shares to recover the plaintext.
+ --
+ -- Note: might want to split the two functions below out of decodeShare
+ --
+ -- shareToCipherText :: r -> [(Int, WhichShare)] -> LB.ByteString
+ --
+ -- cipherTextToPlainText :: r -> LB.ByteString -> LB.ByteString
decodeShare :: MonadIO m => r -> [(Int, WhichShare)] -> m (Either DownloadError LB.ByteString)
--- Might want to split the two functions below out of decodeShare
--- shareToCipherText :: Share ->
--- cipherTextToPlainText
instance Readable CHK.Reader CHK.Verifier where
getVerifiable = verifier
decodeShare r shareList = do
@@ -124,8 +136,15 @@ instance Readable CHK.Reader CHK.Verifier where
Just ct ->
pure . Right $ Tahoe.CHK.Encrypt.decrypt (readKey r) ct
-data WhichShare = CHK {unWhich :: Tahoe.CHK.Share.Share} -- \| SDMF SDMF.Share
+{- | Represent the kind of share to operate on. This forms a closed world of
+ share types. It might eventually be interesting to make an open world
+ variation instead.
+-}
+newtype WhichShare = CHK {unWhich :: Tahoe.CHK.Share.Share} -- \| SDMF SDMF.Share
+{- | Deserialize some bytes representing some kind of share to that kind of
+ share, if possible.
+-}
bytesToShare :: LB.ByteString -> Either DeserializeError WhichShare
bytesToShare bytes = do
case decodeOrFail bytes of
diff --git a/src/Tahoe/Download/Internal/Client.hs b/src/Tahoe/Download/Internal/Client.hs
index fd6afe6..4b81131 100644
--- a/src/Tahoe/Download/Internal/Client.hs
+++ b/src/Tahoe/Download/Internal/Client.hs
@@ -1,3 +1,6 @@
+{- | Functionality related to acting as a client for the Great Black Swamp
+ protocol.
+-}
module Tahoe.Download.Internal.Client where
import Control.Monad.IO.Class
@@ -118,4 +121,7 @@ data LookupError
AnnouncementStructureUnmatched
deriving (Eq, Ord, Show)
+{- | A problem was encountered attempting to deserialize bytes to a structured
+ representation of some value.
+-}
data DeserializeError = UnknownDeserializeError -- add more later?
diff --git a/src/Tahoe/Download/Internal/Immutable.hs b/src/Tahoe/Download/Internal/Immutable.hs
index b699652..f7c9cb8 100644
--- a/src/Tahoe/Download/Internal/Immutable.hs
+++ b/src/Tahoe/Download/Internal/Immutable.hs
@@ -1,3 +1,4 @@
+-- | Functionality related to retrieving "immutable" shares (mainly CHK).
module Tahoe.Download.Internal.Immutable where
import Control.Exception
@@ -58,6 +59,9 @@ announcementToImmutableStorageServer ann =
Nothing -> pure . Left . URIParseError $ ann
Just uri -> makeImmutableServer uri
+{- | If possible, populate a StorageServer with functions for operating on
+ immutable data on the server at the given URI.
+-}
makeImmutableServer :: MonadIO m => URI -> m (Either LookupError StorageServer)
makeImmutableServer
URI
--
GitLab