oras.land/oras-go/v2@v2.5.1-0.20240520045656-aef90e4d04c4/registry/remote/url.go (about)

     1  /*
     2  Copyright The ORAS Authors.
     3  Licensed under the Apache License, Version 2.0 (the "License");
     4  you may not use this file except in compliance with the License.
     5  You may obtain a copy of the License at
     6  
     7  http://www.apache.org/licenses/LICENSE-2.0
     8  
     9  Unless required by applicable law or agreed to in writing, software
    10  distributed under the License is distributed on an "AS IS" BASIS,
    11  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  See the License for the specific language governing permissions and
    13  limitations under the License.
    14  */
    15  
    16  package remote
    17  
    18  import (
    19  	"fmt"
    20  	"net/url"
    21  	"strings"
    22  
    23  	"github.com/opencontainers/go-digest"
    24  	"oras.land/oras-go/v2/registry"
    25  )
    26  
    27  // buildScheme returns HTTP scheme used to access the remote registry.
    28  func buildScheme(plainHTTP bool) string {
    29  	if plainHTTP {
    30  		return "http"
    31  	}
    32  	return "https"
    33  }
    34  
    35  // buildRegistryBaseURL builds the URL for accessing the base API.
    36  // Format: <scheme>://<registry>/v2/
    37  // Reference: https://docs.docker.com/registry/spec/api/#base
    38  func buildRegistryBaseURL(plainHTTP bool, ref registry.Reference) string {
    39  	return fmt.Sprintf("%s://%s/v2/", buildScheme(plainHTTP), ref.Host())
    40  }
    41  
    42  // buildRegistryCatalogURL builds the URL for accessing the catalog API.
    43  // Format: <scheme>://<registry>/v2/_catalog
    44  // Reference: https://docs.docker.com/registry/spec/api/#catalog
    45  func buildRegistryCatalogURL(plainHTTP bool, ref registry.Reference) string {
    46  	return fmt.Sprintf("%s://%s/v2/_catalog", buildScheme(plainHTTP), ref.Host())
    47  }
    48  
    49  // buildRepositoryBaseURL builds the base endpoint of the remote repository.
    50  // Format: <scheme>://<registry>/v2/<repository>
    51  func buildRepositoryBaseURL(plainHTTP bool, ref registry.Reference) string {
    52  	return fmt.Sprintf("%s://%s/v2/%s", buildScheme(plainHTTP), ref.Host(), ref.Repository)
    53  }
    54  
    55  // buildRepositoryTagListURL builds the URL for accessing the tag list API.
    56  // Format: <scheme>://<registry>/v2/<repository>/tags/list
    57  // Reference: https://docs.docker.com/registry/spec/api/#tags
    58  func buildRepositoryTagListURL(plainHTTP bool, ref registry.Reference) string {
    59  	return buildRepositoryBaseURL(plainHTTP, ref) + "/tags/list"
    60  }
    61  
    62  // buildRepositoryManifestURL builds the URL for accessing the manifest API.
    63  // Format: <scheme>://<registry>/v2/<repository>/manifests/<digest_or_tag>
    64  // Reference: https://docs.docker.com/registry/spec/api/#manifest
    65  func buildRepositoryManifestURL(plainHTTP bool, ref registry.Reference) string {
    66  	return strings.Join([]string{
    67  		buildRepositoryBaseURL(plainHTTP, ref),
    68  		"manifests",
    69  		ref.Reference,
    70  	}, "/")
    71  }
    72  
    73  // buildRepositoryBlobURL builds the URL for accessing the blob API.
    74  // Format: <scheme>://<registry>/v2/<repository>/blobs/<digest>
    75  // Reference: https://docs.docker.com/registry/spec/api/#blob
    76  func buildRepositoryBlobURL(plainHTTP bool, ref registry.Reference) string {
    77  	return strings.Join([]string{
    78  		buildRepositoryBaseURL(plainHTTP, ref),
    79  		"blobs",
    80  		ref.Reference,
    81  	}, "/")
    82  }
    83  
    84  // buildRepositoryBlobUploadURL builds the URL for blob uploading.
    85  // Format: <scheme>://<registry>/v2/<repository>/blobs/uploads/
    86  // Reference: https://docs.docker.com/registry/spec/api/#initiate-blob-upload
    87  func buildRepositoryBlobUploadURL(plainHTTP bool, ref registry.Reference) string {
    88  	return buildRepositoryBaseURL(plainHTTP, ref) + "/blobs/uploads/"
    89  }
    90  
    91  // buildRepositoryBlobMountURLbuilds the URL for cross-repository mounting.
    92  // Format: <scheme>://<registry>/v2/<repository>/blobs/uploads/?mount=<digest>&from=<other_repository>
    93  // Reference: https://docs.docker.com/registry/spec/api/#blob
    94  func buildRepositoryBlobMountURL(plainHTTP bool, ref registry.Reference, d digest.Digest, fromRepo string) string {
    95  	return fmt.Sprintf("%s?mount=%s&from=%s",
    96  		buildRepositoryBlobUploadURL(plainHTTP, ref),
    97  		d,
    98  		fromRepo,
    99  	)
   100  }
   101  
   102  // buildReferrersURL builds the URL for querying the Referrers API.
   103  // Format: <scheme>://<registry>/v2/<repository>/referrers/<digest>?artifactType=<artifactType>
   104  // Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers
   105  func buildReferrersURL(plainHTTP bool, ref registry.Reference, artifactType string) string {
   106  	var query string
   107  	if artifactType != "" {
   108  		v := url.Values{}
   109  		v.Set("artifactType", artifactType)
   110  		query = "?" + v.Encode()
   111  	}
   112  
   113  	return fmt.Sprintf(
   114  		"%s/referrers/%s%s",
   115  		buildRepositoryBaseURL(plainHTTP, ref),
   116  		ref.Reference,
   117  		query,
   118  	)
   119  }