feat(referrers): delete manifest with subject

src/OrasProject.Oras/Registry/Reference.cs

@@ -201,6 +201,18 @@
         }
     }
 
+    public Reference(Reference other)
+    {
+        if (other == null)
+        {
+            throw new ArgumentNullException(nameof(other));
+        }
+
+        _registry = other.Registry;
+        _repository = other.Repository;
+        ContentReference = other.ContentReference;
+    }
+
     public Reference(string registry) => _registry = ValidateRegistry(registry);
 
     public Reference(string registry, string? repository) : this(registry)

src/OrasProject.Oras/Registry/Remote/HttpResponseMessageExtensions.cs

@@ -98,7 +98,7 @@ public static void VerifyContentDigest(this HttpResponseMessage response, string
         }
         if (contentDigest != expected)
         {
-            throw new HttpIOException(HttpRequestError.InvalidResponse, $"{response.RequestMessage!.Method} {response.RequestMessage.RequestUri}: invalid response; digest mismatch in Docker-Content-Digest: received {contentDigest} when expecting {digestStr}");
+            throw new HttpIOException(HttpRequestError.InvalidResponse, $"{response.RequestMessage!.Method} {response.RequestMessage.RequestUri}: invalid response; digest mismatch in Docker-Content-Digest: received {contentDigest} when expecting {expected}");
         }
     }
 

src/OrasProject.Oras/Registry/Remote/ManifestStore.cs

@@ -29,7 +29,7 @@
 
 public class ManifestStore(Repository repository) : IManifestStore
 {
     public Repository Repository { get; init; } = repository;
 
     /// <summary>
     /// Fetches the content identified by the descriptor.
@@ -306,7 +306,7 @@
         }
 
         // 4. delete the dangling original referrers index, if applicable
         await DeleteAsync(oldDesc, cancellationToken).ConfigureAwait(false);
     }
 
     /// <summary>
@@ -397,5 +397,79 @@
     /// <param name="cancellationToken"></param>
     /// <returns></returns>
     public async Task DeleteAsync(Descriptor target, CancellationToken cancellationToken = default)
-        => await Repository.DeleteAsync(target, true, cancellationToken).ConfigureAwait(false);
+        => await DeleteWithIndexing(target, cancellationToken).ConfigureAwait(false);
+
+    /// <summary>
+    /// DeleteWithIndexing deletes the specified target (Descriptor) from the repository,
+    /// handling referrer indexing if necessary.
+    /// </summary>
+    /// <param name="target">The target descriptor to delete.</param>
+    /// <param name="cancellationToken">A cancellation token to cancel the operation if needed. Defaults to default.</param>
+    /// <returns></returns>
+    private async Task DeleteWithIndexing(Descriptor target, CancellationToken cancellationToken = default)
+    {
+        switch (target.MediaType)
+        {
+            case MediaType.ImageManifest:
+            case MediaType.ImageIndex:
+                if (Repository.ReferrersState == Referrers.ReferrersState.Supported)
+                {
+                    // referrers API is available, no client-side indexing needed
+                    await Repository.DeleteAsync(target, true, cancellationToken).ConfigureAwait(false);
+                    return;
+                }
+
+                await using (var manifest = await FetchAsync(target, cancellationToken).ConfigureAwait(false))
+                {
+                    await IndexReferrersForDelete(target, manifest, cancellationToken).ConfigureAwait(false);
+                }
+                break;
+        }
+        await Repository.DeleteAsync(target, true, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// IndexReferrersForDelete indexes referrers for manifests with a subject field on manifest delete.
+    /// References:
+    ///   - Latest spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#deleting-manifests
+    /// </summary>
+    /// <param name="target"></param>
+    /// <param name="manifestContent"></param>
+    /// <param name="cancellationToken"></param>
+    private async Task IndexReferrersForDelete(Descriptor target, Stream manifestContent, CancellationToken cancellationToken = default)
+    {
+        Descriptor subject;
+        switch (target.MediaType)
+        {
+            case MediaType.ImageManifest:
+                var imageManifest = JsonSerializer.Deserialize<Manifest>(manifestContent);
+                if (imageManifest?.Subject == null)
+                {
+                    // no subject, no indexing needed
+                    return;
+                }
+                subject = imageManifest.Subject;
+                break;
+            case MediaType.ImageIndex:
+                var imageIndex = JsonSerializer.Deserialize<Index>(manifestContent);
+                if (imageIndex?.Subject == null)
+                {
+                    // no subject, no indexing needed
+                    return;
+                }
+                subject = imageIndex.Subject;
+                break;
+            default:
+                return;
+        }
+
+        var isReferrersSupported = Repository.PingReferrers(cancellationToken);
+        if (isReferrersSupported)
+        {
+            // referrers API is available, no client-side indexing needed
+            return;
+        }
+        await UpdateReferrersIndex(subject, new Referrers.ReferrerChange(target, Referrers.ReferrerOperation.Delete), cancellationToken)
+            .ConfigureAwait(false);
+    }
 }

src/OrasProject.Oras/Registry/Remote/Referrers.cs

@@ -12,9 +12,7 @@
 // limitations under the License.
 
 using System.Collections.Generic;
-using System.Linq;
 using OrasProject.Oras.Content;
-using OrasProject.Oras.Exceptions;
 using OrasProject.Oras.Oci;
 
 namespace OrasProject.Oras.Registry.Remote;
@@ -29,6 +27,8 @@ internal enum ReferrersState
     }
 
     internal record ReferrerChange(Descriptor Referrer, ReferrerOperation ReferrerOperation);
