Plugins

[rkusa]

I think it would be great if it'd be possible to extend the DCS-gRPC server with plugins (we can also call them extensions, but I'll just go with plugins for the rest of the post).

Example

Write your own little plugin, with its own proto definition, eg.:

syntax = "proto3";
package example.greeter.v0;

service GreeterService {
  rpc Greet(GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  bool success = 1;
}

Compile the plugin to either a DLL (or EXE, see implementation ideas at the end) and copy it into a dedicated plugin directory. Example:

Once in there, the server automatically picks it up on its next start. It then takes care of starting, stopping and restarting on errors. It also makes sure to forward all requests to example.greeter.v0.GreeterService/Greet, to the plugin. So your plugin would be available through the main gRPC endpoint of the gRPC server. Eg.:

.\grpcurl.exe -plaintext -import-path ./plugin-example/protos -proto ./plugin-example/protos/example/example.proto \
    -d '{\"name\": \"Someone\"}' 127.0.0.1:50051 example.greeter.v0.GreeterService/Greet

Motivation

I'd love for DATIS to use DCS-gRPC instead of its own RPC mechanism (DCS-gRPC actually re-uses parts of DATIS's RPC). I'd also like to expose the SRS integration from DATIS for other use-cases.

So I would:

• create a standalone SRS integration (that can be used outside of DATIS too), and
• DATIS itself which basically just collects the data (through DCS-gRPC) for ATIS reports and passes them through the SRS integration above.

If both would be standalone programs, everyone would have to start two additional programs besides DCS just to get ATIS stations. Something I personally highly dislike. I'd like for DATIS to stay as much plug'n'play as possible. Right now, you just have to copy files into your saved games DCS directory and that is it (not even MissionScripting.lua patching is necessary).

The only solution to make it easier to use other tools based on DCS-gRPC I can think of is to make the server a plugin host. So that you can write plugins either as a dll (or exe if we prefer) and the server takes care of starting and stopping the plugins and also of proxying traffic to them.

I could then have a plugin for srs.tts.v0.TtsService. Just copy the dll/exe for this plugin into a dedicated plugin directory of the server, and after that I can send requests for srs.tts.v0.TtsService to the server, and they are automatically proxied to the plugin.

Pros/Cons

I see the following pros and cons.

Pros:

• I only have to start DCS and not other program.
• The server can take care of restarting the plugins on failures instead of me having to take care of this too.
• I still have a single entry point for my gRPC requests.
• Plugins can have their own proper proto definitions.

Cons:

• The gained extensibility might discourage people from contributing to DCS-gRPC.
• Plugins might just be out of scope for what we image the DCS-gRPC server's responsibilities to be.

Implementation Ideas

DLL

The plugin could be a DLL that exposes certain functions. E.g.:

// A function to get the plugin name. This is used to route requests to the plugin, this could be
// `example.greeter.v0.GreeterService` in the example above.
uintptr_t name(const uint8_t **name);

// A function to ensure API compatibility between the server and the plugin
int32_t api_version(void);

// A function to start the plugin
void start(void);

// A function to stop the plugin
void stop(void);

For the communication between the plugin and the DCS-gRPC server I see the following possible solutions: a) pass requests through FFI functions, too; or b) just let the plugin start its own gRPC server and communicate with the DCS-gRPC server through http2. I have a POC for both, so can confirm that they actually work and are not just theoretically.

a) Pass requests through FFI

This could be achieved by the following adjustment to the C interface:

// The start function receives a function that can be used to send requests to the DCS-gRPC server.
typedef uintptr_t (*RequestFn)(const char *method_ptr, uintptr_t method_len, const uint8_t *request_ptr, uintptr_t request_len, uint8_t **response_ptr);
void start(RequestFn request_fn);

// The plugin exposes a function to receive requests itself.
uintptr_t call(const char *method_ptr,
               uintptr_t method_len,
               const uint8_t *request_ptr,
               uintptr_t request_len,
               uint8_t **response_ptr);

The functions to pass requests around is basically: fn(method: &str, request: &[u8]) -> Vec<u8>. So the plugin basically has a function that it can call to pass requests to the main server, and it exposes a function that it receives requests with. This gets rid of the overhead of sending the requests through HTTP/2 as the main server and the plugin already life in the same process anyway. However, I wouldn't be surprised if this is hard to implement in certain languages (probably depends on how flexible a certain gRPC integration is). Something to keep in mind.

b) Communicate through HTTP/2

The start method is adjusted as follows:

void start(uin16_t server_port, uin16_t plugin_port);

