Module ticket

Flow for managing ratelimit tickets.

Tickets are the Ratelimiter’s method of managing approval for a consumer to be able to send a request.

Ratelimit Consumer

1. Requesting a ticket

Consumers of a ratelimiter will call Ratelimiter::ticket.

2. Waiting for approval

In return consumers will receive a TicketReceiver. This must be polled in order to know when the ratelimiter has approved a ticket.

3. Receiving approval

When a ticket is approved and the future resolves, a TicketSender is provided. This must be used to provide the ratelimiter with the response’s ratelimit headers.

4. Performing the request

Consumers may now execute the HTTP request associated with the ticket. Once a response (or lack of one) is received, the headers must be parsed and sent to the ratelimiter via TicketSender::headers. This completes the cycle.

Ratelimiter

1. Initializing a ticket’s channels

Ratelimiters will accept a request for a ticket when Ratelimiter::ticket is called. You must call channel to create a channel between the ratelimiter and the consumer.

2. Keeping the consumer waiting

channel will return two halves: TicketNotifier and TicketReceiver. Ratelimiters must keep the notifier and give the user the receiver in return.

3. Notifying the consumer of ticket approval

When any ratelimits have passed and a user is free to perform their request, call TicketNotifier::available. If the user hasn’t canceled their request for a ticket, you will receive a TicketHeaders.

4. Receiving the response’s headers

The consumer will perform their HTTP request and parse the response’s headers. Once the headers (or lack of headers) are available the user will send them along the channel. Poll the provided TicketHeaders for those headers to complete the cycle.

Structs

• TicketHeaders
  Receiver to wait for the headers sent by the API consumer.
• TicketNotifier
  Indicate to the ratelimit consumer that their ticket has been granted and they may now send a request.
• TicketReceiver
  Channel receiver to wait for availability of a ratelimit ticket.
• TicketSender
  Channel sender to send response ratelimit information to the ratelimiter.

Functions

• channel
  Produce a new channel consisting of a sender and receiver.