+
+    internal const string ZeroDigest = "sha256:0000000000000000000000000000000000000000000000000000000000000000";
 
     internal enum ReferrerOperation
     {

src/OrasProject.Oras/Registry/Remote/Repository.cs

@@ -76,6 +76,8 @@
 
     private RepositoryOptions _opts;
 
+    private static readonly Object _referrersPingLock = new();
+
     /// <summary>
     /// Creates a client to the remote repository identified by a reference
     /// Example: localhost:5000/hello-world
@@ -369,6 +371,69 @@
     public async Task MountAsync(Descriptor descriptor, string fromRepository, Func<CancellationToken, Task<Stream>>? getContent = null, CancellationToken cancellationToken = default) 
         => await ((IMounter)Blobs).MountAsync(descriptor, fromRepository, getContent, cancellationToken).ConfigureAwait(false);
 
+    /// <summary>
+    /// PingReferrers returns true if the Referrers API is available for the repository,
+    /// otherwise returns false
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
+    /// <exception cref="ResponseException"></exception>
+    /// <exception cref="Exception"></exception>
+    internal bool PingReferrers(CancellationToken cancellationToken = default)
+    {
+        switch (ReferrersState)
+        {
+            case Referrers.ReferrersState.Supported:
+                return true;
+            case Referrers.ReferrersState.NotSupported:
+                return false;
+        }
+
+        lock (_referrersPingLock)
+        {
+            // referrers state is unknown
+            // lock to limit the rate of pinging referrers API
+            if (ReferrersState == Referrers.ReferrersState.Supported)
+            {
+                return true;
+            }
+
+            if (ReferrersState == Referrers.ReferrersState.NotSupported)
+            {
+                return false;
+            }
+
+            var reference = new Reference(Options.Reference);
+            reference.ContentReference = Referrers.ZeroDigest;
+            var url = new UriFactory(reference, Options.PlainHttp).BuildReferrersUrl();
+            var request = new HttpRequestMessage(HttpMethod.Get, url);
+            var response = Options.HttpClient.SendAsync(request, cancellationToken).ConfigureAwait(true).GetAwaiter()
+                .GetResult();
+
+            switch (response.StatusCode)
+            {
+                case HttpStatusCode.OK:
+                    var supported = response.Content.Headers.ContentType?.MediaType == MediaType.ImageIndex;
+                    SetReferrersState(supported);
+                    return supported;
+                case HttpStatusCode.NotFound:
+                    var err = (ResponseException)response.ParseErrorResponseAsync(cancellationToken)
+                        .ConfigureAwait(true).GetAwaiter().GetResult();
+                    if (err.Errors?.First().Code == ResponseException.ErrorCodeNameUnknown)
+                    {
+                        // referrer state is unknown because the repository is not found
+                        throw err;
+                    }
+
+                    SetReferrersState(false);
+                    return false;
+                default:
+                    throw response.ParseErrorResponseAsync(cancellationToken).ConfigureAwait(true).GetAwaiter()
+                        .GetResult();
+            }
+        }
+    }
+
     /// <summary>
     /// SetReferrersState indicates the Referrers API state of the remote repository. true: supported; false: not supported.
     /// SetReferrersState is valid only when it is called for the first time.

src/OrasProject.Oras/Registry/Remote/ResponseException.cs

@@ -15,15 +15,14 @@
 using System.Collections.Generic;
 using System.Net;
 using System.Net.Http;
-using System.Text;
 using System.Text.Json;
-using System.Text.Json.Nodes;
 using System.Text.Json.Serialization;
 
 namespace OrasProject.Oras.Registry.Remote;
 
 public class ResponseException : HttpRequestException
-{
+{
+    public static readonly string ErrorCodeNameUnknown = "NAME_UNKNOWN";
     public class Error
     {
         [JsonPropertyName("code")]
@@ -34,45 +33,45 @@ public class Error
 
         [JsonPropertyName("detail")]
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
-        public JsonElement? Detail { get; set; }
+        public JsonElement? Detail { get; set; }
     }
 
-    public class ErrorResponse
-    {
+    public class ErrorResponse
+    {
         [JsonPropertyName("errors")]
-        public required IList<Error> Errors { get; set; }
+        public required IList<Error> Errors { get; set; }
     }
 
     public HttpMethod? Method { get; }
 
     public Uri? RequestUri { get; }
 
-    public IList<Error>? Errors { get; }
-
-    public ResponseException(HttpResponseMessage response, string? responseBody = null)
-        : this(response, responseBody, null)
-    {
-    }
-
-    public ResponseException(HttpResponseMessage response, string? responseBody, string? message)
-        : this(response, responseBody, response.StatusCode == HttpStatusCode.Unauthorized ? HttpRequestError.UserAuthenticationError : HttpRequestError.Unknown, message, null)
-    {
-    }
-
-    public ResponseException(HttpResponseMessage response, string? responseBody, HttpRequestError httpRequestError, string? message, Exception? inner)
-        : base(httpRequestError, message, inner, response.StatusCode)
-    {
-        var request = response.RequestMessage;
-        Method = request?.Method;
-        RequestUri = request?.RequestUri;
-        if (responseBody != null)
-        {
-            try
-            {
-                var errorResponse = JsonSerializer.Deserialize<ErrorResponse>(responseBody);
-                Errors = errorResponse?.Errors;
-            }
-            catch { }
+    public IList<Error>? Errors { get; }
+
+    public ResponseException(HttpResponseMessage response, string? responseBody = null)
+        : this(response, responseBody, null)
+    {
+    }
+
+    public ResponseException(HttpResponseMessage response, string? responseBody, string? message)
+        : this(response, responseBody, response.StatusCode == HttpStatusCode.Unauthorized ? HttpRequestError.UserAuthenticationError : HttpRequestError.Unknown, message, null)
+    {
+    }
+
+    public ResponseException(HttpResponseMessage response, string? responseBody, HttpRequestError httpRequestError, string? message, Exception? inner)
+        : base(httpRequestError, message, inner, response.StatusCode)
+    {
+        var request = response.RequestMessage;
+        Method = request?.Method;
+        RequestUri = request?.RequestUri;
+        if (responseBody != null)
+        {
+            try
+            {
+                var errorResponse = JsonSerializer.Deserialize<ErrorResponse>(responseBody);
+                Errors = errorResponse?.Errors;
+            }
+            catch { }
         }
     }
 }

src/OrasProject.Oras/Registry/Remote/UriFactory.cs

@@ -13,6 +13,7 @@
 
 using OrasProject.Oras.Exceptions;
 using System;
+using System.Web;
 
 namespace OrasProject.Oras.Registry.Remote;
 
@@ -102,6 +103,26 @@ public Uri BuildRepositoryBlobUpload()
         return builder.Uri;
     }
 
+    /// <summary>
+    /// Builds the URL for accessing the Referrers API
+    /// Format: <scheme>://<registry>/v2/<repository>/referrers/<reference>?artifactType=<artifactType>
+    /// </summary>
+    /// <param name="artifactType"></param>
+    /// <returns></returns>
+    public Uri BuildReferrersUrl(string? artifactType = null)
+    {
+        var builder = NewRepositoryBaseBuilder();
+        builder.Path += $"/referrers/{_reference.ContentReference}";
+        if (!string.IsNullOrEmpty(artifactType))
+        {
+            var query = HttpUtility.ParseQueryString(builder.Query);
+            query.Add("artifactType", artifactType);
+            builder.Query = query.ToString();
+        }
+
+        return builder.Uri;
+    }
+
     /// <summary>
     /// Generates a UriBuilder with the base endpoint of the remote repository.
     /// Format: <scheme>://<registry>/v2/<repository>