docker / node-sdk

Docker CLI gRPC JavaScript SDK

Docker CLI JavaScript SDK

This repository contains the source for the Node SDK to work with the experimental Docker command line for Azure integration. The SDK is available as an npm package

⚠️ This SDK is in beta, expect things to change or break!

Getting started

Add @docker/sdk to the dependencies

yarn add @docker/sdk

You can then use the SDK:

// import the contexts client
import { Contexts } from '@docker/sdk';
// import request and response classes
import { ListRequest, ListResponse } from '@docker/sdk/contexts';

const client = new Contexts();

// Get the list of contexts
client.list(new ListRequest(), (err: any, resp: ListResponse) => {
  if (err) {
    console.error(err);
    return;
  }

  const contexts = resp.getContextsList().map((c) => c.getName());

  console.log(contexts);
});

When you run this code you should see a list of contexts, for example:

$ ts-node example.ts
aci-context
default

Examples

You can find examples for how to use this SDK in the examples directory.

node-sdk's Issues

Equivalent to `--context` / `DOCKER_CONTEXT` for SDK

The CLI has a --context flag that allows you to specify a context to use without necessarily changing to that context. The SDK has a ContextsClient.setCurrent() method, but this is more like docker context use--it does appear to change the global context.

Is there a way to set the context on specific requests, more like --context? If not can it be added?

Additional APIs

Some additional APIs that would be nice to have for our July release:

• OS type on the List API?
• Start / restart container
• Stop container
• OS type on the Inspect API
• Inspect container

SDK needs a license file

Volumes API

The new Docker CLI recently added volumes support (at least in ACI contexts). Can this SDK also add support for that? I assume it would mean new protos for volumes.

Octokit dependency: should it be a dev dependency

The SDK causes the consumer to reference a bunch of octokit (GitHub client) packages. That seems to be a development-only dependency? Should it be classified as such?

Containers.ListRequest does not return any containers deployed to Azure Container Instances

See microsoft/vscode-docker#2941 for repro steps and result. I have debugged and the getContainers() call simply does not return anything.

I suspect we simply need a new release of the SDK--there have been changes tot the API/contracts, but they have never been released; the last release of the SDK is 7 months old (version 1.0.3).

BTW I am using Docker Desktop/Win version 3.3.3.

@gtardif @rumpl FYI

Add bwateratmsft to the repo

@rumpl or @chris-crone , could we add @bwateratmsft to the repo?

He will be working with me on the SDK adoption in VS Code Docker extension codebase.

Thx!
Karol

Docker SDK doesn't work if Docker Desktop is shut down

@BigMorty found this the other day.

Repro steps:

1. Create an ACI context
2. Run a container in the ACI context
3. Shut down Docker Desktop
4. Doing docker ps on the command line works, the above container is shown

Expected:
The SDK also works since it shouldn't need Docker Desktop running to talk to ACI

Actual:
The SDK throws an error, 14 UNAVAILABLE: No connection established

Is the SDK daemon lifecycle tied to Docker Desktop?

ps example error on unknown context

Happens on both Mac and WSL2.

> @docker/[email protected] example /Users/metcalfc/src/node-sdk
> ts-node -O '{"module": "CommonJS"}' "examples/ps.ts"


/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call.ts:81
  return Object.assign(new Error(message), status);
                       ^
Error: 2 UNKNOWN: context "default": not found
    at Object.callErrorFromStatus (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call.ts:81:24)
    at Object.onReceiveStatus (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/client.ts:334:36)
    at Object.onReceiveStatus (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/client-interceptors.ts:434:34)
    at Object.onReceiveStatus (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/client-interceptors.ts:397:48)
    at Http2CallStream.outputStatus (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call-stream.ts:230:22)
    at Http2CallStream.maybeOutputStatus (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call-stream.ts:280:14)
    at Http2CallStream.endCall (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call-stream.ts:263:12)
    at Http2CallStream.handleTrailers (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call-stream.ts:412:10)
    at ClientHttp2Stream.<anonymous> (/Users/metcalfc/src/node-sdk/node_modules/@grpc/grpc-js/src/call-stream.ts:467:16)
    at ClientHttp2Stream.emit (events.js:315:20)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @docker/[email protected] example: `ts-node -O '{"module": "CommonJS"}' "examples/ps.ts"`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the @docker/[email protected] example script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

