Deno `/x/docker_registry_client`

A port of a Docker Registry API V2 client.

The original Node.JS project README included these notes:

Limitations: Currently only support for [...] Registry API v2 pull support. Support for v2 push endpoints is coming.

Note: This repository is part of the Joyent Triton project. See the contribution guidelines and general documentation at the main Triton project page.

Design Points

Only handling the v2 Registry API.
Typescript, async/await, Promises, fetch()
Focus on image management. For example, listing and deleting tags.
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 { createClient } from 'https://deno.land/x/docker_registry_client/registry-client-v2.ts';
var REPO = 'alpine';
var client = createClient({name: REPO});

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

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

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

var client = createClient({
    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>`	No*	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/`	No*	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>`	No*	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.

*: Endpoints with Javascript implementations that haven't been partially fully ported to Deno / Typescript yet.