Deno `/x/docker_registry_client`

A port / fork of a Docker Registry API V2 client. Support for v1 registries has been removed and support for OCI registries has been added.

The original Node.JS project supported v1 registries/manifests.

Requires Deno v1.17 or later to typecheck cleanly, starting from v0.4.0.

Design Points

Only handling the v2 Registry API.
Typescript, async/await, Promises, fetch()
Covers most APIs: pull, push, list, delete
I’m mostly using gcr.io though there’s also some tests against major registries.

Auth Approaches

Dockerhub: normal user/password
Github: username $USERNAME password $GITHUB_TOKEN
- like with Github API, username can probably be anything (haven’t confirmed)
AWS ECR: username "AWS" password from running aws ecr get-login-password
- you need AWS auth even for ‘public’ images
Gcloud GCR: username "oauth2accesstoken" password from running gcloud auth print-access-token

Overview

Most usage of this package involves creating a Registry API client for a specific repository and calling its methods.

Usage

Simple usage will look like this:

import { RegistryClientV2 } from 'https://deno.land/x/docker_registry_client/registry-client-v2.ts';
var REPO = 'alpine';
var client = new RegistryClientV2({name: REPO});

const tags = await client.listTags();
console.log(JSON.stringify(tags, null, 4));

If you need to authenticate, the RegistryClientV2 call might look more like this:

import { RegistryClientV2 } from 'https://deno.land/x/docker_registry_client/registry-client-v2.ts';

var client = new RegistryClientV2({
    name: 'alpine',
    // Optional basic auth to the registry
    username: <username>,
    password: <password>,
    // Optional, for a registry without a signed TLS certificate.
    // NOTE: Deno does not currently support this option
    // insecure: <true|false>,
    // ... see the source code for other options
});

NOTE: This module does not include v1 API support.

v2 API

A mapping of the Docker Registry API v2 endpoints to the API equivalents in this client lib.

Name / Endpoint	Implemented	Description
ping `GET /v2/`	Yes	Check that the endpoint implements Docker Registry API V2.
listTags `GET /v2/<name>/tags/list`	Yes	Fetch the tags under the repository identified by `name`.
getManifest `GET /v2/<name>/manifests/<reference>`	Yes	Fetch the manifest identified by `name` and `reference` where `reference` can be a tag or digest.
putManifest `PUT /v2/<name>/manifests/<reference>`	Yes	Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest.
deleteManifest `DELETE /v2/<name>/manifests/<reference>`	Yes	Delete the manifest identified by `name` and `reference` where `reference` can be a tag or digest.
createBlobReadStream `GET /v2/<name>/blobs/<digest>`	Yes	Retrieve the blob from the registry identified by `digest`.
headBlob `HEAD /v2/<name>/blobs/<digest>`	Yes	Retrieve the blob from the registry identified by `digest` – just the headers.
startBlobUpload `POST /v2/<name>/blobs/uploads/`	Yes	Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request.
getBlobUploadStatus `GET /v2/<name>/blobs/uploads/<uuid>`	No	Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload.
uploadBlobChunk `PATCH /v2/<name>/blobs/uploads/<uuid>`	No	Upload a chunk of data for the specified upload.
completeBlobUpload `PUT /v2/<name>/blobs/uploads/<uuid>`	Yes	Complete the upload specified by `uuid`, optionally appending the body as the final chunk.
cancelBlobUpload `DELETE /v2/<name>/blobs/uploads/<uuid>`	No	Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout.
deleteBlob `DELETE /v2/<name>/blobs/<digest>`	No	Delete the blob identified by `name` and `digest`. Warning: From the Docker spec I’m not sure that `deleteBlob` doesn’t corrupt images if you delete a shared blob.
listRepositories `GET /v2/_catalog/`	No	List all repositories in this registry. Spec.