discord.pony

A Pony library for working with Discord's API.

Features

• API - v10
• Gateway - v10
• Voice - Unsupported!

Installation

• Requires ponyc 0.68.0 or later.
• Install corral
• corral add github.com/vxern/discord.pony.git --version 1.0.0
• corral fetch to fetch your dependencies
• corral run -- ponyc -Dopenssl_3.0.x to compile your application

discord.pony depends on ponylang/ssl. It requires a C SSL library to be installed. Please see the ssl installation instructions for more information.

An SSL version must be selected at compile time, or the build fails with You must select an SSL version to use. Pass -Dopenssl_3.0.x, -Dopenssl_4.0.x, -Dopenssl_1.1.x or -Dlibressl to match the library you have installed.

Packages

The library is split across four packages, and Pony does not re-export across package boundaries, so pull in whichever ones you use:

• use "discord" for Bot, which pairs a REST client with a gateway connection, along with the CDN and message formatting helpers
• use "discord/rest" for Rest, Routes and RestOptions
• use "discord/gateway" for Gateway, Events and GatewayOptions
• use "discord/data" for the Discord objects themselves, such as Snowflake, Message and GatewayIntent

Note that constructing a Bot opens a gateway connection straight away. For REST-only work, construct a Rest on its own.

Working examples live in examples/. Each one reads the bot token from the DISCORD_TOKEN environment variable, so it never lands in the process arguments, where any other user on the machine could read it:

corral run -- ponyc -Dopenssl_3.0.x -o build ./examples/polls
DISCORD_TOKEN=<bot-token> ./build/polls <channel-id>

REST

Transport

• ✅ Connection reuse, with a pool of up to 20 keep-alive connections
  • ✅ Requests held back when every connection is busy, and handed on as one comes free
• ✅ Timeouts
  • ✅ 15s on the connect and the TLS handshake
  • ✅ 30s on the response, so a connection that goes quiet cannot stall a bucket
• ✅ Rate limits
  • ✅ Per-bucket windows, taken from X-RateLimit-Remaining and X-RateLimit-Reset-After
  • ✅ Buckets keyed by Discord's own X-RateLimit-Bucket hash, scoped by major parameter
  • ✅ Global 429 handling, pausing every bucket for as long as the response asks for
  • ✅ 50 requests a second, and the Cloudflare limit of 10,000 in 10 minutes
• ✅ Retries
  • ✅ 3 attempts on 500, 502, 503 and 504, and on a request that never comes back
  • ✅ Exponential backoff with jitter
• ✅ Bounded queues, 1,000 to a bucket and 10,000 across the client
• ✅ Idle buckets swept after 10 minutes, so a long-lived client holds no more than it uses
• ✅ Audit log reasons, on every route that takes one
• ✅ File uploads, as multipart/form-data

Endpoints

• Application Role Connection Metadata
  • ✅ Get Application Role Connection Metadata Records
  • ✅ Update Application Role Connection Metadata Records
• Application
  • ✅ Get Current Application
  • ✅ Edit Current Application
  • ✅ Get Application Activity Instance
• Audit Log
  • ✅ Get Guild Audit Log
• Auto Moderation
  • ✅ List Auto Moderation Rules for Guild
  • ✅ Get Auto Moderation Rule
  • ✅ Create Auto Moderation Rule
  • ✅ Modify Auto Moderation Rule
  • ✅ Delete Auto Moderation Rule
• Channel
  • ✅ Get Channel
  • ✅ Modify Channel
  • ✅ Delete/Close Channel
  • ✅ Set Voice Channel Status
  • ✅ Edit Channel Permissions
  • ✅ Delete Channel Permission
  • ✅ Get Channel Invites
  • ✅ Create Channel Invite
  • ✅ Follow Announcement Channel
  • ✅ Trigger Typing Indicator
  • ✅ Group DM Add Recipient
  • ✅ Group DM Remove Recipient
  • ✅ Start Thread from Message
  • ✅ Start Thread without Message
  • ✅ Start Thread in Forum or Media Channel
  • ✅ Join Thread
  • ✅ Add Thread Member
  • ✅ Leave Thread
  • ✅ Remove Thread Member
  • ✅ Get Thread Member
  • ✅ List Thread Members
  • ✅ List Public Archived Threads
  • ✅ List Private Archived Threads
  • ✅ List Joined Private Archived Threads
