Merge pull request #67 from diogob/metadata-channel

Add a configuration option to open a channel for metadata

Author: diogob

CHANGELOG.md

@@ -1,9 +1,15 @@
 # CHANGELOG
 
+## 0.10.0.0
+
+- Add `PGWS_META_CHANNEL` to configure optional metadata channel to send events from the server. Initially the oply event is `ConnectionOpen`.
+- Add property `event` to message JSON. Two possible values so far: `ConnectionOpen` and `WebsocketMessage`.
+- Breaking change: the property `channel` is not appended to claims anymore. If `channel` is in the original token claims it will still be present.
+
 ## 0.9.0.0
 
 - Add @filename semantics to PGWS_DB_URI configiration variable to allow secret management to use a file instead of an environment variable.
-- Add PGWS_RETRIES to limit the amount of times the server tries to open a database connection upon startup (defaults to 5). This breaks backward compatibility if you rely on the behaviour of the server to try infitite times.
+- Add `PGWS_RETRIES` to limit the amount of times the server tries to open a database connection upon startup (defaults to 5). This breaks backward compatibility if you rely on the behaviour of the server to try infitite times.
 
 ## 0.8.0.1
 

README.md

@@ -90,9 +90,10 @@ To use a secure socket (`wss://`) you will need a proxy server like nginx to han
 Every message received from the browser will be in JSON format as:
 ```javascript
 {
-  "claims": { "message_delivered_at": 0.0, "a_custom_claim_from_the_jwt": "your_custom_value" },
+  "event": "WebsocketMessage",
   "channel": "destination_channel",
-  "payload": "message content"
+  "payload": "message content",
+  "claims": { "message_delivered_at": 0.0, "a_custom_claim_from_the_jwt": "your_custom_value" }
 }
 ```
 
@@ -109,8 +110,19 @@ To send a message to a particular channel on the browser one should notify the p
 ```sql
 SELECT pg_notify(
   'postgres-websockets-listener',
-  json_build_object('channel', 'chat', 'payload', 'test')::text
+  json_build_object('event', 'WebsocketMessage', 'channel', 'chat', 'payload', 'test')::text
 );
 ```
 
 Where `postgres-websockets-listener` is the database channel used by your instance of postgres-websockets and `chat` is the channel where the browser is connected (the same issued in the JWT used to connect).
+
+## Monitoring Connections
+
+To monitor connection opening one should set the variable `PGWS_META_CHANNEL` which will enable the meta-data messages generation in the server on the channel name specified.
+For instamce, if we use the configuration in the [sample-env](./sample-env) we will see messages like the one bellow each time a connection is estabilished (only after the JWT is validated).
+
+```javascript
+{"event":"ConnectionOpen","channel":"server-info","payload":"server-info","claims":{"mode":"rw","message_delivered_at":1.602719440727465893e9}}
+```
+
+You can monitor these messages on another websocket connection with a proper read token for the channel `server-info` or also having an additional database listener on the `PGWS_LISTEN_CHANNEL`.

client-example/client.js

