[RFC] Serenity as a Collection of Sub-crates

[BastiDood]

Proposal

Serenity is currently packaged as one massive crate that bundles several modules. Each of these modules may be included/excluded via Cargo's feature flags (see example below).

serenity/Cargo.toml

Lines 172 to 188 in f42ec02

	builder = ["utils"]
	cache = ["dashmap", "parking_lot"]
	collector = ["gateway", "model", "rustversion"]
	client = ["http", "typemap_rev"]
	extras = []
	framework = ["client", "model", "utils"]
	gateway = ["flate2", "http", "utils"]
	http = []
	absolute_ratelimits = ["http"]
	model = ["builder", "http"]
	voice_model = ["serenity-voice-model"]
	standard_framework = ["framework", "uwl", "levenshtein", "command_attr", "static_assertions"]
	unstable_discord_api = []
	utils = ["base64"]
	voice = ["client", "model"]
	tokio_task_builder = ["tokio/tracing"]
	time = []

I propose that we modularize Serenity as sub-crates (i.e., serenity-model, serenity-http, serenity-cache, etc.) instead of modules. In doing so, the main serenity crate effectively becomes a "stub crate" which simply re-exports from its sub-crates.

Advantages

• No user-facing breaking changes are necessary.
  • We may simply re-export the sub-crates from the main serenity crate as if they were modules.
• From the consumer's perspective, dependencies can be made on specific sub-crates.
  • We no longer have to download the entire repository of module source files.
  • If we aim to target only one feature (e.g., the data models), we may opt to just directly depend on the sub-crate (i.e., serenity-model) rather than the serenity crate proper.
• Sub-crate compilation may be further parallelized.
  • This is because serenity will no longer be just a single compilation unit.
  • Cargo may freely compile sub-crates in parallel as long as dependencies are preserved.
• Greater flexibility in patch releases.
  • Sub-crates no longer have to wait for a proper release of the main serenity crate to be bumped.

Disadvantages

• Certain optimizations (e.g., function inlining) may be less visible to the compiler by default (via cargo build --release) when compiling sub-crates (i.e., separate compilation units).
  • This may be alleviated with link-time optimization.
• More crates to publish per release.
  • This may be automated if it becomes too cumbersome.
• More dependencies to keep track of.
  • Each sub-crate maintains its own list of dependencies, which must be upgraded separately.
  • This may be alleviated by workspace dependencies.

Prior Art

• Twilight - Powerful, flexible, and scalable ecosystem of Rust libraries for the Discord API.
• futures-rs - Zero-cost asynchronous programming in Rust.
• Gloo - A modular toolkit for building fast, reliable Web applications and libraries with Rust and WASM.
• Bevy - A refreshingly simple data-driven game engine built in Rust.