[ResponseOps][Rules] Allow users to create a snooze schedule for rule via API

[js-jankisalvi]

Summary

Resolves first part of #198783 (snooze API)
Creates a public API for adding snooze schedule to rules.
For this purpose we created new schedule schema which will be used as standard schedule schema across rules and alerting framework.

Note
The code to be reviewed for public API is under common/routes/schedule and inside external folders.
Rest of the code is just moving existing internal API route and its code to /internal folders.

Checklist

• Documentation was added for features that require explanation or tutorials
• Unit or functional tests were updated or added to match the most common scenarios

How to test

• Create a rule in kibana
• Snooze that rule via new public API

Path: https://localhost:5601/api/alerting/rule/<rule_id>/snooze_schedule
Method: POST
Body: 
{
    "schedule": { 
       "custom": {
         "start": "2025-02-25T18:00:00.000Z",
         "duration": "15m",
         "recurring": {
            "every": "1w",
            "onWeekDay": ["TU", "FR"],
            "occurrences": 10
         }
       }
    }
}

• Verify various snooze schedule scenarios are generated correctly

Flaky test runner:

https://buildkite.com/elastic/kibana-flaky-test-suite-runner/builds/8009

Release note

Allow users to create a snooze schedule for rule via API

[elasticmachine]

Pinging @elastic/response-ops (Team:ResponseOps)

[cnasikas]

Great work! Very meticulous with great testing coverage. I left some minor comments, and I would like to discuss the following:

• If the user puts 48h as a duration, we return 2d because of the transformation we do. As we do not persist with the initial request, I do not think there is anything we can do. I just wanted to call it out. I think it is fine as long as we are consistent and always return the same. Maybe we have to document it.
• Users can define seconds in the duration field. This can lead to the following interesting scenario: I set the duration to 129600s, which will be converted to 1.5d. How do you think we should handle this? Is it okay to leave it as it is?

[cnasikas]

@cnasikas What do you think of having duration: undefined instead of duration: -1? Isn't that clearer?

An answer for the future (aside from the fact that we will not support it initially): I think it is better if we force users to be explicit when they want to schedule the rule indefinitely. Having undefined to mean indefinitely can easily lead to mistakes, where users forget to put the duration and accidentally snooze a critical rule forever.

[cnasikas]

How does the rrule library handles this scenario?

[cnasikas]

nit: Should we mention that it has to be in the UTC format (with the z in the end) and use the timezone field to specify the timezone?

[js-jankisalvi]

Updated to use UTC timezone format and added example

[Zacqary]

How then do we validate the duration, does it have to match exactly the difference between the start and end date?

end is optional, it gets converted to the until property in RRULE, meaning "recur until this date." Maybe we should rename end to until to reduce confusion? Making it part of recurring.end is a little helpful but I think if @adcoelho is getting confused then the user might also.

It's possible for the duration to go on longer than the end date, the rrule library won't throw an error or anything, it just won't make the rule recur ever.

[Zacqary]

Good, excellent, we have absolutely had SDHs come up around this before. This would technically work but let's not let the user hurt themselves.

[js-jankisalvi]

• If the user puts 48h as a duration, we return 2d because of the transformation we do. As we do not persist with the initial request, I do not think there is anything we can do. I just wanted to call it out. I think it is fine as long as we are consistent and always return the same. Maybe we have to document it.
• Users can define seconds in the duration field. This can lead to the following interesting scenario: I set the duration to 129600s, which will be converted to 1.5d. How do you think we should handle this? Is it okay to leave it as it is?

I found a way to return same duration string passed by user in request. We pass request duration to our transform method transformRRuleToCustomSchedule from snooze rule route and use that as response duration

transformRRuleToCustomSchedule({
  snoozeSchedule: createdSchedule,
  originalDuration: customSchedule.duration,
 }) 

[cnasikas]

• If the user puts 48h as a duration, we return 2d because of the transformation we do. As we do not persist with the initial request, I do not think there is anything we can do. I just wanted to call it out. I think it is fine as long as we are consistent and always return the same. Maybe we have to document it.
• Users can define seconds in the duration field. This can lead to the following interesting scenario: I set the duration to 129600s, which will be converted to 1.5d. How do you think we should handle this? Is it okay to leave it as it is?

I found a way to return same duration string passed by user in request. We pass request duration to our transform method transformRRuleToCustomSchedule from snooze rule route and use that as response duration

transformRRuleToCustomSchedule({
  snoozeSchedule: createdSchedule,
  originalDuration: customSchedule.duration,
 }) 

I like the idea, but instead of passing it to the transformRRuleToCustomSchedule I think it is better to move the responsibility to the router like:

const customScheduleRes = transformRRuleToCustomSchedule(createdSchedule);

const response: SnoozeResponse = {
            body: {
              schedule: {
                id: snoozeScheduleId,
                custom: { ...customScheduleRes, duration: customSchedule.duration <-- this is req.body.schedule?.custom }
              },
            },
          };

Also, could you please open an issue to persist the new format to ES along with the old rrule format?

[js-jankisalvi]

I like the idea, but instead of passing it to the transformRRuleToCustomSchedule I think it is better to move the responsibility to the router like:

updated

Also, could you please open an issue to persist the new format to ES along with the old rrule format?

Created issue

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: df69e33

Metrics [docs]

Unknown metric groups

ESLint disabled line counts

id	before	after	diff
@kbn/test-suites-xpack	723	725	+2

Total ESLint disabled count

id	before	after	diff
@kbn/test-suites-xpack	749	751	+2

History

• 💚 Build #283423 succeeded 5563855
• 💔 Build #283267 failed 17f8115
• 💚 Build #283164 succeeded af5ca48
• 💚 Build #282517 succeeded 3cec82b
• 💛 Build #282195 was flaky 88cd8cd
• 💚 Build #281541 succeeded 190edbb

cc @js-jankisalvi

[cnasikas]

LGTM! 🚀

[adcoelho]

ship it 🎉

[kibanamachine]

Starting backport for target branches: 8.x

https://github.com/elastic/kibana/actions/runs/13837846074

[kibanamachine]

💔 All backports failed

Status	Branch	Result
❌	8.x	Backport failed because of merge conflicts

Manual backport

To create the backport manually run:

node scripts/backport --pr 210584

Questions ?

Please refer to the Backport tool documentation

[js-jankisalvi]

💚 All backports created successfully

Status	Branch	Result
✅	8.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

[js-jankisalvi]

💚 All backports created successfully

Status	Branch	Result
✅	8.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation