Options

[FedorLap2006]

Since the beginning, DiscordGo did not have ability for adding per-call customization:

• What if you want to disable automatic rate limit handling when you call ChannelMessageDelete, instead handling the error by yourself?
• Or what if you want to set additional headers on GuildBanCreate, like X-Audit-Log-Reason, to comment your action in audit log?

We’ve been thinking on how to combat this problem, and came up with the following solutions:

• Builders pattern

  s.WithAuditLogReason("my reason").GuildBanCreate(...)
  s.WithRetryOnRateLimit(false).ChannelMessageDelete(...)

• Functional options

  s.GuildBanCreate(..., discordgo.WithAuditLogReason("reason"))
  s.ChannelMessageDelete(..., discordgo.WithRetryOnRateLimit(false))

This PR implements the latter. It provides a few pre-built options. However, you can always supply your custom option.

Options have access to a RequestConfig struct, which is internally used by RequestX functions. This config allows you to modify a few global settings, like Client, ShouldRetryOnRateLimit and MaxRestRetries, but it also allows you to modify the request directly.

A typical functional option would look like this:

func WithQuery(key string, value string) discordgo.RequestOption {
	return func(cfg *discordgo.RequestConfig) {
		q := cfg.Request.Query()
		q.Add(key, value)
		cfg.Request.RawQuery = q.Encode()
	}
}

These are built-in options discordgo will provide:

• WithClient - Control http.Client used for the request (defaults to s.Client)
• WithHeader - Change a certain header in the request
  • WithAuditLogReason - Set X-Audit-Log-Reason header
  • WithLocale - Set X-Discord-Locale header
• WithRetryOnRateLimit - Control Session.ShouldRetryOnRateLimit field for the request
• WithMaxRestRetries - Control Session.MaxRestRetries field for the request
• WithContext - Provide a context.Context to the http.Request

This change will be affecting all of the REST endpoints. However it should be non-breaking.

If you have used any function signatures though, you would need to change them accordingly:

- func (s *Session) XXX(...) (...) {}
+ func (s *Session) XXX(..., options ...RequestOption) (...) {}

---

Special thanks to @jalavosus for bringing up the issue with context in REST functions. His PR (#1119) was one of the factors that inspired me to implement this functionality.