Files
factorio-clusterio/packages/lib/link/link.js
T
Hornwitser bcd94709d2 Refactor link system to JSON serialisable class pattern
Reverse the direction of the API for sending messages from

    messageDefinition.send(link, { content });

to

    link.send(new MessageClass(content));

and convert all message definitions to use the JSON serialisable class
pattern and explicit registration of message handlers, along with a
end-to-end based routing of messages instead of link to link.

The experience I gained from the existing way messages were defined and
sent over links was that it was difficult to understand for people
unfamiliar with the system.  The automatic registration of message
handlers ment that code was being called as if by magic from nowhere
with no easy way to discover it.  The manual forwarding and rules for
what can be sent where and how obscured its working.

The use of pure JSON as both input and output from message handlers made
it tedious to work with.  Data had to be manually converted between the
program representation and the over the wire format, which made handler
code unplesant to write.  Particularly because the over the wire format
used snake_case while the program code uses camelCase for variables.
The idea behind the decision to do it this way was to make it more clear
which data came from the wire and which from the program, and while this
worked it didn't make message handlers any nicer to write.

The direction of the API and magic registration of message handlers also
meant that a future migration to TypeScript would be troublesome.  While
it may be possible to implement, the degree of TypeScript magic required
would go starkly against the principle of keep it simple stupid.

By refactoring to using the JSON serialisable class pattern most of
these issues go away.  There is no longer a need to distinguish the on
wire format of messages with the program representation because the only
place that deals with the wire format of messages are the toJSON and
fromJSON methods on the classes themselves.  Message handlers will work
with proper instances of classes instead of raw data, something that
makes them easier to write, and trivial to type with TypeScript.

End-to-end routing also simplifies sending messages that need to do
mulitple hops to reach the destination.  And removes the need for having
all messages be specified in plugin's info module, as they can be routed
without having to be parsed completely.

The explicit registration of message handlers is something that I
thought would be tedious boilerplate code that could be automated away.
But experience now shows it to be the opposite.  Allthough dull
repetition, the purpose it serves is to link together the code in a way
that humans can easily find.  With explicit registration searching the
name of the message handler in the editor will show the registration that
ties it together with the type of message it handles and the kind of
registration.  With implicit registration searching the name of the
message handler turns up only the handler with no clue as to what calls
it.
2023-04-23 13:19:46 +02:00

462 lines
13 KiB
JavaScript