It receives a port the main DCS-gRPC listens on (server_port). This lets the plugin know where to send requests. It also receives a port where the plugin is expected to listen to itself (plugin_port). This is where the requests meant for the plugin are proxied to.

EXE

If we think that creating DLLs is too complicated. We can also consider EXE plugins instead. Plugins are then basically CLI applications. This is how they could work:

• The communication would go through HTTP/2 (similar to as described in (b) above).
• The EXE would receive their port and the port of the main server through environment variables.
• EXE plugins could log to stdout and stderr - and both are included in the log file of DCS-gRPC.
• As the EXE can not easily provide data to the server. The API version for plugin-server compatibility would also be provided as an env variable. The difference here would be that the plugin is responsible to check compatibility.
• The service name, that is used to determine which requests to send to the plugin, could be the name of the plugin. E.g.: example.greeter.v0.GreeterService.exe (though I am not sure if Windows is happy with so many . in a file name)
• The DCS-gRPC server starts each plugin in a separate process

Even though I find the DLL approach subjectively more appealing, objectively, I see some serious advantages with the EXE approach:

• Since the EXE runs as a separate process, when it stops or crashes, it isn't taking DCS with it.
• Easier to test the plugin stand alone as it is basically just a CLI.
• Easier to integrate logging, as it is just stdout and stderr.

Cons I see:

• I wouldn't be surprised if people trust a DLL more than an EXE
• The API compatibility is in the responsibility of a plugin (so most plugins will probably just not check it)
• Overhead to go through HTTP/2 (I expect the overhead is very minor though)
• DLLs subjectively feel more like a real plugin system

Conclusion

With such a system a distribution of DATIS could just be two plugins for DCS-gRPC that a user has to copy into a plugin directory and that is it. This simplicity of installation / using it could be summarized as the main motivation for me to think about the plugin system.

Let me know what you think. Also no need to go easy on the idea. If you don't like the idea of plugins feel free to simply state that (with the reason to think so ofc) 😊

[rkusa]

Plugins that receive commands from the Mission Scripting Environment

Another use-case for plugins, which I haven't touched on above, is to send commands from within the mission scripting environment to a plugin. Taking the SRS plugin as an example, this would allow to not only use the plugin by connecting to the gRPC server, but also via Lua calls inside the mission.

I see two ways of achieving this: a) an untyped way, and a b) typed way.

a) Untyped Approach

This is rather straight forward. We expose an event that can hold arbitrary data:

  message PluginEvent {
    string plugin = 1;
    google.protobuf.Struct details = 3;
  }

Plugins than just listen to the regular event stream, and pick out their events and try to make sense out of the details. If we'd want to achieve a plugin command that also returns something as a result (like a handle to an ATIS station to be able to e.g. stop it in a follow up call), we could add something like the current event mechanism, just with the addition of also returning something. The return would than also be of type google.protobuf.Struct.

b) Typed Approach

For plugins, we don't know the types during compile time of the server. So we'd have to make sense of the message types of a plugin during runtime. This can be achieved using self-describing messages. This is how it could look like:

1. A plugin has a message dedicated for receiving commands from the Lua environment. E.g.

   message Command {
     oneof command {
       GreetCommand greet = 1;
     }
   }
   
   message GreetCommand {
     string name = 1;
   }

2. The plugin generates a descriptor set for those messages, eg:

   protoc.exe --proto_path=plugin-example\protos \
       --descriptor_set_out=plugin-example\protos\descriptor_set.bin \
       plugin-example\protos\example\example.proto

3. The plugin structure is changed to something like:

   • a directory named after the service (or the package) it exposes
   • a plugin.exe (or .dll) inside the directory, which is the plugin itself
   • a descriptor_set.bin inside the directory, which is the result of the protoc.exe command above

   

   This gives the server everything it needs to encode/decode the messages for the plugin from and to Lua.

4. The plugin can be called from within the mission scripting environment via:

   GRPC.plugin("example", {greet = { name = "Someone" }})

[rkusa]

If it helps, here is an example plugin (using the EXE) method for a POC I've created: https://github.com/DCS-gRPC/rust-server/blob/poc-plugins/plugin-example/src/main.rs (it doesn't implement actually receiving commands from Lua yet; just starting a gRPC service and talking to the main DCS-gRPC server)

[rurounijones]

My vision was that DCS-gRPC would almost always run on multiplayer DCS servers and therefore would be running 24/7 or close to and DCS-gRPC clients to run separately as background services. Therefore I have always optimised for that scenario.