• Emoji
  • ✅ List Guild Emojis
  • ✅ Get Guild Emoji
  • ✅ Create Guild Emoji
  • ✅ Modify Guild Emoji
  • ✅ Delete Guild Emoji
  • ✅ List Application Emojis
  • ✅ Get Application Emoji
  • ✅ Create Application Emoji
  • ✅ Modify Application Emoji
  • ✅ Delete Application Emoji
• Entitlement
  • ✅ List Entitlements
  • ✅ Get Entitlement
  • ✅ Consume an Entitlement
  • ✅ Create Test Entitlement
  • ✅ Delete Test Entitlement
• Guild
  • ✅ Get Guild
  • ✅ Get Guild Preview
  • ✅ Modify Guild
  • ✅ Get Guild Channels
  • ✅ Create Guild Channel
  • ✅ Modify Guild Channel Positions
  • ✅ List Active Guild Threads
  • ✅ Get Guild Member
  • ✅ List Guild Members
  • ✅ Search Guild Members
  • ✅ Add Guild Member
  • ✅ Modify Guild Member
  • ✅ Modify Current Member
  • ✅ Modify Current User Nick (deprecated)
  • ✅ Add Guild Member Role
  • ✅ Remove Guild Member Role
  • ✅ Remove Guild Member
  • ✅ Get Guild Bans
  • ✅ Get Guild Ban
  • ✅ Create Guild Ban
  • ✅ Remove Guild Ban
  • ✅ Bulk Guild Ban
  • ✅ Get Guild Roles
  • ✅ Get Guild Role
  • ✅ Get Guild Role Member Counts
  • ✅ Create Guild Role
  • ✅ Modify Guild Role Positions
  • ✅ Modify Guild Role
  • ✅ Delete Guild Role
  • ✅ Get Guild Prune Count
  • ✅ Begin Guild Prune
  • ✅ Get Guild Voice Regions
  • ✅ Get Guild Invites
  • ✅ Get Guild Integrations
  • ✅ Delete Guild Integration
  • ✅ Get Guild Widget Settings
  • ✅ Modify Guild Widget
  • ✅ Get Guild Widget
  • ✅ Get Guild Vanity URL
  • ✅ Get Guild Widget Image
  • ✅ Get Guild Welcome Screen
  • ✅ Modify Guild Welcome Screen
  • ✅ Get Guild Onboarding
  • ✅ Modify Guild Onboarding
  • ✅ Modify Guild Incident Actions
• Guild Scheduled Event
  • ✅ List Scheduled Events for Guild
  • ✅ Create Guild Scheduled Event
  • ✅ Get Guild Scheduled Event
  • ✅ Modify Guild Scheduled Event
  • ✅ Delete Guild Scheduled Event
  • ✅ Get Guild Scheduled Event Users
• Guild Template
  • ✅ Get Guild Template
  • ✅ Get Guild Templates
  • ✅ Create Guild Template
  • ✅ Sync Guild Template
  • ✅ Modify Guild Template
  • ✅ Delete Guild Template
• Invite
  • ✅ Get Invite
  • ✅ Delete Invite
  • ✅ Get Target Users
  • ✅ Update Target Users
  • ✅ Get Target Users Job Status
