Kraigie/nostrum

Nostrum is an Elixir library that provides a client for the Discord API, enabling developers to build bots with support for REST interactions, gateway events, and voice connections. It features a modular architecture with pluggable caching and storage backends, allowing for flexible data persistence strategies across guilds, members, and messages. The system handles modern Discord features such as application commands, auto-moderation, and polls, while managing low-level details like rate limiting, shard management, and voice encryption.

17 changes.

The project transitioned from the legacy Mixcord library to the Nostrum v0.11.0 release, upgrading to Discord API v10 and Elixir 1.15+. This period involved a comprehensive architectural refactor, including the introduction of multi-bot support, a pluggable ETS-based caching system, and a modular REST API layer using the Gun HTTP client. The work also focused on expanding struct definitions to cover new Discord features like Application Commands, AutoModeration, and Forum Channels, while removing all legacy code and dependencies.

12 changes.

This period focused on a complete rewrite of the voice module to support Discord's v8 gateway protocol and modern encryption standards, alongside the introduction of pluggable cache backends for users, guilds, and presence data. Significant effort was also dedicated to expanding test coverage across core components and adding support for new Discord interaction features like modals and select menus.

19 changes.

This period focused on overhauling the library's internal state management by introducing pluggable, per-bot stores and dedicated caching backends (ETS and Mnesia) for guilds, members, and messages. Significant performance improvements were achieved through native Erlang QLC optimizations for message queries and expanded support for voice encryption algorithms and gateway compression.

The channel-to-guild mapping cache now supports three backends: an ETS-based implementation for in-memory caching, an Mnesia-based implementation for persistent storage (available when the Mnesia application is loaded), and a NoOp implementation that discards all changes. Each backend is implemented as a supervisor that manages its own named table, with table names scoped to the bot instance via the bot name. This allows users to choose the appropriate persistence strategy for their deployment needs.

_lib/nostrum/cache/channel\_guild\mapping · high confidence

Added new structs to represent Discord poll data: \Nostrum.Struct.Message.Poll.Answer\ for individual poll answers, \Nostrum.Struct.Message.Poll.MediaObject\ for text and emoji display objects, and \Nostrum.Struct.Message.Poll.Results\ for poll outcome data including vote counts and finalization status. These structs enable parsing and encoding of poll-related information in messages.

lib/nostrum/struct/message/poll · high confidence

New structs have been introduced to support the Guild Scheduled Events API: \Nostrum.Struct.Guild.ScheduledEvent.EntityMetadata\ now represents additional metadata for events (specifically the \location\ field required for external events), and \Nostrum.Struct.Guild.ScheduledEvent.User\ models a user subscribed to a scheduled event, including their guild member context. These additions enable proper parsing and encoding of scheduled event details and attendee information.

_lib/nostrum/struct/guild/scheduled\event · high confidence

The library now supports decompressing Discord gateway events using zlib or zstd compression algorithms. This change introduces an internal compression behavior and specific implementations for zlib (using the standard library) and zstd (using the optional :ezstd dependency), allowing the client to handle compressed WebSocket frames more efficiently.

lib/nostrum/shard/session · high confidence

The voice module has been completely rewritten to support Discord's v8 voice gateway protocol, introducing full compatibility with modern encryption modes including AEAD-AES256-GCM, AEAD-XChaCha20-Poly1305, and XSalsa20-Poly1305 (with RTP-size variants). This update adds support for DAVE (Discord Audio Voice Encryption) for secure audio transmission, integrates native Opus encoding/decoding via the new Nostrum.Voice.Opus module, and replaces the previous port management with a custom GenServer-based port handler for safer process lifecycle management. Users can now stream audio via ffmpeg, youtube-dl, or streamlink, with configurable audio timeouts, frames-per-burst settings, and automatic handling of RTP header extensions and duplicate packet filtering. The voice session management now uses DynamicSupervisor for better resilience, and new events like VoiceReady and SpeakingUpdate (with timeout support) are dispatched to consumers.