Package should not include both `*.d.ts` files and `*.ts` files

The package includes both *.d.ts files and *.ts files. It should only include the *.d.ts files. Having the *.ts files causes tsc to get upset that not all TS files are within the root directory.

Here's an example of the error you might see:

docker sdk

Description

Steps to reproduce the issue:
1.
2.
3.

Describe the results you received:

Describe the results you expected:

Additional information you deem important (e.g. issue happens only occasionally):

Output of docker version:

(paste your output here)

Output of docker context show:
You can also run docker context inspect context-name to give us more details but don't forget to remove sensitive content.

(paste your output here) 

Additional environment details (AWS ECS, Azure ACI, local, etc.):

The SDK uses both grpc and grpc-js packages

grpc package is obsolete and will stop receiving any updates in less than a year.

grpc-js is a drop-in replacement for grpc

Can't connect to Docker API server on Windows

Repro steps:

1. Install Docker Desktop Edge 45896
2. Run the following example

import { Contexts } from "@docker/sdk";
import {
  ListRequest,
  ListResponse,
} from "@docker/sdk/dist/contexts";

// On Windows this is the endpoint the API server listens on (Docker Desktop Edge 45896)
const addr = 'npipe:////./pipe/dockerCliApi';

const client = new Contexts(addr);

// Get the list of contexts
client.list(new ListRequest(), (err: any, resp: ListResponse) => {
    if (err) {
        console.error(err);
        return;
    }

    const contexts = resp
        .getContextsList()
        .map((c) => new Contexts(c.getName()));

    console.log(contexts);
});

Expected: should see the list of Docker context names

Actual:

C:\code\docker-node-sdk-play>npx ts-node listContexts.ts

C:\code\docker-node-sdk-play\node_modules\@grpc\grpc-js\src\resolver-dns.ts:276
      throw new Error(`Failed to parse target ${uriToString(target)}`);
            ^
Error: Failed to parse target dns:npipe:////./pipe/dockerCliApi
    at Function.getDefaultAuthority (C:\code\docker-node-sdk-play\node_modules\@grpc\grpc-js\src\resolver-dns.ts:276:13)
    at Object.getDefaultAuthority (C:\code\docker-node-sdk-play\node_modules\@grpc\grpc-js\src\resolver.ts:129:47)
    at new ChannelImplementation (C:\code\docker-node-sdk-play\node_modules\@grpc\grpc-js\src\channel.ts:184:31)
    at new Client (C:\code\docker-node-sdk-play\node_modules\@grpc\grpc-js\src\client.ts:146:30)
    at new ServiceClientImpl (C:\code\docker-node-sdk-play\node_modules\@grpc\grpc-js\src\make-client.ts:119:3)
    at new Contexts (C:\code\docker-node-sdk-play\node_modules\@docker\sdk\src\index.ts:22:5)
    at Object.<anonymous> (C:\code\docker-node-sdk-play\listContexts.ts:10:16)
    at Module._compile (internal/modules/cjs/loader.js:1138:30)
    at Module.m._compile (C:\code\docker-node-sdk-play\node_modules\ts-node\src\index.ts:858:23)
    at Module._extensions..js (internal/modules/cjs/loader.js:1158:10)

This makes the SDK pretty much busted on Windows 😞

@gtardif FYI

Default endpoint address not set for win32 platform

Understand it is not implemented yet--creating issue for tracking

google-auth-library needs to be added back to dependencies

Webpack is failing due to this error:

ERROR in ./node_modules/@grpc/grpc-js/build/src/channel-credentials.js
Module not found: Error: Can't resolve 'google-auth-library' in 'D:\vscode-docker\node_modules\@grpc\grpc-js\build\src'
[15:34:00] 'webpackProdTask' errored after 1.22 min
[15:34:00] Error: exited with error code: 2
    at ChildProcess.onexit (D:\vscode-docker\node_modules\end-of-stream\index.js:40:36)
    at ChildProcess.emit (events.js:223:5)
    at ChildProcess.EventEmitter.emit (domain.js:498:23)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:272:12)

I believe that means google-auth-library needs to be added back to dependencies.