[ACR] Improvements to README, TSG and samples (Azure#25746)

### Packages impacted by this PR

- `@azure/container-registry`

### Issues associated with this PR

- Azure#25448

### Describe the problem that is addressed by this PR

- Add documentation about resumable upload 404 issue.
- Add select samples for blob operations to README to be consistent with
the other languages.
- Increment version in preparation for GA and republish samples.

Author: timovv

sdk/containerregistry/container-registry/CHANGELOG.md

@@ -1,14 +1,20 @@
 # Release History
 
-## 1.1.0-beta.4 (Unreleased)
+## 1.1.0 (2023-05-09)
 
 ### Features Added
+ - Added `ContainerRegistryContentClient` for uploading and downloading OCI blobs and manifests.
 
 ### Breaking Changes
 
-### Bugs Fixed
-
-### Other Changes
+Since `1.1.0-beta.3`:
+- The manifest property on GetManifestResult is now `Record<string, unknown>` instead of OciImageManifest. This property is now populated regardless of the media type of the manifest, instead of only being populated when the manifest was an OCI image manifest.
+- Added an `isOciImageManifest` type guard to check if a manifest is an OCI image manifest, providing strong typing.
+- Renamed properties on `OciImageManifest`, `OciDescriptor`, and `OciAnnotations` to match the specification exactly:
+  - Renamed `OciAnnotations.createdOn` to `created`.
+  - Renamed `OciDescriptor.sizeInBytes` to `size`.
+  - Renamed `OciImageManifest.configuration` to `config`.
+- Removed `GetOciImageManifestResult` and the corresponding type guard, `isGetOciImageManifestResult`.
 
 ## 1.1.0-beta.3 (2023-04-11)
 

sdk/containerregistry/container-registry/README.md

@@ -104,7 +104,9 @@ For more information please see [Container Registry Concepts](https://docs.micro
 
 ## Examples
 
-### Listing repositories
+### Registry operations
+
+#### Listing repositories
 
 Iterate through the collection of repositories in the registry.
 
@@ -135,7 +137,7 @@ main().catch((err) => {
 });
 ```
 
-### List tags with anonymous access
+#### List tags with anonymous access
 
 ```javascript
 const {
@@ -170,7 +172,7 @@ main().catch((err) => {
 });
 ```
 
-### Set artifact properties
+#### Set artifact properties
 
 ```javascript
 const {
@@ -198,7 +200,7 @@ main().catch((err) => {
 });
 ```
 
-### Delete images
+#### Delete images
 
 ```javascript
 const {
@@ -247,6 +249,173 @@ main().catch((err) => {
 });
 ```
 
+### Blob and manifest operations
+
+#### Upload images
+
+```javascript
+const { ContainerRegistryContentClient } = require("@azure/container-registry");
+const { DefaultAzureCredential } = require("@azure/identity");
+require("dotenv").config();
+
+async function main() {
+  // endpoint should be in the form of "https://myregistryname.azurecr.io"
+  // where "myregistryname" is the actual name of your registry
+  const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
+  const repository = process.env.CONTAINER_REGISTRY_REPOSITORY || "library/hello-world";
+  const client = new ContainerRegistryContentClient(
+    endpoint,
+    repository,
+    new DefaultAzureCredential()
+  );
+
+  const config = Buffer.from("Sample config");
+  const { digest: configDigest, sizeInBytes: configSize } = await client.uploadBlob(config);
+
+  const layer = Buffer.from("Sample layer");
+  const { digest: layerDigest, sizeInBytes: layerSize } = await client.uploadBlob(layer);
+
+  const manifest = {
+    schemaVersion: 2,
+    config: {
+      digest: configDigest,
+      size: configSize,
+      mediaType: "application/vnd.oci.image.config.v1+json",
+    },
+    layers: [
+      {
+        digest: layerDigest,
+        size: layerSize,
+        mediaType: "application/vnd.oci.image.layer.v1.tar",
+      },
+    ],
+  };
+
+  await client.setManifest(manifest, { tag: "demo" });
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});
+```
+
+#### Download images
+
+```javascript
+const { ContainerRegistryContentClient, isOciImageManifest } = require("@azure/container-registry");
+const { DefaultAzureCredential } = require("@azure/identity");
+const dotenv = require("dotenv");
+const fs = require("fs");
+dotenv.config();
+
+function trimSha(digest) {
+  const index = digest.indexOf(":");
+  return index === -1 ? digest : digest.substring(index);
+}
+
+async function main() {
+  // endpoint should be in the form of "https://myregistryname.azurecr.io"
+  // where "myregistryname" is the actual name of your registry
+  const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
+  const repository = process.env.CONTAINER_REGISTRY_REPOSITORY || "library/hello-world";
+  const client = new ContainerRegistryContentClient(
+    endpoint,
+    repository,
+    new DefaultAzureCredential()
+  );
+
+  // Download the manifest to obtain the list of files in the image based on the tag
+  const result = await client.getManifest("demo");
+
+  const manifest = result.manifest;
+  if (!isOciImageManifest(manifest)) {
+    throw new Error("Expected an OCI image manifest");
+  }
+
+  // Manifests of all media types have a buffer containing their content; this can be written to a file.
+  fs.writeFileSync("manifest.json", result.content);
+
+  const configResult = await client.downloadBlob(manifest.config.digest);
+  const configFile = fs.createWriteStream("config.json");
+  configResult.content.pipe(configFile);
+
+  // Download and write out the layers
+  for (const layer of manifest.layers) {
+    const fileName = trimSha(layer.digest);
+    const layerStream = fs.createWriteStream(fileName);
+    const downloadLayerResult = await client.downloadBlob(layer.digest);
+    downloadLayerResult.content.pipe(layerStream);
+  }
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});
+
+```
+
+#### Delete manifest
+
+```javascript
+const { ContainerRegistryContentClient } = require("@azure/container-registry");
+const { DefaultAzureCredential } = require("@azure/identity");
+require("dotenv").config();
+
+async function main() {
+  // Get the service endpoint from the environment
+  const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
+  const repository = process.env.CONTAINER_REGISTRY_REPOSITORY || "library/hello-world";
+  // Create a new ContainerRegistryClient
+  const client = new ContainerRegistryContentClient(
+    endpoint,
+    repository,
+    new DefaultAzureCredential()
+  );
+
+  const downloadResult = await client.getManifest("latest");
+  await client.deleteManifest(downloadResult.digest);
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});
+```
+
+#### Delete blob
+
+```javascript
+const { ContainerRegistryContentClient, isOciImageManifest } = require("@azure/container-registry");
+const { DefaultAzureCredential } = require("@azure/identity");
+require("dotenv").config();
+
+async function main() {
+  // Get the service endpoint from the environment
+  const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
+  const repository = process.env.CONTAINER_REGISTRY_REPOSITORY || "library/hello-world";
+  // Create a new ContainerRegistryClient
+  const client = new ContainerRegistryContentClient(
+    endpoint,
+    repository,
+    new DefaultAzureCredential()
+  );
+
+  const downloadResult = await client.getManifest("latest");
+
+  if (!isOciImageManifest(downloadResult.manifest)) {
+    throw new Error("Expected an OCI image manifest");
+  }
+
+  for (const layer of downloadResult.manifest.layers) {
+    await client.deleteBlob(layer.digest);
+  }
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});
+
+```
+
 ## Troubleshooting
 
 For infomation about troubleshooting, refer to the [troubleshooting guide].

sdk/containerregistry/container-registry/TROUBLESHOOTING.md

@@ -61,6 +61,33 @@ RestError: {"errors":[{"code":"DENIED","message":"client with IP '<your IP addre
 s/acr/firewall to grant access."}]}
 ```
 
+## Service errors
+
+When working with `ContainerRegistryContentClient` and `ContainerRegistryAsyncContentClient` you may get a `RestError` with
+message containing additional information and [Docker error code](https://docs.docker.com/registry/spec/api/#errors-2).
+
+### Getting BLOB_UPLOAD_INVALID
+
+In rare cases, transient error (such as connection reset) can happen during blob upload which may lead a `RestError` being thrown with a message similar to
+`{"errors":[{"code":"BLOB_UPLOAD_INVALID","message":"blob upload invalid"}]}`, resulting in a failed upload. In this case upload should to be restarted from the beginning.
+
+The following code snippet shows how to access detailed error information:   
+```ts
+const config = Buffer.from(`{"hello":"world"}`);
+
+try {
+  const uploadResult = await contentClient.uploadBlob(config);
+  console.log(`Uploaded blob: digest - ${uploadResult.digest}, size - ${uploadResult.sizeInBytes}`);
+} catch (e) {
+  // isRestError is exported by @azure/core-rest-pipeline
+  if(isRestError(e) && e.statusCode === 404 && (e.details as any).errors.some((error: any) => error.code === "BLOB_UPLOAD_INVALID")) {
+    // Retry upload
+  } else {
+    throw e;
+  }
+}
+```
+
 <!-- Links -->
 
 [`resterror`]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-rest-pipeline/src/restError.ts

sdk/containerregistry/container-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/container-registry",
-  "version": "1.1.0-beta.4",
+  "version": "1.1.0",
   "description": "An isomorphic client library for the Azure Container Registry service.",
   "sdk-type": "client",
   "main": "dist/index.js",