Add large-payload blob auto-purge (opt-in singleton job, worker/SDK side)

src/Client/Core/LargePayloadPurgeDisposition.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask.Client;
+
+/// <summary>
+/// The outcome of a single large-payload blob deletion attempt. The split is by whether a failure can
+/// self-heal. Mirrors the <c>LargePayloadPurgeDisposition</c> protobuf enum.
+/// </summary>
+public enum LargePayloadPurgeDisposition
+{
+    /// <summary>
+    /// No disposition was specified.
+    /// </summary>
+    Unspecified = 0,
+
+    /// <summary>
+    /// Terminal success. The blob was deleted, was already absent, or was deliberately left in place because
+    /// it is not owned by the payload store. The backend deletes the tombstone in all three cases.
+    /// </summary>
+    Deleted = 1,
+
+    /// <summary>
+    /// The failure may self-heal, so the row stays pending and the backend sets the next attempt.
+    /// </summary>
+    Retry = 2,
+
+    /// <summary>
+    /// A deterministic failure or protocol violation that retrying can never fix. The backend preserves the
+    /// evidence, alerts, and stops automatic retries.
+    /// </summary>
+    Quarantined = 3,
+}

src/Client/Core/LargePayloadPurgeResult.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask.Client;
+
+/// <summary>
+/// Serializable outcome of exactly one attempted large-payload blob deletion. Mirrors the
+/// <c>LargePayloadPurgeResult</c> protobuf message but is safe to pass through the orchestration/activity
+/// boundary. The backend owns retry scheduling and branches solely on
+/// <see cref="Disposition"/>: it deletes rows reported as
+/// <see cref="LargePayloadPurgeDisposition.Deleted"/>, reschedules
+/// <see cref="LargePayloadPurgeDisposition.Retry"/> on its own backoff, and moves
+/// <see cref="LargePayloadPurgeDisposition.Quarantined"/> rows out of the active fetch. The worker never
+/// computes a retry delay.
+/// </summary>
+/// <remarks>
+/// The disposition is deliberately the only outcome field: anything finer would be write-only on the backend.
+/// Why an attempt failed stays in the worker's own telemetry, which holds the cause at full fidelity rather
+/// than as a lossy classification.
+/// </remarks>
+/// <param name="TombstoneToken">
+/// The opaque correlation token echoed unchanged from the fetched <see cref="LargePayloadTombstone"/>. It is
+/// what identifies the row being reported on, so it must be passed back exactly as received: callers must not
+/// parse it, derive from it, or construct one.
+/// <para>
+/// Opaqueness here is encapsulation, not security. The token is not an authentication credential and carries
+/// no integrity guarantee, so treating a well-formed token as proof that the caller was entitled to report on
+/// that row would be wrong. Authentication and task-hub scope are the security boundary.
+/// </para>
+/// </param>
+/// <param name="Disposition">The disposition of the deletion attempt.</param>
+public sealed record LargePayloadPurgeResult(
+    string TombstoneToken,
+    LargePayloadPurgeDisposition Disposition);

src/Client/Core/LargePayloadTombstone.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask.Client;
+
+/// <summary>
+/// Serializable representation of a tombstoned large-payload row whose external blob a credentialed caller
+/// must delete. Mirrors the <c>LargePayloadTombstone</c> protobuf message but is safe to pass through the
+/// orchestration/activity boundary.
+/// </summary>
+/// <param name="TombstoneToken">
+/// The opaque, backend-issued correlation token for this exact tombstone version. Its format is deliberately
+/// not part of the contract: callers must not parse it, and must echo it back unchanged in the corresponding
+/// <see cref="LargePayloadPurgeResult"/> so the backend can resolve the row it came from.
+/// </param>
+/// <param name="PayloadToken">
+/// The self-describing <c>blob:v2:{fullBlobUrl}</c> payload token whose backing blob should be deleted.
+/// </param>
+public sealed record LargePayloadTombstone(string TombstoneToken, string PayloadToken)
+{
+    /// <summary>
+    /// The maximum number of tombstones a single <c>GetLargePayloadTombstones</c> request may ask for. The
+    /// service clamps a larger request down to its own maximum, so this is the largest value that is worth
+    /// asking for rather than a value that will be rejected. Validators that bound a caller-supplied limit
+    /// compare against this shared value rather than a hard-coded literal so the bound cannot drift between
+    /// the client and the auto-purge extension.
+    /// </summary>
+    public const int MaxRequestLimit = 1000;
+}

src/Client/Grpc/GrpcDurableTaskClient.cs

@@ -14,17 +14,19 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using static Microsoft.DurableTask.Protobuf.TaskHubSidecarService;
+using LP = Microsoft.DurableTask.Protobuf.LargePayloads;
 using P = Microsoft.DurableTask.Protobuf;
 
 namespace Microsoft.DurableTask.Client.Grpc;
 
 /// <summary>
 /// Durable Task client implementation that uses gRPC to connect to a remote "sidecar" process.
 /// </summary>
