dosarf / elm-yet-another-polling / YetAnotherPolling

A package for polling made easier.

You need to initialize it's model with basic retry-after and backing-off configuration (Configuration), a function that yields a task (this would be your HTTP task polling something, but it can actually be any other task) another function that defines, based on the result of a task, how to continue with polling, a constructor of a message of yours,

and out come messages bearing results of those tasks attempted.

You have to call update the polling model (Model) with the messages you recieve to keep it going.

Configuration


type alias Configuration =
{ minRetryAfterMillis : Basics.Float
, maxRetryAfterMillis : Basics.Float
, backOffRate : Basics.Float 
}

How polling should behave in case of recoverable failure (see PollOne): minRetryAfterMillis: the minimum time interval to wait before retrying, maxRetryAfterMillis: the maximum time interval to wait before retrying, * backOffRate: the ratio of the time interval to wait before retrying and the time interval waited on the last try.

defaultConfiguration : Configuration

Default Configuration minRetryAfterMillis: 10 seconds, maxRetryAfterMillis: 160 seconds, * backOffRate: 2, i.e. twice the time interval will be waited before subsequent retry attempts.

Model

The model for tracking polling state as well issuing request tasks.


type State
    = Polling
    | NotPolling
    | RetryAfterMillis Basics.Float
    | QuittingPolling

Current state of polling. Whenever entering or re-entering the state Polling, a request task will be executed.

QuittingPolling is that state between a call to stop and the next result that comes back from a currently outstanding retry, only after which the state will be finally NotPolling. During this QuittingPolling state, any new calls to start will be ignored.


type alias Model error value msg =
{ configuration : Configuration
, requestTask : () -> Task error value
, decidePolling : Result error value -> PollingDecision
, createMessage : Result error value -> msg
, state : State 
}

Model to track polling state, initialized with Configuration and some necessary functions.

Use stateOf to figure out the current State.

stateOf : Model error value msg -> State

The current state of polling.

init : Configuration -> (() -> Task error value) -> (Result error value -> PollingDecision) -> (Result error value -> msg) -> Model error value msg

Constructs a model to execute and track polling.

Arguments: configuration: min/max time intervals before retries as well as back-off rate, see Configuration. requestTask: Provides the task to execute, for each try. Normally an Http.task, but could be anything, really. decidePolling: Based on the result of a try, decides the fate of the polling loop. Should a HTTP 204 No Content be interpreted as re-try immediately, or back-off, or quit the loop entirely? How about HTTP 429 Too Many Requests? In some cases, even a successfully obtained response (HTTP 200 Ok) could mean, based on the received contents, to quit the polling loop. Therefore such decision is application specific. createMessage: Turns the result of a try to a message of yours.

Operations

start : Model error value msg -> ( Model error value msg, Platform.Cmd.Cmd msg )

Puts the model into polling state and produces a command with an HTTP task.

stop : Model error value msg -> ( Model error value msg, Platform.Cmd.Cmd msg )

If currently in any of the states: Polling, RetryAfterMillis or QuittingPolling, it will put to the state QuittingPolling (so that the next result will put to final NotPolling).

If already in state NotPolling, remains in NotPolling.

update : Result error value -> Model error value msg -> ( Model error value msg, Platform.Cmd.Cmd msg )

Updates the model, based on the results of the previous polling that you feed back.

Invoke this function on the current polling model whenever you get your message carrying a Result error value, to keep things rolling.


type PollingDecision
    = PollOne
    | QuitPolling
    | RetryAfter

Decision to bring the model from previous polling state to the next one.