• Lobby
  • ✅ Create Lobby
  • ✅ Create or Join Lobby
  • ✅ Get Lobby
  • ✅ Modify Lobby
  • ✅ Delete Lobby
  • ✅ Add a Member to a Lobby
  • ✅ Bulk Update Lobby Members
  • ✅ Remove a Member from a Lobby
  • ✅ Leave Lobby
  • ✅ Link Channel to Lobby
  • ✅ Unlink Channel from Lobby
  • ✅ Send Lobby Message
  • ✅ Get Lobby Messages
  • ✅ Update Lobby Message Moderation Metadata
  • ✅ Create Lobby Channel Invite for Self
  • ✅ Create Lobby Channel Invite for User
• Message
  • ✅ Get Channel Messages
  • ✅ Search Guild Messages
  • ✅ Get Channel Message
  • ✅ Create Message
  • ✅ Crosspost Message
  • ✅ Create Reaction
  • ✅ Delete Own Reaction
  • ✅ Delete User Reaction
  • ✅ Get Reactions
  • ✅ Delete All Reactions
  • ✅ Delete All Reactions for Emoji
  • ✅ Edit Message
  • ✅ Delete Message
  • ✅ Bulk Delete Messages
  • ✅ Get Channel Pins
  • ✅ Pin Message
  • ✅ Unpin Message
  • ✅ Get Pinned Messages (deprecated)
  • ✅ Pin Message (deprecated)
  • ✅ Unpin Message (deprecated)
• Poll
  • ✅ Get Answer Voters
  • ✅ End Poll
• SKU & Subscription
  • ✅ List SKUs
  • ✅ List SKU Subscriptions
  • ✅ Get SKU Subscription
• Soundboard
  • ✅ Send Soundboard Sound
  • ✅ List Default Soundboard Sounds
  • ✅ List Guild Soundboard Sounds
  • ✅ Get Guild Soundboard Sound
  • ✅ Create Guild Soundboard Sound
  • ✅ Modify Guild Soundboard Sound
  • ✅ Delete Guild Soundboard Sound
• Stage Instance
  • ✅ Create Stage Instance
  • ✅ Get Stage Instance
  • ✅ Modify Stage Instance
  • ✅ Delete Stage Instance
• Sticker
  • ✅ Get Sticker
  • ✅ List Sticker Packs
  • ✅ Get Sticker Pack
  • ✅ List Guild Stickers
  • ✅ Get Guild Sticker
  • ✅ Create Guild Sticker
  • ✅ Modify Guild Sticker
  • ✅ Delete Guild Sticker
• User
  • ✅ Get Current User
  • ✅ Get User
  • ✅ Modify Current User
  • ✅ Get Current User Guilds
  • ✅ Get Current User Guild Member
  • ✅ Leave Guild
  • ✅ Create DM
  • ✅ Create Group DM
  • ✅ Get Current User Connections
  • ✅ Get Current User Application Role Connection
  • ✅ Update Current User Application Role Connection
  • ✅ Delete Current User Application Role Connection
• Voice
  • ✅ List Voice Regions
  • ✅ Get Current User Voice State
  • ✅ Get User Voice State
  • ✅ Modify Current User Voice State
  • ✅ Modify User Voice State
• Webhook
  • ✅ Create Webhook
  • ✅ Get Channel Webhooks
  • ✅ Get Guild Webhooks
  • ✅ Get Webhook
  • ✅ Get Webhook with Token
  • ✅ Modify Webhook
  • ✅ Modify Webhook with Token
  • ✅ Delete Webhook
  • ✅ Delete Webhook with Token
  • ✅ Execute Webhook
  • ✅ Execute Slack-Compatible Webhook
  • ✅ Execute GitHub-Compatible Webhook
  • ✅ Get Webhook Message
  • ✅ Edit Webhook Message
  • ✅ Delete Webhook Message
• Receiving and Responding
  • ✅ Create Interaction Response
  • ✅ Get Original Interaction Response
  • ✅ Edit Original Interaction Response
  • ✅ Delete Original Interaction Response
  • ✅ Create Followup Message
  • ✅ Get Followup Message
  • ✅ Edit Followup Message
  • ✅ Delete Followup Message
