Plan Retries Before They Run

A retry policy may seem reasonable when viewed in isolation, yet it can become unfeasible within the context of the request that it is associated with. Consider a situation where a single provider attempt may take 800 milliseconds. The configuration permits four attempts with escalating backoff, while the request itself only has two seconds remaining. The individual components are accurate, but their collective composition proves incompatible.

The WorkIt core library provides a time policy evaluation module, accessible via the " @workit/core/time-policy " package. By importing the required configurations, a planner can assess the policy before task execution. The planner does not interact with the provider; instead, it calculates a conservative upper limit based on the declared policy and generates typed warnings when the composition fails to fit within the constraints.

The planner and runtime policies in WorkIt serve distinct purposes. The planner conducts pre-execution analysis, examining declared attempt costs and composition rules such as attempt, retry, hedge, and timeout deadlines. In contrast, the runtime is responsible for invoking the task, handling cancellation, sleeping with signal notifications, and determining whether additional attempts should commence.

WorkIt 0.5.0 separates these responsibilities, ensuring that the planner does not generate side effects, while the runtime does not attempt to predict provider latency. A deadline is an integral part of the task context, and WorkIt provides the earliest effective absolute deadline via the ctx.deadlineAt property.

When a task possesses both an inherited scope deadline and a wrapper deadline, the task utilizes the earlier value. Retry, fallback, and hedge compositions maintain this effective deadline for their task bodies. The deadline value serves merely as introspective information and does not preempt the task. The task must still adhere to the signal context, and external I/O must respond to the signal when the client supports abort operations.

A retry count represents an individual operational limit, preventing a single wrapper from running indefinitely. However, it does not halt multiple sibling operations from collectively exhausting the available retries. Version 0.5.0 introduces the concept of a shared retry budget, allowing developers to encapsulate provider boundaries.

This budget can be applied to restrict the total number of additional provider invocations across a request, effectively turning "three retries per call" into a policy that can also express "no more than five additional provider invocations in total."