// Implementation of Link class
"use strict";
const libData = require("../data");
const libErrors = require("../errors");
const { logger } = require("../logging");
const libSchema = require("../schema");
// Some definitions for the terminology used here:
// link: Either side of a controller - client connection
// connector: Adapter between a link and a socket connection
// connection: the controller side of a link
// client: the side that is not the controller of a link
// message: the complete object sent using the 'message' event
// data: the data property of a message, essentially the payload.
// type: the type property of a message, identifies what to expect in data.
/**
* Common interface for server and client connections
*
* @memberof module:lib/link
*/
class Link {
constructor(connector) {
this.connector = connector;
this.router = undefined;
this.validateSent = true;
this._registeredRequests = new Map();
this._fallbackedRequests = new Map();
this._registeredEvents = new Map();
this._snoopedEvents = new Map();
this._eventHandlers = new Map();
this._pendingRequests = new Map();
this._nextRequestId = 1;
this.register(libData.PingRequest, () => {});
// Process messages received by the connector
connector.on("message", payload => {
try {
this._processMessage(payload);
} catch (err) {
if (err instanceof libErrors.InvalidMessage) {
logger.error(err.message);
if (err.errors) {
logger.error(JSON.stringify(err.errors, null, 4));
}
} else {
// Unexpected error, bubble back to connector
this.connector.emit("error", err);
}
}
});
connector.on("disconnectPrepare", () => {
this.prepareDisconnect().catch(
err => {
logger.error(`Unexpected error preparing disconnect:\n${err.stack}`);
}
).finally(
() => {
this.connector.send(new libData.MessageDisconnect("ready"));
},
);
});
connector.on("invalidate", () => {
for (let pending of this._pendingRequests.values()) {
pending.reject(new libErrors.SessionLost("Session Lost"));
}
this._pendingRequests.clear();
});
connector.on("close", () => {
for (let pending of this._pendingRequests.values()) {
pending.reject(new libErrors.SessionLost("Session Closed"));
}
this._pendingRequests.clear();
});
}
/**
* Process a received message on the link
*
* Validates and invokes the handler and/or waiters for a message that has
* been received. An unhandled message is considered to be an error.
*
* @param {module:lib/data.Message} message - Message to process.
* @throws {module:lib/errors.InvalidMessage} if the message is invalid or not handled.
*/
_processMessage(message) {
if (!["request", "response", "responseError", "event"].includes(message.type)) {
throw new libErrors.InvalidMessage(`Unhandled message type ${message.type}`);
}
if (message.type === "event" && this._snoopedEvents.has(message.name)) {
let event = this._snoopedEvents.get(message.name);
event.handler(event.eventFromJSON(message.data), message.src, message.dst).catch(err => {
logger.error(`Unexpected error snooping ${message.name}:\n${err.stack}`);
});
}
if (!message.dst.addressedTo(this.connector.src)) {
this._routeMessage(message);
return;
}
if (message.type === "request") {
let request = this._registeredRequests.get(message.name);
if (!request) {
this.connector.sendResponseError(
new libData.ResponseError(`Unrecognized request ${message.name}`),
message.src,
);
return;
}
this._processRequest(message, request);
} else if (message.type === "response") {
this._processResponse(message);
} else if (message.type === "responseError") {
this._processResponseError(message);
} else if (message.type === "event") {
this._processEvent(message);
}
}
_routeMessage(message) {
if (!this.router) {
let err = new libErrors.InvalidMessage(
`Received message addressed to ${message.dst} but this link does not route messages`
);
if (message.type === "request") {
this.connector.sendResponseError(
new libData.ResponseError(err.message, err.code), message.src
);
}
throw err;
}
let fallback = this._fallbackedRequests.get(message.name);
if (this.router.forwardMessage(this, message, Boolean(fallback))) {
return;
}
if (!fallback) {
throw new Error("Router requested fallback handling when fallback is unavailable");
}
if (message.type !== "request") {
throw new Error(`Router requested fallback handling of unsupported message type ${message.type}`);
}
this._processRequest(message, fallback);
}
_processRequest(message, request) {
if (!request.handler) {
this.connector.sendResponseError(
new libData.ResponseError(`No handler registered for ${request.Request.name}`), message.src
);
return;
}
let response;
try {
response = request.handler(request.requestFromJSON(message.data), message.src, message.dst);
} catch (err) {
if (err.errors) {
logger.error(JSON.stringify(err.errors, null, 4));
}
this.connector.sendResponseError(
new libData.ResponseError(err.message, err.code, err.stack), message.src
);
return;
}
if (!(response instanceof Promise)) {
response = Promise.resolve(response);
}
response.then(
result => {
if (this.validateSent) {
if (request.Response) {
request.responseFromJSON(JSON.parse(JSON.stringify(result)));
} else if (result !== undefined) {
throw new Error(`Expected empty response from ${request.Request.name} handler`);
}
}
this.connector.sendResponse(result, message.src);
}
).catch(
err => {
if (!(err instanceof libErrors.RequestError)) {
logger.error(`Unexpected error responding to ${message.name}:\n${err.stack}`);
}
this.connector.sendResponseError(
new libData.ResponseError(err.message, err.code, err.stack), message.src
);
}
);
}
_processResponse(message) {
let pending = this._pendingRequests.get(message.dst.requestId);
if (!pending) {
throw new libErrors.InvalidMessage(
`Received response ${message.dst.requestId} without a pending request`
);
}
try {
pending.resolve(pending.request.responseFromJSON(message.data));
} catch (err) {
// An invalid response object was likely received
pending.reject(err);
}
}
_processResponseError(message) {
let pending = this._pendingRequests.get(message.dst.requestId);
if (!pending) {
throw new libErrors.InvalidMessage(
`Received error response ${message.dst.requestId} without a pending request`
);
}
pending.reject(new libErrors.RequestError(message.data.message, message.data.code, message.data.stack));
}
_processEvent(message) {
let event = this._registeredEvents.get(message.name);
if (!event) {
throw new libErrors.InvalidMessage(`Unrecognized event ${message.name}`);
}
if (!event.handler) {
return;
}
event.handler(event.eventFromJSON(message.data), message.src, message.dst).catch(err => {
logger.error(`Unexpected error handling ${message.name}:\n${err.stack}`);
});
}
/**
* Prepare connection for disconnect
*
* Waits for all pending requests on the connection to resolve.
* Sub-classes should implement this handler with code that prevents
* additional requests to be sent out before calling the super class
* method.
*/
async prepareDisconnect() {
let promises = [];
for (let pending of this._pendingRequests.values()) {
promises.push(pending.promise.then(() => {}, () => {}));
}
await Promise.all(promises);
}
/**
* Send a request or event to the other side of this link
* @param {*} requestOrEvent - Request or event to send
* @returns {Promise<*>|undefined}
* Promise that resolves to the response if a request was sent or
* undefined if it was an event.
*/
send(requestOrEvent) {
return this.sendTo(requestOrEvent, this.connector.dst);
}
/**
* Send a request or event to the given address
*
* @param {*} requestOrEvent - Request or event to send
* @param {*|module:lib/data.Address} destination - Where to send it
* @returns {Promise<*>|undefined}
* Promise that resolves to the response if a request was sent or
* undefined if it was an event.
*/
sendTo(requestOrEvent, destination) {
let dst = libData.Address.fromShorthand(destination);
if (requestOrEvent.constructor.type === "request") {
return this.sendRequest(requestOrEvent, dst);
}
if (requestOrEvent.constructor.type === "event") {
return this.sendEvent(requestOrEvent, dst);
}
throw Error(`Expected request or event but got type ${requestOrEvent.constructor.type}`);
}
sendRequest(request, dst) {
let name = request.constructor.name;
if (!this._registeredRequests.has(name)) {
// XXX should this be allowed?
this.registerRequest(request.constructor);
}
let registeredRequest = this._registeredRequests.get(name);
if (this.validateSent) {
registeredRequest.requestFromJSON(JSON.parse(JSON.stringify(request)));
}
let pending = {
request: registeredRequest,
};
pending.promise = new Promise((resolve, reject) => {
pending.resolve = resolve;
pending.reject = reject;
});
let requestId = this._nextRequestId;
this._nextRequestId += 1;
this._pendingRequests.set(requestId, pending);
this.connector.sendRequest(request, requestId, dst);
return pending.promise;
}
sendEvent(event, dst) {
if (this.validateSent) {
let name = event.constructor.name;
if (!this._registeredEvents.has(name)) {
// XXX should this be allowed?
this.registerEvent(event.constructor);
}
this._registeredEvents.get(name).eventFromJSON(JSON.parse(JSON.stringify(event)));
}
this.connector.sendEvent(event, dst);
}
register(Class, handler) {
if (Class.type === "request") {
this.registerRequest(Class, handler);
} else if (Class.type === "event") {
this.registerEvent(Class, handler);
} else {
throw new Error(`Class ${Class.name} has unrecognized type ${Class.type}`);
}
}
_requestEntry(Request, handler) {
let name = Request.name;
let entry = {
Request,
handler,
};
if (Request.fromJSON) {
if (!Request.jsonSchema) {
throw new Error(`Request ${name} has static fromJSON but is missing static jsonSchema`);
}
let validate = libSchema.compile(Request.jsonSchema);
entry.requestFromJSON = (json) => {
if (!validate(json)) {
throw new libErrors.InvalidMessage(`Request ${name} failed validation`, validate.errors);
}
return Request.fromJSON(json);
};
} else if (Request.jsonSchema) {
throw new Error(`Request ${name} has static jsonSchema but is missing static fromJSON`);
} else {
entry.requestFromJSON = () => new Request();
}
let Response = Request.Response;
if (Response) {
if (!Response.jsonSchema) {
throw new Error(`Response for Request ${name} is missing static jsonSchema`);
}
if (!Response.fromJSON) {
throw new Error(`Response for Request ${name} is missing static fromJSON`);
}
let validate = libSchema.compile(Response.jsonSchema);
entry.responseFromJSON = (json) => {
if (!validate(json)) {
throw new libErrors.InvalidMessage(
`Response for request ${name} failed validation`, validate.errors
);
}
return Response.fromJSON(json);
};
entry.Response = Response;
} else {
entry.responseFromJSON = () => undefined;
}
return entry;
}
registerRequest(Request, handler) {
let name = Request.name;
if (this._registeredRequests.has(name)) {
throw new Error(`Request ${name} is already registered`);
}
let request = this._requestEntry(Request, handler);
this._registeredRequests.set(name, request);
}
fallbackRequest(Request, handler) {
let name = Request.name;
if (this._fallbackedRequests.has(name)) {
throw new Error(`Request ${name} is already fallbacked`);
}
let request = this._requestEntry(Request, handler);
this._fallbackedRequests.set(name, request);
}
_createEventFromJSON(Event) {
if (Event.fromJSON) {
if (!Event.jsonSchema) {
throw new Error(`Event ${Event.name} has static fromJSON but is missing static jsonSchema`);
}
let validate = libSchema.compile(Event.jsonSchema);
return (json) => {
if (!validate(json)) {
throw new libErrors.InvalidMessage(`Event ${Event.name} failed validation`, validate.errors);
}
return Event.fromJSON(json);
};
}
if (Event.jsonSchema) {
throw new Error(`Event ${Event.name} has static jsonSchema but is missing static fromJSON`);
}
return () => new Event();
}
registerEvent(Event, handler) {
if (this._registeredEvents.has(Event.name)) {
throw new Error(`Event ${Event.name} is already registered`);
}
let event = {
Event,
handler,
eventFromJSON: this._createEventFromJSON(Event),
};
this._registeredEvents.set(Event.name, event);
}
snoopEvent(Event, handler) {
let name = Event.name;
if (this._snoopedEvents.has(name)) {
throw new Error(`Event ${name} is already snooped`);
}
let event = {
Event,
handler,
eventFromJSON: this._createEventFromJSON(Event),
};
this._snoopedEvents.set(Event.name, event);
}
}
module.exports = {
Link,
};