@@ -64,7 +64,7 @@ function jwt() {
 }
 
 $(document).ready(function () {
-    var ws = null;
+    var ws = null, meta = null;
 
     $('#channel').keyup(updateJWT);
     updateJWT();
@@ -74,6 +74,10 @@ $(document).ready(function () {
         if(ws === null){
             var jwt = $('#jwt').val();
             var channel = $('#channel').val();
+
+            meta = createWebSocket('/server-info/' + jwt);
+            meta.onmessage = onMessage('#meta-messages');
+
             if(channel == ""){
               ws = createWebSocket('/' + jwt);
             } else {

client-example/index.html

@@ -34,6 +34,9 @@ <h2>Chat</h2>
                 <h2>Messages sent to chat channel</h2>
                 <div id="messages">
                 </div>
+                <h2>Messages sent to meta channel</h2>
+                <div id="meta-messages">
+                </div>
             </div>
         </div>
     </body>

postgres-websockets.cabal

@@ -1,5 +1,5 @@
 name:                postgres-websockets
-version:             0.9.0.0
+version:             0.10.0.0
 synopsis:            Middleware to map LISTEN/NOTIFY messages to Websockets
 description:         Please see README.md
 homepage:            https://github.com/diogob/postgres-websockets#readme
@@ -25,6 +25,7 @@ library
   other-modules:       Paths_postgres_websockets
                      , PostgresWebsockets.Server
                      , PostgresWebsockets.Middleware
+                     , PostgresWebsockets.Context
   build-depends:       base >= 4.7 && < 5
                      , hasql-pool >= 0.5 && < 0.6
                      , text >= 1.2 && < 1.3

sample-env

@@ -10,6 +10,9 @@ export PGWS_ROOT_PATH="./client-example"
 ## Sends a copy of every message received from websocket clients to the channel specified bellow as an aditional NOTIFY command.
 export PGWS_LISTEN_CHANNEL="postgres-websockets-listener"
 
+## Send postgres-websockets server events to this channel (will be sent both to the database and the connected websocket clients)
+export PGWS_META_CHANNEL="server-info"
+
 ## Host and port on which the websockets server (and the static files server) will be listening.
 export PGWS_HOST="*4"
 export PGWS_PORT=3000

src/PostgresWebsockets.hs

@@ -11,6 +11,6 @@ module PostgresWebsockets
   , postgresWsMiddleware
   ) where
 
-import           PostgresWebsockets.Middleware
-import           PostgresWebsockets.Server
-import           PostgresWebsockets.Config
+import PostgresWebsockets.Middleware ( postgresWsMiddleware )
+import PostgresWebsockets.Server ( serve )
+import PostgresWebsockets.Config ( prettyVersion, loadConfig )

src/PostgresWebsockets/Claims.hs

@@ -11,15 +11,16 @@ module PostgresWebsockets.Claims
   ( ConnectionInfo,validateClaims
   ) where
 
-import           Control.Lens
-import qualified Crypto.JOSE.Types   as JOSE.Types
-import           Crypto.JWT
-import qualified Data.HashMap.Strict as M
-import           Protolude
+import Protolude
+import Control.Lens
+import Crypto.JWT
 import Data.List
 import Data.Time.Clock (UTCTime)
+import qualified Crypto.JOSE.Types as JOSE.Types
+import qualified Data.HashMap.Strict as M
 import qualified Data.Aeson as JSON
 
+
 type Claims = M.HashMap Text JSON.Value
 type ConnectionInfo = ([ByteString], ByteString, Claims)
 

src/PostgresWebsockets/Config.hs

@@ -31,6 +31,7 @@ data AppConfig = AppConfig {
   , configHost              :: Text
   , configPort              :: Int
   , configListenChannel     :: Text
+  , configMetaChannel       :: Maybe Text
   , configJwtSecret         :: ByteString
   , configJwtSecretIsBase64 :: Bool
   , configPool              :: Int
@@ -68,6 +69,7 @@ readOptions =
                 <*> var str "PGWS_HOST" (def "*4" <> helpDef show <> help "Address the server will listen for websocket connections")
                 <*> var auto "PGWS_PORT" (def 3000 <> helpDef show <> help "Port the server will listen for websocket connections")
                 <*> var str "PGWS_LISTEN_CHANNEL" (def "postgres-websockets-listener" <> helpDef show <> help "Master channel used in the database to send or read messages in any notification channel")
+                <*> optional (var str "PGWS_META_CHANNEL" (help "Websockets channel used to send events about the server state changes."))
                 <*> var str "PGWS_JWT_SECRET" (help "Secret used to sign JWT tokens used to open communications channels")
                 <*> var auto "PGWS_JWT_SECRET_BASE64" (def False <> helpDef show <> help "Indicate whether the JWT secret should be decoded from a base64 encoded string")
                 <*> var auto "PGWS_POOL_SIZE" (def 10 <> helpDef show <> help "How many connection to the database should be used by the connection pool")

src/PostgresWebsockets/Context.hs

@@ -0,0 +1,39 @@
+{-|
+Module      : PostgresWebsockets.Context
+Description : Produce a context capable of running postgres-websockets sessions
+-}
+module PostgresWebsockets.Context
+        ( Context (..)
+        , mkContext
+        ) where
+
+import Protolude
+import Data.Time.Clock (UTCTime, getCurrentTime)
+import Control.AutoUpdate       ( defaultUpdateSettings
+                                , mkAutoUpdate
+                                , updateAction
+                                )
+import qualified Hasql.Pool as P
+
+import PostgresWebsockets.Config ( AppConfig(..) )
+import PostgresWebsockets.HasqlBroadcast (newHasqlBroadcaster)
+import PostgresWebsockets.Broadcast (Multiplexer)
+
+data Context = Context {
+    ctxConfig :: AppConfig
+  , ctxPool :: P.Pool
+  , ctxMulti :: Multiplexer
+  , ctxGetTime :: IO UTCTime
+  }
+
+-- | Given a configuration and a shutdown action (performed when the Multiplexer's listen connection dies) produces the context necessary to run sessions
+mkContext :: AppConfig -> IO () -> IO Context
+mkContext conf@AppConfig{..} shutdown = do
+  Context conf
+    <$> P.acquire (configPool, 10, pgSettings)
+    <*> newHasqlBroadcaster shutdown (toS configListenChannel) configRetries pgSettings
+    <*> mkGetTime
+  where
+    mkGetTime :: IO (IO UTCTime)
+    mkGetTime = mkAutoUpdate defaultUpdateSettings {updateAction = getCurrentTime}
+    pgSettings = toS configDatabase