Deno CI

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.

For more code examples, check out the other folders in this Github repo.