Module Reddit_api_async.Connection

Connection manages the connection to Reddit, including authentication and rate limiting behavior.

It is responsible for taking the endpoint specifications in Reddit_api_kernel.Endpoint and actually performing HTTP requests.

Consider wrapping your Connection in a Retry_manager if you are writing a long-running process and want to just retry forever on transient errors.

Authentication

Connection currently supports a subset of Reddit's OAuth2 app types via the Credentials module. See Reddit's documentation on app types.

Rate-limiting behavior

Connection enforces two different forms of rate-limiting:

HTTP rate-limiting headers

Reddit tracks API usage and requires that a client make no more than 600 requests in a 10 minute period.

Rather than simply keeping a counter of requests internally, Connection reads Reddit's API response headers to learn about the request quota, including the number of remaining requests and the time until the quota resets. This allows multiple Connection.ts with the same credentials to run in parallel, accounting for each others' quota usage without explicit coordination.

Minimum time between requests

In order to abide by /u/kemitche's request to "be reasonable" and not slam all 600 requests in as quickly as possible, Connection also enforces a 100ms delay between requests.

module Credentials : sig ... end
type t
val sexp_of_t : t -> Sexplib0.Sexp.t
module Access_token_request_error : sig ... end

An Access_token_request_error.t represents an error encountered while fetching an access token.

module Error : sig ... end

A request via Connection may result in two different HTTP requests: a request to the explicitly named API endpoint and, as necessary, a request to retrieve an OAuth2 access token. This type distinguishes errors associated with each of these requests.

val create : Credentials.t -> user_agent:string -> t
val call : t -> 'a Reddit_api_kernel.Endpoint.t -> ('a, Reddit_api_kernel.Endpoint.Error.t Error.t) Core.Result.t Async.Deferred.t
val call_exn : t -> 'a Reddit_api_kernel.Endpoint.t -> 'a Async.Deferred.t
val call_raw : t -> 'a Reddit_api_kernel.Endpoint.t -> (Cohttp.Response.t * Cohttp.Body.t, Core.Exn.t Error.t) Core.Result.t Async.Deferred.t

call_raw returns the raw HTTP response from Reddit.

module Remote : sig ... end

Any connection can be turned into an RPC server, acting as a shared connection for multiple client Connection.ts. Rate limiting is managed on the server side.

module For_testing : sig ... end