• Application Commands
  • ✅ Get Global Application Commands
  • ✅ Create Global Application Command
  • ✅ Get Global Application Command
  • ✅ Edit Global Application Command
  • ✅ Delete Global Application Command
  • ✅ Bulk Overwrite Global Application Commands
  • ✅ Get Guild Application Commands
  • ✅ Create Guild Application Command
  • ✅ Get Guild Application Command
  • ✅ Edit Guild Application Command
  • ✅ Delete Guild Application Command
  • ✅ Bulk Overwrite Guild Application Commands
  • ✅ Get Guild Application Command Permissions
  • ✅ Get Application Command Permissions
  • ✅ Edit Application Command Permissions
  • ✅ Batch Edit Application Command Permissions
• OAuth2
  • ✅ Get Current Bot Application Information
  • ✅ Get Current Authorization Information
• Gateway
  • ✅ Get Gateway
  • ✅ Get Gateway Bot

Gateway

Connection

• ✅ Identify
• ✅ Resume
• ✅ Heartbeat
  • ✅ Jittered first beat
  • ✅ Acknowledgement tracking, with a reconnect when a beat goes unacknowledged
  • ✅ Out-of-band beats on request (opcode 1)
• ✅ Automatic reconnect
  • ✅ Exponential backoff with jitter, reset once the session settles
  • ✅ Close code handling, staying down on the codes that cannot be recovered from
  • ✅ Session invalidation handling (opcode 9), resuming or re-identifying as instructed
  • ✅ Stage timeouts, so a connect, hello, ready or close that never arrives cannot hang the gateway
• ✅ Send rate limits
  • ✅ 120 commands per 60s, with slots held back for heartbeats
  • ✅ 5 presence updates per 20s
  • ✅ Identify concurrency, taken from max_concurrency
• ✅ 4096-byte payload limit, enforced before the wire
• ✅ 4 MiB receive limit, and a nesting depth limit checked before a frame is parsed
• ✅ Bounded send queue, retained across reconnects
• ✅ Backpressure
• ✅ Session start limit, checked before identifying
• ✅ Sharding
  • ✅ Automatic shard count, taken from Get Gateway Bot
  • ✅ Explicit shard count, and running only a subset so the rest can live in other processes
  • ✅ Identify concurrency shared across shards, bucketed by shard_id % max_concurrency
  • ✅ Guild events routed to the shard that owns the guild
• ❌ Transport compression (zlib-stream, zstd-stream)
• ❌ Payload compression
• ❌ ETF encoding

Send Events

• ✅ Presence Update
• ✅ Voice State Update
• ✅ Request Guild Members
• ✅ Request Soundboard Sounds
• ✅ Request Channel Info

Receive Events

• Lifecycle
  • ✅ Ready
  • ✅ Resumed
  • ✅ Rate Limited
• Application Commands
  • ✅ Application Command Permissions Update
• Auto Moderation
  • ✅ Auto Moderation Rule Create
  • ✅ Auto Moderation Rule Update
  • ✅ Auto Moderation Rule Delete
  • ✅ Auto Moderation Action Execution
• Channel
  • ✅ Channel Create
  • ✅ Channel Update
  • ✅ Channel Delete
  • ✅ Channel Info
  • ✅ Channel Pins Update
• Thread
  • ✅ Thread Create
  • ✅ Thread Update
  • ✅ Thread Delete
  • ✅ Thread List Sync
  • ✅ Thread Member Update
  • ✅ Thread Members Update
• Entitlement
  • ✅ Entitlement Create
  • ✅ Entitlement Update
  • ✅ Entitlement Delete
• Guild
  • ✅ Guild Create
  • ✅ Guild Update
  • ✅ Guild Delete
  • ✅ Guild Audit Log Entry Create
  • ✅ Guild Ban Add
  • ✅ Guild Ban Remove
  • ✅ Guild Emojis Update
  • ✅ Guild Stickers Update
  • ✅ Guild Integrations Update
  • ✅ Guild Member Add
  • ✅ Guild Member Remove
  • ✅ Guild Member Update
  • ✅ Guild Members Chunk
  • ✅ Guild Role Create
  • ✅ Guild Role Update
  • ✅ Guild Role Delete