-public sealed class GrpcDurableTaskClient : DurableTaskClient
+public sealed class GrpcDurableTaskClient : DurableTaskClient, Internal.ILargePayloadAutoPurgeClient
 {
     readonly ILogger logger;
     readonly TaskHubSidecarServiceClient sidecarClient;
+    readonly LP.LargePayloadPurge.LargePayloadPurgeClient largePayloadPurgeClient;
     readonly GrpcDurableTaskClientOptions options;
     readonly DurableEntityClient? entityClient;
     AsyncDisposable asyncDisposable;
@@ -56,6 +58,13 @@ public GrpcDurableTaskClient(string name, GrpcDurableTaskClientOptions options,
         this.asyncDisposable = GetCallInvoker(options, logger, out CallInvoker callInvoker);
         this.sidecarClient = new TaskHubSidecarServiceClient(callInvoker);
 
+        // Built on the SAME effective invoker as the sidecar client, which is what keeps the DTS-only purge
+        // service on this client's existing channel and inside its configured interceptors. That invoker may be
+        // a ChannelRecreatingCallInvoker, so the generated client follows the client's channel swaps rather than
+        // pinning the channel it happened to see here. Constructed unconditionally: it opens no connection of
+        // its own, so an app that never touches auto-purge pays only the allocation.
+        this.largePayloadPurgeClient = new LP.LargePayloadPurge.LargePayloadPurgeClient(callInvoker);
+
         if (this.options.EnableEntitySupport)
         {
             this.entityClient = new GrpcDurableEntityClient(this.Name, this.DataConverter, this.sidecarClient, logger);
@@ -625,6 +634,26 @@ public override async Task<IList<HistoryEvent>> GetOrchestrationHistoryAsync(
         }
     }
 
+    /// <inheritdoc/>
+    async Task Internal.ILargePayloadAutoPurgeClient.SetLargePayloadAutoPurgeAsync(bool enabled, CancellationToken cancellation)
+    {
+        try
+        {
+            await this.largePayloadPurgeClient.SetLargePayloadAutoPurgeAsync(
+                new LP.SetLargePayloadAutoPurgeRequest { Enabled = enabled },
+                cancellationToken: cancellation);
+        }
+        catch (RpcException e) when (e.StatusCode == StatusCode.Cancelled)
+        {
+            throw new OperationCanceledException(
+                "The SetLargePayloadAutoPurge operation was canceled.", e, cancellation);
+        }
+        catch (RpcException e) when (e.StatusCode == StatusCode.Unimplemented)
+        {
+            throw new NotImplementedException(e.Status.Detail);
+        }
+    }
+
     static AsyncDisposable GetCallInvoker(GrpcDurableTaskClientOptions options, ILogger logger, out CallInvoker callInvoker)
     {
         AsyncDisposable disposable = GetCallInvokerCore(options, logger, out CallInvoker core);

src/Client/Grpc/Internal/ILargePayloadAutoPurgeClient.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask.Client.Grpc.Internal;
+
+/// <summary>
+/// Exposes the backend's large-payload auto-purge setting to the Azure Blob payloads extension, which owns the
+/// public API that turns the feature on and off.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is an internal API that supports the DurableTask infrastructure and not subject to
+/// the same compatibility standards as public APIs. It may be changed or removed without notice in
+/// any release. You should not implement it, and should not use it directly in your code. Doing so
+/// can result in application failures when updating to a new DurableTask release.
+/// </para>
+/// <para>
+/// Deliberately narrow. The extension needs exactly one backend operation, and it must reach it over the
+/// client's own transport - the same post-interceptor <c>CallInvoker</c> the client uses for every other RPC,
+/// so the call carries the configured auth chain and follows channel recreation. Handing out the raw
+/// <c>CallInvoker</c> instead would let a caller build arbitrary clients on the transport. The other two purge
+/// RPCs are not here: they are executed by the worker's activities on the worker's transport, and no client
+/// ever calls them.
+/// </para>
+/// <para>
+/// Implemented explicitly by <see cref="GrpcDurableTaskClient"/>, so a client that is not the gRPC client - or
+/// a gRPC client from an SDK version that predates this - fails the cast rather than silently doing nothing.
+/// </para>
+/// </remarks>
+public interface ILargePayloadAutoPurgeClient
+{
+    /// <summary>
+    /// Sets the large-payload blob auto-purge setting for the caller's authenticated task hub.
+    /// </summary>
+    /// <param name="enabled">The setting to persist.</param>
+    /// <param name="cancellation">The cancellation token.</param>
+    /// <returns>A task that completes once the backend has acknowledged the setting.</returns>
+    Task SetLargePayloadAutoPurgeAsync(bool enabled, CancellationToken cancellation = default);
+}