lib/nostrum/voice · high confidence

The library now supports Discord's newer interaction components, allowing users to build richer UIs. This includes dedicated structs and helper functions for new select menu types (User, Role, Mentionable, and Channel selects) alongside the existing String Select, as well as support for Modal components via the new TextInput struct. Action rows have been updated to accept these new component types, and the Option struct has been enhanced to handle emojis correctly.

lib/nostrum/struct/component · high confidence

The library now parses additional Discord message fields into dedicated structs, allowing users to access rich presence activities, application details, message references, and reactions. It introduces full support for message components (buttons, select menus, and text inputs) including multi-select values, and adds a new Poll struct with helper methods to create and manage polls. Attachment structs have been updated with newer fields like title, description, and ephemeral flags.

lib/nostrum/struct/message · high confidence

The library now includes comprehensive struct definitions and parsing logic for new Discord API v8 capabilities, specifically Application Commands (slash commands, context menus, and autocomplete), AutoModeration rules and actions, and Message Components (buttons, select menus, and modals). This change also introduces updated Channel structs to support new types like threads and forums, and refactors Embed structs to use builder functions and behaviors for easier construction.

lib/nostrum/struct · high confidence

This change introduces the Nostrum library, an Elixir client for the Discord API, replacing the previous 'Mixcord' project. It provides a REST API with ratelimiting, local caching with multi-node distribution, and voice data support. The release includes a new MIT license, a CONTRIBUTING guide, and a \.dialyzer\_ignore\ file to handle static analysis warnings for specific modules like interaction handling, shard sessions, and test utilities.

(repo-wide) · high confidence

The message cache now supports an Mnesia-backed implementation (Nostrum.Cache.MessageCache.Mnesia) that stores messages in a local database with configurable limits (default 10,000 messages) and batch eviction of the oldest records (default 100) when the limit is reached. Users can customize the cache via configuration options including size\_limit, eviction\_count, table\_name, compressed storage, and table type (:set or :ordered\_set). A no-op cache implementation (Nostrum.Cache.MessageCache.Noop) is also provided for environments where caching is not desired, returning not\_found errors for all retrieval operations.

_lib/nostrum/cache/message\cache · high confidence

The user cache now supports multiple storage backends, allowing users to choose between an in-memory ETS cache, a persistent Mnesia cache, or a NoOp implementation that disables caching entirely. This change replaces the previous single implementation with a behavior-based architecture, enabling users to configure the caching strategy via the bot's supervision tree options while maintaining the same public API for retrieving, creating, updating, and deleting user data.

_lib/nostrum/cache/user\cache · high confidence

Added three new documentation cheat sheets to the guides directory: \api.cheatmd\ provides examples for sending messages, handling embeds, uploading attachments, replying, creating polls, reacting, updating bot status, and creating guild emojis via the \Nostrum.Api\ module; \telemetry.cheatmd\ documents the optional telemetry events emitted by the API, ratelimiter, and gateway for monitoring and debugging; and \voice.cheatmd\ covers playing audio via the \Nostrum.Voice\ module, including methods for handling connection readiness, configuring volume, setting start positions and durations, and applying advanced FFmpeg filters.

guides/cheat-sheets · high confidence

The library now includes a dedicated member cache with three selectable backends: an ETS-based cache for in-memory performance, an Mnesia-based cache for persistent storage (available if Mnesia is installed), and a NoOp cache for users who do not need to cache member data. These implementations replace the previous generic caching approach for guild members, providing specific optimizations such as ETS safe\_fixtable for query safety and Mnesia transactional writes, while maintaining a consistent interface for retrieving, creating, updating, and deleting member records.

_lib/nostrum/cache/member\cache · high confidence

