In an app on the Heisenware platform, a counter registered its event handler again once a minute. Nothing in between knew it was the same listener. After 19 hours the instance held 1,100 copies of one handler, and every pulse of the counter went out 1,100 times.
VRPC 3.15 ends that for good. It brings protocol 4, and with it a simple rule: an event function runs once, however many listen.
VRPC makes the classes of one program callable from others, as if they were local. You register a class with an agent; any client - a backend service, a browser, a device - creates instances of it, calls their functions and listens to their events. Agents and clients only connect out to an MQTT broker, so code behind a firewall is reachable, and there is no API layer to write: the class is the contract.
// on the Raspberry Pi in the kitchen
const { VrpcAdapter, VrpcAgent } = require('vrpc')
class Sensor { /* read(), onReading(handler) */ }
VrpcAdapter.register(Sensor)
new VrpcAgent({ domain: 'home', agent: 'pi-kitchen' }).serve()
// anywhere else: a backend, a browser
const { VrpcClient } = require('vrpc')
const client = new VrpcClient({ domain: 'home' })
await client.connect()
const sensor = await client.getInstance('kitchen')
console.log(await sensor.read())
await sensor.onReading(celsius => chart.add(celsius))
Before 3.15, every subscribing call reached the class's event function anew. Ten browsers on one sensor meant ten listeners on it, and a client that subscribed again after a hiccup added one more. Protocol 4 separates two things:
The agent hands every event of a registration to all of its subscriptions, and releases the registration when the last subscription leaves. Ten browsers on one sensor are one listener on the emitter, not ten - and the counter from above holds exactly one.
An event function returns a registration object. It says how to release the registration, and optionally how to greet a newcomer:
onReading (handler) {
this._emitter.on('reading', handler)
return {
[Symbol.dispose]: () => this._emitter.off('reading', handler),
greet: greeting => greeting(this._reading)
}
}
[Symbol.dispose] runs when the last subscriber leaves. greet runs for
every new subscriber, the first one included, so each one starts with the
current reading instead of waiting for the next change - however late it
joins.
A registration can end: its instance is deleted, or the class ends it. Every
subscriber is told, and the client emits ended instead of calling the
handler again. When an agent goes offline, the client keeps its
subscriptions there and declares them again once the agent is back - it
emits lost, then healed, and nobody has to rebuild anything.
callAll selects instances. instances: 'line-3*' calls those alone,
in one request per agent however many instances it holds, and
agent: 'edge-*' asks all matching agents at once.emit and private helpers
were reachable with a hand-made request; now they are not, and @private
in the JSDoc keeps a function inside as well.{ message, cause }.Protocol 4 is specified rule by rule in the protocol specification: numbered rules, and tests that name the rule they check. It binds every VRPC implementation. The C++, Python and Arduino ports speak protocol 3 today, and that keeps working: a 3.15 agent serves older clients, and a 3.15 client talks to older agents.
npm install vrpc@3.15
Getting started takes ten minutes, Events explains the model, and the changelog lists every change. If VRPC saves you some boilerplate, a star on GitHub helps others find it.
]]>Ein Zähler in einer App auf der Heisenware-Plattform hat sich jede Minute neu für sein Event registriert. Aufgefallen ist das niemandem – bis nach 19 Stunden 1.100 Kopien desselben Handlers an der Instanz hingen und jeder einzelne Impuls 1.100-mal verschickt wurde.
Mit VRPC 3.15 ist damit Schluss. Das Release bringt Protokoll 4 und eine einfache Regel: Eine Event-Funktion läuft genau einmal – egal, wie viele Clients sie abonnieren.
Mit VRPC werden die Klassen eines Programms aus anderen Programmen heraus aufgerufen, als wären sie lokal. Eine Klasse wird bei einem Agenten registriert; Clients – ein Backend, ein Browser, ein Gerät – erzeugen davon Instanzen, rufen Funktionen auf und abonnieren Events. Alle verbinden sich nur ausgehend mit einem MQTT-Broker, deshalb ist auch Code hinter einer Firewall erreichbar, und eine API-Schicht braucht es nicht: Die Klasse ist die Schnittstelle.
// läuft auf dem Raspberry Pi in der Küche
const { VrpcAdapter, VrpcAgent } = require('vrpc')
class Sensor { /* read(), onReading(handler) */ }
VrpcAdapter.register(Sensor)
new VrpcAgent({ domain: 'home', agent: 'pi-kitchen' }).serve()
// läuft überall sonst: im Backend, im Browser
const { VrpcClient } = require('vrpc')
const client = new VrpcClient({ domain: 'home' })
await client.connect()
const sensor = await client.getInstance('kitchen')
console.log(await sensor.read())
await sensor.onReading(celsius => chart.add(celsius))
Bisher landete jeder Aufruf, der ein Event abonnierte, direkt in der Event-Funktion der Klasse. Zehn Browser am selben Sensor bedeuteten zehn Listener, und jeder Client, der nach einem Verbindungsabbruch neu abonnierte, legte noch einen drauf. Protokoll 4 trennt das sauber:
Jedes Event wird vom Agenten an alle Subscriptions einer Registrierung verteilt. Verschwindet die letzte Subscription, wird auch die Registrierung freigegeben. Zehn Browser an einem Sensor ergeben damit einen Listener statt zehn – und an dem Zähler von oben hängt genau einer.
Damit klar ist, wie eine Registrierung wieder abgebaut wird, gibt die Event-Funktion ein Registrierungsobjekt zurück. Optional steht darin auch, wie neue Abonnenten begrüßt werden:
onReading (handler) {
this._emitter.on('reading', handler)
return {
[Symbol.dispose]: () => this._emitter.off('reading', handler),
greet: greeting => greeting(this._reading)
}
}
[Symbol.dispose] wird aufgerufen, wenn die letzte Subscription weg ist.
greet läuft für jede neue Subscription, auch für die erste. So startet
jeder Client mit dem aktuellen Messwert und muss nicht auf die nächste
Änderung warten – auch wenn er erst Stunden später dazukommt.
Endet eine Registrierung, weil die Instanz gelöscht wurde oder die Klasse
sie beendet, bekommen alle Abonnenten Bescheid: Der Client meldet ended,
und der Handler wird nicht mehr aufgerufen. Geht ein Agent offline, bleiben
die Subscriptions beim Client erhalten und werden von selbst neu angemeldet,
sobald der Agent wieder da ist (lost, danach healed). Neu aufgebaut
werden muss nichts.
callAll mit Auswahl: Mit instances: 'line-3*' werden nur die
passenden Instanzen aufgerufen, mit einer einzigen Anfrage pro Agent.
agent: 'edge-*' fragt alle passenden Agenten gleichzeitig.emit und private
Hilfsfunktionen ließen sich bisher mit einer selbst gebauten Anfrage
erreichen. Das ist vorbei, und mit @private im JSDoc bleibt eine Funktion
ebenfalls intern.{ message, cause }.Protokoll 4 ist in der Protokollspezifikation Regel für Regel festgehalten – nummeriert, und jeder Test nennt die Regel, die er prüft. Die Spezifikation gilt für alle VRPC-Implementierungen. Die Portierungen für C++, Python und Arduino sprechen noch Protokoll 3, und das funktioniert weiterhin: Ein Agent ab 3.15 bedient auch ältere Clients, und umgekehrt.
npm install vrpc@3.15
Die Dokumentation ist auf Englisch. Mit Getting started läuft das erste Beispiel in zehn Minuten, Events erklärt das Modell, und im Changelog steht jede Änderung. Wenn dir VRPC Boilerplate erspart, freuen wir uns über einen Stern auf GitHub – damit es auch andere finden.
]]>