apiclient.xyz/docker
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

BREAKING CHANGE(DockerHost): Refactor public API to DockerHost facade; introduce DockerResource base; make resource static methods internal; support flexible descriptors and stream compatibility

Browse Source
This commit is contained in:
Jürgen Kunz
2025-11-24 12:20:30 +00:00
parent cc9c20882e
commit 6fe70e0a1d
16 changed files with 1388 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@apiclient.xyz/docker',
version: '2.1.0',
version: '3.0.0',
description: 'Provides easy communication with Docker remote API from Node.js, with TypeScript support.'
}

27
ts/classes.base.ts Normal file
View File

@@ -0,0 +1,27 @@
import { DockerHost } from './classes.host.js';
/**
* Abstract base class for all Docker resources.
* Provides standardized patterns for resource management and lifecycle.
*/
export abstract class DockerResource {
/**
* Reference to the DockerHost that manages this resource.
* All API operations go through this host instance.
*/
protected readonly dockerHost: DockerHost;
/**
* Creates a new Docker resource instance.
* @param dockerHost The DockerHost instance that manages this resource
*/
constructor(dockerHost: DockerHost) {
this.dockerHost = dockerHost;
}
/**
* Refreshes this resource's state from the Docker daemon.
* Implementations should fetch current data and update instance properties.
*/
abstract refresh(): Promise<void>;
}

337
ts/classes.container.ts
View File