Added three new example files in the examples directory: audio\_player\_example.ex demonstrates playing audio via Discord voice connections using application commands; cache.ex shows how to use GuildCache and UserCache with API fallbacks for a userinfo command; and event\_consumer.ex provides a basic bot structure handling message events like ping and sleep. These examples illustrate the new consumer behavior and supervisor setup patterns.

examples · high confidence

Added a new \Nostrum.Struct.Guild.Member.Flags\ module that represents specific guild member flags (such as \did\_rejoin\, \completed\_onboarding\, \bypasses\_verification\, and \started\_onboarding\) and provides \from\_integer/1\ and \to\_integer/1\ functions to convert between these flag structs and the integer values received from the Discord API.

lib/nostrum/struct/guild/member · high confidence

This change introduces a suite of new structs in the \lib/nostrum/struct/guild\ directory to support recent Discord API features. Users can now access guild audit logs via \Nostrum.Struct.Guild.AuditLog\ and \Nostrum.Struct.Guild.AuditLogEntry\, which parse log entries, affected users, and webhooks. Guild integrations are now represented by \Nostrum.Struct.Guild.Integration\ (including nested \Account\ and \Application\ structs), allowing inspection of connected services. Scheduled events are handled by \Nostrum.Struct.Guild.ScheduledEvent\, which converts ISO8601 timestamps into \DateTime\ objects for start and end times. Additionally, new structs for guild bans (\Nostrum.Struct.Guild.Ban\), system channel flags (\Nostrum.Struct.Guild.SystemChannelFlags\), and unavailable guilds (\Nostrum.Struct.Guild.UnavailableGuild\) have been added to provide structured access to these specific data types.

lib/nostrum/struct/guild · high confidence

Added two new Mix tasks to the library. \mix gh.docs\ automates the process of generating documentation and pushing it to the GitHub Pages branch. Additionally, \mix nostrum.update\_api\_functions\ provides an automated migration tool that updates deprecated \Nostrum.Api\ function calls in user code to their new module-specific equivalents (e.g., moving message operations to the \Message\ module), though users are advised to manually update module aliases and back up their code before running this task.

lib/mix · high confidence

The library now provides dedicated structs for a wide range of Discord gateway events, including AutoModeration rule executions, channel pin updates, guild bans and integrations, invite creation and deletion, message deletions (single and bulk), reaction changes, poll vote changes, thread synchronization and membership updates, typing indicators, and voice state/ready/server updates. These structs normalize incoming gateway payloads by converting string keys to atoms, casting ID fields to Snowflakes, parsing timestamps to DateTime objects, and embedding related objects (such as Users, Members, Channels, and Emojis) as typed structs, ensuring consistent and type-safe event handling for users.

lib/nostrum/struct/event · high confidence

The presence cache now supports pluggable storage backends, allowing users to choose between an in-memory ETS implementation, a persistent Mnesia implementation, or a NoOp mode that disables caching entirely. This change introduces new modules (\Nostrum.Cache.PresenceCache.ETS\, \Nostrum.Cache.PresenceCache.Mnesia\, and \Nostrum.Cache.PresenceCache.NoOp\) that implement the \PresenceCache\ behavior, enabling distributed or persistent presence data storage depending on the selected backend.

_lib/nostrum/cache/presence\cache · high confidence

The \Discord\ module, which previously provided a basic HTTP client for interacting with the Discord API v6, has been removed from the codebase. This change eliminates the unused dependency and associated routing functions, simplifying the library by discarding the hardcoded base URL, authorization header logic, and response parsing that were no longer in use.

lib/discord · high confidence

The \Message\ struct, previously defined in \lib/mixcord/message.ex\ with \id\ and \username\ fields, has been removed from the codebase. This change eliminates the legacy data structure used for representing messages within the Mixcord library.

lib/mixcord · high confidence

The \lib/mixcord.ex\ file has been removed. This file previously contained a hardcoded example script that started the Discord application and made a direct HTTP request to fetch channel data using HTTPoison. Users relying on this module for quick prototyping or as a starting point for integration will no longer have this example available in the library code.

