fix(SDK): Added a new IScheduleBuilder fluent builder service used to build and configure a workflow's start schedule

Closes #42

Author: cdavernas

src/ServerlessWorkflow.Sdk.UnitTests/Cases/Services/WorkflowBuilderTests.cs

@@ -14,6 +14,7 @@
  * limitations under the License.
  *
  */
+using Cronos;
 using Newtonsoft.Json.Linq;
 using ServerlessWorkflow.Sdk.Models;
 using ServerlessWorkflow.Sdk.Services.FluentBuilders;
@@ -47,10 +48,9 @@ public void Build()
                     strat.WithName("retry1")
                         .WithNoDelay()
                         .MaxAttempts(5))
-                .StartsWith(flow => 
-                    flow.Delay(TimeSpan.FromSeconds(3)))
-                .Then(flow => 
-                    flow.Inject(new JObject()))
+                .StartsWith(flow => flow.Delay(TimeSpan.FromSeconds(3)),
+                            schedule => schedule.Every("0 * * * *"))
+                .Then(flow => flow.Inject(new JObject()))
                 .Then(flow =>
                     flow.Execute(action => 
                         action.Invoke(function => 

src/ServerlessWorkflow.Sdk/Cron.cs

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2021-Present The Serverless Workflow Specification Authors
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+using Cronos;
+
+namespace ServerlessWorkflow.Sdk
+{
+
+    /// <summary>
+    /// Defines helper methods to handle CRON expressions
+    /// </summary>
+    public static class Cron
+    {
+
+        /// <summary>
+        /// Parses the specified input into a new <see cref="CronExpression"/>
+        /// </summary>
+        /// <param name="input">The input to parse</param>
+        /// <returns>A new <see cref="CronExpression"/></returns>
+        public static CronExpression Parse(string input) => CronExpression.Parse(input);
+
+        /// <summary>
+        /// Parses the specified input into a new <see cref="CronExpression"/>
+        /// </summary>
+        /// <param name="input">The input to parse</param>
+        /// <param name="cron">The parsed <see cref="CronExpression"/>, if any</param>
+        /// <returns>A boolean indicating whether or not the specified input could be parsed</returns>
+        public static bool TryParse(string input, out CronExpression? cron)
+        {
+            cron = default;
+            try
+            {
+                cron = Parse(input);
+                return true;
+            }
+            catch
+            {
+                return false;
+            }
+        }
+
+    }
+
+}

src/ServerlessWorkflow.Sdk/Models/ScheduleDefinition.cs

@@ -15,6 +15,7 @@
  *
  */
 using Newtonsoft.Json.Linq;
+using System;
 using YamlDotNet.Serialization;
 
 namespace ServerlessWorkflow.Sdk.Models
@@ -31,9 +32,11 @@ public class ScheduleDefinition
         /// <summary>
         /// Gets/sets the time interval (ISO 8601 format) describing when workflow instances can be created.
         /// </summary>
+        [Newtonsoft.Json.JsonConverter(typeof(Newtonsoft.Json.Converters.Iso8601TimeSpanConverter))]
+        [System.Text.Json.Serialization.JsonConverter(typeof(System.Text.Json.Serialization.Converters.Iso8601NullableTimeSpanConverter))]
         [ProtoMember(1)]
         [DataMember(Order = 1)]
-        public virtual string? Interval { get; set; }
+        public virtual TimeSpan? Interval { get; set; }
 
         /// <summary>
         /// Gets/sets a <see cref="JToken"/> that represents the CRON expression that defines when the workflow instance should be created

src/ServerlessWorkflow.Sdk/ServerlessWorkflow.Sdk.csproj

@@ -4,9 +4,9 @@
     <TargetFramework>net6.0</TargetFramework>
 	<Nullable>enable</Nullable>
     <NeutralLanguage>en</NeutralLanguage>
-    <AssemblyVersion>0.8.1.16</AssemblyVersion>
-    <FileVersion>0.8.1.16</FileVersion>
-    <Version>0.8.1.16</Version>
+    <AssemblyVersion>0.8.2</AssemblyVersion>
+    <FileVersion>0.8.2</FileVersion>
+    <Version>0.8.2</Version>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
@@ -44,6 +44,7 @@
 
   <ItemGroup>
     <PackageReference Include="CloudNative.CloudEvents" Version="2.3.1" />
+    <PackageReference Include="Cronos" Version="0.7.1" />
     <PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.2.1" />
     <PackageReference Include="Iso8601DurationHelper" Version="1.0.5" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="6.0.0" />

src/ServerlessWorkflow.Sdk/ServerlessWorkflow.Sdk.xml

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2021-Present The Serverless Workflow Specification Authors
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+using ServerlessWorkflow.Sdk.Models;
+using System;
+
+namespace ServerlessWorkflow.Sdk.Services.FluentBuilders
+{
+
+    /// <summary>
+    /// Defines the fundamentals of a service used to build a <see cref="ScheduleDefinition"/>
+    /// </summary>
+    public interface IScheduleBuilder
+    {
+
+        /// <summary>
+        /// Configures the <see cref="ScheduleDefinition"/> to execute at the specified interval
+        /// </summary>
+        /// <param name="interval">The interval at which to execute the <see cref="ScheduleDefinition"/></param>
+        /// <returns>The configured <see cref="IScheduleBuilder"/></returns>
+        IScheduleBuilder AtInterval(TimeSpan interval);
+
+        /// <summary>
+        /// Configures the <see cref="ScheduleDefinition"/> to execute at a frequency defined by the specified CRON expression
+        /// </summary>
+        /// <param name="cronExpression">A CRON expression that defines the frequency at which to execute the <see cref="ScheduleDefinition"/></param>
+        /// <param name="validUntil">The date and time when the cron expression invocation is no longer valid</param>
+        /// <returns>The configured <see cref="IScheduleBuilder"/></returns>
+        IScheduleBuilder Every(string cronExpression, DateTime? validUntil = null);
+
+        /// <summary>
+        /// Configures the <see cref="ScheduleDefinition"/> to use the specified timezone
+        /// </summary>
+        /// <param name="timezone">The timezone to use</param>
+        /// <returns>The configured <see cref="IScheduleBuilder"/></returns>
+        IScheduleBuilder UseTimezone(string? timezone);
+
+        /// <summary>
+        /// Builds a new <see cref="ScheduleDefinition"/>
+        /// </summary>
+        /// <returns>A new <see cref="ScheduleDefinition"/></returns>
+        ScheduleDefinition Build();
+
+    }
+
+}

src/ServerlessWorkflow.Sdk/Services/FluentBuilders/Interfaces/IScheduleBuilder.cs

@@ -215,6 +215,23 @@ public interface IWorkflowBuilder
         /// <returns>A new <see cref="IPipelineBuilder"/> used to configure the <see cref="WorkflowDefinition"/>'s <see cref="StateDefinition"/>s</returns>
         IPipelineBuilder StartsWith(string name, Func<IStateBuilderFactory, IStateBuilder> stateSetup);
 
+        /// <summary>
+        /// Sets and configures the startup <see cref="StateDefinition"/>
+        /// </summary>
+        /// <param name="stateSetup">An <see cref="Func{T, TResult}"/> used to setup the startup <see cref="StateDefinition"/></param>
+        /// <param name="scheduleSetup">An <see cref="Action{T}"/> used to setup the <see cref="WorkflowDefinition"/>'s schedule</param>
+        /// <returns>A new <see cref="IPipelineBuilder"/> used to configure the <see cref="WorkflowDefinition"/>'s <see cref="StateDefinition"/>s</returns>
+        IPipelineBuilder StartsWith(Func<IStateBuilderFactory, IStateBuilder> stateSetup, Action<IScheduleBuilder> scheduleSetup);
+
+        /// <summary>
+        /// Sets and configures the startup <see cref="StateDefinition"/>
+        /// </summary>
+        /// <param name="name">The name of the startup <see cref="StateDefinition"/></param>
+        /// <param name="stateSetup">An <see cref="Func{T, TResult}"/> used to setup the startup <see cref="StateDefinition"/></param>
+        /// <param name="scheduleSetup">An <see cref="Action{T}"/> used to setup the <see cref="WorkflowDefinition"/>'s schedule</param>
+        /// <returns>A new <see cref="IPipelineBuilder"/> used to configure the <see cref="WorkflowDefinition"/>'s <see cref="StateDefinition"/>s</returns>
+        IPipelineBuilder StartsWith(string name, Func<IStateBuilderFactory, IStateBuilder> stateSetup, Action<IScheduleBuilder> scheduleSetup);
+
         /// <summary>
         /// Adds the <see cref="EventDefinition"/>s defined in the specified file
         /// </summary>