Promoting Jobs to stable APIs

src/Dapr.Jobs/Dapr.Jobs.csproj

@@ -6,7 +6,6 @@
         <PackageId>Dapr.Jobs</PackageId>
         <Title>Dapr Jobs Authoring SDK</Title>
         <Description>Dapr Jobs SDK for scheduling jobs and tasks with Dapr</Description>
-        <VersionSuffix>alpha</VersionSuffix>
     </PropertyGroup>
 
     <ItemGroup>

src/Dapr.Jobs/DaprJobsClient.cs

@@ -11,7 +11,6 @@
 // limitations under the License.
 // ------------------------------------------------------------------------
 
-using System.Diagnostics.CodeAnalysis;
 using Dapr.Common;
 using Dapr.Jobs.Models;
 using Dapr.Jobs.Models.Responses;
@@ -34,7 +33,6 @@ namespace Dapr.Jobs;
 /// exhaustion and other problems.
 /// </para>
 /// </summary>
-[Experimental("DAPR_JOBS", UrlFormat = "https://docs.dapr.io/developing-applications/building-blocks/jobs/jobs-overview/")]
 public abstract class DaprJobsClient(Autogenerated.DaprClient client, HttpClient httpClient, string? daprApiToken = null) : IDaprClient
 {
     private bool disposed;

src/Dapr.Jobs/DaprJobsClientBuilder.cs

@@ -11,7 +11,6 @@
 // limitations under the License.
 // ------------------------------------------------------------------------
 
-using System.Diagnostics.CodeAnalysis;
 using Dapr.Common;
 using Microsoft.Extensions.Configuration;
 using Autogenerated = Dapr.Client.Autogen.Grpc.v1;
@@ -22,7 +21,6 @@ namespace Dapr.Jobs;
 /// Builds a <see cref="DaprJobsClient"/>.
 /// </summary>
 /// <param name="configuration">An optional instance of <see cref="IConfiguration"/>.</param>
-[Experimental("DAPR_JOBS", UrlFormat = "https://docs.dapr.io/developing-applications/building-blocks/jobs/jobs-overview/")]
 public sealed class DaprJobsClientBuilder(IConfiguration? configuration = null) : DaprGenericClientBuilder<DaprJobsClient>(configuration)
 {
     /// <summary>

src/Dapr.Jobs/DaprJobsGrpcClient.cs

@@ -11,7 +11,6 @@
 // limitations under the License.
 // ------------------------------------------------------------------------
 
-using System.Diagnostics.CodeAnalysis;
 using Dapr.Common;
 using Dapr.Jobs.Models;
 using Dapr.Jobs.Models.Responses;
@@ -25,7 +24,6 @@ namespace Dapr.Jobs;
 /// <summary>
 /// A client for interacting with the Dapr endpoints.
 /// </summary>
-[Experimental("DAPR_JOBS", UrlFormat = "https://docs.dapr.io/developing-applications/building-blocks/jobs/jobs-overview/")]
 internal sealed class DaprJobsGrpcClient(Autogenerated.Dapr.DaprClient client, HttpClient httpClient, string? daprApiToken = null) : DaprJobsClient(client, httpClient, daprApiToken: daprApiToken)
 {
     /// <summary>
@@ -134,7 +132,7 @@ public override async Task ScheduleJobAsync(string jobName, DaprJobSchedule sche
 
         try
         {
-            await Client.ScheduleJobAlpha1Async(envelope, grpcCallOptions).ConfigureAwait(false);
+            await Client.ScheduleJobAsync(envelope, grpcCallOptions).ConfigureAwait(false);
         }
         catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
         {
@@ -169,7 +167,7 @@ public override async Task<DaprJobDetails> GetJobAsync(string jobName, Cancellat
         {
             var envelope = new Autogenerated.GetJobRequest { Name = jobName };
             var grpcCallOptions = DaprClientUtilities.ConfigureGrpcCallOptions(typeof(DaprJobsClient).Assembly, this.DaprApiToken, cancellationToken);
-            var response = await Client.GetJobAlpha1Async(envelope, grpcCallOptions);
+            var response = await Client.GetJobAsync(envelope, grpcCallOptions);
             return DeserializeJobResponse(response);
         }
         catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
@@ -228,7 +226,7 @@ internal static DaprJobDetails DeserializeJobResponse(Autogenerated.GetJobRespon
         {
             DueTime = !string.IsNullOrWhiteSpace(response.Job.DueTime) ? DateTime.Parse(response.Job.DueTime) : null,
             Ttl = !string.IsNullOrWhiteSpace(response.Job.Ttl) ? DateTime.Parse(response.Job.Ttl) : null,
-            RepeatCount = (int?)response.Job.Repeats ?? 0,
+            RepeatCount = (int?)response.Job.Repeats,
             Payload = response.Job.Data?.Value?.ToByteArray() ?? null,
             FailurePolicy = failurePolicyResponse
         };
@@ -251,7 +249,7 @@ public override async Task DeleteJobAsync(string jobName, CancellationToken canc
         {
             var envelope = new Autogenerated.DeleteJobRequest { Name = jobName };
             var grpcCallOptions = DaprClientUtilities.ConfigureGrpcCallOptions(typeof(DaprJobsClient).Assembly, this.DaprApiToken, cancellationToken);
-            await Client.DeleteJobAlpha1Async(envelope, grpcCallOptions);
+            await Client.DeleteJobAsync(envelope, grpcCallOptions);
         }
         catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
         {

src/Dapr.Jobs/Extensions/DaprJobsServiceCollectionExtensions.cs

@@ -11,7 +11,6 @@
 // limitations under the License.
 // ------------------------------------------------------------------------
 
-using System.Diagnostics.CodeAnalysis;
 using Dapr.Common.Extensions;
 using Microsoft.Extensions.DependencyInjection;
 
@@ -20,7 +19,6 @@ namespace Dapr.Jobs.Extensions;
 /// <summary>
 /// Contains extension methods for using Dapr Jobs with dependency injection.
 /// </summary>
-[Experimental("DAPR_JOBS", UrlFormat = "https://docs.dapr.io/developing-applications/building-blocks/jobs/jobs-overview/")]
 public static class DaprJobsServiceCollectionExtensions
 {
     /// <summary>

src/Dapr.Jobs/Extensions/DaprSerializationExtensions.cs

@@ -11,7 +11,6 @@
 // limitations under the License.
 // ------------------------------------------------------------------------
 
-using System.Diagnostics.CodeAnalysis;
 using System.Text;
 using System.Text.Json;
 using Dapr.Jobs.Models;
@@ -21,13 +20,12 @@ namespace Dapr.Jobs.Extensions;
 /// <summary>
 /// Provides helper extensions for performing serialization operations when scheduling one-time Cron jobs for the developer.
 /// </summary>
-[Experimental("DAPR_JOBS", UrlFormat = "https://docs.dapr.io/developing-applications/building-blocks/jobs/jobs-overview/")]
 public static class DaprJobsSerializationExtensions
 {
     /// <summary>
     /// Default JSON serializer options.
     /// </summary>
-    private static readonly JsonSerializerOptions defaultOptions = new(JsonSerializerDefaults.Web);
+    private static readonly JsonSerializerOptions DefaultOptions = new(JsonSerializerDefaults.Web);
 
     /// <summary>
     /// Schedules a job with Dapr.
@@ -51,7 +49,7 @@ public static async Task ScheduleJobWithPayloadAsync(this DaprJobsClient client,
     {
         ArgumentNullException.ThrowIfNull(payload, nameof(payload));
 
-        var serializerOptions = jsonSerializerOptions ?? defaultOptions;
+        var serializerOptions = jsonSerializerOptions ?? DefaultOptions;
         var payloadBytes =
             JsonSerializer.SerializeToUtf8Bytes(payload, serializerOptions);
 

src/Dapr.Jobs/IDaprJobsBuilder.cs

@@ -12,7 +12,6 @@
 //  ------------------------------------------------------------------------
 
 using Dapr.Common;
-using Microsoft.Extensions.DependencyInjection;
 
 namespace Dapr.Jobs;
 

src/Dapr.Jobs/Models/DaprJobSchedule.cs

@@ -22,16 +22,16 @@ namespace Dapr.Jobs.Models;
 /// Used to build a schedule for a job.
 /// </summary>
 [JsonConverter(typeof(DaprJobScheduleConverter))]
-public sealed class DaprJobSchedule
+public sealed partial class DaprJobSchedule
 {
     /// <summary>
     /// A regular expression used to evaluate whether a given prefix period embodies an @every statement.
     /// </summary>
-    private static readonly Regex isEveryExpression = new(@"^@every (\d+(m?s|m|h))+$", RegexOptions.Compiled);
+    private static readonly Regex IsEveryExpression = IsEveryExpressionRegex();
     /// <summary>
     /// The various prefixed period values allowed.
     /// </summary>
-    private static readonly string[] acceptablePeriodValues = { "yearly", "monthly", "weekly", "daily", "midnight", "hourly" };
+    private static readonly string[] AcceptablePeriodValues = { "yearly", "monthly", "weekly", "daily", "midnight", "hourly" };
 
     /// <summary>
     /// The value of the expression represented by the schedule.
@@ -114,8 +114,8 @@ public static DaprJobSchedule FromCronExpression(CronExpressionBuilder builder)
     /// </summary>
     public bool IsPrefixedPeriodExpression =>
         ExpressionValue.StartsWith('@') &&
-        (isEveryExpression.IsMatch(ExpressionValue) ||
-         ExpressionValue.EndsWithAny(acceptablePeriodValues, StringComparison.InvariantCulture));
+        (IsEveryExpression.IsMatch(ExpressionValue) ||
+         ExpressionValue.EndsWithAny(AcceptablePeriodValues, StringComparison.InvariantCulture));
 
     /// <summary>
     /// Reflects that the schedule represents a fixed point in time.
@@ -131,4 +131,7 @@ public static DaprJobSchedule FromCronExpression(CronExpressionBuilder builder)
     /// Reflects that the schedule represents a Cron expression.
     /// </summary>
     public bool IsCronExpression => CronExpressionBuilder.IsCronExpression(ExpressionValue);
+
+    [GeneratedRegex(@"^@every (\d+(m?s|m|h))+$", RegexOptions.Compiled)]
+    private static partial Regex IsEveryExpressionRegex();
 }

src/Dapr.Protos/Protos/dapr/proto/common/v1/common.proto

@@ -180,4 +180,4 @@ message JobFailurePolicyConstant {
   // max_retries is the optional maximum number of retries to attempt before giving up.
   // If unset, the Job will be retried indefinitely.
   optional uint32 max_retries = 2;
-}
+}

src/Dapr.Protos/Protos/dapr/proto/runtime/v1/dapr.proto

@@ -232,18 +232,45 @@ service Dapr {
   // Shutdown the sidecar
   rpc Shutdown (ShutdownRequest) returns (google.protobuf.Empty) {}
 
+  // Deprecated: Create and schedule a job
+  rpc ScheduleJobAlpha1(ScheduleJobRequest) returns (ScheduleJobResponse) {
+    option deprecated = true;
+  }
+
   // Create and schedule a job
-  rpc ScheduleJobAlpha1(ScheduleJobRequest) returns (ScheduleJobResponse) {}
+  rpc ScheduleJob(ScheduleJobRequest) returns (ScheduleJobResponse) {}
+
+  // Deprecated: Gets a scheduled job
+  rpc GetJobAlpha1(GetJobRequest) returns (GetJobResponse) {
+    option deprecated = true;
+  }
 
   // Gets a scheduled job
-  rpc GetJobAlpha1(GetJobRequest) returns (GetJobResponse) {}
+  rpc GetJob(GetJobRequest) returns (GetJobResponse) {}
+
+  // Deprecated: Delete a job
+  rpc DeleteJobAlpha1(DeleteJobRequest) returns (DeleteJobResponse) {
+    option deprecated = true;
+  }
 
   // Delete a job
-  rpc DeleteJobAlpha1(DeleteJobRequest) returns (DeleteJobResponse) {}
+  rpc DeleteJob(DeleteJobRequest) returns (DeleteJobResponse) {}
+
+  // Deprecated: Delete jobs by name prefix
+  rpc DeleteJobsByPrefixAlpha1(DeleteJobsByPrefixRequestAlpha1) returns (DeleteJobsByPrefixResponseAlpha1) {
+    option deprecated = true;
+  }
 
-  rpc DeleteJobsByPrefixAlpha1(DeleteJobsByPrefixRequestAlpha1) returns (DeleteJobsByPrefixResponseAlpha1) {}
+  // Delete jobs by name prefix
+  rpc DeleteJobsByPrefix(DeleteJobsByPrefixRequest) returns (DeleteJobsByPrefixResponse) {}
+
+  // Deprecated: List all jobs
+  rpc ListJobsAlpha1(ListJobsRequestAlpha1) returns (ListJobsResponseAlpha1) {
+    option deprecated = true;
+  }
 
-  rpc ListJobsAlpha1(ListJobsRequestAlpha1) returns (ListJobsResponseAlpha1) {}
+  // List all jobs
+  rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) {}
 
   // Converse with a LLM service
   rpc ConverseAlpha1(ConversationRequest) returns (ConversationResponse) {}

src/Dapr.Protos/Protos/dapr/proto/runtime/v1/jobs.proto

@@ -122,6 +122,17 @@ message DeleteJobsByPrefixResponseAlpha1 {
   // Empty
 }
 
+// DeleteJobsByPrefixRequest is the stable message to delete jobs by name prefix.
+message DeleteJobsByPrefixRequest {
+  // name_prefix is the prefix of the job names to delete. If not provided, all
+  // jobs associated with this app ID will be deleted.
+  optional string name_prefix = 1;
+}
+
+message DeleteJobsByPrefixResponse {
+  // Empty
+}
+
 message ListJobsRequestAlpha1 {
   // Empty
 }
@@ -130,4 +141,14 @@ message ListJobsRequestAlpha1 {
 message ListJobsResponseAlpha1 {
   // The list of jobs.
   repeated Job jobs = 1;
-}
+}
+
+message ListJobsRequest {
+  // Empty
+}
+
+// ListJobsResponse is the stable message response containing the list of jobs.
+message ListJobsResponse {
+  // The list of jobs.
+  repeated Job jobs = 1;
+}

test/Dapr.Jobs.Test/Dapr.Jobs.Test.csproj

@@ -26,6 +26,7 @@
 
     <ItemGroup>
       <ProjectReference Include="..\..\src\Dapr.Jobs\Dapr.Jobs.csproj" />
+      <ProjectReference Include="..\..\src\Dapr.Testcontainers.Xunit\Dapr.Testcontainers.Xunit.csproj" />
     </ItemGroup>
 
 </Project>

test/Dapr.Jobs.Test/DaprJobsClientBuilderTests.cs

@@ -59,7 +59,7 @@ public void DaprJobsClientBuilder_ValidatesGrpcEndpointScheme()
         var builder = new DaprJobsClientBuilder();
         builder.UseGrpcEndpoint("ftp://example.com");
 
-        var ex = Assert.Throws<InvalidOperationException>(() => builder.Build());
+        var ex = Assert.Throws<InvalidOperationException>(builder.Build);
         Assert.Equal("The gRPC endpoint must use http or https.", ex.Message);
     }
 
@@ -69,7 +69,7 @@ public void DaprJobsClientBuilder_ValidatesHttpEndpointScheme()
         var builder = new DaprJobsClientBuilder();
         builder.UseHttpEndpoint("ftp://example.com");
 
-        var ex = Assert.Throws<InvalidOperationException>(() => builder.Build());
+        var ex = Assert.Throws<InvalidOperationException>(builder.Build);
         Assert.Equal("The HTTP endpoint must use http or https.", ex.Message);
     }