brillout / brillout/wildcard-api
Real-time/bi-directional communication (Wildcard callbacks)
- Dominant language
- JavaScript
- Stars
- 368
- Forks
- 14
- PR merge metrics
- No merged PRs in 30d
Description
The idea is to allow the client to pass a callback to the server:
~~~js
// Browser-side
// We define a callback which will be called by the server!
function callback(event) {
console.log('Message from the server: '+event.message);
}
// We pass `callback` to the server.
server.subscribeEvents(callback);
~~~
~~~js
// Server-side
server.subscribeEvents = async function(callback) {
callback({message: 'Hello!'});
await sleep({seconds: 3});
callback({message: 'This is another message from the server.'});
};
~~~
This enables all kinds of bi-directional communications, for example real-time chat, real-time gaming, live subscriptions, etc.
Proposed name: Wildcard callbacks.
The lifecycle can be managed thanks to two `_onClose` functions provided by Wildcard, as described in the following example.
## Example - Live chat
~~~js
// Browser-side
import { server } from '@wildcard-api/client';
main();
async function joinChat(roomId) {
const { leave } = await server.joinChatRoom(
roomId,
// Our client-side defined `onNewMessage` is called by the server.
onNewMessage,
);
print(`Joined chat room ${roomId}.`);
// Leave chat room after 30 seconds
setTimeout(
() => {
leave();
print(`Left chat room ${roomId}.`);
},
30*1000
);
}
server._onClose = function() {
// Browser is offline, or server is down.
// All callbacks are now closed.
print('Lost connection to server');
}
async function main() {
const roomId = 123;
await joinChat(roomId);
};
async function onNewMessage(message) {
print(message);
}
function print(text) {
// (One should never do this; prone to JS injection.)
document.body.innerHTML += `
}
~~~
~~~js
// Server-side
import { server } from '@wildcard-api/server';
const chatRooms = require('./path/to/chatRooms');
server.joinChatRoom = async function(roomId, onNewMessage) {
const removeListener = chatRooms[roomId].addListener(message => {
onNewMessage(message);
});
function leave() {
removeListener();
}
this._onClose = function() {
// The connection to the client is lost
// - The user closed his browser, or
// - There is a network connection problem
leave();
};
// We return `leave` to the client so that
// the frontend can leave the chat room.
return { leave };
};
~~~
Contributor guide
No contributing guide indexed for this repository
Research direction
The issue provides browser-side and server-side JavaScript examples for subscribeEvents, joinChatRoom, returned leave functions, and _onClose handlers. Start by tracing the existing client/server connection and callback entry points; completion would require bi-directional callbacks with cleanup when leaving or when the connection closes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- api, backend, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100