Intents and the future of data accuracy

[SinisterRectus]

To the best of my recollection, and as documented, bot developers and community library developers have been encouraged to implement a stateful connection to Discord's gateway to supplement and minimize usage of the HTTP API. In doing so, developers can offer to their users a reasonable guarantee for data to be cached and up-to-date, as long as events are received and tracked (subject to eventual consistency). For data that is not available, a library may emit an exception and/or offer an opportunity for a consumer to fetch the data via HTTP.

With the introduction of intents and feature whitelisting (discord/discord-api-docs#1363 and discord/discord-api-docs#1307), some of these data guarantees are lost. General purpose library and application developers who wish to offer an accurate and total wrapper for the Discord API must now take care to negotiate this new paradigm, without inundating users and dependent bot developers with inaccurate data or exceptions or HTTP fallbacks for data that is no longer guaranteed. We must consider how to access objects and data that may never be received by gateway events and we must consider when and for how long to cache certain objects and data that are received but may never be updated by gateway events.

[SinisterRectus]

If no gateway connection is used, the HTTP API remains the only place to access Discord data. In this case, internal caching should probably be avoided and data persistence left to the user.

If a full gateway connection is used, all objects that are created and updated by the gateway can be safely cached until deleted. Objects that may be numerous should be cached conditionally.

If a partial gateway connection is used (with intents or whitelisting), then caching should either not be used or be used conditionally based on the specific configuration.

[SinisterRectus]

I've flip-flopped on this, but as of now, 3.0 requires a gateway connection and requires that at least the guilds intent be included. Based on this, guilds and their roles, emojis, and channels are the only permanently cached objects and the only objects that may be fetched directly from cache. All others may be weakly cached, may not be cached at all, may never be updated, and may not be accessible by anything other than HTTP request (or gateway request in the case of members).