lib · high confidence

The REST API implementation has been restructured to use a new \Nostrum.Api.Adapter\ module for handling HTTP requests via the \:gun\ client, replacing the previous JSON parsing logic with \Jason\. Endpoint logic has been decomposed into dedicated modules (e.g., \ApplicationCommand\, \AutoModeration\, \Channel\, \Guild\, \Interaction\, \Invite\, \Message\, \Poll\), providing a cleaner, organized interface for interacting with Discord's API endpoints.

lib/nostrum/api · high confidence

The voice encryption subsystem now fully supports AES-256-GCM, XChaCha20-Poly1305, and XSalsa20-Poly1305 modes. New internal modules (Aes, Chacha, Salsa) handle these algorithms, leveraging Erlang's :crypto NIFs for AES and ChaCha, and the external Salchicha library for XSalsa20, while optimizing performance by reducing binary copies and binding crypto functions at compile time.

lib/nostrum/voice/crypto · high confidence

The caching system has been refactored into a modular, pluggable architecture where each cache type (guilds, members, users, presences, messages, and channel-guild mapping) is handled by its own dedicated module. By default, these caches now use ETS tables for performance, with the message cache disabled by default to save memory. Users can override the implementation for any cache type via compile-time application configuration, and each cache instance is now started as a named child under a per-bot supervisor, ensuring isolation between multiple bots.

lib/nostrum/cache · high confidence

Nostrum now uses a new, configurable store architecture for internal state that is isolated per bot instance. This change introduces \Nostrum.Store.GuildShardMapping\ to track which shard handles which guild, and \Nostrum.Store.UnavailableGuild\ to track guild availability status. Both stores support pluggable backends—defaulting to ETS but allowing Mnesia or custom implementations via compile-time configuration (\:stores, :guild\_shard\_mapping\ and \:stores, :unavailable\_guilds\). The store processes are now supervised under \Nostrum.Store.Supervisor\ and named per bot, ensuring that multi-bot setups do not share state.

lib/nostrum/store · high confidence

The application configuration has been updated to use the modern \import Config\ syntax, replacing the deprecated \use Mix.Config\. This change includes adding metadata (shard, guild, channel, bot) to the console logger and configuring Nostrum's message cache with a no-op implementation and specific limits for the test environment. Additionally, a new Credo configuration file has been introduced to enforce code consistency and readability standards across the codebase.

config · high confidence

The message cache now uses native Erlang QLC (Query List Comprehension) operations for specific lookup patterns, bypassing the performance overhead of recompiling Elixir-based queries. This change introduces new Erlang modules to handle efficient, index-aware scanning for operations such as retrieving messages by channel, by author, or by channel and author within specific ID ranges, ensuring faster response times for these cache lookups.

src · high confidence

The library introduces three new exception modules—Nostrum.Error.ApiError, Nostrum.Error.CacheError, and Nostrum.Error.VoiceError—to provide more specific and informative error handling. ApiError now captures HTTP status codes and detailed Discord API responses, including nested error structures, allowing users to distinguish between network failures and specific API errors. CacheError exceptions now explicitly identify the missing finding or key and the cache name involved, improving debugging for cache-related issues. VoiceError exceptions now specify the reason for failure and the affected executable (e.g., ffmpeg, youtube-dl), aiding in troubleshooting audio playback problems.

lib/nostrum/error · high confidence

This release upgrades the Discord API and Gateway to version 10, adding support for new platform features including AutoMod, Sticker Packs, Polls, Forum Channels, and Guild Scheduled Events. The library introduces a new \Nostrum.Bot\ module, allowing multiple bots to be started and managed within a single supervision tree with automatic context resolution, replacing the previous single-bot application configuration. The HTTP client has been switched to \:gun\ for improved WebSocket and HTTP performance, and the library now requires Erlang/OTP 25.1 or newer.

lib/nostrum · high confidence

