Real-time API
The Codehooks.io real-time API enables applications and clients to publish and subscribe to data events.
API quick overview
State diagram
The following diagram shows the necessary dataflow between a client and a server.
realtime.createChannel(channel)
Create a real-time channel for clients listeners and and server publishers.
Parameters
- channel: string - e.g. '/goals'
Returns: void.
Code example for creating a channel
index.js
import {app, realtime} from 'codehooks-js';
// create a real-time channel
realtime.createChannel('/goals');
/* more code here ... */
// bind to serverless runtime
export default app.init();
realtime.publishEvent(channel,data, [query])
Publish a data event on a channel to all or some (query) listeners.
Parameters
- channel: string - e.g. '/goals'
- data: object - Event object to publish
- query: object - optional matching criteria for listeners to get the event
Returns: Promise: object
Code example for publish events
index.js
import {app, realtime} from 'codehooks-js';
// create a real-time channel
realtime.createChannel('/goals');
// broadcast event
async function someFunction() {
const listeners = {topic: "score"}; // send to all listeners subscribing to topic
const event = {"team A": 0, "team B": 1, "player": "Messi"};
const data = await realtime.publishEvent('/goals', event, listeners);
}
/* more logic here ...*/
// bind to serverless runtime
export default app.init();
realtime.createListener(channel, data)
Create a new listener (ID) that clients can use to subscribe to an EventSource channel.
Parameters
- channel: string - Channel name, e.g. '/goals'
- data: object - Listener topics of interest, e.g.
{topic: "score"}
Returns: Promise: listenerData with a unique _id
Code example for creating a new listener
index.js
import {app, realtime} from 'codehooks-js';
// create a real-time channel
realtime.createChannel('/clock');
// client rest api to connect to the real time channel
app.post('/connect', async (req, res) => {
const listenerData = await realtime.createListener('/clock', req.body)
// return listener ID to client
res.json({listenerID: listenerData._id})
})
app.job('* * * * *', async (req, res) => {
const listeners = {topic: "tick"}; // send to all listeners subscribing to topic
const event = {"The time is": new Date()};
const data = await realtime.publishEvent('/clock', event, listeners);
})
// bind to serverless runtime
export default app.init();
realtime.getListener(channel, listenerID)
Get a listener object for a specific listener (ID) on a channel.
Parameters
- channel: string - Channel name, e.g. '/goals'
- listenerID: string - A valid _id for an existing listener
Returns: Promise: listenerData
realtime.getListeners(channel)
Get all listeners on a channel (channel).
Parameters
- channel: string - Channel name, e.g. '/goals'
Returns: Promise: array of listenerData
realtime.removeListener(channel, listenerID)
Remove a listener (listenerID) from a channel (channel).
Parameters
- channel: string - Channel name, e.g. '/goals'
- listenerID: string - A valid _id for an existing listener
Returns: Promise: listenerData
Complete code example - Real-time chat
To better understand how the Codehooks.io real-time API works, check out the following code example. The complete source code, including install instructions, is avaliable at Github.
The code example is a simple web (plain vanilla ugly HTML) chat app for POST'ing messages to a REST API endpoint. The messages are then received on the client in real-time from the server. The server (Codehooks.io) uses the real-time API to subscribe and publish data to/from client requests.
You can test out a live example here
HTML client page
/public/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Codehooks.io - Chat App</title>
<link rel="stylesheet" href="styles.css">
<script src="https://unpkg.com/[email protected]/src/eventsource.js"></script>
</head>
<body>
<h1>Codehooks.io - Chat example</h1>
<div id="chat">
<label for="aliasInput">Chat Alias:</label>
<input type="text" id="aliasInput" placeholder="Enter your alias...">
<div id="status">Real-time status: <span id="statusIndicator" style="color: red;">Initializing</span></div>
<div id="messages" style="height: 150px; overflow: auto; border: 1px solid #ccc; margin-bottom: 10px;"></div>
<div id="inputContainer" style="display: flex; width: 100%;">
<input type="text" id="messageInput" placeholder="Type a message..."
style="flex-grow: 1; margin-right: 10px;">
<button id="sendButton">Send</button>
</div>
</div>
<script src="chat.js"></script>
</body>
</html>
HTML client JavaScript
/public/chat.js
const API_TOKEN = '0a2249d4-5f10-489c-8229-1f060ad1e0f6';
let listenerID = null;
document.addEventListener('DOMContentLoaded', function() {
const aliasInput = document.getElementById('aliasInput');
const messageInput = document.getElementById('messageInput');
const sendButton = document.getElementById('sendButton');
// Function to send a message to the server
function sendMessage(message) {
fetch('/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-apikey': API_TOKEN
},
body: JSON.stringify({ message: message, listenerID, alias: aliasInput.value.trim() }),
})
.then(response => response.json())
.then(data => {
console.log('Message sent:', data);
messageInput.value = ''; // Clear input after sending
messageInput.focus(); // Keep focus on input field
})
.catch((error) => {
console.error('Error:', error);
});
}
sendButton.addEventListener('click', function() {
if (messageInput.value) {
sendMessage(messageInput.value);
}
});
messageInput.addEventListener('keydown', function(event) {
// Check if Enter key is pressed without Shift key
if (event.key === 'Enter' && !event.shiftKey) {
event.preventDefault(); // Prevent default to avoid line breaks or form submission
if (messageInput.value) {
sendMessage(messageInput.value);
}
}
});
// init real-time connection
startListener();
});
function addMessage(message) {
const messagesDiv = document.getElementById('messages');
const messageElement = document.createElement('div');
messageElement.textContent = message;
messagesDiv.appendChild(messageElement); // Adds the message at the bottom
// Auto-scroll to the bottom
messagesDiv.scrollTop = messagesDiv.scrollHeight;
}
// connect to realtime SSE
async function startListener() {
// setup the real time stuff
const statusIndicator = document.getElementById('statusIndicator');
const interests = {}; // everything
var requestOptions = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-apikey': API_TOKEN
},
body: JSON.stringify(interests)
};
// get a real time listenerID
console.log('Connect request', requestOptions)
const response = await fetch('/connect', requestOptions);
const result = await response.json();
listenerID = result.listenerID;
console.log('GOT clientID', result)
// connect to reatime channel
let eventSource = new EventSourcePolyfill(`/chat/${result.listenerID}`, {
headers: {
'x-apikey': API_TOKEN
}
});
statusIndicator.textContent = 'Connected';
statusIndicator.style.color = 'green';
// incoming message event
eventSource.onmessage = function (event) {
console.log("Event", event.data)
const result = JSON.parse(event.data);
addMessage(result.message)
};
// here we go
eventSource.onopen = function(event) {
// Connection is open
statusIndicator.textContent = 'Live data ready';
statusIndicator.style.color = 'green';
};
// oops, reconnecting if possible
eventSource.onerror = function(event) {
console.log("Error", event);
// An error occurred or the connection was closed
if (eventSource.readyState == EventSource.CLOSED) {
console.log("Connection was closed.");
}
statusIndicator.textContent = 'No connection';
statusIndicator.style.color = 'red';
};
return result;
}
Codehooks.io Server
See install and deploy docs at Github.
index.js
// Codehooks.io - Chat example
import {app, realtime} from 'codehooks-js';
// create a real-time channel
realtime.createChannel('/chat');
// client connects for a new real-time listener ID
app.post('/connect', async (req, res) => {
const listenerData = await realtime.createListener('/chat')
// return listener ID to client
res.json({listenerID: listenerData._id})
})
// client post a new message
app.post('/messages', async (req, res) => {
console.log('Message in', req.body)
const {message, listenerID, alias} = req.body;
const data = await realtime.publishEvent('/chat', {"message": `${alias || 'Anonymous'}: ${message}`});
res.end(data)
})
// annoying message from a cron job every second minute ;)
app.job('*/2 * * * *', async (_, job) => {
const message = `Hello from cron job at ${new Date().toISOString()}`;
const data = await realtime.publishEvent('/chat', {"message": `cron: ${message}`});
job.end()
})
app.static({route:'/public', directory: '/public'})
// bind to serverless runtime
export default app.init();