• Guild Scheduled Event
  • ✅ Guild Scheduled Event Create
  • ✅ Guild Scheduled Event Update
  • ✅ Guild Scheduled Event Delete
  • ✅ Guild Scheduled Event User Add
  • ✅ Guild Scheduled Event User Remove
• Soundboard
  • ✅ Guild Soundboard Sound Create
  • ✅ Guild Soundboard Sound Update
  • ✅ Guild Soundboard Sound Delete
  • ✅ Guild Soundboard Sounds Update
  • ✅ Soundboard Sounds
• Integration
  • ✅ Integration Create
  • ✅ Integration Update
  • ✅ Integration Delete
• Interaction
  • ✅ Interaction Create
• Invite
  • ✅ Invite Create
  • ✅ Invite Delete
• Message
  • ✅ Message Create
  • ✅ Message Update
  • ✅ Message Delete
  • ✅ Message Delete Bulk
  • ✅ Message Reaction Add
  • ✅ Message Reaction Remove
  • ✅ Message Reaction Remove All
  • ✅ Message Reaction Remove Emoji
• Poll
  • ✅ Message Poll Vote Add
  • ✅ Message Poll Vote Remove
• Presence
  • ✅ Presence Update
  • ✅ Typing Start
  • ✅ User Update
• Stage Instance
  • ✅ Stage Instance Create
  • ✅ Stage Instance Update
  • ✅ Stage Instance Delete
• Subscription
  • ✅ Subscription Create
  • ✅ Subscription Update
  • ✅ Subscription Delete
• Voice
  • ✅ Voice Channel Effect Send
  • ✅ Voice Channel Status Update
  • ✅ Voice Channel Start Time Update
  • ✅ Voice State Update
  • ✅ Voice Server Update
• Webhook
  • ✅ Webhooks Update

Objects

• Application
  • ✅ Application
  • ✅ ApplicationIntegrationTypeConfiguration
  • ✅ InstallParams
  • ✅ ActivityInstance
  • ✅ ActivityLocation
• Application Command
  • ✅ ApplicationCommandOptionChoice
  • ✅ ApplicationCommandOption
  • ✅ ApplicationCommandPermission
• Application Role Connection Metadata
  • ✅ ApplicationRoleConnectionMetadata
• Audit Log
  • ✅ AuditLog
  • ✅ AuditLogEntry
  • ✅ OptionalAuditEntryInfo
  • ✅ AuditLogChange
• Auto Moderation
  • ✅ AutoModerationRule
  • ✅ AutoModerationTriggerMetadata
  • ✅ AutoModerationAction
  • ✅ AutoModerationActionMetadata
• Channel
  • ✅ Channel
  • ✅ FollowedChannel
  • ✅ PermissionOverwrite
  • ✅ ThreadMetadata
  • ✅ ThreadMember
  • ✅ DefaultReaction
  • ✅ ForumTag
• Component
  • ✅ ActionRowComponent
  • ✅ ButtonComponent
  • ✅ StringSelectComponent
  • ✅ SelectOption
  • ✅ TextInputComponent
  • ✅ UserSelectComponent
  • ✅ RoleSelectComponent
  • ✅ MentionableSelectComponent
  • ✅ ChannelSelectComponent
  • ✅ SelectDefaultValue
  • ✅ SectionComponent
  • ✅ TextDisplayComponent
  • ✅ ThumbnailComponent
  • ✅ MediaGalleryComponent
  • ✅ MediaGalleryItem
  • ✅ FileComponent
  • ✅ SeparatorComponent
  • ✅ ContainerComponent
  • ✅ LabelComponent
  • ✅ FileUploadComponent
  • ✅ RadioGroupComponent
  • ✅ RadioGroupOption
  • ✅ CheckboxGroupComponent
  • ✅ CheckboxGroupOption
  • ✅ CheckboxComponent
  • ✅ UnfurledMediaItem