Given that line of thinking (which could be wrong) I never thought "Having to install something separately" was a concern. I have also never considered having to start a separate client to be a problem either and can in fact be an advantage as you can update a DCS-gRPC clients without having to restart the DCS server. I make a lot of use of this feature when updating OverlordBot since pdating just the bot is very easy but when I have to update DCS-gRPC as well I have to wait until server restarts which can be a real pain because I need to replace the DLL, I assume plugins would have the same issue.

The general bullet-point list of cons I see with plugins are:

• Tied to the server. Something like OverlordBot runs in a single process and connects / reconnects to multiple DCS servers so it is slightly more efficient than it would be running one bot per server as a plugin for example.
• I think we are overestimating the number of people who would be willing to write plugins in a language that would be usable as a plugin.
• This is not an issue with plugins themselves but since it is a new idea it fragments the ecosystem into "plugin" and "not plugin" which adds maintenance and complexity. (This would be the same issue if we started with plugins and then added external DCS-gRPC clients)

However none of the above are deal-breakers and it could well be down to personal preference of the server owners but again I worry about added complexity "This thing is a separate client, this thing is a plugin, they are completely different in how they are installed and managed"

My absolute main concern is that there does not become API fragmentation with multiple ways of communicating with DCS-gRPC clients / plugins from the DCS mission environment (or, indeed other clients) and especially that we avoid coupling between any of the parts (MSE, Client, Plugin).

Currently we can communicate with a DCS-gRPC client from the MSE using events. The MissionCommand APIs are the first step along those lines and I am considering having a "generic" event that can be emitted from the MSE with scripts.

  message ScriptEvent {
    string publisher = 1;
    string name = 2
    google.protobuf.Struct details = 3;
  }

if (GRPC is not nil) then
  local event = {
    type = "scriptEvent",    -- Defined in DCS-gRPC
    publisher = "scriptName" -- All scriptEvents will have a publisher field which should be the name of the script. Used by clients to filter out events from scripts they don't care about. Also avoids possible conflicts in event names.
    name = "someEventName"   -- Unique event name. Allows the client to identify the exact event.
    details = {
      -- Add your event specific information here
    }
  }
  GRPC.event(event)
end

The advantage of events is that they are essentiall a PubSub system fan out to all clients (and plugins) and completely uncouple the processors of the events from the publisher. This could be a great advantage if you have, for example, one client that processes the event that affects the mission while another performs some sort of event logging to Discord or something like that.

Having a specific GRPC.plugin("example", {greet = { name = "Someone" }}) would mean that we now have an API that is plugin specific and has to be maintained by the script writer in case they replace one plugin with another or someone wants to write another plugin that should be called at the same time.

Related to the above is my concern is that DCS-gRPC non-plugins essentially become second-class citizens which is something I dearly want to avoid.

If we can architect plugins such that they process events just like a DCS-gRPC client does and do not require any specific calling convention then that would alleviate my main concern.

I realise that this makes plugins that have synchronous APIs that return values to the MSE almost impossible to implement but my thought is that if there is so much custom logic coupling between a specific lua script and a plugin then they should just be bundled together and not use DCS-gRPC at all.

[rkusa]

We definitely come from different perspectives. I am mostly concerned with running my squadron's server, which isn't running 24/7. So I don't mind restarting DCS when updating tools/plugins. I ran a second DCS server for an event once on the same machine and my preferred approach was to create a separate Windows user and duplicate everything (DCS ofc, but also SRS, etc.).

The general bullet-point list of cons I see with plugins are:

• Tied to the server. Something like OverlordBot runs in a single process and connects / reconnects to multiple DCS servers so it is slightly more efficient than it would be running one bot per server as a plugin for example.

I somehow agree for the OverlordBot use-case. Even though I'd personally favour one process per DCS instance, I see that running OverlordBot as a separate/standalone program instead of as a plugin makes sense.
However, for me it wouldn't make sense to run a separate program for an TTS/SRS integration, which is then again used by other programs (DATIS, etc.).

• I think we are overestimating the number of people who would be willing to write plugins in a language that would be usable as a plugin.

