diff --git a/app/Main.hs b/app/Main.hs --- a/app/Main.hs +++ b/app/Main.hs @@ -2,7 +2,6 @@ import Protolude import PostgRESTWS -import PostgRESTWS.HasqlBroadcast import Config (AppConfig (..), PgVersion (..), minimumPgVersion, diff --git a/postgrest-ws.cabal b/postgrest-ws.cabal --- a/postgrest-ws.cabal +++ b/postgrest-ws.cabal @@ -1,5 +1,5 @@ name: postgrest-ws -version: 0.3.0.0 +version: 0.3.1.0 synopsis: PostgREST extension to map LISTEN/NOTIFY messages to Websockets description: Please see README.md homepage: https://github.com/diogob/postgrest-ws#readme diff --git a/src/PostgRESTWS.hs b/src/PostgRESTWS.hs --- a/src/PostgRESTWS.hs +++ b/src/PostgRESTWS.hs @@ -1,13 +1,12 @@ -{-| -Module : PostgRESTWS -Description : PostgRESTWS Middleware, composing this allows postgrest to create -websockets connections that will communicate with the database through LISTEN/NOTIFY channels. - +{-| PostgRESTWS Middleware, composing this allows postgrest to create + websockets connections that will communicate with the database through LISTEN/NOTIFY channels. -} {-# LANGUAGE DeriveGeneric #-} module PostgRESTWS ( postgrestWsMiddleware + -- * Re-exports + , newHasqlBroadcasterOrError ) where import Protolude @@ -26,6 +25,7 @@ import PostgRESTWS.Claims import PostgRESTWS.Database import PostgRESTWS.Broadcast (Multiplexer, onMessage, readTChan) +import PostgRESTWS.HasqlBroadcast (newHasqlBroadcasterOrError) import qualified PostgRESTWS.Broadcast as B data Message = Message @@ -35,13 +35,15 @@ instance A.ToJSON Message --- | Given a Maybe Secret, a function to fetch the system time, a Hasql Pool and a Multiplexer this will give you a WAI middleware. +-- | Given a secret, a function to fetch the system time, a Hasql Pool and a Multiplexer this will give you a WAI middleware. postgrestWsMiddleware :: ByteString -> IO POSIXTime -> H.Pool -> Multiplexer -> Wai.Application -> Wai.Application postgrestWsMiddleware = WS.websocketsOr WS.defaultConnectionOptions `compose` wsApp where compose = (.) . (.) . (.) . (.) +-- private functions + -- when the websocket is closed a ConnectionClosed Exception is triggered -- this kills all children and frees resources for us wsApp :: ByteString -> IO POSIXTime -> H.Pool -> Multiplexer -> WS.ServerApp @@ -69,8 +71,6 @@ then forkAndWait $ forever $ notifySession channel validClaims pqCon conn else newMVar () takeMVar notifySessionFinished - --- private functions -- Having both channel and claims as parameters seem redundant -- But it allows the function to ignore the claims structure and the source diff --git a/src/PostgRESTWS/Broadcast.hs b/src/PostgRESTWS/Broadcast.hs --- a/src/PostgRESTWS/Broadcast.hs +++ b/src/PostgRESTWS/Broadcast.hs @@ -1,12 +1,9 @@ -{-| -Module : PostgRESTWS.Broadcast -Description : PostgRESTWS functions to broadcast messages to several listening clients - -This module provides a type called Multiplexer. -The multiplexer contains a map of channels and a producer thread. +{-| PostgRESTWS functions to broadcast messages to several listening clients + This module provides a type called Multiplexer. + The multiplexer contains a map of channels and a producer thread. -This module avoids any database implementation details, it is used by HasqlBroadcast where -the database logic is combined. + This module avoids any database implementation details, it is used by HasqlBroadcast where + the database logic is combined. -} module PostgRESTWS.Broadcast ( Multiplexer (src) , Message (..) diff --git a/src/PostgRESTWS/Claims.hs b/src/PostgRESTWS/Claims.hs --- a/src/PostgRESTWS/Claims.hs +++ b/src/PostgRESTWS/Claims.hs @@ -1,3 +1,8 @@ +{-| This module provides the JWT claims validation. Since websockets and + listening connections in the database tend to be resource intensive + (not to mention stateful) we need claims authorizing a specific channel and + mode of operation. +-} module PostgRESTWS.Claims ( validateClaims ) where @@ -17,6 +22,9 @@ type Claims = M.HashMap Text Value type ConnectionInfo = (ByteString, ByteString, Claims) +{-| Given a secret, a token and a timestamp it validates the claims and returns + either an error message or a triple containing channel, mode and claims hashmap. +-} validateClaims :: ByteString -> Text -> POSIXTime -> Either Text ConnectionInfo validateClaims secret jwtToken time = do cl <- case jwtClaims jwtSecret jwtToken time of diff --git a/src/PostgRESTWS/Database.hs b/src/PostgRESTWS/Database.hs --- a/src/PostgRESTWS/Database.hs +++ b/src/PostgRESTWS/Database.hs @@ -1,7 +1,4 @@ -{-| -Module : PostgRESTWS.Database -Description : This module encapsulates knowledge about the SQL commands and the Hasql interface. - +{-| This module encapsulates knowledge about the SQL commands and the Hasql interface. -} module PostgRESTWS.Database ( notifyPool diff --git a/src/PostgRESTWS/HasqlBroadcast.hs b/src/PostgRESTWS/HasqlBroadcast.hs --- a/src/PostgRESTWS/HasqlBroadcast.hs +++ b/src/PostgRESTWS/HasqlBroadcast.hs @@ -1,10 +1,6 @@ -{-| -Module : PostgRESTWS.HasqlBroadcast -Description : Uses Broadcast module adding database as a source producer. - -This module provides a function to produce a 'Multiplexer' from a Hasql 'Connection'. -The producer issues a LISTEN command upon Open commands and UNLISTEN upon Close. - +{-| Uses Broadcast module adding database as a source producer. + This module provides a function to produce a 'Multiplexer' from a Hasql 'Connection'. + The producer issues a LISTEN command upon Open commands and UNLISTEN upon Close. -} module PostgRESTWS.HasqlBroadcast ( newHasqlBroadcaster @@ -26,7 +22,7 @@ {- | Returns a multiplexer from a connection URI or an error message on the left case This function also spawns a thread that keeps relaying the messages from the database to the multiplexer's listeners -} - + newHasqlBroadcasterOrError :: ByteString -> IO (Either ByteString Multiplexer) newHasqlBroadcasterOrError = acquire >=> (sequence . mapBoth show newHasqlBroadcaster)