Crons

[pranaygp]

Putting this up from an internal discussion to track native cron support in workflow. This is the simplest way to get cron support and we can iterate from there on feedback and features.

Schedules are defined on workflows

function myWorkflow() {
  "use workflow"
  ...
}
myWorkflow.schedule = "0 5 * * *"

These schedules are extracted and validated at build time and included in the manifest. When building on vercel, it would also compile into Build Ouptut API cron expressions:

{
  "crons": [
    {
      "path": "/.well-known/workflow/v2/cron?workflow=[myWorkflow-specifier]",
      "schedule": "0 5 * * *"
    }
  ]
}

This means we have a new generated route on user deployments that authenticates requests against a CRON_SECRET env variable (respected by vercel cron) and then it runs start(myWorkflow, [])

For postgres world, crons would be powered by graphile crontab. startWorld() would be responsible for setup and teardown of cron jobs. Essentially - when startWorld is run in a production environment, it compares the build manifest crons with the graphile crons and makes any updates necessary

For local world, we'll do it in-process

---

Open questions at this time:

• Sanity checking the postgres/graphile implementation - does this make sense for production graphile use cases
• Removing the CRON_SECRET dependency on vercel - using crons should require no additional config on vercel

[NathanColosimo]

How could crons fit in with "repeatable workflows" ?

For example, right now I have triggered repeatable / stoppable workflows in my app via:

const REPEAT_INTERVAL = 1 hour

"use workflow" 
if (sleepDuration) sleep(sleepDuration)

const step1 = await stepOne()

start(abcd, [REPEAT_INTERVAL])

*I have hooks as well for stopping this repeat cycle and the sleep duration accounts for the time it takes so it always repeats on a stable interval like a cron would, the duration of each individual workflow doesn't matter (as long as its less than the interval duration)

This avoids having the same workflow have the same steps / loop hundreds of times and makes each individual run more easily debuggable.

But this is also annoying, and if one workflow encounters an error then it stops the whole repeat cycle.

I would prefer something like

repeat: {
    cron?: string
    }
}

And this way, on startup, say in instrumentation.ts for Nextjs, you can call

await world.start()
startRepeat(cron1, [args], {
repeat: {
cron: "0 * * * *"
}

For once an hour.

The benefit here is no .schedule attribute on the workflow function, and also crons don't have to be registered or pre configured ahead of time.

You could start a repeating cron at any point (e.g. a user signs up, you start a cron workflow just for them, or increase the frequency when they upgrade to a higher tier, so pro tier gets 4x an hour sync or whatever and free is 1x an hour) there are lots of ways this is beneficial.

And then you could also STOP the cron at any point via something like
stopRepeating(cron1)

---

The actual function names and DX outlined above is random but I think triggering / creating / stopping any cron for any workflow function via code would be awesome.

I can see how this would throw a wrench in the proposed vercel implementation bc that is leaning on the existing vercel cron product but I'm sure there's a way!

Same with graphile cron tab, seems to be a pre configured file too. Maybe cron could just be part of the workflow runtime rather than a world implementation detail? Via durably chaining / scheduling with sleep() etc in coordination with hooks?

[pranaygp]

imo - this view intuitively makes sense. I'd term this as imperative crons, vs. the proposal in the RFC is a declarative cron syntax.

There are use cases for both. The biggest difference being that with imperative crons, you can control the cron scheduling itself based on external events. Or, like you said, you can start a cron/repeating workflow based on an external events - like for every user.

You very often do want to do this - for example look at https://v0-chess-match.vercel.app/ - it daisy chains games so it's running forever but not on a fixed/static cron schedule. Durable daisy chaining is a documented and recommended pattern.

The downsides with imperative crons are, either the queue needs to support it natively (which significantly reduces what worlds workflow can support - SQS, vercel queue, etc. don't natively have a "cron message" type, and note that worlds don't encapsulate compute - they're just storage), or it needs to be daisy chained in the runtime (like you mentioned). Secondly, since they're not statically registered, they don't play very well with a version pinning based runtime (for ex. what happens when you deploy a new version while there are many ongoing crons? staying on the pinned version is the safe, consistent answer with how start works, but that's not what you want with cron usually. Upgrading gets messy. You'd need to wire in more options into this to support upgrade strategies, and you need be careful not to change the workflow function name and signature to not break it. We'd also need an answer on how to handle changing the schedule itself across deployments, and also handling dynamic schedules themselves since).

Ultimately, declarative crons start to look exactly like workflows. They're long running. They can stay version pinned, or be cancelled/interrupted and restarted on latest version. They need UI to track active crons and invocations and to cancel them from the UI. They need IDs cron_abc123. etc. And if they look like workflows, I reckon they should just be workflows...

---

My current thinking is

• Imperative crons should be user defined daisy chained based. We should add more to the cookbook, but this gives you full control. You can choose how to handle upgrades yourself (using start with "latest" deploymentId option), you can choose how to handle cancellations (using hooks, etc). A pattern and resulable components/library on top of workflow goes a long way here.

• Declarative crons are infrastructure as code to statically orchestrate crons at build time. Every new build can output the list of crons needed, and runtimes that support it would spin up/modify/tear down resources accordingly - like terraform. Hence why it compiles to vercel.json on vercel, and graphile workers for postgres, but can also compile into EventBridge on AWS, crontab in linux, CronJobs on k8s, crontrigger on cloudflare, etc). You can already expose an API endpoint with start and then setup a cron in any runtime to do this today - but reasoning about it and managing crons becomes easier when natively specced

[pranaygp]

That said, will continue to think on imperative crons too though. Maybe there is a good solution to all those problems...

[rovo89]

Specifying the schedule at build-time is way too unflexible. That might work for some cleanup jobs, but it doesn't allow for any configurations by admins (e.g. when/how often shall we fetch currency rates), and it can't handle user-defined jobs at all. An example for the latter would be sync jobs with external providers that my users could set up (within bounds, of course). The developers don't always know what's best, and having to rebuild and redeploy for any adjustment doesn't feel right. 😉

I found this issue because I checked whether I could hook into the Graphile worker (add tasks and jobs), but that doesn't seem to be possible. And of course, I would enjoy the benefits of running jobs as workflows, with streamed logs, retries etc.

An alternative would be a meta cron which runs every minute and checks if there's anything to do... but that would blow up the logs, and would probably be easier to implement background function started in instrumentation.ts. Actually, that should alreay work today and might fit better to my needs than what you seem to be planning, so I'll explore more into that direction.

[pranaygp]

Just left a longer answer here on the same thing - #1649 (reply in thread). lmk what you think