SocketPlugin establishes a common authentication scheme for @fantaptik/Socket.
See the Getting Started tutorial for example usage.
Redux
SocketPlugin subscribes to changes in the Redux store.
See ReducerState's documentation for details on when a session is authenticated versus a guest.
Authentication
When the Redux store is authenticated the socket's connect() method is automatically called.
The onconnect() handler verifies the store's session values with the server -- if this step fails
the store is returned to guest mode.
Guest
Calling SocketPlugin's logout() method sends a message to the server to end the session. If successful the store
is returned to guest mode.
Whenever the store changes from authenticated to guest the Socket's stop() method is called to prevent
the Socket from continuously trying to connect to the server when authentication is guaranteed to fail.
Automatic Session End
SocketPlugin's ondata() handler inspects incoming messages for an appropriate session-end
message. When received the store is returned to guest mode.
Use this feature to cleanly stop instances of Socket in connected clients when:
- A single session is ended by calling
logout() as described above; i.e. one browser tab
calls logout(), the server notifies all other Sockets using the same session, and other browser
tabs will enter guest mode.
- When the server is shutting down and session data will not be remembered when it starts again.
React
SocketPlugin's React property is a shortcut to the associated Gob.React property and provided
for convenience.
Multiple Sockets
Multiple instances of Socket can use the same store however each Socket needs its own
instance of SocketPlugin.
Since SocketPlugin calls connect() and stop() on the Socket instance reactively to changes in the store
it is sufficient to call logout() on a single SocketPlugin instance to stop all Sockets. Similarly setting
the store to authenticated is sufficient to connect and authenticate all Sockets as well.
Multiple Servers
The common use case is for an application to connect and authenticate to a single server. The types exported
by this package are ideal for this case.
Authenticating with multiple servers is possible with the use of Gobs. See the Understanding Gobs tutorial
for details.