The guild cache system has been refactored to support pluggable backends, allowing users to choose between an ETS-based cache (the default), an Mnesia-based cache for distributed persistence, or a NoOp cache that discards data. This change replaces the previous QLC-based implementation and introduces a shared base module for common upsert logic. The new architecture ensures that operations like role creation and updates correctly return the guild ID alongside the role data, and adds support for caching stickers and emojis. Users can now configure their bot's guild caching strategy via the cache module selection, with the ETS implementation providing high-performance in-memory storage and the Mnesia implementation offering transactional durability.

_lib/nostrum/cache/guild\cache · high confidence

The shard subsystem now includes a dedicated connector process to manage connection timing and concurrency limits, ensuring the bot respects Discord's session start limits before connecting. The event pipeline has been restructured into a state machine-based session that handles gateway protocols (identify, resume, heartbeat) and routes incoming events through a new dispatch module. This module converts payloads, updates internal caches, and asynchronously sends events to user-defined consumers, supporting a wide range of Discord API events including auto-moderation, threads, and polls.

lib/nostrum/shard · high confidence

Added embed struct and gateway payload stubs for testing; Added meta-tests for cache and store implementations; Added microbenchmarks for Guild and Member caches; Added test infrastructure and coverage for core Nostrum components; Added tests for Mnesia message cache implementation; Added tests for Poll helper methods; Added tests for Sticker Pack struct; Added tests for User Flags serialization; Added tests for guild member flags; Added tests for guild member, role, and system channel flags structs; Added tests for shard dispatch and gateway intents; Added tests for voice encryption modules; Added unit tests for Nostrum struct modules; Added unit tests for the API ratelimiter.

The project has been renamed from Mixcord to Nostrum and bumped to version 0.11.0-dev, requiring Elixir 1.15 or higher. This update replaces the HTTP client from HTTPoison to Gun (upgraded to 2.1.0) and the JSON library from Poison to Jason. The dependency list has been significantly expanded to include development and tooling packages such as Credo (1.7.12), Dialyxir (1.4.5), ExDoc (0.37.2), Benchee, Recon, and Salchicha for voice cryptography, alongside runtime dependencies like Telemetry and Ezstd.

(dependencies) · high confidence

Added a README file to the assets directory explaining that it contains media files, specifically noting that propaganda assets are inspired by the 9front project and outlining the requirement for release promotional images in the versions directory.

assets/propaganda · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 63 → 64 (+0.8)
• Rubric changed (rubric-2026.09.15 → rubric-2026.10.1) — scores are not directly comparable.

• Code Health 98 → 98 (-0.1)
• Architecture 84 → 81 (-3.0)
• Maturity 53 → 53 (+0.2)
• Readiness 62 → 64 (+2.0)
• Security 80 → 84 (+4.1)

• Documentation: no architecture or design documentation (README.md)
• Duplicated block (12 lines × 3) (lib/nostrum/cache/guild_cache/ets.ex)
• Duplicated block (33 lines × 3) (lib/nostrum/struct/guild/member/flags.ex)
• Duplicated block (7 lines × 2) (lib/nostrum/struct/component/mentionable_select.ex)
• Duplicated block (9 lines × 2) (lib/nostrum/voice/event.ex)
• Off-boarding risk: anonymized user #1

• Duplicated block (10 lines × 2) (lib/nostrum/voice/event.ex)
• Duplicated block (13 lines × 3) (lib/nostrum/cache/guild_cache/ets.ex)
• Duplicated block (24 lines × 7) (lib/nostrum/struct/embed/author.ex)
• Duplicated block (35 lines × 3) (lib/nostrum/struct/guild/member/flags.ex)
• Duplicated block (7 lines × 3) (lib/nostrum/api/ratelimiter.ex)
• Duplicated block (8 lines × 2) (lib/nostrum/struct/component/mentionable_select.ex)
• Off-boarding risk: anonymized user #1
• Projects may be oversized for their cohesion

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Kraigie/nostrum was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.