catsnake v2.0.0
What is CatSnake?
CatSnake is a package built on top of WebSockets to allow for a publish & subscribe style messaging for quickly building fast realtime applications. Catsnake also utilizes MessagePack so package sizes are very small making Catsnake very fast.
Docs
For detailed documentation visit this link.
Quickstart Guide
Install
For quick use you can simply include catsnke in your <head>.
<script type="text/javascript" src="https://cdn.jsdelivr.net/catsnake/0.2.5/catsnake.js"></script>For installation with npm just install with
npm i --save pubsuband then require it
const PubSub = require('pubsub');Now connect to the PubSub server. See pubsub-server to run your own server, Otherwise you can use the example below to use our free server. (note that channel names may already be reserved, so be creative!)
const cs = new PubSub('ws://catsnake.io:3081', {
commonName: 'A Random Catsnake'
});
// It is best practice to wrap the rest of your Catsnake code in the on method.
// this ensures that you're connected to the websocket server before executing.
cs.on(() => {
// Your code here.
});Methods
Subscribe
Before you can start sending messages, you should subscribe to a channel (but you don't have to). Don't worry, it's super easy.
cs.subscribe('General', data => console.log(data));Publish
Now that you've subscibed to a channel, let's publish a message to all of the other subscribers, and ourselves ofcourse.
cs.publish('General', {
message: 'Ahh! Your dog is attacking me! What is it with mail men and dogs anyways?'
}).then(msg => { console.log('Yay, the server got our message.') });History
Wanna fetch some history? Easy.
cs.history('General', limit);History will be sent back in the subscribe method with the metadata.type of 'history'.
Info
Nice, now let's get info from the channel, this will return information like connected clients, author, etc.
cs.info('General');Access Control
Catsnake gives you multiple options for access control to a channel.
Denying a client access to a channel protected by access control is easy
cs.deny('General', 'client-123215', 'secretKey');Granting a client access to a channel protected by access control is just as simple.
cs.grant('General', 'client-123215', 'secretKey');Unsubscribe
Before exiting your application you should unsubscribe from the channel. This will leave your client in an offline state but
you can later reconnect with the same client id via the new Catsnake method, we will go over this more in the advanced
features below.
cs.unsubscribe('General');Private Servers
In the event that you are trying to access a private server, after connecting to the server be sure to authenticate with the correct secret.
Catsnake also provides chaining for most methods, so you can prepend authenticate to the beginning of your subscribe function to keep things clean!
cs.authenticate('mostSecureSecretEver');Contributing
For catsnake to keep up to date, and become the best tool it can be; we need contributors like you! We know trying to add your own work might be scary, what will people say? Is my code quality good enough? What if I look dumb? It's fine! Just go ahead and submit your work, worst case we'll tidy things up a bit; I'm positive we can benifit from seeing your ideas.
See the Contributing.md over here for a full list of instructions.