DiscSharp.Voice 0.1.0-preview.7

DiscSharp

DiscSharp is a .NET 10 Discord library built for people who care about production behavior: typed REST clients, observable Gateway orchestration, transport-neutral interaction handling, modern Components V2 payloads, and an active voice/DAVE implementation track.

The point is simple: Discord libraries should not make production feel like archaeology. DiscSharp favors explicit contracts, typed payloads, composable modules, rate-limit discipline, and diagnostics that tell you what actually happened.

What We Have Built

DiscSharp is no longer just scaffolding. The current repo contains real library surface across the major Discord bot layers:

• DiscSharp.Rest: Discord API v10 routes, bot-authenticated clients, interaction callbacks/followups, webhook execution, multipart upload support, application command sync, component models, typed guild channel/role/community write surfaces, permission bitfields, signature verification, token redaction, and bucket-aware rate-limit coordination.
• DiscSharp.Gateway: identify/resume lifecycle support, heartbeat and ACK watchdogs, typed dispatch envelopes, ordered multi-handler fan-out, session-start coordination, zlib payload decompression, reconnect behavior, and telemetry seams.
• DiscSharp.Application: a transport-neutral interaction pipeline with modules, preconditions, middleware, response plans, deferred response writing, and REST-backed response adapters.
• DiscSharp.Voice: voice gateway/UDP/RTP primitives, modern AEAD transport encryption paths, DAVE protocol models, libdave-backed native MLS/frame-transformer integration, and packaged Windows/Linux x64 native libdave assets.
• DiscSharp.UI: a Blazor control surface with Bot Studio, component lab, REST explorer, gateway viewer, status monitoring, and shared UI primitives.
• Feature packs: Raid Manager and Music Player packs that show how bot functionality can be shipped as composable modules instead of copy-pasted command handlers.

Why It Is Different

DiscSharp is being designed around the things that usually hurt later:

• Rate limits are first-class, including Discord retry_after handling and seams for distributed state.
• Interaction and webhook tokens are redacted from diagnostic paths, logs, exceptions, and route keys.
• Gateway handlers are orchestrated instead of fired into the dark.
• Interactions run through a real pipeline, so preconditions, middleware, failures, and response writing have clear ownership.
• Guild-facing REST stays typed too: channel creation, role mutation, permission overwrites, welcome screens, onboarding writes, and auto-moderation all have request/response models instead of anonymous payloads.
• DAVE failures are not hidden behind generic native errors; native MLS failure data and named result codes flow back into managed diagnostics.
• Receive-side DAVE frame transformation tracks sender-specific decryptor state, which is the shape needed for multi-user voice instead of one shared receive ratchet.
• The repo has a production verification script, focused unit tests, native load tests, and a real Discord smoke harness.

Current Verification

The current hardening pass has been validated with:

.\scripts\verify-production.ps1

That gate restores, builds, tests, packs, and runs repository hygiene checks. The latest local run passed REST, Gateway, Application, Voice, build, and pack verification.

Native DAVE loading has also been checked on both Windows and Linux/WSL:

• src/DiscSharp.Voice/runtimes/win-x64/native/libdave.dll
• src/DiscSharp.Voice/runtimes/linux-x64/native/libdave.so

Real Discord smoke testing has been run against a configured guild/application for:

• application lookup
• bot user lookup
• guild lookup
• channel lookup
• guild command listing
• temporary guild command create/delete
• Components V2 message create/delete

The smoke harness also handles Discord 429 Too Many Requests responses using the API's retry_after value instead of guessing.

See docs/production-verification.md and docs/components-v2-smoke-tests.md.

What We Are Working On

DiscSharp is moving toward a public preview with the uncomfortable parts handled openly:

1. Voice/DAVE live validation: prove opcode 28 commit/welcome handling, sender transitions, reconnect behavior, and encrypted audio behavior against real Discord voice sessions.
2. Multi-user DAVE testing: validate the per-sender decryptor model with controlled multi-bot or real participant voice fixtures.
3. Distributed production paths: run live VapeCache-backed rate-limit smoke tests for multi-container REST coordination.
4. REST coverage expansion: continue filling long-tail Discord API routes and payload tests.
5. Gateway event coverage: expand typed event models beyond the current lifecycle and interaction flow.
6. Interaction packages: add richer precondition/middleware packages and more production examples around deferred responses and followups.
7. Docs and samples: keep turning hard-earned behavior into runnable examples instead of folklore.

Quickstart

Reference the layers your app needs:

<ItemGroup>
  <ProjectReference Include="..\DiscSharp.Rest\DiscSharp.Rest.csproj" />
  <ProjectReference Include="..\DiscSharp.Gateway\DiscSharp.Gateway.csproj" />
  <ProjectReference Include="..\DiscSharp.Application\DiscSharp.Application.csproj" />