@@ -2,21 +2,23 @@ import * as plugins from './plugins.js';
import * as interfaces from './interfaces/index.js';
import { DockerHost } from './classes.host.js';
import { DockerResource } from './classes.base.js';
import { logger } from './logger.js';
export class DockerContainer {
// STATIC
export class DockerContainer extends DockerResource {
// STATIC (Internal - prefixed with _ to indicate internal use)
/**
* get all containers
* Internal: Get all containers
* Public API: Use dockerHost.getContainers() instead
*/
public static async getContainers(
public static async _list(
dockerHostArg: DockerHost,
): Promise<DockerContainer[]> {
const result: DockerContainer[] = [];
const response = await dockerHostArg.request('GET', '/containers/json');
// TODO: Think about getting the config by inpsecting the container
// TODO: Think about getting the config by inspecting the container
for (const containerResult of response.body) {
result.push(new DockerContainer(dockerHostArg, containerResult));
}
@@ -24,46 +26,49 @@ export class DockerContainer {
}
/**
* gets an container by Id
* @param containerId
* Internal: Get a container by ID
* Public API: Use dockerHost.getContainerById(id) instead
*/
public static async getContainerById(containerId: string) {
// TODO: implement get container by id
public static async _fromId(
dockerHostArg: DockerHost,
containerId: string,
): Promise<DockerContainer> {
const response = await dockerHostArg.request('GET', `/containers/${containerId}/json`);
return new DockerContainer(dockerHostArg, response.body);
}
/**
* create a container
* Internal: Create a container
* Public API: Use dockerHost.createContainer(descriptor) instead
*/
public static async create(
public static async _create(
dockerHost: DockerHost,
containerCreationDescriptor: interfaces.IContainerCreationDescriptor,
) {
// check for unique hostname
const existingContainers = await DockerContainer.getContainers(dockerHost);
): Promise<DockerContainer> {
// Check for unique hostname
const existingContainers = await DockerContainer._list(dockerHost);
const sameHostNameContainer = existingContainers.find((container) => {
// TODO implement HostName Detection;
return false;
});
const response = await dockerHost.request('POST', '/containers/create', {
Hostname: containerCreationDescriptor.Hostname,
Domainname: containerCreationDescriptor.Domainname,
User: 'root',
});
if (response.statusCode < 300) {
logger.log('info', 'Container created successfully');
// Return the created container instance
return await DockerContainer._fromId(dockerHost, response.body.Id);
} else {
logger.log(
'error',
'There has been a problem when creating the container',
);
logger.log('error', 'There has been a problem when creating the container');
throw new Error(`Failed to create container: ${response.statusCode}`);
}
}
// INSTANCE
// references
public dockerHost: DockerHost;
// properties
// INSTANCE PROPERTIES
public Id: string;
public Names: string[];
public Image: string;
@@ -95,10 +100,294 @@ export class DockerContainer {
};
};
public Mounts: any;
constructor(dockerHostArg: DockerHost, dockerContainerObjectArg: any) {
this.dockerHost = dockerHostArg;
super(dockerHostArg);
Object.keys(dockerContainerObjectArg).forEach((keyArg) => {
this[keyArg] = dockerContainerObjectArg[keyArg];
});
}
// INSTANCE METHODS
/**
* Refreshes this container's state from the Docker daemon
*/
public async refresh(): Promise<void> {
const updated = await DockerContainer._fromId(this.dockerHost, this.Id);
Object.assign(this, updated);
}
/**
* Inspects the container and returns detailed information
*/
public async inspect(): Promise<any> {
const response = await this.dockerHost.request('GET', `/containers/${this.Id}/json`);
// Update instance with fresh data
Object.assign(this, response.body);
return response.body;
}
/**
* Starts the container
*/
public async start(): Promise<void> {
const response = await this.dockerHost.request('POST', `/containers/${this.Id}/start`);
if (response.statusCode >= 300) {
throw new Error(`Failed to start container: ${response.statusCode}`);
}
await this.refresh();
}
/**
* Stops the container
* @param options Options for stopping (e.g., timeout in seconds)
*/
public async stop(options?: { t?: number }): Promise<void> {
const queryParams = options?.t ? `?t=${options.t}` : '';
const response = await this.dockerHost.request('POST', `/containers/${this.Id}/stop${queryParams}`);
if (response.statusCode >= 300) {
throw new Error(`Failed to stop container: ${response.statusCode}`);
}
await this.refresh();
}
/**
* Removes the container
* @param options Options for removal (force, remove volumes, remove link)
*/
public async remove(options?: { force?: boolean; v?: boolean; link?: boolean }): Promise<void> {
const queryParams = new URLSearchParams();
if (options?.force) queryParams.append('force', '1');
if (options?.v) queryParams.append('v', '1');
if (options?.link) queryParams.append('link', '1');
const queryString = queryParams.toString();
const response = await this.dockerHost.request(
'DELETE',
`/containers/${this.Id}${queryString ? '?' + queryString : ''}`,
);
if (response.statusCode >= 300) {
throw new Error(`Failed to remove container: ${response.statusCode}`);
}
}
/**
* Gets container logs
* @param options Log options (stdout, stderr, timestamps, tail, since, follow)
*/
public async logs(options?: {
stdout?: boolean;
stderr?: boolean;
timestamps?: boolean;
tail?: number | 'all';
since?: number;
follow?: boolean;
}): Promise<string> {
const queryParams = new URLSearchParams();
queryParams.append('stdout', options?.stdout !== false ? '1' : '0');
queryParams.append('stderr', options?.stderr !== false ? '1' : '0');
if (options?.timestamps) queryParams.append('timestamps', '1');
if (options?.tail) queryParams.append('tail', options.tail.toString());
if (options?.since) queryParams.append('since', options.since.toString());
if (options?.follow) queryParams.append('follow', '1');
const response = await this.dockerHost.request('GET', `/containers/${this.Id}/logs?${queryParams.toString()}`);
// Docker returns logs with a special format (8 bytes header + payload)
// For simplicity, we'll return the raw body as string
return response.body.toString();
}
/**
* Gets container stats
* @param options Stats options (stream for continuous stats)
*/
public async stats(options?: { stream?: boolean }): Promise<any> {
const queryParams = new URLSearchParams();
queryParams.append('stream', options?.stream ? '1' : '0');
const response = await this.dockerHost.request('GET', `/containers/${this.Id}/stats?${queryParams.toString()}`);
return response.body;
}
/**
* Streams container logs continuously (follow mode)
* Returns a readable stream that emits log data as it's produced
* @param options Log streaming options
*/
public async streamLogs(options?: {
stdout?: boolean;
stderr?: boolean;
timestamps?: boolean;
tail?: number | 'all';
since?: number;
}): Promise<plugins.smartstream.stream.Readable> {
const queryParams = new URLSearchParams();
queryParams.append('stdout', options?.stdout !== false ? '1' : '0');
queryParams.append('stderr', options?.stderr !== false ? '1' : '0');
queryParams.append('follow', '1'); // Always follow for streaming
if (options?.timestamps) queryParams.append('timestamps', '1');
if (options?.tail) queryParams.append('tail', options.tail.toString());
if (options?.since) queryParams.append('since', options.since.toString());
const response = await this.dockerHost.requestStreaming(
'GET',
`/containers/${this.Id}/logs?${queryParams.toString()}`
);
// requestStreaming returns Node.js stream
return response as plugins.smartstream.stream.Readable;
}
/**
* Attaches to the container's main process (PID 1)
* Returns a duplex stream for bidirectional communication
* @param options Attach options
*/
public async attach(options?: {
stream?: boolean;
stdin?: boolean;
stdout?: boolean;
stderr?: boolean;
logs?: boolean;
}): Promise<{
stream: plugins.smartstream.stream.Duplex;
close: () => Promise<void>;
}> {
const queryParams = new URLSearchParams();
queryParams.append('stream', options?.stream !== false ? '1' : '0');
queryParams.append('stdin', options?.stdin ? '1' : '0');
queryParams.append('stdout', options?.stdout !== false ? '1' : '0');
queryParams.append('stderr', options?.stderr !== false ? '1' : '0');
if (options?.logs) queryParams.append('logs', '1');
const response = await this.dockerHost.requestStreaming(
'POST',
`/containers/${this.Id}/attach?${queryParams.toString()}`
);
// Create a duplex stream for bidirectional communication
const nodeStream = response as plugins.smartstream.stream.Readable;
// Convert to duplex by wrapping in SmartDuplex
const duplexStream = new plugins.smartstream.SmartDuplex({
writeFunction: async (chunk) => {
// Write data is sent to the container's stdin
return chunk;
},
readableObjectMode: false,
writableObjectMode: false,
});
// Pipe container output to our duplex readable side
nodeStream.on('data', (chunk) => {
duplexStream.push(chunk);
});
nodeStream.on('end', () => {
duplexStream.push(null); // Signal end of stream
});
nodeStream.on('error', (error) => {
duplexStream.destroy(error);
});
// Helper function to close the attachment
const close = async () => {
duplexStream.end();
if (nodeStream.destroy) {
nodeStream.destroy();
}
};
return {
stream: duplexStream,
close,
};
}
/**
* Executes a command in the container
* Returns a duplex stream for command interaction
* @param command Command to execute (string or array of strings)
* @param options Exec options
*/
public async exec(
command: string | string[],
options?: {
tty?: boolean;
attachStdin?: boolean;
attachStdout?: boolean;
attachStderr?: boolean;
env?: string[];
workingDir?: string;
user?: string;
}
): Promise<{
stream: plugins.smartstream.stream.Duplex;
close: () => Promise<void>;
}> {
// Step 1: Create exec instance
const createResponse = await this.dockerHost.request('POST', `/containers/${this.Id}/exec`, {
Cmd: typeof command === 'string' ? ['/bin/sh', '-c', command] : command,
AttachStdin: options?.attachStdin !== false,
AttachStdout: options?.attachStdout !== false,
AttachStderr: options?.attachStderr !== false,
Tty: options?.tty || false,
Env: options?.env || [],
WorkingDir: options?.workingDir,
User: options?.user,
});
const execId = createResponse.body.Id;
// Step 2: Start exec instance with streaming response
const startResponse = await this.dockerHost.requestStreaming(
'POST',
`/exec/${execId}/start`,
undefined, // no stream input
{
Detach: false,
Tty: options?.tty || false,
}
);
const nodeStream = startResponse as plugins.smartstream.stream.Readable;
// Create duplex stream for bidirectional communication
const duplexStream = new plugins.smartstream.SmartDuplex({
writeFunction: async (chunk) => {
return chunk;
},
readableObjectMode: false,
writableObjectMode: false,
});
// Pipe exec output to duplex readable side
nodeStream.on('data', (chunk) => {
duplexStream.push(chunk);
});
nodeStream.on('end', () => {
duplexStream.push(null);
});
nodeStream.on('error', (error) => {
duplexStream.destroy(error);
});
const close = async () => {
duplexStream.end();
if (nodeStream.destroy) {
nodeStream.destroy();
}
};
return {
stream: duplexStream,
close,
};
}
}

184
ts/classes.host.ts
View File

@@ -1,8 +1,10 @@
import * as plugins from './plugins.js';
import * as paths from './paths.js';
import * as interfaces from './interfaces/index.js';
import { DockerContainer } from './classes.container.js';
import { DockerNetwork } from './classes.network.js';
import { DockerService } from './classes.service.js';
import { DockerSecret } from './classes.secret.js';
import { logger } from './logger.js';
import { DockerImageStore } from './classes.imagestore.js';
import { DockerImage } from './classes.image.js';
@@ -26,7 +28,7 @@ export class DockerHost {
*/
public socketPath: string;
private registryToken: string = '';
public imageStore: DockerImageStore;
private imageStore: DockerImageStore; // Now private - use storeImage/retrieveImage instead
public smartBucket: plugins.smartbucket.SmartBucket;
/**
@@ -123,70 +125,190 @@ export class DockerHost {
}
// ==============
// NETWORKS
// NETWORKS - Public Factory API
// ==============
/**
* gets all networks
* Gets all networks
*/
public async getNetworks() {
return await DockerNetwork.getNetworks(this);
return await DockerNetwork._list(this);
}
/**
* create a network
*/
public async createNetwork(
optionsArg: Parameters<typeof DockerNetwork.createNetwork>[1],
) {
return await DockerNetwork.createNetwork(this, optionsArg);
}
/**
* get a network by name
* Gets a network by name
*/
public async getNetworkByName(networkNameArg: string) {
return await DockerNetwork.getNetworkByName(this, networkNameArg);
return await DockerNetwork._fromName(this, networkNameArg);
}
/**
* Creates a network
*/
public async createNetwork(
descriptor: interfaces.INetworkCreationDescriptor,
) {
return await DockerNetwork._create(this, descriptor);
}
// ==============
// CONTAINERS
// CONTAINERS - Public Factory API
// ==============
/**
* gets all containers
* Gets all containers
*/
public async getContainers() {
const containerArray = await DockerContainer.getContainers(this);
return containerArray;
return await DockerContainer._list(this);
}
/**
* Gets a container by ID
*/
public async getContainerById(containerId: string) {
return await DockerContainer._fromId(this, containerId);
}
/**
* Creates a container
*/
public async createContainer(
descriptor: interfaces.IContainerCreationDescriptor,
) {
return await DockerContainer._create(this, descriptor);
}
// ==============
// SERVICES
// SERVICES - Public Factory API
// ==============
/**
* gets all services
* Gets all services
*/
public async getServices() {
const serviceArray = await DockerService.getServices(this);
return serviceArray;
return await DockerService._list(this);
}
/**
* Gets a service by name
*/
public async getServiceByName(serviceName: string) {
return await DockerService._fromName(this, serviceName);
}
/**
* Creates a service
*/
public async createService(
descriptor: interfaces.IServiceCreationDescriptor,
) {
return await DockerService._create(this, descriptor);
}
// ==============
// IMAGES
// IMAGES - Public Factory API
// ==============
/**
* get all images
* Gets all images
*/
public async getImages() {
return await DockerImage.getImages(this);
return await DockerImage._list(this);
}
/**
* get an image by name
* Gets an image by name
*/
public async getImageByName(imageNameArg: string) {
return await DockerImage.getImageByName(this, imageNameArg);
return await DockerImage._fromName(this, imageNameArg);
}
/**
* Creates an image from a registry
*/
public async createImageFromRegistry(
descriptor: interfaces.IImageCreationDescriptor,
) {
return await DockerImage._createFromRegistry(this, {
creationObject: descriptor,
});
}
/**
* Creates an image from a tar stream
*/
public async createImageFromTarStream(
tarStream: plugins.smartstream.stream.Readable,
descriptor: interfaces.IImageCreationDescriptor,
) {
return await DockerImage._createFromTarStream(this, {
creationObject: descriptor,
tarStream: tarStream,
});
}
/**
* Builds an image from a Dockerfile
*/
public async buildImage(imageTag: string) {
return await DockerImage._build(this, imageTag);
}
// ==============
// SECRETS - Public Factory API
// ==============
/**
* Gets all secrets
*/
public async getSecrets() {
return await DockerSecret._list(this);
}
/**
* Gets a secret by name
*/
public async getSecretByName(secretName: string) {
return await DockerSecret._fromName(this, secretName);
}
/**
* Gets a secret by ID
*/
public async getSecretById(secretId: string) {
return await DockerSecret._fromId(this, secretId);
}
/**
* Creates a secret
*/
public async createSecret(
descriptor: interfaces.ISecretCreationDescriptor,
) {
return await DockerSecret._create(this, descriptor);
}
// ==============
// IMAGE STORE - Public API
// ==============
/**
* Stores an image in the local image store
*/
public async storeImage(
imageName: string,
tarStream: plugins.smartstream.stream.Readable,
): Promise<void> {
return await this.imageStore.storeImage(imageName, tarStream);
}
/**
* Retrieves an image from the local image store
*/
public async retrieveImage(
imageName: string,
): Promise<plugins.smartstream.stream.Readable> {
return await this.imageStore.getImage(imageName);
}
/**
@@ -330,6 +452,7 @@ export class DockerHost {
methodArg: string,
routeArg: string,
readStream?: plugins.smartstream.stream.Readable,
jsonData?: any,
) {
const requestUrl = `${this.socketPath}${routeArg}`;
@@ -342,6 +465,11 @@ export class DockerHost {
.timeout(30000)
.options({ keepAlive: false, autoDrain: true }); // Disable auto-drain for streaming
// If we have JSON data, add it to the request
if (jsonData && Object.keys(jsonData).length > 0) {
smartRequest.json(jsonData);
}
// If we have a readStream, use the new stream method with logging
if (readStream) {
let counter = 0;

91
ts/classes.image.ts
View File

@@ -1,14 +1,20 @@
import * as plugins from './plugins.js';
import * as interfaces from './interfaces/index.js';
import { DockerHost } from './classes.host.js';
import { DockerResource } from './classes.base.js';
import { logger } from './logger.js';
/**
* represents a docker image on the remote docker host
*/
export class DockerImage {
// STATIC
public static async getImages(dockerHost: DockerHost) {
export class DockerImage extends DockerResource {
// STATIC (Internal - prefixed with _ to indicate internal use)
/**
* Internal: Get all images
* Public API: Use dockerHost.getImages() instead
*/
public static async _list(dockerHost: DockerHost) {
const images: DockerImage[] = [];
const response = await dockerHost.request('GET', '/images/json');
for (const imageObject of response.body) {
@@ -17,11 +23,15 @@ export class DockerImage {
return images;
}
public static async getImageByName(
/**
* Internal: Get image by name
* Public API: Use dockerHost.getImageByName(name) instead
*/
public static async _fromName(
dockerHost: DockerHost,
imageNameArg: string,
) {
const images = await this.getImages(dockerHost);
const images = await this._list(dockerHost);
const result = images.find((image) => {
if (image.RepoTags) {
return image.RepoTags.includes(imageNameArg);
@@ -32,7 +42,11 @@ export class DockerImage {
return result;
}
public static async createFromRegistry(
/**
* Internal: Create image from registry
* Public API: Use dockerHost.createImageFromRegistry(descriptor) instead
*/
public static async _createFromRegistry(
dockerHostArg: DockerHost,
optionsArg: {
creationObject: interfaces.IImageCreationDescriptor;
@@ -76,7 +90,7 @@ export class DockerImage {
'info',
`Successfully pulled image ${imageUrlObject.imageUrl} from the registry`,
);
const image = await DockerImage.getImageByName(
const image = await DockerImage._fromName(
dockerHostArg,
imageUrlObject.imageOriginTag,
);
@@ -87,11 +101,10 @@ export class DockerImage {
}
/**
*
* @param dockerHostArg
* @param tarStreamArg
* Internal: Create image from tar stream
* Public API: Use dockerHost.createImageFromTarStream(stream, descriptor) instead
*/
public static async createFromTarStream(
public static async _createFromTarStream(
dockerHostArg: DockerHost,
optionsArg: {
creationObject: interfaces.IImageCreationDescriptor;
@@ -161,11 +174,11 @@ export class DockerImage {
}
// Now try to look up that image by the "loadedImageTag".
// Depending on Docker’s response, it might be something like:
// Depending on Docker's response, it might be something like:
// "myrepo/myimage:latest" OR "sha256:someHash..."
// If Docker gave you an ID (e.g. "sha256:..."), you may need a separate
// DockerImage.getImageById method; or if you prefer, you can treat it as a name.
const newlyImportedImage = await DockerImage.getImageByName(
const newlyImportedImage = await DockerImage._fromName(
dockerHostArg,
loadedImageTag,
);
@@ -192,15 +205,15 @@ export class DockerImage {
);
}
public static async buildImage(dockerHostArg: DockerHost, dockerImageTag) {
/**
* Internal: Build image from Dockerfile
* Public API: Use dockerHost.buildImage(tag) instead
*/
public static async _build(dockerHostArg: DockerHost, dockerImageTag) {
// TODO: implement building an image
}
// INSTANCE
// references
public dockerHost: DockerHost;
// properties
// INSTANCE PROPERTIES
/**
* the tags for an image
*/
@@ -215,13 +228,28 @@ export class DockerImage {
public Size: number;
public VirtualSize: number;
constructor(dockerHostArg, dockerImageObjectArg: any) {
this.dockerHost = dockerHostArg;
constructor(dockerHostArg: DockerHost, dockerImageObjectArg: any) {
super(dockerHostArg);
Object.keys(dockerImageObjectArg).forEach((keyArg) => {
this[keyArg] = dockerImageObjectArg[keyArg];
});
}
// INSTANCE METHODS
/**
* Refreshes this image's state from the Docker daemon
*/
public async refresh(): Promise<void> {
if (!this.RepoTags || this.RepoTags.length === 0) {
throw new Error('Cannot refresh image without RepoTags');
}
const updated = await DockerImage._fromName(this.dockerHost, this.RepoTags[0]);
if (updated) {
Object.assign(this, updated);
}
}
/**
* tag an image
* @param newTag
@@ -234,7 +262,7 @@ export class DockerImage {
* pulls the latest version from the registry
*/
public async pullLatestImageFromRegistry(): Promise<boolean> {
const updatedImage = await DockerImage.createFromRegistry(this.dockerHost, {
const updatedImage = await DockerImage._createFromRegistry(this.dockerHost, {
creationObject: {
imageUrl: this.RepoTags[0],
},
@@ -244,6 +272,25 @@ export class DockerImage {
return true;
}
/**
* Removes this image from the Docker daemon
*/
public async remove(options?: { force?: boolean; noprune?: boolean }): Promise<void> {
const queryParams = new URLSearchParams();
if (options?.force) queryParams.append('force', '1');
if (options?.noprune) queryParams.append('noprune', '1');
const queryString = queryParams.toString();
const response = await this.dockerHost.request(
'DELETE',
`/images/${encodeURIComponent(this.Id)}${queryString ? '?' + queryString : ''}`,
);
if (response.statusCode >= 300) {
throw new Error(`Failed to remove image: ${response.statusCode}`);
}
}
// get stuff
public async getVersion() {
if (this.Labels && this.Labels.version) {

49
ts/classes.network.ts
View File

@@ -2,11 +2,18 @@ import * as plugins from './plugins.js';
import * as interfaces from './interfaces/index.js';
import { DockerHost } from './classes.host.js';
import { DockerResource } from './classes.base.js';
import { DockerService } from './classes.service.js';
import { logger } from './logger.js';
export class DockerNetwork {
public static async getNetworks(
export class DockerNetwork extends DockerResource {
// STATIC (Internal - prefixed with _ to indicate internal use)
/**
* Internal: Get all networks
* Public API: Use dockerHost.getNetworks() instead
*/
public static async _list(
dockerHost: DockerHost,
): Promise<DockerNetwork[]> {
const dockerNetworks: DockerNetwork[] = [];
@@ -19,17 +26,25 @@ export class DockerNetwork {
return dockerNetworks;
}
public static async getNetworkByName(
/**
* Internal: Get network by name
* Public API: Use dockerHost.getNetworkByName(name) instead
*/
public static async _fromName(
dockerHost: DockerHost,
dockerNetworkNameArg: string,
) {
const networks = await DockerNetwork.getNetworks(dockerHost);
const networks = await DockerNetwork._list(dockerHost);
return networks.find(
(dockerNetwork) => dockerNetwork.Name === dockerNetworkNameArg,
);
}
public static async createNetwork(
/**
* Internal: Create a network
* Public API: Use dockerHost.createNetwork(descriptor) instead
*/
public static async _create(
dockerHost: DockerHost,
networkCreationDescriptor: interfaces.INetworkCreationDescriptor,
): Promise<DockerNetwork> {
@@ -54,7 +69,7 @@ export class DockerNetwork {
});
if (response.statusCode < 300) {
logger.log('info', 'Created network successfully');
return await DockerNetwork.getNetworkByName(
return await DockerNetwork._fromName(
dockerHost,
networkCreationDescriptor.Name,
);
@@ -67,11 +82,7 @@ export class DockerNetwork {
}
}
// INSTANCE
// references
public dockerHost: DockerHost;
// properties
// INSTANCE PROPERTIES
public Name: string;
public Id: string;
public Created: string;
@@ -93,11 +104,23 @@ export class DockerNetwork {
};
constructor(dockerHostArg: DockerHost) {
this.dockerHost = dockerHostArg;
super(dockerHostArg);
}
// INSTANCE METHODS
/**
* Refreshes this network's state from the Docker daemon
*/
public async refresh(): Promise<void> {
const updated = await DockerNetwork._fromName(this.dockerHost, this.Name);
if (updated) {
Object.assign(this, updated);
}
}
/**
* removes the network
* Removes the network
*/
public async remove() {
const response = await this.dockerHost.request(

62
ts/classes.secret.ts
View File

@@ -1,12 +1,18 @@
import * as plugins from './plugins.js';
import { DockerHost } from './classes.host.js';
import { DockerResource } from './classes.base.js';
// interfaces
import * as interfaces from './interfaces/index.js';
export class DockerSecret {
// STATIC
public static async getSecrets(dockerHostArg: DockerHost) {
export class DockerSecret extends DockerResource {
// STATIC (Internal - prefixed with _ to indicate internal use)
/**
* Internal: Get all secrets
* Public API: Use dockerHost.getSecrets() instead
*/
public static async _list(dockerHostArg: DockerHost) {
const response = await dockerHostArg.request('GET', '/secrets');
const secrets: DockerSecret[] = [];
for (const secret of response.body) {
@@ -17,20 +23,32 @@ export class DockerSecret {
return secrets;
}
public static async getSecretByID(dockerHostArg: DockerHost, idArg: string) {
const secrets = await this.getSecrets(dockerHostArg);
/**
* Internal: Get secret by ID
* Public API: Use dockerHost.getSecretById(id) instead
*/
public static async _fromId(dockerHostArg: DockerHost, idArg: string) {
const secrets = await this._list(dockerHostArg);
return secrets.find((secret) => secret.ID === idArg);
}
public static async getSecretByName(
/**
* Internal: Get secret by name
* Public API: Use dockerHost.getSecretByName(name) instead
*/
public static async _fromName(
dockerHostArg: DockerHost,
nameArg: string,
) {
const secrets = await this.getSecrets(dockerHostArg);
const secrets = await this._list(dockerHostArg);
return secrets.find((secret) => secret.Spec.Name === nameArg);
}
public static async createSecret(
/**
* Internal: Create a secret
* Public API: Use dockerHost.createSecret(descriptor) instead
*/
public static async _create(
dockerHostArg: DockerHost,
secretDescriptor: interfaces.ISecretCreationDescriptor,
) {
@@ -48,12 +66,12 @@ export class DockerSecret {
Object.assign(newSecretInstance, response.body);
Object.assign(
newSecretInstance,
await DockerSecret.getSecretByID(dockerHostArg, newSecretInstance.ID),
await DockerSecret._fromId(dockerHostArg, newSecretInstance.ID),
);
return newSecretInstance;
}
// INSTANCE
// INSTANCE PROPERTIES
public ID: string;
public Spec: {
Name: string;
@@ -63,13 +81,24 @@ export class DockerSecret {
Index: string;
};
public dockerHost: DockerHost;
constructor(dockerHostArg: DockerHost) {
this.dockerHost = dockerHostArg;
super(dockerHostArg);
}
// INSTANCE METHODS
/**
* Refreshes this secret's state from the Docker daemon
*/
public async refresh(): Promise<void> {
const updated = await DockerSecret._fromId(this.dockerHost, this.ID);
if (updated) {
Object.assign(this, updated);
}
}
/**
* updates a secret
* Updates a secret
*/
public async update(contentArg: string) {
const route = `/secrets/${this.ID}/update?=version=${this.Version.Index}`;
@@ -84,11 +113,16 @@ export class DockerSecret {
);
}
/**
* Removes this secret from the Docker daemon
*/
public async remove() {
await this.dockerHost.request('DELETE', `/secrets/${this.ID}`);
}
// get things
/**
* Gets the version label of this secret
*/
public async getVersion() {
return this.Spec.Labels.version;
}

103
ts/classes.service.ts
View File

@@ -2,13 +2,19 @@ import * as plugins from './plugins.js';
import * as interfaces from './interfaces/index.js';
import { DockerHost } from './classes.host.js';
import { DockerResource } from './classes.base.js';
import { DockerImage } from './classes.image.js';
import { DockerSecret } from './classes.secret.js';
import { logger } from './logger.js';
export class DockerService {
// STATIC
public static async getServices(dockerHost: DockerHost) {
export class DockerService extends DockerResource {
// STATIC (Internal - prefixed with _ to indicate internal use)
/**
* Internal: Get all services
* Public API: Use dockerHost.getServices() instead
*/
public static async _list(dockerHost: DockerHost) {
const services: DockerService[] = [];
const response = await dockerHost.request('GET', '/services');
for (const serviceObject of response.body) {
@@ -19,11 +25,15 @@ export class DockerService {
return services;
}
public static async getServiceByName(
/**
* Internal: Get service by name
* Public API: Use dockerHost.getServiceByName(name) instead
*/
public static async _fromName(
dockerHost: DockerHost,
networkName: string,
): Promise<DockerService> {
const allServices = await DockerService.getServices(dockerHost);
const allServices = await DockerService._list(dockerHost);
const wantedService = allServices.find((service) => {
return service.Spec.Name === networkName;
});
@@ -31,20 +41,30 @@ export class DockerService {
}
/**
* creates a service
* Internal: Create a service
* Public API: Use dockerHost.createService(descriptor) instead
*/
public static async createService(
public static async _create(
dockerHost: DockerHost,
serviceCreationDescriptor: interfaces.IServiceCreationDescriptor,
): Promise<DockerService> {
// lets get the image
logger.log(
'info',
`now creating service ${serviceCreationDescriptor.name}`,
);
// await serviceCreationDescriptor.image.pullLatestImageFromRegistry();
const serviceVersion = await serviceCreationDescriptor.image.getVersion();
// Resolve image (support both string and DockerImage instance)
let imageInstance: DockerImage;
if (typeof serviceCreationDescriptor.image === 'string') {
imageInstance = await DockerImage._fromName(dockerHost, serviceCreationDescriptor.image);
if (!imageInstance) {
throw new Error(`Image not found: ${serviceCreationDescriptor.image}`);
}
} else {
imageInstance = serviceCreationDescriptor.image;
}
const serviceVersion = await imageInstance.getVersion();
const labels: interfaces.TLabels = {
...serviceCreationDescriptor.labels,
@@ -90,6 +110,7 @@ export class DockerService {
}
}
// Resolve networks (support both string[] and DockerNetwork[])
const networkArray: Array<{
Target: string;
Aliases: string[];
@@ -101,8 +122,11 @@ export class DockerService {
logger.log('warn', 'Skipping null network in service creation');
continue;
}
// Resolve network name
const networkName = typeof network === 'string' ? network : network.Name;
networkArray.push({
Target: network.Name,
Target: networkName,
Aliases: [serviceCreationDescriptor.networkAlias],
});
}
@@ -119,9 +143,20 @@ export class DockerService {
});
}
// lets configure secrets
// Resolve secrets (support both string[] and DockerSecret[])
const secretArray: any[] = [];
for (const secret of serviceCreationDescriptor.secrets) {
// Resolve secret instance
let secretInstance: DockerSecret;
if (typeof secret === 'string') {
secretInstance = await DockerSecret._fromName(dockerHost, secret);
if (!secretInstance) {
throw new Error(`Secret not found: ${secret}`);
}
} else {
secretInstance = secret;
}
secretArray.push({
File: {
Name: 'secret.json', // TODO: make sure that works with multiple secrets
@@ -129,8 +164,8 @@ export class DockerService {
GID: '33',
Mode: 384,
},
SecretID: secret.ID,
SecretName: secret.Spec.Name,
SecretID: secretInstance.ID,
SecretName: secretInstance.Spec.Name,
});
}
@@ -155,7 +190,7 @@ export class DockerService {
Name: serviceCreationDescriptor.name,
TaskTemplate: {
ContainerSpec: {
Image: serviceCreationDescriptor.image.RepoTags[0],
Image: imageInstance.RepoTags[0],
Labels: labels,
Secrets: secretArray,
Mounts: mounts,
@@ -189,15 +224,15 @@ export class DockerService {
},
});
const createdService = await DockerService.getServiceByName(
const createdService = await DockerService._fromName(
dockerHost,
serviceCreationDescriptor.name,
);
return createdService;
}
// INSTANCE
public dockerHostRef: DockerHost;
// INSTANCE PROPERTIES
// Note: dockerHost (not dockerHostRef) for consistency with base class
public ID: string;
public Version: { Index: number };
@@ -229,27 +264,49 @@ export class DockerService {
public Endpoint: { Spec: {}; VirtualIPs: [any[]] };
constructor(dockerHostArg: DockerHost) {
this.dockerHostRef = dockerHostArg;
super(dockerHostArg);
}
// INSTANCE METHODS
/**
* Refreshes this service's state from the Docker daemon
*/
public async refresh(): Promise<void> {
const updated = await DockerService._fromName(this.dockerHost, this.Spec.Name);
if (updated) {
Object.assign(this, updated);
}
}
/**
* Removes this service from the Docker daemon
*/
public async remove() {
await this.dockerHostRef.request('DELETE', `/services/${this.ID}`);
await this.dockerHost.request('DELETE', `/services/${this.ID}`);
}
/**
* Re-reads service data from Docker engine
* @deprecated Use refresh() instead
*/
public async reReadFromDockerEngine() {
const dockerData = await this.dockerHostRef.request(
const dockerData = await this.dockerHost.request(
'GET',
`/services/${this.ID}`,
);
// TODO: Better assign: Object.assign(this, dockerData);
}
/**
* Checks if this service needs an update based on image version
*/
public async needsUpdate(): Promise<boolean> {
// TODO: implement digest based update recognition
await this.reReadFromDockerEngine();
const dockerImage = await DockerImage.createFromRegistry(
this.dockerHostRef,
const dockerImage = await DockerImage._createFromRegistry(
this.dockerHost,
{
creationObject: {
imageUrl: this.Spec.TaskTemplate.ContainerSpec.Image,

1
ts/index.ts
View File

@@ -1,3 +1,4 @@
export * from './classes.base.js';
export * from './classes.host.js';
export * from './classes.container.js';
export * from './classes.image.js';

7
ts/interfaces/container.ts
View File

@@ -1,7 +1,12 @@
import { DockerNetwork } from '../classes.network.js';
/**
* Container creation descriptor supporting both string references and class instances.
* Strings will be resolved to resources internally.
*/
export interface IContainerCreationDescriptor {
Hostname: string;
Domainname: string;
networks?: DockerNetwork[];
/** Network names (strings) or DockerNetwork instances */
networks?: (string | DockerNetwork)[];
}

13
ts/interfaces/service.ts
View File

@@ -5,13 +5,20 @@ import { DockerNetwork } from '../classes.network.js';
import { DockerSecret } from '../classes.secret.js';
import { DockerImage } from '../classes.image.js';
/**
* Service creation descriptor supporting both string references and class instances.
* Strings will be resolved to resources internally.
*/
export interface IServiceCreationDescriptor {
name: string;
image: DockerImage;
/** Image tag (string) or DockerImage instance */
image: string | DockerImage;
labels: interfaces.TLabels;
networks: DockerNetwork[];
/** Network names (strings) or DockerNetwork instances */
networks: (string | DockerNetwork)[];
networkAlias: string;
secrets: DockerSecret[];
/** Secret names (strings) or DockerSecret instances */
secrets: (string | DockerSecret)[];
ports: string[];
accessHostDockerSock?: boolean;
resources?: {