• Emoji
  • ✅ Emoji
• Entitlement
  • ✅ Entitlement
• Guild
  • ✅ Guild
  • ✅ GuildPreview
  • ✅ GuildWidgetSettings
  • ✅ GuildWidget
  • ✅ GuildMember
  • ✅ Integration
  • ✅ IntegrationAccount
  • ✅ IntegrationApplication
  • ✅ Ban
  • ✅ WelcomeScreen
  • ✅ WelcomeScreenChannel
  • ✅ GuildOnboarding
  • ✅ OnboardingPrompt
  • ✅ OnboardingPromptOption
  • ✅ IncidentsData
  • ✅ GuildChannelPosition
  • ✅ GuildRolePosition
• Guild Scheduled Event
  • ✅ GuildScheduledEvent
  • ✅ GuildScheduledEventEntityMetadata
  • ✅ GuildScheduledEventRecurrenceRule
  • ✅ GuildScheduledEventRecurrenceRuleNWeekday
  • ✅ GuildScheduledEventUser
• Guild Template
  • ✅ GuildTemplate
• Interaction
  • ✅ Interaction
  • ✅ ApplicationCommand
  • ✅ ApplicationCommandData
  • ✅ ApplicationCommandInteractionDataOption
  • ✅ MessageComponentData
  • ✅ ModalSubmitData
  • ✅ ResolvedData
  • ✅ InteractionResponse
  • ✅ InteractionCallbackResponse
  • ✅ InteractionCallback
  • ✅ InteractionCallbackResource
  • ✅ InteractionCallbackActivityInstanceResource
  • ✅ GuildApplicationCommandPermissions
• Invite
  • ✅ Invite
  • ✅ InviteMetadata
  • ✅ InviteStageInstance
• Lobby
  • ✅ Lobby
  • ✅ LobbyMember
  • ✅ LobbyMessage
• Message
  • ✅ Message
  • ✅ MessageActivity
  • ✅ ApplicationCommandInteractionMetadata
  • ✅ MessageComponentInteractionMetadata
  • ✅ ModalSubmitInteractionMetadata
  • ✅ MessageInteraction
  • ✅ MessageCall
  • ✅ MessageReference
  • ✅ MessageSnapshot
  • ✅ MessageReaction
  • ✅ MessageReactionCountDetails
  • ✅ MessageEmbed
  • ✅ MessageEmbedVideo
  • ✅ MessageEmbedImage
  • ✅ MessageEmbedProvider
  • ✅ MessageEmbedAuthor
  • ✅ MessageEmbedFooter
  • ✅ MessageEmbedField
  • ✅ MessageAttachment
  • ✅ ChannelMention
  • ✅ AllowedMentions
  • ✅ RoleSubscriptionData
  • ✅ MessagePin
  • ✅ SharedClientTheme
• Permission
  • ✅ Role
  • ✅ RoleTags
  • ✅ RoleColors
• Poll
  • ✅ Poll
  • ✅ PollMedia
  • ✅ PollAnswer
  • ✅ PollResults
  • ✅ PollAnswerCount
• Sku
  • ✅ SKU
• Snowflake
  • ✅ Snowflake
• Soundboard
  • ✅ SoundboardSound
• Stage Instance
  • ✅ StageInstance
• Sticker
  • ✅ Sticker
  • ✅ StickerItem
  • ✅ StickerPack
• Subscription
  • ✅ Subscription
• Team
  • ✅ Team
  • ✅ TeamMember
• User
  • ✅ User
  • ✅ AvatarDecorationData
  • ✅ Collectibles
  • ✅ Nameplate
  • ✅ UserPrimaryGuild
  • ✅ Connection
  • ✅ ApplicationRoleConnection
• Webhook
  • ✅ Webhook