API Design

[quackduck]

API Design

[CodeLongAndProsper90]

I think that having plugins be spawned as children and passing messages across the child's stdin/stdout is the simplest way to do it. Example session:

< { 'action': 'register_cmd', 'name': 'hello', 'usage': 'hello <world>', 'args': [] }
> { 'event: 'command', 'invoker': { 'name': 'John Doe', 'id': '314159' }, 'args': [] }
# processes event
< { 'action': 'send_msg', 'to': '314159', 'text': 'Hello, World!' }

actions:

• register_cmd
• register_listener
• send_msg
• set_nick
• set_color
• set_pronouns
• get_nick
• get_color
• get_pronouns

events:

• msg
• join
• kick

[Merlin04]

For reference here's the API design idea I came up with on the slack. It's missing some important things but it covers most of the core features (like events and middleware):

Actions

 register_cmd(name: string)
 send_message(from?: string, ephemeral?: bool)
 send_image(src_type: "file" | "url" | "b64", src: string)
 register_listener(event: "send" | "something else?", middleware?: bool, once?: bool)
 mw_edit_message(text?: string)
 mw_done()

Messages

 event(name: string, data?: object)
 cmd(name: string, args: string)

The actual data format would look something like

 {
     type: string,
     args: object
 }

You could also batch actions in a single communication by putting them in an array

If middleware is enabled for an event listener the server will not proceed with sending the message until mw_done is called, and once just makes the listener only fire for the next event (useful for bots)

[Merlin04]

@quackduck I've heard gRPC is good for efficient inter-process communication but I have no idea how practical it is/how easy it is to integrate with plugins

[quackduck]

IIRC you wanted this to use gRPC, right?

[Merlin04]

It also might be a good idea to consider versioning the API, so plugins can detect breaking changes

[quackduck]

🎉 current solution: 3025512

(Thanks Benjamin!)