Module twilight_http_ratelimiting::ticket
source · [−]Expand description
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
Receiver to wait for the headers sent by the API consumer.
Indicate to the ratelimit consumer that their ticket has been granted and they may now send a request.
Channel receiver to wait for availability of a ratelimit ticket.
Channel sender to send response ratelimit information to the ratelimiter.
Functions
Produce a new channel consisting of a sender and receiver.