APIs for creating, editing, and deleting plugins

[alexanderson1993]

A bit of explanation. Skip ahead to the "Net Request" section if you just want to know what this issue is about.

Okay, there is currently one way of getting data from the client to the server: Inputs. Inputs are given parameters, make changes to the database, and trigger publishes. Pretty simple.

There are currently two ways of getting data from the server to the client: Data Streams and Card Subscriptions.

Data Streams are pretty simple. Some data needs to be sent at high frequency. To keep bandwidth low, we only send the kind of data that would change frequently - XYZ position and rotation. Cards can subscribe to a data stream by exporting a function that filters the list of all entities so the card only gets the data for those entities.

Card Subscriptions are also defined by cards and cause the server to automatically send data to clients, without them even needing to ask for it. The card exports a fetch function which is called when the card is first loaded and whenever there is change to the data (signaled by a pubsub.publish call). That function collects the data the card needs and sends it down. Optionally, card subscriptions can define a filter function, which will only make the fetch function call if the filter function returns true.

Since the server automatically sends the card subscription data, it's not possible to pass parameters to those functions. The only "parameter" the fetch and filter functions get is the ID of the client making the request, which they can use to find out what ship and station are assigned to that client and derive even more context from that.

Net Request

In some cases, though, we need to pass parameters to get data. This came up as I was working on the plugins, where I wanted to just subscribe to changes to a single plugin, but the current data fetching mechanisms don't provide that.

So, here's how Net Requests work. The client sends a web socket message that looks like {type: "netRequest", data:{requestName:string, params:any}, requestId:string} to the server. The server IDs the subscription to keep track of it, calls a function matching the requestName with the params that were sent, and starts sending {type:"netRequestData", data:any} messages back to the client. Those messages are triggered by pubsub.publish calls, just like card subscriptions, and call the function for each subscribed client.

Net Requests can choose to not send a message to a client, based on the client context or the parameters passed in, by throw-ing null.

export const pluginRequests = {
  // ...
  plugin(context: DataContext, params:{pluginId:string}, publishParams:{pluginId:string}) {
    if (params.pluginId !== publishParams.pluginId) throw null; // Don't send the update to this client
    // Collect the rest of the data
  }
  // ...
}

Net Requests are defined in the /server/src/netRequests folder, and look an awful lot like netSends - just with subscription handling.

Net Requests can be ended either by the client disconnecting or the client sending a web socket message that says {"type": "netRequestEnd", requestId:string}. Changing parameters for the request requires unsubscribing and resubscribing.

On the client, requests can be made using a new hook called useNetRequest. The hook takes two parameters - the name of the request and the params for the request, and it returns the data, automatically updating when new data comes in. Behind the scenes, the hook takes care of sending the appropriate WebSocket messages, caching the data, and providing it to the component.