Dropper is a custom Event-driven WebSocket framework for Deno, using the deno-std ws module as base.
Send and receive notifications, messages, updates and any data, all in real-time with custom events and methods served on your own, Dropper is Open Source, self-served and FREE forever!
Since Dropper is a WebSocket solution for delivering messages between servers and clients in real-time, it’s Side by Side APIs are designed to handle custom events sent by the application peers, you can work with the structured event handlers that allows to send and receive classified data in a woshhh.
Server:
import { Server } from 'https://deno.land/x/dropper@1.8.0/src/mod.ts';
//or
import { Server } from 'https://x.nest.land/dropper@1.8.0/src/mod.ts'
Deno client:
You can import the client directly on your Deno app.
import Dropper from 'https://deno.land/x/dropper@1.8.0/src/mod.ts';
//or
import Dropper from 'https://x.nest.land/dropper@1.8.0/src/mod.ts'
Browser client
You can import this client on the browser in a module script.
import Dropper from 'https://deno.land/x/dropper@1.8.0/dist/clients/dropper.browser.js';
//or
import Dropper from 'https://x.nest.land/dropper@1.8.0/dist/clients/dropper.browser.js'
By default, it exports two instances of WebSocket. The API is very similar to the websockets API for browsers, but based on custom events.
The server waits for socket connections using the global event connection
. This event gets the new connected socket on its callback. This socket represents a client so the API is the same as in the client side.
Dropper is stand alone by default, which means tha you don’t need to provide an http server, when you create a dropper it serves by default on port 8080.
This is useful whe you are creating an app without a server side.
const options;
const dropper = new Server(options); // Creates a default server on port 8080
dropper.on('connection', socket => { // W
socket.send('pizza', 'I sent you a pizza!')
socket.on('thanks', data => {
console.log(data) // => Thanks btw
})
})
// Listening for global events
dropper.on('thanks', data => {
console.log(data) // => Thanks btw
})
You can also use Dropper with a server/framework setup since it handles each request separately with the method Dropper.handle(req)
import { opine } from 'https://opinesource/mod.ts'
const app = opine();
import { Server as Dropper } from '...'
const dropper = new Dropper({
serve: false // Important
})
app.use('/dropper' (req) => dropper.handle(req)); // Don't respond or call next, just use the request.
app.get('/', (req, res) => {
//...foo
})
dropper.on('connection', socket => {
..foo
})
app.listen(3000)
import { serve } from 'https://serverhttpsouce/mod.ts'
import { Server as Dropper } from '...'
const server = serve('localhost:3000')
const dropper = new Dropper({
serve: false // Important
})
dropper.on('connection', socket => {
..foo
})
for await (const req of server) {
if (req.url === '/dropper') {
dropper.handle(req);
} else {
// return static content, etc
}
}
Please note that we use the
/dropper
endpoint on both of the examples. This is because we don’t want to touch any usable endpoint, you can use whatever you want as endpoint, but you have to provide it in the Dropper client config object which is by default/dropper
.
host
: The host you want to use if the serve is true.
port
: The host you want to use if the serve is true
interval
: The ping interval in ms.
serve
: Set false if you don’t want to serve Dropper (stand alone)
Methods:
Dropper.on
- Listen for the server events.
The on
method receives two arguments:
event
- The event namecallback
- Callback function to get the new connected socket instance if the event is connection
or the event data if the event is any
.Dropper.send
- Send global data to all connected sockets
The send
method receive two arguments.
event
| data
- This argument changes to data if the data argument is not provided, by default it is the event name.data
(optional) - This is the data to be sent.Dropper.handle
- Handles the request to accept WebSockets
The handle
method receive one arguments.
request
- This is a deno std http request object of the type ServerRequest
.Properties:
Dropper.clients
- List of all connected clients instances.You can send data to clients in three ways:
dropper.on('connection', socket => {
socket.send('hello')
})
No one will receive this data except the current socket.
dropper.on('connection', socket => {
socket.broadcast('hello')
})
All clients will receive the data except the current client.
dropper.send('hello')
All clients will receive the data .
The event name for listening to all events is _all_
dropper.on('connection', socket => {
socket.on('_all_', data => { // Listen for all events from this socket
})
})
// or globally
dropper.on('_all_', ...foo)
...
socket.on('custom_event', ...foo) // Catch event just from the socket
...
dropper.on('custom_event', ...foo) // Catch event from all sockets
If the client send a no named event (client_side_dropper.send('no named')
), you can listen to it with the event name message
...
socket.on('message', ...foo) // Catch no named event just from the socket
...
dropper.on('message', ...foo) // Catch no named event from all sockets
You can handle disconnections on two scopes:
From socket:
Handling disconnects from sockets only works if the socket is manually disconnected. It will not work if the client loses connection. The callback receives the same two arguments as in the client API (bellow).
dropper.on('connection', socket => {
socket.on('close', (code, reason) => {
//...foo
})
})
From global
Handling global disconnects will listen to all clients that disconnect manually and also those that lose connection. The callback receives the same two arguments as in the client API (bellow) plus the disconnected socket as in the connection event.
dropper.on('disconnection', (code, reason, socket) => {
//...foo
})
This is a list with the events you shouldn’t play with:
connection
- The connection event sending is reserved for handling peer connection on server.error
- The error event sending is reserved for handling connection issues.disconnection
- The disconnection event sending is reserved for handling peer disconnection on server.The client API connects to a server and it is a socket instance, so it has the same methods as the socket
above.
const dropper = new Dropper(); // Connect the client on port 8080
dropper.on('pizza', function(data){
console.log(data) // => I sent you a pizza!
dropper.send('thanks', 'Thanks btw');
dropper.close() // Closes the connection manually
});
dropper.on('close' => console.log('done'))
endpoint
- This is the endpoint that the server uses to handle wbsockets.
/dropper
Methods:
close
- Closes the connection.
The close
method receives two optional arguments:
code
- Connection close code numberreason
- A reason message for the close event.broadcast
- Send the data to the server to be broadcasted to all peers but this (Meant to be used on server-side).
The broadcast
method receive two arguments.
event
| data
- This argument changes to data if the data argument is not provided, by default it is the event name.data
(optional) - This is the data to be sent.on
- Listen for the client events.
The on
method receives two arguments:
event
- The event namecallback
- Callback function to get the event data.send
- Send the data to the server.
The send
method receive same arguments as the broadcast
method.
Properties:
Dropper.uuid
- The id of the client.Dropper._socket
- This is the WebSocket instance itself.Dropper.uri
- The WebSockets connection uri.This is pushing a custom event to the server
dropper.send('pizza', 'this is a pizza')
This is pushing a no named event to the server
dropper.send('this is a pizza')
This is listening a custom event from the server
dropper.on('pizza', data => {
...foo
})
This is listening a no named event from the server
dropper.on('message', data => {
...foo
})
To handle the socket disconnection you can use the close
event. It only listen when the sockets disconnects itself.
dropper.on('close', (code, reason) => {
...foo
})
When a peer disconnects the server trigger the disconnection
event that is useful for listening when other peers leave. It provides de uuid of the leaving socket.
dropper.on('disconnection', uuid => {
...foo
})
This is a list with the events you shouldn’t play with:
_binary_
- The binary event sending is reserved for handling Uint8Array data.error
- The error event sending is reserved for handling connection issues._all_
- The message event is the global event for listening to data._ping_
- The ping event is a websockets connection handler._pong_
- The pong event is a websockets connection handler._broadcast_
- The broadcast event is an internal event for transport data to all users but the current one.All the Dropper internal events has as prefix and suffix _
. For example this is an internal event: _ping_
, This is for preventing event collisions.
By now, you can find detailed code in the examples folder.
message
event to _all_
Author: denyncrawford
Source Code: https://github.com/denyncrawford/dropper-deno
#deno #nodejs #node