diff --git a/Database/EventStore.hs b/Database/EventStore.hs --- a/Database/EventStore.hs +++ b/Database/EventStore.hs @@ -11,19 +11,55 @@ -- -------------------------------------------------------------------------------- module Database.EventStore - ( Event + ( -- * Event + Event , EventData + , createEvent + , withJson + , withJsonAndMetadata + -- * Connection , Connection , Credentials - , ExpectedVersion(..) - , HostName - , Port , Settings(..) - , Subscription(..) - , Catchup(..) - , CatchupError(..) , credentials - -- * Result + , defaultSettings + , connect + , shutdown + -- * Read Operations + , readEvent + , readAllEventsBackward + , readAllEventsForward + , readStreamEventsBackward + , readStreamEventsForward + -- * Write Operations + , deleteStream + , sendEvent + , sendEvents + -- * Transaction + , Transaction + , transactionStart + , transactionCommit + , transactionRollback + , transactionSendEvents + -- * Volatile Subscription + , DropReason(..) + , Subscription + , subscribe + , subAwait + , subId + , subStream + , subResolveLinkTos + , subLastCommitPos + , subLastEventNumber + , subUnsubscribe + -- * Catch-up Subscription + , Catchup + , CatchupError(..) + , subscribeFrom + , catchupAwait + , catchupStream + , catchupUnsubscribe + -- * Results , AllEventsSlice(..) , DeleteResult(..) , WriteResult(..) @@ -36,34 +72,12 @@ , ReadEventResult(..) , ResolvedEvent(..) , ReadStreamResult(..) - , DropReason(..) + , OperationException(..) , eventResolved , resolvedEventOriginal , resolvedEventOriginalStreamId - -- * Event - , createEvent - , withJson - , withJsonAndMetadata - -- * Connection manager - , defaultSettings - , connect - , deleteStream - , readEvent - , readAllEventsBackward - , readAllEventsForward - , readStreamEventsBackward - , readStreamEventsForward - , sendEvent - , sendEvents - , shutdown - , transactionStart - , subscribe - , subscribeFrom - -- * Transaction - , Transaction - , transactionCommit - , transactionRollback - , transactionSendEvents + -- * Misc + , ExpectedVersion(..) -- * Re-export , module Control.Concurrent.Async ) where @@ -89,12 +103,9 @@ import Database.EventStore.Internal.Operation.WriteEventsOperation -------------------------------------------------------------------------------- -type HostName = String -type Port = Int - --------------------------------------------------------------------------------- -- Connection -------------------------------------------------------------------------------- +-- | Represents a connection to a single EventStore node. data Connection = Connection { conProcessor :: Processor @@ -102,19 +113,22 @@ } -------------------------------------------------------------------------------- --- | Creates a new connection to a single node. It maintains a full duplex --- connection to the EventStore. An EventStore @Connection@ operates quite +-- | Creates a new 'Connection' to a single node. It maintains a full duplex +-- connection to the EventStore. An EventStore 'Connection' operates quite -- differently than say a SQL connection. Normally when you use a SQL -- connection you want to keep the connection open for a much longer of time -- than when you use a SQL connection. -- --- Another difference is that with the EventStore @Connection@ all operation +-- Another difference is that with the EventStore 'Connection' all operation -- are handled in a full async manner (even if you call the synchronous --- behaviors). Many threads can use an EvenStore connection at the same time +-- behaviors). Many threads can use an EvenStore 'Connection' at the same time -- or a single thread can make many asynchronous requests. To get the most -- performance out of the connection it is generally recommend to use it in --- this way -connect :: Settings -> HostName -> Port -> IO Connection +-- this way. +connect :: Settings + -> String -- ^ HostName + -> Int -- ^ Port + -> IO Connection connect settings host port = do processor <- newProcessor settings processorConnect processor host port @@ -122,12 +136,14 @@ return $ Connection processor settings -------------------------------------------------------------------------------- +-- | Asynchronously closes the 'Connection'. shutdown :: Connection -> IO () shutdown Connection{..} = processorShutdown conProcessor -------------------------------------------------------------------------------- +-- | Sends a single 'Event' to given stream. sendEvent :: Connection - -> Text -- ^ Stream + -> Text -- ^ Stream name -> ExpectedVersion -> Event -> IO (Async WriteResult) @@ -135,8 +151,9 @@ sendEvents mgr evt_stream exp_ver [evt] -------------------------------------------------------------------------------- +-- | Sends a list of 'Event' to given stream. sendEvents :: Connection - -> Text -- ^ Stream + -> Text -- ^ Stream name -> ExpectedVersion -> [Event] -> IO (Async WriteResult) @@ -149,8 +166,9 @@ return as -------------------------------------------------------------------------------- +-- | Deletes given stream. deleteStream :: Connection - -> Text + -> Text -- ^ Stream name -> ExpectedVersion -> Maybe Bool -- ^ Hard delete -> IO (Async DeleteResult) @@ -163,8 +181,9 @@ return as -------------------------------------------------------------------------------- +-- | Starts a transaction on given stream. transactionStart :: Connection - -> Text + -> Text -- ^ Stream name -> ExpectedVersion -> IO (Async Transaction) transactionStart Connection{..} evt_stream exp_ver = do @@ -180,10 +199,11 @@ return as -------------------------------------------------------------------------------- +-- | Reads a single event from given stream. readEvent :: Connection - -> Text - -> Int32 - -> Bool + -> Text -- ^ Stream name + -> Int32 -- ^ Event number + -> Bool -- ^ Resolve Link Tos -> IO (Async ReadResult) readEvent Connection{..} stream_id evt_num res_link_tos = do (as, mvar) <- createAsync @@ -194,21 +214,23 @@ return as -------------------------------------------------------------------------------- +-- | Reads events from a given stream forward. readStreamEventsForward :: Connection - -> Text - -> Int32 - -> Int32 - -> Bool + -> Text -- ^ Stream name + -> Int32 -- ^ From event number + -> Int32 -- ^ Batch size + -> Bool -- ^ Resolve Link Tos -> IO (Async StreamEventsSlice) readStreamEventsForward mgr = readStreamEventsCommon mgr Forward -------------------------------------------------------------------------------- +-- | Reads events from a given stream backward. readStreamEventsBackward :: Connection - -> Text - -> Int32 - -> Int32 - -> Bool + -> Text -- ^ Stream name + -> Int32 -- ^ From event number + -> Int32 -- ^ Batch size + -> Bool -- ^ Resolve Link Tos -> IO (Async StreamEventsSlice) readStreamEventsBackward mgr = readStreamEventsCommon mgr Backward @@ -236,21 +258,23 @@ return as -------------------------------------------------------------------------------- +-- | Reads events from the $all stream forward. readAllEventsForward :: Connection - -> Int64 - -> Int64 - -> Int32 - -> Bool + -> Int64 -- ^ Commit position + -> Int64 -- ^ Prepare position + -> Int32 -- ^ Batch size + -> Bool -- ^ Resolve Link Tos -> IO (Async AllEventsSlice) readAllEventsForward mgr = readAllEventsCommon mgr Forward -------------------------------------------------------------------------------- +-- | Reads events from the $all stream backward readAllEventsBackward :: Connection - -> Int64 - -> Int64 - -> Int32 - -> Bool + -> Int64 -- ^ Commit position + -> Int64 -- ^ Prepare position + -> Int32 -- ^ Batch size + -> Bool -- ^ Resolve Link Tos -> IO (Async AllEventsSlice) readAllEventsBackward mgr = readAllEventsCommon mgr Backward @@ -278,9 +302,10 @@ return as -------------------------------------------------------------------------------- +-- | Subcribes to given stream. subscribe :: Connection - -> Text - -> Bool + -> Text -- ^ Stream name + -> Bool -- ^ Resolve Link Tos -> IO (Async Subscription) subscribe Connection{..} stream_id res_lnk_tos = do tmp <- newEmptyMVar @@ -291,14 +316,18 @@ async $ readMVar tmp -------------------------------------------------------------------------------- +-- | Subscribes to given stream. If last checkpoint is defined, this will +-- 'readStreamEventsForward' from that event number, otherwise from the +-- beginning. Once last stream event reached up, a subscription request will +-- be sent using 'subscribe'. subscribeFrom :: Connection - -> Text - -> Bool - -> Maybe Int32 - -> Maybe Int32 + -> Text -- ^ Stream name + -> Bool -- ^ Resolve Link Tos + -> Maybe Int32 -- ^ Last checkpoint + -> Maybe Int32 -- ^ Batch size -> IO Catchup subscribeFrom conn stream_id res_lnk_tos last_chk_pt batch_m = do - catchStart evts_fwd get_sub stream_id batch_m last_chk_pt + catchupStart evts_fwd get_sub stream_id batch_m last_chk_pt where evts_fwd cur_num batch_size = readStreamEventsForward conn stream_id cur_num batch_size res_lnk_tos diff --git a/Database/EventStore/Catchup.hs b/Database/EventStore/Catchup.hs --- a/Database/EventStore/Catchup.hs +++ b/Database/EventStore/Catchup.hs @@ -11,9 +11,12 @@ -- -------------------------------------------------------------------------------- module Database.EventStore.Catchup - ( Catchup(..) + ( Catchup , CatchupError(..) - , catchStart + , catchupAwait + , catchupStart + , catchupStream + , catchupUnsubscribe ) where -------------------------------------------------------------------------------- @@ -35,6 +38,8 @@ import Database.EventStore.Internal.Types -------------------------------------------------------------------------------- +-- | Errors that could arise during a catch-up subscription. 'Text' value +-- represents the stream name. data CatchupError = CatchupStreamDisappeared Text | CatchupStreamDeleted Text @@ -46,14 +51,22 @@ instance Exception CatchupError -------------------------------------------------------------------------------- +-- | Representing catch-up subscriptions. data Catchup = Catchup - { catchupStream :: Text + { catchupStream :: Text + -- ^ The name of the stream to which the subscription is subscribed. , catchupChan :: Chan (Either CatchupError ResolvedEvent) , catchupUnsubscribe :: IO () + -- ^ Asynchronously unsubscribes from the stream. } -------------------------------------------------------------------------------- +-- | Awaits for the next 'ResolvedEvent'. +catchupAwait :: Catchup -> IO (Either CatchupError ResolvedEvent) +catchupAwait c = readChan $ catchupChan c + +-------------------------------------------------------------------------------- defaultBatchSize :: Int32 defaultBatchSize = 500 @@ -62,13 +75,13 @@ secs = 1000000 -------------------------------------------------------------------------------- -catchStart :: (Int32 -> Int32 -> IO (Async StreamEventsSlice)) - -> IO (Async Subscription) - -> Text - -> Maybe Int32 - -> Maybe Int32 - -> IO Catchup -catchStart evt_fwd get_sub stream_id batch_size_m last_m = do +catchupStart :: (Int32 -> Int32 -> IO (Async StreamEventsSlice)) + -> IO (Async Subscription) + -> Text + -> Maybe Int32 + -> Maybe Int32 + -> IO Catchup +catchupStart evt_fwd get_sub stream_id batch_size_m last_m = do chan <- newChan var <- newEmptyMVar let batch_size = fromMaybe defaultBatchSize batch_size_m @@ -88,7 +101,7 @@ sub <- wait action putMVar var sub forever $ do - evt_e <- readChan $ subChan sub + evt_e <- subAwait sub case evt_e of Right evt -> writeChan chan (Right evt) Left r -> do diff --git a/Database/EventStore/Internal/Manager/Subscription.hs b/Database/EventStore/Internal/Manager/Subscription.hs --- a/Database/EventStore/Internal/Manager/Subscription.hs +++ b/Database/EventStore/Internal/Manager/Subscription.hs @@ -17,7 +17,14 @@ module Database.EventStore.Internal.Manager.Subscription ( DropReason (..) , NewSubscriptionCB - , Subscription(..) + , Subscription + , subAwait + , subId + , subStream + , subResolveLinkTos + , subLastCommitPos + , subLastEventNumber + , subUnsubscribe , subscriptionNetwork ) where @@ -86,6 +93,7 @@ instance Decode StreamEventAppeared -------------------------------------------------------------------------------- +-- | Represents the reason subscription drop happened. data DropReason = D_Unsubscribed | D_AccessDenied @@ -116,23 +124,32 @@ } -------------------------------------------------------------------------------- -data SubscriptionException - = StreamAccessDenied - | StreamNotFound - | SubscriptionDeleted - deriving Show - --------------------------------------------------------------------------------- +-- | Represents a subscription to a single stream or $all stream +-- in the EventStore. data Subscription = Subscription - { subId :: !UUID - , subStream :: !Text + { subId :: !UUID + -- ^ ID of the subscription. + , subStream :: !Text + -- ^ The name of the stream to which the subscription is subscribed. , subResolveLinkTos :: !Bool - , subLastCommitPos :: !Int64 + -- ^ Determines whether or not any link events encontered in the stream + -- will be resolved. + , subLastCommitPos :: !Int64 + -- ^ The last commit position seen on the subscription (if this a + -- subscription to $all stream). , subLastEventNumber :: !(Maybe Int32) - , subChan :: Chan (Either DropReason ResolvedEvent) - , subUnsubscribe :: IO () + -- ^ The last event number seen on the subscription (if this is a + -- subscription to a single stream). + , subChan :: Chan (Either DropReason ResolvedEvent) + , subUnsubscribe :: IO () + -- ^ Asynchronously unsubscribe from the the stream. } + +-------------------------------------------------------------------------------- +-- | Awaits for the next 'ResolvedEvent'. +subAwait :: Subscription -> IO (Either DropReason ResolvedEvent) +subAwait Subscription{..} = readChan subChan -------------------------------------------------------------------------------- data Manager diff --git a/Database/EventStore/Internal/Operation/ReadAllEventsOperation.hs b/Database/EventStore/Internal/Operation/ReadAllEventsOperation.hs --- a/Database/EventStore/Internal/Operation/ReadAllEventsOperation.hs +++ b/Database/EventStore/Internal/Operation/ReadAllEventsOperation.hs @@ -63,6 +63,8 @@ } -------------------------------------------------------------------------------- +-- | Enumeration detailing the possible outcomes of reading a slice of $all +-- stream. data ReadAllResult = RA_SUCCESS | RA_NOT_MODIFIED @@ -87,14 +89,22 @@ instance Decode ReadAllEventsCompleted -------------------------------------------------------------------------------- +-- | The result of a read operation from the $all stream. data AllEventsSlice = AllEventsSlice - { allEventsSliceResult :: !ReadAllResult - , allEventsSliceFrom :: !Position - , allEventsSliceNext :: !Position - , allEventsSliceIsEOS :: !Bool - , allEventsSliceEvents :: ![ResolvedEvent] + { allEventsSliceResult :: !ReadAllResult + -- ^ Representing the status of the read attempt. + , allEventsSliceFrom :: !Position + -- ^ Representing the position where the next slice should be read + -- from. + , allEventsSliceNext :: !Position + -- ^ Representing the position where the next slice should be read from. + , allEventsSliceIsEOS :: !Bool + -- ^ Representing whether or not this is the end of the $all stream. + , allEventsSliceEvents :: ![ResolvedEvent] + -- ^ The events read. , allEventsSliceDirection :: !ReadDirection + -- ^ The direction of read request. } deriving Show diff --git a/Database/EventStore/Internal/Operation/ReadEventOperation.hs b/Database/EventStore/Internal/Operation/ReadEventOperation.hs --- a/Database/EventStore/Internal/Operation/ReadEventOperation.hs +++ b/Database/EventStore/Internal/Operation/ReadEventOperation.hs @@ -55,6 +55,7 @@ } -------------------------------------------------------------------------------- +-- | Enumeration representing the status of a single event read operation. data ReadEventResult = RE_SUCCESS | RE_NOT_FOUND @@ -77,11 +78,12 @@ instance Decode ReadEventCompleted -------------------------------------------------------------------------------- +-- | Result of a single event read operation to the EventStore. data ReadResult = ReadResult - { readResultStatus :: !ReadEventResult - , readResultStreamId :: !Text - , readResultEventNumber :: !Int32 + { readResultStatus :: !ReadEventResult -- ^ Attempt status + , readResultStreamId :: !Text -- ^ Stream name + , readResultEventNumber :: !Int32 -- ^ Event number , readResultResolvedEvent :: !(Maybe ResolvedEvent) } deriving Show diff --git a/Database/EventStore/Internal/Operation/ReadStreamEventsOperation.hs b/Database/EventStore/Internal/Operation/ReadStreamEventsOperation.hs --- a/Database/EventStore/Internal/Operation/ReadStreamEventsOperation.hs +++ b/Database/EventStore/Internal/Operation/ReadStreamEventsOperation.hs @@ -61,6 +61,7 @@ instance Encode ReadStreamEvents -------------------------------------------------------------------------------- +-- | Enumeration detailing the possible outcomes of reading a slice of a stream data ReadStreamResult = RS_SUCCESS | RS_NO_STREAM @@ -87,16 +88,26 @@ instance Decode ReadStreamEventsCompleted -------------------------------------------------------------------------------- +-- | Represents the result of a single read operation to the EventStore. data StreamEventsSlice = StreamEventsSlice - { streamEventsSliceResult :: !ReadStreamResult - , streamEventsSliceStreamId :: !Text - , streamEventsSliceStart :: !Int32 - , streamEventsSliceNext :: !Int32 - , streamEventsSliceLast :: !Int32 - , streamEventsSliceIsEOS :: !Bool - , streamEventsSliceEvents :: ![ResolvedEvent] + { streamEventsSliceResult :: !ReadStreamResult + -- ^ Representing the status of the read attempt. + , streamEventsSliceStreamId :: !Text + -- ^ The name of the stream read. + , streamEventsSliceStart :: !Int32 + -- ^ The starting point (represented as a sequence number) of the read + -- operation. + , streamEventsSliceNext :: !Int32 + -- ^ The next event number that can be read. + , streamEventsSliceLast :: !Int32 + -- ^ The last event number in the stream. + , streamEventsSliceIsEOS :: !Bool + -- ^ Representing whether or not this is the end of the stream. + , streamEventsSliceEvents :: ![ResolvedEvent] + -- ^ The events read represented as 'ResolvedEvent' , streamEventsSliceDirection :: !ReadDirection + -- ^ The direction of the read request. } deriving Show diff --git a/Database/EventStore/Internal/Processor.hs b/Database/EventStore/Internal/Processor.hs --- a/Database/EventStore/Internal/Processor.hs +++ b/Database/EventStore/Internal/Processor.hs @@ -16,8 +16,15 @@ ( InternalException(..) , Processor(..) , DropReason(..) - , Subscription(..) , NewSubscriptionCB + , Subscription + , subAwait + , subId + , subStream + , subResolveLinkTos + , subLastCommitPos + , subLastEventNumber + , subUnsubscribe , newProcessor ) where diff --git a/Database/EventStore/Internal/Types.hs b/Database/EventStore/Internal/Types.hs --- a/Database/EventStore/Internal/Types.hs +++ b/Database/EventStore/Internal/Types.hs @@ -54,7 +54,7 @@ | AccessDenied Text -- ^ Stream | InvalidServerResponse Word8 Word8 -- ^ Expected, Found | ProtobufDecodingError String - | ServerError (Maybe Text) + | ServerError (Maybe Text) -- ^ Reason deriving (Show, Typeable) -------------------------------------------------------------------------------- @@ -66,6 +66,8 @@ -------------------------------------------------------------------------------- -- Event -------------------------------------------------------------------------------- +-- | Contains event information like its type and data. Only used for write +-- queries. data Event = Event { eventType :: !Text @@ -73,10 +75,13 @@ } -------------------------------------------------------------------------------- -createEvent :: Text -> EventData -> Event +createEvent :: Text -- ^ Event type + -> EventData -- ^ Event data + -> Event createEvent = Event -------------------------------------------------------------------------------- +-- | Holds event data. data EventData = Json A.Value (Maybe A.Value) @@ -89,10 +94,12 @@ eventMetadataType _ = 0 -------------------------------------------------------------------------------- +-- | Creates a event using JSON format withJson :: A.Value -> EventData withJson value = Json value Nothing -------------------------------------------------------------------------------- +-- | Create a event with metadata using JSON format withJsonAndMetadata :: A.Value -> A.Value -> EventData withJsonAndMetadata value metadata = Json value (Just metadata) @@ -107,10 +114,24 @@ -------------------------------------------------------------------------------- -- Expected Version -------------------------------------------------------------------------------- +-- | Constants used for expected version control. +-- +-- The use of expected version can be a bit tricky especially when discussing +-- idempotency assurances given by the EventStore. +-- +-- The EventStore will assure idempotency for all operations using any value +-- in 'ExpectedVersion' except for 'Any'. When using 'Any' the EventStore will +-- do its best to assure idempotency but will not guarantee idempotency. data ExpectedVersion - = Any -- ^ Says that you should not conflict with anything - | NoStream -- ^ Stream should not exist when doing your write - | EmptyStream -- ^ Stream should exist but be empty when doing the write + = Any + -- ^ This write should not conflict with anything and should always + -- succeed. + | NoStream + -- ^ The stream being written to should not yet exist. If it does exist + -- treat that as a concurrency problem. + | EmptyStream + -- ^ The stream should exist and should be empty. If it does not exist or + -- is not empty, treat that as a concurrency problem. deriving Show -------------------------------------------------------------------------------- @@ -319,38 +340,55 @@ -------------------------------------------------------------------------------- -- Result -------------------------------------------------------------------------------- +-- | A structure referring to a potential logical record position in the +-- EventStore transaction file. data Position = Position - { positionCommit :: !Int64 - , positionPrepare :: !Int64 + { positionCommit :: !Int64 -- ^ Commit position of the record + , positionPrepare :: !Int64 -- ^ Prepare position of the record } deriving Show -------------------------------------------------------------------------------- +-- | Returned after writing to a stream. data WriteResult = WriteResult { writeNextExpectedVersion :: !Int32 - , writePosition :: !Position + -- ^ Next expected version of the stream. + , writePosition :: !Position + -- ^ 'Position' of the write. } deriving Show -------------------------------------------------------------------------------- +-- | Returned after deleting a stream. 'Position' of the write. newtype DeleteResult = DeleteResult { deleteStreamPosition :: Position } deriving Show -------------------------------------------------------------------------------- +-- | Represents a previously written event. data RecordedEvent = RecordedEvent - { recordedEventStreamId :: !Text - , recordedEventId :: !UUID - , recordedEventNumber :: !Int32 - , recordedEventType :: !Text - , recordedEventData :: !ByteString - , recordedEventMetadata :: !(Maybe ByteString) - , recordedEventIsJson :: !Bool - , recordedEventCreated :: !(Maybe UTCTime) + { recordedEventStreamId :: !Text + -- ^ The event stream that this event belongs to. + , recordedEventId :: !UUID + -- ^ Unique identifier representing this event. + , recordedEventNumber :: !Int32 + -- ^ Number of this event in the stream. + , recordedEventType :: !Text + -- ^ Type of this event. + , recordedEventData :: !ByteString + -- ^ Representing the data of this event. + , recordedEventMetadata :: !(Maybe ByteString) + -- ^ Representing the metadada associated with this event. + , recordedEventIsJson :: !Bool + -- ^ Indicates whether the content is internally marked as json. + , recordedEventCreated :: !(Maybe UTCTime) + -- ^ Representing when this event was created in the system. , recordedEventCreatedEpoch :: !(Maybe Integer) + -- ^ Representing the milliseconds since the epoch when the event was + -- created in the system. } deriving Show @@ -378,10 +416,14 @@ } -------------------------------------------------------------------------------- +-- | A structure representing a single event or an resolved link event. data ResolvedEvent = ResolvedEvent { resolvedEventRecord :: !(Maybe RecordedEvent) - , resolvedEventLink :: !(Maybe RecordedEvent) + -- ^ The event, or the resolved link event if this 'ResolvedEvent' is a + -- link event. + , resolvedEventLink :: !(Maybe RecordedEvent) + -- ^ The link event if this 'ResolvedEvent' is a link event. } deriving Show @@ -408,36 +450,52 @@ } -------------------------------------------------------------------------------- +-- | Returns the event that was read or which triggered the subscription. +-- +-- If this 'ResolvedEvent' represents a link event, the link will be the +-- original event, otherwise it will be the event. resolvedEventOriginal :: ResolvedEvent -> Maybe RecordedEvent resolvedEventOriginal (ResolvedEvent record link) = link <|> record -------------------------------------------------------------------------------- +-- | Indicates whether this 'ResolvedEvent' is a resolved link event. eventResolved :: ResolvedEvent -> Bool eventResolved = isJust . resolvedEventOriginal -------------------------------------------------------------------------------- +-- | The stream name of the original event. resolvedEventOriginalStreamId :: ResolvedEvent -> Maybe Text resolvedEventOriginalStreamId = fmap recordedEventStreamId . resolvedEventOriginal -------------------------------------------------------------------------------- +-- | Represents the direction of read operation (both from $all an usual +-- streams). data ReadDirection - = Forward - | Backward + = Forward -- ^ From beginning to end + | Backward -- ^ From end to beginning deriving Show -------------------------------------------------------------------------------- -- Transaction -------------------------------------------------------------------------------- +-- | Represents a multi-request transaction with the EventStore. data Transaction = Transaction - { transactionId :: Int64 - , transactionStreamId :: Text + { transactionId :: Int64 + -- ^ The ID of the transaction. This can be used to recover a + -- transaction later. + , transactionStreamId :: Text + -- ^ The name of the stream. , transactionExpectedVersion :: ExpectedVersion - , transactionCommit :: IO (Async WriteResult) - , transactionSendEvents :: [Event] -> IO (Async ()) - , transactionRollback :: IO () + -- ^ Expected version of the stream. + , transactionCommit :: IO (Async WriteResult) + -- ^ Asynchronously commits this transaction. + , transactionSendEvents :: [Event] -> IO (Async ()) + -- ^ Asynchronously writes to a transaction in the EventStore. + , transactionRollback :: IO () + -- ^ Rollback this transaction. } -------------------------------------------------------------------------------- @@ -456,6 +514,7 @@ -------------------------------------------------------------------------------- -- Credentials -------------------------------------------------------------------------------- +-- | Holds login and password information. data Credentials = Credentials { credLogin :: !ByteString @@ -464,7 +523,9 @@ deriving Show -------------------------------------------------------------------------------- -credentials :: ByteString -> ByteString -> Credentials +credentials :: ByteString -- ^ Login + -> ByteString -- ^ Password + -> Credentials credentials = Credentials -------------------------------------------------------------------------------- @@ -482,7 +543,7 @@ -------------------------------------------------------------------------------- -- Settings -------------------------------------------------------------------------------- --- | Global @ConnectionManager@ settings +-- | Global 'Connection' settings data Settings = Settings { s_heartbeatInterval :: NominalDiffTime @@ -493,6 +554,7 @@ } -------------------------------------------------------------------------------- +-- | Default global settings. defaultSettings :: Settings defaultSettings = Settings { s_heartbeatInterval = msDiffTime 750 -- 750ms diff --git a/eventstore.cabal b/eventstore.cabal --- a/eventstore.cabal +++ b/eventstore.cabal @@ -10,7 +10,7 @@ -- PVP summary: +-+------- breaking API changes -- | | +----- non-breaking API additions -- | | | +--- code changes with no API change -version: 0.3.1.0 +version: 0.4.0.0 -- A short (one-line) description of the package. synopsis: EventStore Haskell TCP Client