Design of an wait_for/ EventCollector Feature for Enhanced Discord API Interactions

[nayr7]

Abstract

The goal of this issue is to discuss the design of this feature and provide bot developers with a convenient and self-contained solution to "wait for" specific events during the execution of a control flow without relying on traditional event handlers.

Motivation

To my knowledge, this came up a fair amount of times in the discord server but basically, practical use-cases for this would be:

• Responding to application commands, message components, message/reactions updates, and more.
• Keeping development smooth and user codebase simple: relying on event handlers for everything would complicate the source instead and may even hinder development :(

Currently, users can somewhat cope with the lack of this feature by making it themselves in their code:

# modifed code from xxdicaprioxx on discord: https://play.nim-lang.org/#ix=2tWp

import dimscord, dimscmd, tables, asyncdispatch
type
    Wait = ref object
        eventType: string
        response: Future[string]
        expected: string

var waits: Table[string, Wait]

proc onDispatch(s: Shard, evt: string, data: JsonNode) {.event(discord).} =
    case evt:
    of "MESSAGE_CREATE":
        # If it is a message then check if there is something being awaited in the channel
        if waits.hasKey(data["channel_id"].str):
            let wait = waits[data["channel_id"].str]
            if wait.expected == data["author"]["id"].str:
                wait.response.complete(data["content"].str)
                waits.del(data["channel_id"].str)

    of "MESSAGE_REACTION_ADD":
        # If it is an emoji then check if a message is waiting on a reaction
        let wait = waits[data["message_id"].str]
        if data["emoji"]["name"].str == wait.expected:
            wait.response.complete(data["emoji"]["name"].str)
            waits.del(data["message_id"].str)


proc messageCreate(s: Shard, m: Message) {.event(discord).} =
    if m.author.bot: return
    if m.content == "!echo":
        let sentMessage = await discord.api.sendMessage(m.channelId, "What do you want me to say?")
        let response = await sentMessage.waitFor("MESSAGE_CREATE", m.author.id)
        discard await discord.api.sendMessage(m.channelId, response)

This works for basic and specific usecase but become quickly tedious as you need to handle different kinds of events, falling back to the second bullet point of keeping development smooth and code clean, hence why library support for this feature would be for the best imo.

[krisppurg]

I definitely agree that there should be a waitForEvent, since I was planning to add advanced event handler stuff to dimscord (like eventemitter in javascript but with maybe pragmas). e.g. {.once(discord).}.

Another thing to add here is that the disadvantage of using the onDispatch event is that is emitted before dimscord handles the event e.g. in MESSAGE_CREATE the message is not stored yet on channel.messages. So if you want to waitFor an event that relies a bit on cache and stuff then that could be a problem.

For advanced use-case, as nim is statically-typed I'd say for any generic waitfor event, response could be Future[JsonNode] so it can be any event. So not only expect for m.content but maybe someone might expect m.mentions.len >= 2, another example aside from message_creates is that either the user wants to get guild member by requesting guild members (s.requestGuildMembers), etc.
And with that generic waitfor, I could implement some common waitfor helpers proc that would make it easier for those common use-cases.
example with getting guild members

## inside messageCreate
let guild = s.cache.guilds[m.guild_id.get]
let evt = s.getGuildMembers(guild_id = guild.id, limit = m.member_count.get)
if not withTimeout(evt, 15000): echo "it appears that it is taking long for getting guild members"
let members = (await evt).members

let role_members: seq[Member] = @[]
for member in members:
  if "<insert-role-id>" in member.roles: role_members.add(member)
echo role_members

[nayr7]

Another thing to add here is that the disadvantage of using the onDispatch event is that is emitted before dimscord handles the event e.g. in MESSAGE_CREATE the message is not stored yet on channel.messages. So if you want to waitFor an event that relies a bit on cache and stuff then that could be a problem.

Shouldn't this be a really easy bug to fix ?

# dimscord/gateway.nim
asyncCheck s.client.events.on_dispatch(s, event, data)
asyncCheck s.handleEventDispatch(event, data)

to

# dimscord/gateway.nim
asyncCheck s.handleEventDispatch(event, data)
asyncCheck s.client.events.on_dispatch(s, event, data)

cache is now updated before onDispatch runs.

For advanced use-case, as nim is statically-typed I'd say for any generic waitfor event, response could be Future[JsonNode] so it can be any event. So not only expect for m.content but maybe someone might expect m.mentions.len >= 2, another example aside from message_creates is that either the user wants to get guild member by requesting guild members (s.requestGuildMembers), etc.

I love this ! I also thought of returning Future[JsonNode], it's consistent with what we already do with onDispatch so it only makes sense imo.

Setting aside generic waits, the big challenge is the approach to use to store and retrieve the "waits". Since nim is statically typed this looks like a lot of tables or seq for each type of "waits". Alsofilter/check wont have the same type/argument length, we can just work around that by using either of:

• type variants
• type erasure
• inheritance
  .. or even use some of them at the same time

Consider this:
let waitTable: RefTable[EventKind, Table[string, Wait]]

• waitTable is a global variable that holds a reference to a table
• EventKind is an enum that enumerates all relevant event types as string values, we can match what discord sends us in order to "get" the relevant table.
• string could be a lot of things and we need something reliable in order to know if a Wait is what we really want. Therefore string must be some sort of "hash" (it's probably abusing the word for what we're really doing though) obtained by using channel_id, guild_id and author_id stored in the Wait object when we run a waitFor. When receiving an event, we get channel_id, guild_id author_id in order to get the hash and check if it's present in the table.
  Note: one of channel_id, guild_id author_id might be none(string), hardly an issue though.

This design is almost constant time tmk, it's just checking once for relevant stuff (evt type), get the relevant stuff and checking just once again for relevant stuff (the hash), then checking with filter()/check() the deserialized data.

[krisppurg]

Another thing to add here is that the disadvantage of using the onDispatch event is that is emitted before dimscord handles the event e.g. in MESSAGE_CREATE the message is not stored yet on channel.messages. So if you want to waitFor an event that relies a bit on cache and stuff then that could be a problem.

Shouldn't this be a really easy bug to fix ?

# dimscord/gateway.nim
asyncCheck s.client.events.on_dispatch(s, event, data)
asyncCheck s.handleEventDispatch(event, data)

to

# dimscord/gateway.nim
asyncCheck s.handleEventDispatch(event, data)
asyncCheck s.client.events.on_dispatch(s, event, data)

cache is now updated before onDispatch runs.

Its not a bug or anything it's intended to be in that order since some people could use this event before dimscord handles it which could be useful. I'd recommend the waitForEvent proc to have a handleEvent option so if it's true it could wait for the normal messageCreate event and would do its job, and if false it would just be the normal on dispatch.

Though I think there should be multiple listener support.