Function hdk::time::schedule

pub fn schedule(scheduled_fn: &str) -> ExternResult<()>

Adds a function from the current zome to the scheduler.

Any schedulable function from the current zome can be added to the scheduler by calling this function. Schedulable functions are infallable and MUST return their next trigger time. Trigger times are expressed as either “ephemeral” which means they will run as “best effort” after some duration, or “persisted” which uses crontab like syntax to trigger the scheduled function many times. Ephemeral scheduled functions do not outlive the running conductor but persisted scheduled functions will continue to function after a reboot. Persisted functions MUST continue to return the same persisted crontab every time they are triggered if they wish to maintain their schedule. They MAY change their schedule by returning a different crontab or even returning an ephemeral trigger or None for no further triggers. If this is the initial trigger of a scheduled function the input schedule will be None, otherwise it will be whatever was returned by the previous invocation that triggered the current invocation.

Scheduling a function will trigger it once unconditionally on the next iteration of the conductor’s internal scheduler loop. The frequency of the loop is subject to change between conductor versions and MAY be configurable in the future, so happ devs are advised NOT to assume or rely on any specific granularity. For example the loop has historically ranged from once every 100ms to every 10s.

As schedule is callable in any coordination context it could even be called as the result of inbound remote calls or many times concurrently by some client. Both floods of inbound scheduling requests and “confused deputy” situations must be handled by the conductor.

• Scheduling a function is idempotent. If it is already scheduled the existing schedule will be respected and the schedule call is a noop. If the function is not currently scheduled, even if it recently returned None from a previous schedule, it will immediately be added for inclusion in the next scheduler loop iteration.
• Scheduled functions ALWAYS run as the author of the chain they run for. Any appropriate cap grants must be implemented in front of the schedule call as the provenance of the scheduling agent is lost as soon as the original zome call returns. This resolves the natural tension between disambiguating and handling potentially hundreds of scheduled calls under different provenances, while also wanting a single lightweight and idempotent scheduler.
• Scheduled functions are infallible and their only input and output is their current and next schedule trigger. The #[hdk_extern(infallible)] attribute facilitates this pattern separate to other zome externs that are both fallible and support arbitrary inputs and outputs. Any errors on the host side will simply be logged and otherwise ignored.

  #[hdk_extern(infallible)]
  fn scheduled_fn(_: Option<Schedule>) -> Option<Schedule> {}

  This is because the scheduler runs in a background loop and unlike regular zome calls there is no client or workflow attached to report back to or handle errors. There are no inputs and outputs to scheduleable functions as we don’t want to provide the opportunity to smuggle in data that will be run by the author as themselves if the input originated from some caller who merely held a cap grant to trigger the schedule.
• Happ devs MUST assume that malicious agents are able to trigger scheduled functions at the “wrong time” and write their scheduled functions defensively to noop then delay or terminate themselves if triggered during the incorrect time window.

It is worth noting that at the time of writing, init callbacks are lazy in that they do not execute until/unless some other zome call runs for the first time after installation. It is possible to schedule functions during init but happ devs should be mindful that this may not happen immediately or ever after happ installation.

The only argument to schedule is the name of the schedulable function in the current zome to be scheduled.