I'd agree for the the DLL-approach. The EXE approach should work with almost all programs out there though. However, I agree that I don't expect a lot of people to write plugins. And most of the time, the plugins are probably for personal use (e.g. plugins for the sever owner's own dynamic mission).

• This is not an issue with plugins themselves but since it is a new idea it fragments the ecosystem into "plugin" and "not plugin" which adds maintenance and complexity. (This would be the same issue if we started with plugins and then added external DCS-gRPC clients)

Agree. An alternative could be that we integrate TTS/SRS into the server itself. As we already know that there are multiple potential users of that. I don't mind too much making DATIS a standalone program or self-starting DLL. I just don't see it using an TTS/SRS integration that needs to be started as a separate program.

However none of the above are deal-breakers and it could well be down to personal preference of the server owners but again I worry about added complexity "This thing is a separate client, this thing is a plugin, they are completely different in how they are installed and managed"

In case this helps, I'd define a plugin as a client that, besides being a client itself, also extends the gRPC server by additional services. So at least it wouldn't be a completely different thing. E.g. it would still communicate with the server through the gRPC endpoint every other client uses (ignoring the DDL FFI communication mentioned as one of the possible implementations).

My absolute main concern is that there does not become API fragmentation with multiple ways of communicating with DCS-gRPC clients / plugins from the DCS mission environment (or, indeed other clients) and especially that we avoid coupling between any of the parts (MSE, Client, Plugin).

Currently we can communicate with a DCS-gRPC client from the MSE using events. The MissionCommand APIs are the first step along those lines and I am considering having a "generic" event that can be emitted from the MSE with scripts.

  message ScriptEvent {
    string publisher = 1;
    string name = 2
    google.protobuf.Struct details = 3;
  }

if (GRPC is not nil) then
 local event = {
   type = "scriptEvent",    -- Defined in DCS-gRPC
   publisher = "scriptName" -- All scriptEvents will have a publisher field which should be the name of the script. Used by clients to filter out events from scripts they don't care about. Also avoids possible conflicts in event names.
   name = "someEventName"   -- Unique event name. Allows the client to identify the exact event.
   details = {
     -- Add your event specific information here
   }
 }
 GRPC.event(event)
end

The advantage of events is that they are essentiall a PubSub system fan out to all clients (and plugins) and completely uncouple the processors of the events from the publisher. This could be a great advantage if you have, for example, one client that processes the event that affects the mission while another performs some sort of event logging to Discord or something like that.

While I liked using google.protobuf.Struct for the command API, I'd personally prefer to get back to properly typed messages for plugins. At least for plugins that are potentially used by multiple clients (e.g. TTS-SRS integration). I wouldn't mind it too much for "end-users" like DATIS.

What I'd be missing though is the possibility to receive a response, as the event is basically just a fire and forget.

Having a specific GRPC.plugin("example", {greet = { name = "Someone" }}) would mean that we now have an API that is plugin specific and has to be maintained by the script writer in case they replace one plugin with another or someone wants to write another plugin that should be called at the same time.

I understand the concern, and am not entirely happy with GRPC.plugin myself, but am lacking better ideas for now. The only idea I had was to simply expose the whole gRPC server from the Lua side. But it felt strange exposing it as most of its functions just call back to Lua anyway.

However, I also think that the concerns apply the same to GRPC.scriptEvent. Its usage would also end up being plugin specific.

I realise that this makes plugins that have synchronous APIs that return values to the MSE almost impossible to implement but my thought is that if there is so much custom logic coupling between a specific lua script and a plugin then they should just be bundled together and not use DCS-gRPC at all.

For DATIS it would be useful to receive a response when creating a station to allow interacting with the station in subsequent calls, see #130 (comment).

---

In summary:

• Integrating the TTS-SRS integration into the gRPC server could be an alternative solution (with other/new concerns though)
• GRPC.plugin() isn't a great way to expose plugins to Lua, we/I might have to come up with a better idea

[rkusa]

For reference, here are the main use-cases I have in the back of my mind when thinking about plugins:

1. DATIS

A service where a client can create new ATIS or other broadcast stations (weather, carrier, ...). Upon creation, the client receives an ID for the station that can be used for subsequent interactions with the station. Interactions like: pausing, stopping, changing the coalition, etc.

The SRS-TTS used by DATIS would be another generic plugin, see next use-case.

This needs:

• Cross-plugin communication (DATIS calls the generic SRS-TTS service)
• Request and Responses (as the service returns an station ID; only other option would be if the client must dictate its own ID on station creation)

What I want from it:

• To automatically start and stop with DCS
• A way to call it from Lua (to make it easier to add it to every training mission of my squadron without having to change a client/plugin)

2. Generic SRS-TTS service

A service where a client can send text, a frequency (and other optional parameters like name, coalition, ...) to. The text is then converted to speech (using either the windows TTS, AWS, GCloud or Azure) and broadcasted on the provided frequency on SRS (either once, or in a loop).

This needs:

• A way to receive calls (or events) dedicated for this plugin that are then send to SRS

What I want from it:

• To automatically be available without me having to start and manage yet another program on my server

3. Mission scenario specific SRS voice calls

Using the above SRS-TTS, I am thinking about integrating this into mission I have. E.g. to call out on SRS things like Enfield 1-1, you are cleared hot.

This needs:

• A way to call the SRS-TTS plugin

What I want from it:

• A way to call it from Lua (to easily trigger it from DCS trigger zones without having to change a plugin/client)

[rkusa]

All of https://github.com/DCS-gRPC/rust-server/blob/main/protos/dcs/custom/v0/custom.proto would IMO also be good candidates for plugins:

• RequestMissionAssignment, JoinMission, AbortMission, GetMissionStatus - a plugin by/for DCT (matches my previous concerns to have something like this in core; cc @rurounijones)
• GetMagneticDeclination - a plugin to get the magnetic declination (I am also fine with keeping it in the core, but it is one of our few functions that are an extension to what DCS provides as there is no Lua API to get the declination, it is calculated outside of DCS)
• Eval - potential candidate for a plugin as not enabled by default anyway and because it also required to add a dedicated option to enable/disable it (which could be replaced by a generic install / uninstall it)

[rurounijones]

I am going to put a big comment regarding plugins generally but to specify on this point. I agree with the above suggestions but if we do go with a plugin route then we absolutely have to provide a plugin template repo, with instructions, that people can copy so that they just have to define the proto, rust boilerplate and lua (maybe, I will touch on this later if we go with the plugin route) just like we do now in the main repo when we add an API, it should be as easy as it is now.

Requiring anyone who wants to add custom stuff to DCS-gRPC to write the entire plugin structure, including the stuff that gets compiled to the DLL, would be a huge barrier to entry.

[rurounijones]

Use-cases and services. Now and for future. Very SRP (Single Responsibility focused) with individual services or plugins handling different tasks. Importantly something like SRS-TTS service mentioned above would not exist but be broken down into individual services.

1. SRS STT

A client (or plugin) that can be commanded to listen to a specific frequency on SRS, performs STT and emits an event that contains the transcribed text along with frequency information

This needs:

• A way to be commanded to listen to a specific frequency via API or event
• A way to emit an event into the event stream from a client / plugin.

2. DCS Voice STT

A client (or plugin) that can be commanded to listen to a specific frequency on the built-in DCS Voice comms, performs STT and emits an event that contains the transcribed text along with frequency information

This needs:

• A way to be commanded to listen to a specific frequency via API or event
• A way to emit an event into the event stream from a client / plugin.

3. SRS Transmitter

A client (or plugin) that transmits audio data on the specified SRS frequency via API call or event

4. DCS Voice comms Transmitter

A client (or plugin) that transmits audio data on the specified DCS Voice comms frequency (or room) via API call or event

5. TTS

A client (or plugin) that receives text and performs TTS. it does not transmit the data but publishes an event with the audio data, and potentially, frequency information, for transmitter services.

This needs:

• An API or event processing that system that receives requests for TTS along with frequency info
• A way to emit an event into the event stream from a client / plugin.

6. OverlordBot Core

Receives STT transcription events or F10 command events, performs the language recognition and then emits an TTS event so the other services can then do TTS and transmit. This allows me to remove all audio processing from OverlordBot and instead reuse the other services.

7. STT Display

Have a service that will display the transcriptions from the STT services to a player that opts in to it via the F10 menu. This allows deaf players to read voice chat. I already have a user who is using some hacked-up code to do this in a less integrated manner.

8. SRS Server events

I would like to modify the SRS server to push events into the DCS-gRPC event stream for things like users joining the server, their tuned radio frequencies etc. for things like Overlordbot, Event loggers and the like. Ciribob has already given his approval of this idea.

9. Event logger(s)

Clients or plugins that listen to the Event stream and do stuff with the data. Post to Discord, upload metrics to a metrics server etc.

Vision

My goal is to maximise code-reuse and remove coupling to enable maximum flexibilty and allowing people to swap out clients or plugins that can do the same thing but might suit their purposes better.

It can also be exclusively event based which aids in removing the coupling but synchronous APis are available. There are a few major changes we would need to do;

1. The Event stream, which currently only really handles DCS events, becomes the generic message bus for all events related to the server
2. Clients and plugins must be able to post to this event stream. probably using a DCS-gRPC streaming API where the client streams events rather than converting the event-stream into a bi-directional one (although that is not out of the question)
3. Plugins, if we use them, must an event based system and synchronous API where both are possible.

I cannot think of a good way to have clients accept synchronous APIs so I think they are just going to have to be second-class citizens is we want to initiate things from inside the DCS SSE. However I still think that for the example given where we want to transmit a message from inside the SSE then we emit an event rather than call a named plugin.

This is my not too organised initial set of thoughts. I think an online session in Discord and a whiteboard would be the best way to proceed from here to hammer things out.