List repositories (#275)

Author: jonesbusy

src/main/java/land/oras/ContainerRef.java

@@ -205,6 +205,23 @@ private String getApiPrefix(@Nullable Registry target) {
         return "%s/v2/%s".formatted(getApiRegistry(target), repository);
     }
 
+    /**
+     * Return the catalog repositories URL
+     * @param target The target registry
+     * @return The tag URL
+     */
+    public String getRepositoriesPath(@Nullable Registry target) {
+        return "%s/v2/_catalog".formatted(getApiRegistry(target));
+    }
+
+    /**
+     * Return the catalog repositories URL
+     * @return The tag URL
+     */
+    public String getRepositoriesPath() {
+        return getRepositoriesPath(null);
+    }
+
     /**
      * Return the tag URL
      * @param target The target registry

src/main/java/land/oras/OCI.java

@@ -256,6 +256,12 @@ public final Manifest attachArtifact(T ref, ArtifactType artifactType, LocalPath
      */
     public abstract Tags getTags(T ref);
 
+    /**
+     * Get the tags for a ref
+     * @return The repositories
+     */
+    public abstract Repositories getRepositories();
+
     /**
      * Push an artifact
      * @param ref The container

src/main/java/land/oras/OCILayout.java

@@ -303,6 +303,11 @@ public Tags getTags(LayoutRef ref) {
         return new Tags(name, tags);
     }
 
+    @Override
+    public Repositories getRepositories() {
+        return new Repositories(List.of(path.getFileName().toString()));
+    }
+
     @Override
     public Referrers getReferrers(LayoutRef ref, @Nullable ArtifactType artifactType) {
         Index index = Index.fromPath(getIndexPath());

src/main/java/land/oras/Registry.java

@@ -161,6 +161,19 @@ public Tags getTags(ContainerRef containerRef) {
         return JsonUtils.fromJson(response.response(), Tags.class);
     }
 
+    @Override
+    public Repositories getRepositories() {
+        ContainerRef containerRef = ContainerRef.parse("default").forRegistry(this);
+        URI uri = URI.create("%s://%s".formatted(getScheme(), containerRef.getRepositoriesPath(this)));
+        HttpClient.ResponseWrapper<String> response = client.get(
+                uri,
+                Map.of(Const.ACCEPT_HEADER, Const.DEFAULT_JSON_MEDIA_TYPE),
+                Scopes.of(this, containerRef),
+                authProvider);
+        handleError(response);
+        return JsonUtils.fromJson(response.response(), Repositories.class);
+    }
+
     @Override
     public Referrers getReferrers(ContainerRef containerRef, @Nullable ArtifactType artifactType) {
         if (containerRef.getDigest() == null) {

src/main/java/land/oras/Repositories.java

@@ -0,0 +1,31 @@
+/*-
+ * =LICENSE=
+ * ORAS Java SDK
+ * ===
+ * Copyright (C) 2024 - 2025 ORAS
+ * ===
+ * 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.
+ * =LICENSEEND=
+ */
+
+package land.oras;
+
+import java.util.List;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * The repositories response object
+ * @param repositories The repositories
+ */
+@NullMarked
+public record Repositories(List<String> repositories) {}

src/test/java/land/oras/ContainerRefTest.java

@@ -166,6 +166,7 @@ void shouldParseImageWithNoRegistry() {
                 containerRef.getApiRegistry(
                         Registry.builder().withRegistry("foo.io").build()));
         assertEquals("registry-1.docker.io/v2/library/alpine/tags/list", containerRef.getTagsPath());
+        assertEquals("registry-1.docker.io/v2/_catalog", containerRef.getRepositoriesPath());
         assertEquals("library", containerRef.getNamespace());
         assertEquals("alpine", containerRef.getRepository());
         assertEquals("latest", containerRef.getTag());
@@ -243,6 +244,7 @@ void shouldHandleNoNamespace() {
     void shouldGetTagsPathOtherRegistry() {
         ContainerRef containerRef = ContainerRef.parse("demo.goharbor.io/foo/alpine:latest@sha256:1234567890abcdef");
         assertEquals("demo.goharbor.io/v2/foo/alpine/tags/list", containerRef.getTagsPath());
+        assertEquals("demo.goharbor.io/v2/_catalog", containerRef.getRepositoriesPath());
         assertEquals("demo.goharbor.io/v2/foo/alpine/blobs/sha256:1234567890abcdef", containerRef.getBlobsPath(null));
         assertEquals(
                 "foo/alpine",

src/test/java/land/oras/OCILayoutTest.java

@@ -141,6 +141,19 @@ void shouldListTags() throws Exception {
         assertEquals("latest", tags.tags().get(0));
     }
 
+    @Test
+    void shouldListRepositories() throws Exception {
+        Path extractDir1 = extractDir.resolve("shouldListRepositories");
+        Files.createDirectory(extractDir1);
+
+        LayoutRef layoutRef = LayoutRef.parse("src/test/resources/oci/subject:latest");
+        OCILayout ociLayout =
+                OCILayout.Builder.builder().defaults(layoutRef.getFolder()).build();
+        Repositories repositories = ociLayout.getRepositories();
+        assertEquals(1, repositories.repositories().size());
+        assertEquals("subject", repositories.repositories().get(0));
+    }
+
     @Test
     void shouldPushConfig() throws IOException {
         Path path = layoutPath.resolve("shouldPushConfig");

src/test/java/land/oras/RegistryTest.java

@@ -66,6 +66,21 @@ void before() {
         registry.withFollowOutput();
     }
 
+    @Test
+    void shouldListRepositories() {
+
+        // Setup
+        Registry registry = Registry.Builder.builder()
+                .defaults("myuser", "mypass")
+                .withRegistry(this.registry.getRegistry())
+                .withInsecure(true)
+                .build();
+
+        // Test
+        List<String> repositories = registry.getRepositories().repositories();
+        assertNotNull(repositories);
+    }
+
     @Test
     void shouldFailToPushBlobForInvalidDigest() {
         Registry registry = Registry.Builder.builder()

src/test/java/land/oras/RegistryWireMockTest.java

@@ -158,6 +158,32 @@ void shouldListTags(WireMockRuntimeInfo wmRuntimeInfo) {
         assertEquals("0.1.1", tags.get(1));
     }
 
+    @Test
+    void shouldListRepositories(WireMockRuntimeInfo wmRuntimeInfo) {
+
+        // Return data from wiremock
+        WireMock wireMock = wmRuntimeInfo.getWireMock();
+        wireMock.register(WireMock.get(WireMock.urlEqualTo("/v2/_catalog"))
+                .willReturn(
+                        WireMock.okJson(JsonUtils.toJson(new Repositories(List.of("foo", "bar", "library/alpine"))))));
+
+        // Insecure registry
+        Registry registry = Registry.Builder.builder()
+                .withAuthProvider(authProvider)
+                .withInsecure(true)
+                .withRegistry(wmRuntimeInfo.getHttpBaseUrl().replace("http://", ""))
+                .build();
+
+        // Test
+        List<String> repositories = registry.getRepositories().repositories();
+
+        // Assert
+        assertEquals(3, repositories.size());
+        assertEquals("foo", repositories.get(0));
+        assertEquals("bar", repositories.get(1));
+        assertEquals("library/alpine", repositories.get(2));
+    }
+
     @Test
     void shouldListTagsWithFileStoreAuth(WireMockRuntimeInfo wmRuntimeInfo) throws IOException {