</ItemGroup>

Wire the core modules with Autofac:

using Autofac;
using DiscSharp.Application.DependencyInjection;
using DiscSharp.Gateway.DependencyInjection;
using DiscSharp.Rest.DependencyInjection;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables()
    .Build();

var builder = new ContainerBuilder();

builder.RegisterInstance<IConfiguration>(configuration)
    .As<IConfiguration>()
    .SingleInstance();

builder.RegisterModule(new DiscordRestModule(options =>
{
    options.UserAgent = "DiscordBot (https://github.com/your-org/your-bot, 1.0.0)";
    options.ApiVersion = 10;
}));

builder.RegisterModule(new GatewayOrchestrationModule(configuration));
builder.RegisterModule(new InteractionPipelineModule(configuration));

await using var container = builder.Build();

Guild-management code should stay typed as well:

using DiscSharp.Rest.Endpoints;
using DiscSharp.Rest.Primitives;

var guilds = container.Resolve<IDiscordGuildsRestClient>();

await guilds.CreateGuildChannelAsync(
    guildId,
    new DiscordGuildChannelCreateRequest
    {
        Name = "raid-briefing",
        Type = 0,
        PermissionOverwrites =
        [
            new DiscordPermissionOverwriteRequest
            {
                Id = new DiscordSnowflake("111111111111111111"),
                Type = DiscordPermissionOverwriteType.Role,
                Allow = DiscordPermissionBitField.FromUInt64(1024),
                Deny = DiscordPermissionBitField.FromUInt64(0)
            }
        }
    );

await guilds.CreateGuildRoleAsync(
    guildId,
    new DiscordRoleRequest
    {
        Name = "Raid Lead",
        Permissions = DiscordPermissionBitField.FromUInt64(8),
        Mentionable = true
    });

await guilds.ModifyOnboardingAsync(
    guildId,
    new DiscordGuildOnboardingRequest
    {
        Enabled = true,
        Mode = DiscordGuildOnboardingMode.Advanced
    });

Add an interaction module:

using DiscSharp.Application.Interactions;

public sealed class HelpInteractionModule : IDiscordInteractionModule
{
    public string ModuleName => "help";

    public int Order => 0;

    public bool CanHandle(DiscordInteractionEnvelope interaction) =>
        interaction.Kind is DiscordInteractionKind.ApplicationCommand &&
        string.Equals(interaction.Name, "help", StringComparison.OrdinalIgnoreCase);

    public ValueTask<InteractionModuleResult> HandleAsync(
        DiscordInteractionEnvelope interaction,
        CancellationToken cancellationToken)
    {
        return ValueTask.FromResult(
            InteractionModuleResult.Respond(
                InteractionResponsePlan.Message("DiscSharp is online.", ephemeral: true)));
    }
}

For the full walkthrough, start with docs/guides/getting-started.md.

Build And Test

dotnet restore .\DiscSharp.slnx
dotnet build .\DiscSharp.slnx -c Release --no-restore
dotnet test .\DiscSharp.slnx -c Release --no-build

For the release gate:

.\scripts\verify-production.ps1

For real Discord smoke tests, create .discord-smoke.env from .discord-smoke.env.example, fill in a bot token/application/guild/channel, then run:

.\scripts\run-discord-smoke-tests.ps1

Do not commit .discord-smoke.env; it is ignored on purpose.

Packages

The repo is structured for both umbrella and layered packages:

• DiscSharp
• DiscSharp.Rest
• DiscSharp.Gateway
• DiscSharp.Application
• DiscSharp.Voice
• DiscSharp.Rest.VapeCache
• DiscSharp.InteractionPacks.RaidManager
• DiscSharp.InteractionPacks.MusicPlayer

Local packing:

dotnet pack .\DiscSharp.slnx -c Release

Packages land in artifacts/packages.

Publishing is handled through GitHub Actions Trusted Publishing in build.yml. Use scripts/release-nuget.ps1 to create the release tag, set the NUGET_USER repo secret to the nuget.org profile name that created the policy, and see docs/nuget-publishing.md for the release path.

Status

DiscSharp is under active development. REST, Gateway, Application, UI, smoke testing, and DAVE/native integration have real code and tests behind them. Voice remains preview until live Discord DAVE/audio validation is complete.

The repo does not hide that line. The goal is to cross it with evidence.

• Current status and roadmap: docs/architecture/status-and-roadmap.md
• Voice/DAVE implementation notes: docs/voice-dave-implementation.md
• Voice production readiness: docs/voice-production-readiness.md

Contributing

See CONTRIBUTING.md. If you care about typed APIs, production diagnostics, Discord edge cases, or making DAVE voice reliability less painful, this is exactly the kind of repo where that work matters.