Cron jobs owned by the cluster (Effect's ClusterCron).
make turns a Cron into a layer that runs one recurring job across
the cluster: a singleton schedules the first run, and each run is a
persisted message to an entity, delivered at its instant, that schedules
the next. With calculate_next_run_from_previous every run goes to one
executor entity, so runs never overlap and missed runs are caught up in
order. A run reads its instant from CurrentScheduledTime.
Classes#
Functions#
make#
make[E](*, name: str, cron: Cron, execute: Effect[None, E, CurrentScheduledTime | Scope], shard_group: str | None = None, calculate_next_run_from_previous: bool = False, skip_if_older_than: DurationInput | None = None) -> Layer[Never, Never, Sharding]
make[E, R](*, name: str, cron: Cron, execute: Effect[None, E, R | CurrentScheduledTime | Scope], shard_group: str | None = None, calculate_next_run_from_previous: bool = False, skip_if_older_than: DurationInput | None = None) -> Layer[Never, Never, Sharding | R]A layer running execute on cron through the cluster's
sharding (in shard_group, "default" when None).
The next run is due at the cron's next instant after now, or, with
calculate_next_run_from_previous, after the previous run's instant:
then one executor entity runs every instant in order, and a failed run
is retried in place, holding back later runs. A run older than
skip_if_older_than (one day by default) is skipped. A failure of
execute is logged as a warning; the next run is scheduled anyway.
| Parameter | Type | Description |
|---|---|---|
name | ||
cron | ||
execute | ||
shard_group | = None | |
calculate_next_run_from_previous | = False | |
skip_if_older_than | = None |
@overload
def make[E](
*,
name: str,
cron: Cron,
execute: Effect[None, E, CurrentScheduledTime | Scope],
shard_group: str | None = None,
calculate_next_run_from_previous: bool = False,
skip_if_older_than: DurationInput | None = None,
) -> Layer[Never, Never, Sharding]: ...
@overload
def make[E, R](
*,
name: str,
cron: Cron,
execute: Effect[None, E, R | CurrentScheduledTime | Scope],
shard_group: str | None = None,
calculate_next_run_from_previous: bool = False,
skip_if_older_than: DurationInput | None = None,
) -> Layer[Never, Never, Sharding | R]: ...
def make(
*,
name: str,
cron: Cron,
execute: Effect[None, Any, Any],
shard_group: str | None = None,
calculate_next_run_from_previous: bool = False,
skip_if_older_than: DurationInput | None = None,
) -> Layer[Never, Never, Any]:
"""A layer running ``execute`` on ``cron`` through the cluster's
sharding (in ``shard_group``, ``"default"`` when ``None``).
The next run is due at the cron's next instant after now, or, with
``calculate_next_run_from_previous``, after the previous run's instant:
then one executor entity runs every instant in order, and a failed run
is retried in place, holding back later runs. A run older than
``skip_if_older_than`` (one day by default) is skipped. A failure of
``execute`` is logged as a warning; the next run is scheduled anyway."""
require_effect(execute, "execute")
from_previous = calculate_next_run_from_previous
skip_after = from_input_unsafe(
timedelta(days=1) if skip_if_older_than is None else skip_if_older_than
)
group = "default" if shard_group is None else shard_group
def next_run(after: datetime) -> datetime:
return cron_next(cron, after).astimezone(UTC)
def shard_group_of(_: EntityId) -> str:
return group
run_rpc = (
make_rpc("run", payload=CronPayload)
.annotate(Persisted, True)
.annotate(Uninterruptible, True)
)
start_rpc = make_rpc("start").annotate(Persisted, True)
cron_entity = cast(
"builtins.type[Entity]",
builtins.type(
f"ClusterCron[{name}]",
(Entity,),
{"run": run_rpc, "start": start_rpc},
type=f"ClusterCron/{name}",
annotations=Context.make(ShardGroup, shard_group_of).add(ClientTracingEnabled, False),
),
)
def send(date_time: datetime) -> Effect[None, Any, Sharding]:
def call(make_client: Callable[[str], Any]) -> Effect[None, Any]:
if from_previous:
payload = CronPayload(date_time=date_time, executor=True)
return make_client(_EXECUTOR_ID).run.discard(payload)
return make_client(format_iso(date_time)).run.discard(CronPayload(date_time=date_time))
return cron_entity.client().flat_map(call)
def schedule(date_time: datetime) -> Effect[None, Never, Sharding]:
return _with_retry("Failed to schedule next run, retrying", send(date_time))
if from_previous:
# The executor schedules the next run if its chain has been lost.
# ``start`` has no primary key, so each retry is a new message.
initial: Effect[None, Never, Any] = _with_retry(
"Failed to start cron job, retrying",
cron_entity.client().flat_map(
lambda make_client: cast("Any", make_client(_EXECUTOR_ID)).start()
),
)
else:
initial = now().flat_map(
lambda at: _with_retry("Failed to schedule initial run, retrying", send(next_run(at)))
)
initial_run = singleton.make(f"ClusterCron/{name}", initial, shard_group=shard_group)
def run_execute(date_time: datetime) -> Effect[None, Never, Any]:
def check(at: datetime) -> Effect[None, Any, Any]:
if date_time < at - skip_after.to_timedelta():
return void
return execute.pipe(provide_service(CurrentScheduledTime, date_time))
return now().flat_map(check).or_die()
def build() -> Generator[Effect[Any, Never, Any], Any, Any]:
address = yield from CurrentAddress()
# Runs are processed one at a time, so a run processed before
# ``start`` means the chain is alive.
processed_run = [False]
def run(request: Request[CronPayload]) -> Effect[None, Never, Any]:
date_time = request.payload.date_time
if from_previous and address.entity_id != _EXECUTOR_ID:
# A run scheduled by an earlier release joins the executor's chain.
return schedule(date_time)
processed_run[0] = True
def after(exit: Exit[None, Never]) -> Effect[None, Never, Any]:
warn = log_warning(exit.cause) if isinstance(exit, Failure) else void
following = (
schedule(next_run(date_time))
if from_previous
else now().flat_map(lambda at: schedule(next_run(at)))
)
return warn.flat_map(lambda _: following)
return (
run_execute(date_time)
.match_cause_effect(
on_failure=lambda cause: after(Failure(cause)).flat_map(
lambda _: fail_cause(cause)
),
on_success=lambda _: after(Success(None)),
)
.annotate_logs(
{
"module": "effect/cluster/ClusterCron",
"name": name,
"dateTime": date_time,
}
)
)
def start(_: Request[None]) -> Effect[None, Never, Any]:
if processed_run[0]:
return void
# Deduplicated against the pending run if the chain is alive.
return now().flat_map(lambda at: schedule(next_run(at)))
return cron_entity.handlers().handle(run_rpc)(run).handle(start_rpc)(start)
entity_layer = cron_entity.to_layer_effect(gen(build))
return layer_.merge(initial_run, entity_layer)