brillout / brillout/wildcard-api

Real-time/bi-directional communication (Wildcard callbacks)

Open
#61 0 comments 0 reactions 0 assignees View on GitHub
enhancement vision
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 += `

${text}
`;
}
~~~

~~~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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.