refactor!: modernize Reference

src/OrasProject.Oras/Content/Digest.cs

@@ -27,7 +27,7 @@ internal static class Digest
     /// Verifies the digest header and throws an exception if it is invalid.
     /// </summary>
     /// <param name="digest"></param>
-    internal static string Validate(string digest)
+    internal static string Validate(string? digest)
     {
         if (string.IsNullOrEmpty(digest) || !digestRegex.IsMatch(digest))
         {

src/OrasProject.Oras/Registry/Reference.cs

@@ -0,0 +1,226 @@
+// Copyright The ORAS Authors.
+// 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
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// 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 OrasProject.Oras.Exceptions;
+using System;
+using System.Text.RegularExpressions;
+
+namespace OrasProject.Oras.Registry;
+
+public class Reference
+{
+    /// <summary>
+    /// Registry is the name of the registry. It is usually the domain name of the registry optionally with a port.
+    /// </summary>
+    public string Registry
+    {
+        get => _registry;
+        set => _registry = ValidateRegistry(value);
+    }
+
+    /// <summary>
+    /// Repository is the name of the repository.
+    /// </summary>
+    public string? Repository
+    {
+        get => _repository;
+        set => _repository = value == null ? null : ValidateRepository(value);
+    }
+
+    /// <summary>
+    /// Reference is the reference of the object in the repository. This field
+    /// can take any one of the four valid forms (see ParseReference). In the
+    /// case where it's the empty string, it necessarily implies valid form D,
+    /// and where it is non-empty, then it is either a tag, or a digest
+    /// (implying one of valid forms A, B, or C).
+    /// </summary>
+    public string? ContentReference
+    {
+        get => _reference;
+        set
+        {
+            if (value == null)
+            {
+                _reference = value;
+                _isTag = false;
+                return;
+            }
+
+            if (value.Contains(':'))
+            {
+                _reference = ValidateReferenceAsDigest(value);
+                _isTag = false;
+                return;
+            }
+
+            _reference = ValidateReferenceAsTag(value);
+            _isTag = true;
+        }
+    }
+
+    /// <summary>
+    /// Host returns the host name of the registry
+    /// </summary>
+    public string Host => _registry == "docker.io" ? "registry-1.docker.io" : _registry;
+
+    /// <summary>
+    /// Digest returns the reference as a Digest
+    /// </summary>
+    public string Digest
+    {
+        get
+        {
+            if (_reference == null)
+            {
+                throw new InvalidReferenceException("null content reference");
+            }
+            if (_isTag)
+            {
+                throw new InvalidReferenceException("not a digest");
+            }
+            return _reference;
+        }
+    }
+
+    /// <summary>
+    /// Digest returns the reference as a Tag
+    /// </summary>
+    public string Tag
+    {
+        get
+        {
+            if (_reference == null)
+            {
+                throw new InvalidReferenceException("null content reference");
+            }
+            if (!_isTag)
+            {
+                throw new InvalidReferenceException("not a tag");
+            }
+            return _reference;
+        }
+    }
+
+    private string _registry;
+    private string? _repository;
+    private string? _reference;
+    private bool _isTag;
+
+    /// <summary>
+    /// repositoryRegexp is adapted from the distribution implementation. The
+    /// repository name set under OCI distribution spec is a subset of the docker
+    /// repositoryRegexp is adapted from the distribution implementation. The
+    /// spec. For maximum compatability, the docker spec is verified client-side.
+    /// Further checks are left to the server-side.
+    /// References:
+    /// - https://github.com/distribution/distribution/blob/v2.7.1/reference/regexp.go#L53
+    /// - https://github.com/opencontainers/distribution-spec/blob/v1.0.1/spec.md#pulling-manifests
+    /// </summary>
+    private const string _repositoryRegexPattern = @"^[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*)*$";
+    private static readonly Regex _repositoryRegex = new Regex(_repositoryRegexPattern, RegexOptions.Compiled);
+
+    /// <summary>
+    /// tagRegexp checks the tag name.
+    /// The docker and OCI spec have the same regular expression.
+    /// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.0.1/spec.md#pulling-manifests
+    /// </summary>
+    private const string _tagRegexPattern = @"^[\w][\w.-]{0,127}$";
+    private static readonly Regex _tagRegex = new Regex(_tagRegexPattern, RegexOptions.Compiled);
+
+    public static Reference Parse(string reference)
+    {
+        var parts = reference.Split('/', 2);
+        if (parts.Length == 1)
+        {
+            throw new InvalidReferenceException("missing repository");
+        }
+        var registry = parts[0];
+        var path = parts[1];
+
+        var index = path.IndexOf('@');
+        if (index != -1)
+        {
+            // digest found; Valid From A (if not B)
+            var repository = path[..index];
+            var contentReference = path[(index + 1)..];
+            index = repository.IndexOf(':');
+            if (index != -1)
+            {
+                // tag found ( and now dropped without validation ) since the
+                // digest already present; Valid Form B
+                repository = repository[..index];
+            }
+            var instance = new Reference(registry, repository)
+            {
+                _reference = ValidateReferenceAsDigest(contentReference),
+                _isTag = false
+            };
+            return instance;
+        }
+
+        index = path.IndexOf(':');
+        if (index != -1)
+        {
+            // tag found; Valid Form C
+            var repository = path[..index];
+            var contentReference = path[(index + 1)..];
+            var instance = new Reference(registry, repository)
+            {
+                _reference = ValidateReferenceAsTag(contentReference),
+                _isTag = true
+            };
+            return instance;
+        }
+
+        // empty `reference`; Valid Form D
+        return new Reference(registry, path);
+    }
+
+    public Reference(string registry) => _registry = ValidateRegistry(registry);
+
+    public Reference(string registry, string? repository) : this(registry)
+        => _repository = ValidateRepository(repository);
+
+    public Reference(string registry, string? repository, string? reference) : this(registry, repository)
+        => ContentReference = reference;
+
+    private static string ValidateRegistry(string registry)
+    {
+        var url = "dummy://" + registry;
+        if (!Uri.IsWellFormedUriString(url, UriKind.Absolute) || new Uri(url).Authority != registry)
+        {
+            throw new InvalidReferenceException("invalid registry");
+        }
+        return registry;
+    }
+
+    private static string ValidateRepository(string? repository)
+    {
+        if (repository == null || !_repositoryRegex.IsMatch(repository))
+        {
+            throw new InvalidReferenceException("invalid respository");
+        }
+        return repository;
+    }
+
+    private static string ValidateReferenceAsDigest(string? reference) => Content.Digest.Validate(reference);
+
+    private static string ValidateReferenceAsTag(string? reference)
+    {
+        if (reference == null || !_tagRegex.IsMatch(reference))
+        {
+            throw new InvalidReferenceException("invalid tag");
+        }
+        return reference;
+    }
+}

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

@@ -41,7 +41,7 @@
     {
         var remoteReference = Repository.RemoteReference;
         Digest.Validate(target.Digest);
-        remoteReference.Reference = target.Digest;
+        remoteReference.ContentReference = target.Digest;
         var url = URLUtiliity.BuildRepositoryBlobURL(Repository.PlainHTTP, remoteReference);
         var resp = await Repository.HttpClient.GetAsync(url, cancellationToken);
         switch (resp.StatusCode)
@@ -50,7 +50,7 @@
                 // server does not support seek as `Range` was ignored.
                 if (resp.Content.Headers.ContentLength is var size && size != -1 && size != target.Size)
                 {
                     throw new Exception($"{resp.RequestMessage.Method} {resp.RequestMessage.RequestUri}: mismatch Content-Length");
                 }
                 return await resp.Content.ReadAsStreamAsync();
             case HttpStatusCode.NotFound:
@@ -167,14 +167,14 @@
     public async Task<Descriptor> ResolveAsync(string reference, CancellationToken cancellationToken = default)
     {
         var remoteReference = Repository.ParseReference(reference);
-        var refDigest = remoteReference.Digest();
+        var refDigest = remoteReference.Digest;
         var url = URLUtiliity.BuildRepositoryBlobURL(Repository.PlainHTTP, remoteReference);
         var requestMessage = new HttpRequestMessage(HttpMethod.Head, url);
         using var resp = await Repository.HttpClient.SendAsync(requestMessage, cancellationToken);
         return resp.StatusCode switch
         {
             HttpStatusCode.OK => Repository.GenerateBlobDescriptor(resp, refDigest),
-            HttpStatusCode.NotFound => throw new NotFoundException($"{remoteReference.Reference}: not found"),
+            HttpStatusCode.NotFound => throw new NotFoundException($"{remoteReference.ContentReference}: not found"),
             _ => throw await ErrorUtility.ParseErrorResponse(resp)
         };
     }
@@ -200,7 +200,7 @@
     public async Task<(Descriptor Descriptor, Stream Stream)> FetchAsync(string reference, CancellationToken cancellationToken = default)
     {
         var remoteReference = Repository.ParseReference(reference);
-        var refDigest = remoteReference.Digest();
+        var refDigest = remoteReference.Digest;
         var url = URLUtiliity.BuildRepositoryBlobURL(Repository.PlainHTTP, remoteReference);
         var resp = await Repository.HttpClient.GetAsync(url, cancellationToken);
         switch (resp.StatusCode)

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

@@ -11,7 +11,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using OrasProject.Oras.Remote;
 using System.Net.Http;
 
 namespace OrasProject.Oras.Registry.Remote;
@@ -29,7 +28,7 @@ public interface IRepositoryOption
     /// <summary>
     /// Reference references the remote repository.
     /// </summary>
-    public RemoteReference RemoteReference { get; set; }
+    public Reference RemoteReference { get; set; }
 
     /// <summary>
     /// PlainHTTP signals the transport to access the remote repository via HTTP

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

@@ -47,7 +47,7 @@ public ManifestStore(Repository repository)
     public async Task<Stream> FetchAsync(Descriptor target, CancellationToken cancellationToken = default)
     {
         var remoteReference = Repository.RemoteReference;
-        remoteReference.Reference = target.Digest;
+        remoteReference.ContentReference = target.Digest;
         var url = URLUtiliity.BuildRepositoryManifestURL(Repository.PlainHTTP, remoteReference);
         var req = new HttpRequestMessage(HttpMethod.Get, url);
         req.Headers.Add("Accept", target.MediaType);
@@ -120,7 +120,7 @@ public async Task PushAsync(Descriptor expected, Stream content, CancellationTok
     private async Task InternalPushAsync(Descriptor expected, Stream stream, string reference, CancellationToken cancellationToken)
     {
         var remoteReference = Repository.RemoteReference;
-        remoteReference.Reference = reference;
+        remoteReference.ContentReference = reference;
         var url = URLUtiliity.BuildRepositoryManifestURL(Repository.PlainHTTP, remoteReference);
         var req = new HttpRequestMessage(HttpMethod.Put, url);
         req.Content = new StreamContent(stream);
@@ -159,7 +159,7 @@ public async Task<Descriptor> ResolveAsync(string reference, CancellationToken c
     /// <param name="httpMethod"></param>
     /// <returns></returns>
     /// <exception cref="Exception"></exception>
-    public async Task<Descriptor> GenerateDescriptorAsync(HttpResponseMessage res, RemoteReference reference, HttpMethod httpMethod)
+    public async Task<Descriptor> GenerateDescriptorAsync(HttpResponseMessage res, Reference reference, HttpMethod httpMethod)
     {
         string mediaType;
         try
@@ -183,7 +183,7 @@ public async Task<Descriptor> GenerateDescriptorAsync(HttpResponseMessage res, R
         string refDigest = string.Empty;
         try
         {
-            refDigest = reference.Digest();
+            refDigest = reference.Digest;
         }
         catch (Exception)
         {
@@ -325,7 +325,7 @@ public async Task PushAsync(Descriptor expected, Stream content, string referenc
         CancellationToken cancellationToken = default)
     {
         var remoteReference = Repository.ParseReference(reference);
-        await InternalPushAsync(expected, content, remoteReference.Reference, cancellationToken);
+        await InternalPushAsync(expected, content, remoteReference.ContentReference, cancellationToken);
     }
 
     /// <summary>
@@ -339,6 +339,6 @@ public async Task TagAsync(Descriptor descriptor, string reference, Cancellation
     {
         var remoteReference = Repository.ParseReference(reference);
         var rc = await FetchAsync(descriptor, cancellationToken);
-        await InternalPushAsync(descriptor, rc, remoteReference.Reference, cancellationToken);
+        await InternalPushAsync(descriptor, rc, remoteReference.ContentReference, cancellationToken);
     }
 }