Schedule API

[lorensr]

Re: temporalio/features#73

rendered

Some things I could add if helpful:

• types
• comments with the corresponding gRPC fields

I took minor liberties in choosing different terms for fields compared to gRPC. Downside is having a difference between SDK and tctl. But if we like SDK terms, maybe we submit a PR to tctl so it matches.

Also flattened / removed the schedule from { schedule: { spec, action, policies, state } }.

Note: you can hide comments for easier reading

[bergundy]

What does this contain and what's the response type? Are we doing the same as in workflow.describe where we wrap the raw grpc message?

[lorensr]

.describe() doesn't take anything. Yeah, a ScheduleDescription wrapper that has decoded payloads and base64-encoded binary. Here's the message, I'd flatten schedule to match input.

message DescribeScheduleResponse {
    // The complete current schedule details. This may not match the schedule as
    // created because:
    // - some fields in the state are modified automatically
    // - the schedule may have been modified by UpdateSchedule or PatchSchedule
    temporal.api.schedule.v1.Schedule schedule = 1;
    // Extra schedule state info.
    temporal.api.schedule.v1.ScheduleInfo info = 2;
    // The memo and search attributes that the schedule was created with.
    temporal.api.common.v1.Memo memo = 3;
    temporal.api.common.v1.SearchAttributes search_attributes = 4;

    // This value can be passed back to UpdateSchedule to ensure that the
    // schedule was not modified between a Describe and an Update, which could
    // lead to lost updates and other confusion.
    bytes conflict_token = 5;
}

[bergundy]

One thing that could also be super useful is to be able to duplicate a schedule for a different action

[lorensr]

How's this?

const { spec, policies, state } = await schedule.describe()
const schedule = await client.create({ 
  id: 'foo', 
  spec, 
  policies,
  state,
  action: {
    startWorkflow: {
      workflowId: 'wf-biz-id',
      type: differentWorkflow,
    },
  }
})

[lorensr]

^ is now a lot of fields. Alternative:

const schedule = await schedule.describe()
const options = schedule.copy({ 
  id: 'foo',
  action: {
    startWorkflow: {
      workflowId: 'wf-biz-id',
      type: differentWorkflow,
    },
  }
})
client.create(options)

[bergundy]

Overall this LGTM.

Could use more comments to give more context, I had to make several assumptions when reading this proposal.

[cretz]

I can't really give a reasonable review of this proposal without all of the types present. I would love this proposal presented as a bunch of declaration files, heh.

But if that's gonna be done at implementation time, that's fine, but there isn't enough detail here for me atm.

[cretz]

I would still like to see the full TypeScript definitions. But if that's at implementation time, ok, I will wait to review there.

[lorensr]

@dnr my understanding from Roey is that DescribeScheduleResponse will contain Ranges? If yes, what will the default year and dayOfWeek be?

[dnr]

You saw temporalio/api#230, just clarifying here:

The intention is users can supply a calendar-type spec in one of three ways: single cron string, labeled cron string, structured proto. The first two will be validated and converted to structured proto on the frontend, so when you get a schedule back, you'll only see structured proto.

If we add ical rrule support, that may also get compiled into the structured proto, or it might need to be a third major type (calendar, interval, rrule) if it's not expressible that way.

[lorensr]

What's a labeled cron string?

[dnr]

Sorry, that's what I think of CalendarSpec as in my head

[lorensr]

Now that's what you call a saga 😊. I believe all issues raised so far have been either resolved or left as TODO comments for future consideration. If any future issues come up, feel free to submit an issue or PR. This doc now lives at: https://github.com/temporalio/proposals/blob/master/typescript/schedules.md

The SDKs will start implementing the Schedule API. Some things in this doc are TypeScript-specific, and different languages have different conventions or expectations, so there will be some differences between SDKs. Also, we may find that parts of this doc are suboptimal as we learn through the implementation process, so we may modify this doc. The Schedule API will be marked experimental (i.e. may have breaking changes) until it has been released in at least two SDKs and has had user testing/feedback.