build-strap 4.0.0-dev.46 → 4.0.0

package/dist/src/docker.volume.js

@@ -0,0 +1,62 @@
+import { throttle } from 'lodash-es';
+import { spawn } from './cp.js';
+// calling this function in rapid succession can lead to errors.
+// prefer throttled version
+export async function unthrottledDockerVolumeLs({ filter, } = {}) {
+    return (await spawn('docker', ['volume', 'ls', '--format', '{{json .}}'], {
+        captureOutput: true,
+    })).output
+        .split('\n')
+        .filter((line) => !!line.trim())
+        .map((line) => {
+        const { Driver: driver, Labels, Mountpoint: mountPoint, Name: name, Scope: scope, } = JSON.parse(line.trim());
+        return {
+            driver,
+            inspect: async () => (await dockerVolumeInspect(name))?.[0] || null,
+            labels: Labels.split(',').map((l) => l.trim()),
+            mountPoint,
+            name,
+            rm: async () => dockerVolumeRm(name),
+            scope,
+        };
+    })
+        .filter((v) => v.name && (typeof filter === 'function' ? filter(v) : true));
+}
+export const dockerVolumeLs = throttle(unthrottledDockerVolumeLs, 500, {
+    trailing: false,
+});
+export async function dockerVolumeFind(search, options) {
+    return ((await dockerVolumeLs(options))?.find((v) => v.name === search || v.name.startsWith(search)) ?? null);
+}
+export async function dockerVolumeCreate(name, { labels = [], driver, driverOpts = {} } = {}) {
+    const existing = await dockerVolumeFind(name);
+    if (existing)
+        return existing;
+    await spawn('docker', [
+        'volume',
+        'create',
+        ...labels.flatMap((l) => ['--label', l]),
+        ...(driver ? ['-d', driver] : []),
+        ...Object.entries(driverOpts).flatMap(([k, v]) => ['-o', `${k}=${v}`]),
+        name,
+    ]);
+    return dockerVolumeFind(name);
+}
+export async function dockerVolumeRm(id, ignoreErrors = true) {
+    const ids = Array.isArray(id) ? id : [id];
+    try {
+        await spawn('docker', ['volume', 'rm', ...ids]);
+    }
+    catch (e) {
+        if (!ignoreErrors) {
+            throw new Error(`Failed to remove volume(s): ${e.message}`);
+        }
+    }
+}
+// calling this function in rapid succession can lead to errors.
+// prefer throttled version
+export async function unthrottledDockerVolumeInspect(id) {
+    const ids = Array.isArray(id) ? id : [id];
+    return (JSON.parse((await spawn('docker', ['volume', 'inspect', '--format', '{{json .}}', ...ids], { captureOutput: true })).output.trim()) || []);
+}
+export const dockerVolumeInspect = throttle(unthrottledDockerVolumeInspect, 500, { trailing: true });

package/dist/src/dockerCleanup.d.ts

@@ -0,0 +1,38 @@
+interface CommonDockerCleanupOptions {
+    /** print matched items to console instead of deleting */
+    dryRun?: boolean;
+}
+/**
+ * Purge stopped containers
+ */
+export declare const dockerContainerCleanup: ({ dryRun, }?: CommonDockerCleanupOptions) => Promise<void>;
+interface DockerImageCleanupOptions extends CommonDockerCleanupOptions {
+    /** Image ids known to be produced by this build */
+    buildImageIds?: string[];
+    /** Explicit image names/ids to delete unconditionally */
+    images?: string[];
+    /**
+     * ignore default exclusions of :latest* and images < 1hr old
+     * this will delete all images in the given repos
+     */
+    purgeAll?: boolean;
+    /**
+     * looks for other builds of the same repos
+     * this will still exclude :latest* and images < 1hr old
+     * useful to clean up after past builds that failed to clean themselves properly
+     */
+    purgeOld?: boolean;
+    /** Image repositories to clean (defaults to the one configured in package.json) */
+    repos?: string[];
+}
+/**
+ * Purge docker images created during build process
+ */
+export declare const dockerImageCleanup: ({ repos, buildImageIds, images, purgeAll, purgeOld, dryRun, }?: DockerImageCleanupOptions) => Promise<void>;
+interface DockerCleanupOptions extends DockerImageCleanupOptions, CommonDockerCleanupOptions {
+}
+/**
+ * Purge docker images created during build process
+ */
+export declare const dockerCleanup: ({ dryRun, ...rest }?: DockerCleanupOptions) => Promise<void>;
+export default dockerCleanup;

package/dist/src/dockerCleanup.js

@@ -0,0 +1,77 @@
+import { uniq } from 'lodash-es';
+import moment from 'moment';
+import { dockerContainerLs } from './docker.container.js';
+import { dockerImages, dockerRmi, getDockerRepo, getDockerTags, getUntaggedDockerIds, } from './docker.js';
+import { buildLog } from './run.js';
+// flattens arrays of promises and/or promises for arrays
+// into a single array of (awaited) values
+async function flatten(input) {
+    const result = await input;
+    return Array.isArray(result)
+        ? [].concat(...(await Promise.all(result.map(flatten))))
+        : result;
+}
+/**
+ * Purge stopped containers
+ */
+export const dockerContainerCleanup = async ({ dryRun = process.argv.includes('--dry-run'), } = {}) => {
+    const toClean = await dockerContainerLs({
+        all: true,
+        filter: (c) => c.exited,
+    });
+    if (dryRun) {
+        if (toClean) {
+            buildLog(`Containers to delete (dry run):\n  ${toClean
+                .map((c) => c.id)
+                .join('\n  ')}`);
+        }
+        else {
+            buildLog('No containers to delete (dry run)');
+        }
+    }
+    else if (toClean) {
+        await Promise.all(toClean.map(async (c) => c.rm(true)));
+    }
+};
+/**
+ * Purge docker images created during build process
+ */
+export const dockerImageCleanup = async ({ repos = [getDockerRepo()], buildImageIds = [], images = [], purgeAll = process.argv.includes('--purge-all'), purgeOld = !process.argv.includes('--keep-old'), dryRun = process.argv.includes('--dry-run'), } = {}) => {
+    // only match images without a :latest tag
+    const filterLatest = (m) => purgeAll || !m.tag.match(/^latest(-\w+)?$/);
+    // only match images more than an hour old, AND without a :latest* tag
+    const filterOld = (m) => purgeAll ||
+        (filterLatest(m) && moment().subtract(1, 'h').isAfter(m.created));
+    const uniqueList = uniq([
+        // the things that we know were just built by us
+        // remove all tags from the given repos with a matching `buildImageIds`, except for :latest*
+        ...(await flatten(repos.map((r) => buildImageIds.map(async (b) => getDockerTags(b, r, true, filterLatest))))),
+        // unconditionally delete explicitly passed images/ids
+        ...images,
+        // images in the given `repos` without a tag, older than 1hr
+        ...(await flatten(repos.map(async (r) => getUntaggedDockerIds(r, filterOld)))),
+        // images with no repo and no tag
+        ...(await dockerImages(null, (m) => m.repository === '<none>' && m.tag === '<none>' && filterOld(m))).map((m) => m.id),
+        // any leftover tags from prior builds (only if purgeAll or purgeOld)
+        ...(purgeAll || purgeOld
+            ? await flatten(repos.map(async (r) => getDockerTags(null, r, true, filterOld)))
+            : []),
+    ]);
+    if (dryRun) {
+        buildLog(`Images to delete (dry run):\n  ${uniqueList.join('\n  ')}`);
+    }
+    else {
+        await dockerRmi(uniqueList, true);
+    }
+};
+/**
+ * Purge docker images created during build process
+ */
+export const dockerCleanup = async ({ dryRun, ...rest } = {}) => {
+    await dockerContainerCleanup({ dryRun });
+    await dockerImageCleanup({
+        dryRun,
+        ...rest,
+    });
+};
+export default dockerCleanup;

package/dist/src/dockerCompose.d.ts

@@ -0,0 +1,154 @@
+import { DockerContainer } from './docker.container.js';
+import { DockerNetwork, DockerNetworkCreateOptions } from './docker.network.js';
+import { DockerVolume, DockerVolumeCreateOptions } from './docker.volume.js';
+export declare type DockerComposeResourceTracker = {
+    cleaning: null | Promise<void>;
+    containers: Map<string, DockerContainer>;
+    networks: Map<string, DockerNetwork>;
+    services: Map<string, DockerComposeService>;
+    volumes: Map<string, DockerVolume>;
+};
+export declare const dockerComposeCreateResourceTracker: () => DockerComposeResourceTracker;
+declare type DockerComposeEnvDef = string[] | Record<string, string>;
+declare type DockerComposeULimitDef = number | {
+    hard: number;
+    soft: number;
+};
+declare type DockerComposeULimitsDef = Record<string, DockerComposeULimitDef>;
+interface DockerComposeServiceDef {
+    command?: string[];
+    container_name?: string;
+    environment?: DockerComposeEnvDef;
+    image?: string;
+    links?: string[];
+    networks?: string[];
+    ports?: string[];
+    ulimits?: DockerComposeULimitsDef;
+    volumes?: string[];
+}
+interface DockerComposeVolumeDef extends DockerVolumeCreateOptions {
+    name?: string;
+}
+interface DockerComposeNetworkDef extends DockerNetworkCreateOptions {
+    name?: string;
+}
+interface DockerCompose {
+    networks?: Record<string, DockerComposeNetworkDef>;
+    services?: Record<string, DockerComposeServiceDef>;
+    version: string;
+    volumes?: Record<string, DockerComposeVolumeDef>;
+}
+/**
+ * Parse a docker-compose.yml file into a pojo representation
+ * @param {string} filePath Path to the docker-compose.yml file
+ */
+export declare const dockerComposeParse: (filePath?: string) => Promise<DockerCompose>;
+/**
+ * Get the main docker-compose.yml from the root of the repo
+ * @param {boolean} force Force reload from file
+ */
+export declare const dockerComposeGetMain: (force?: boolean) => Promise<DockerCompose>;
+interface PortMap {
+    docker: number;
+    local: null | number;
+    localDefault: number;
+}
+interface UrlMap {
+    docker: null | string;
+    local: null | string;
+}
+interface ParsedPortInfo {
+    ports: PortMap[];
+    runArgs: string[];
+}
+interface ParsedVolumeInfo {
+    runArgs: string[];
+    volumes: string[];
+}
+interface ParsedNetworkInfo {
+    networks: string[];
+    runArgs: string[];
+}
+export declare const dockerComposeCreateNetworks: (names?: string[] | null | undefined, dockerCompose?: string | DockerCompose | null | undefined, tracker?: DockerComposeResourceTracker) => Promise<void>;
+export declare const dockerComposeCreateVolumes: (names?: string[] | undefined, dockerCompose?: string | DockerCompose | null | undefined, tracker?: DockerComposeResourceTracker) => Promise<void>;
+declare type HealthCheckFn = (result: UpResult) => Promise<void>;
+interface UpOptions {
+    avoidConflicts?: boolean;
+    cmd?: string[];
+    healthCheck?: HealthCheckFn;
+    mapPorts?: boolean;
+    mapVolumes?: boolean;
+    tracker?: DockerComposeResourceTracker;
+}
+interface ServiceNameInfo {
+    aliases: string[];
+    name: string;
+    suffix: string;
+}
+interface UpResult {
+    aliases: string[];
+    container: DockerContainer;
+    containerName: string;
+    ports: PortMap[];
+    service: DockerComposeService;
+    urls: UrlMap[];
+    volumes: string[];
+}
+export declare class DockerComposeService {
+    #private;
+    constructor(name: string, serviceDef: DockerComposeServiceDef, dockerCompose?: null | (DockerCompose | string));
+    get name(): string;
+    get serviceDef(): DockerComposeServiceDef;
+    get image(): null | string;
+    get defaultContainerName(): string;
+    get cmd(): string[];
+    get envArgs(): string[];
+    /**
+     * Find (available) container name and alias(es)
+     * @param {boolean} avoidConflicts if `true`, find a container name that is unused
+     * @param {number} max maximum number of names to try
+     */
+    getNames(avoidConflicts?: boolean, max?: number): Promise<ServiceNameInfo>;
+    getPorts(avoidConflicts?: boolean, mapLocal?: boolean): Promise<ParsedPortInfo>;
+    getDefaultPortInfo(): Promise<ParsedPortInfo>;
+    getDefaultPorts(): Promise<PortMap[]>;
+    getDefaultPortArgs(): Promise<string[]>;
+    getDefaultUrls(): Promise<UrlMap[]>;
+    getDefaultNetworkInfo(): Promise<ParsedNetworkInfo>;
+    getDefaultNetworks(): Promise<string[]>;
+    getDefaultNetworkArgs(): Promise<string[]>;
+    getDefaultVolumeInfo(): Promise<ParsedVolumeInfo>;
+    getDefaultVolumes(): Promise<string[]>;
+    getDefaultVolumeArgs(): Promise<string[]>;
+    pull(): Promise<void>;
+    getBaseRunArgs(): Promise<string[]>;
+    assembleRunArgs(containerName?: string, aliases?: string[], additionalArgs?: null | string[]): Promise<string[]>;
+    getRunArgs(avoidConflicts?: boolean, mapLocalPorts?: boolean): Promise<string[]>;
+    up({ healthCheck, avoidConflicts, mapVolumes, mapPorts, cmd, tracker, }?: UpOptions): Promise<UpResult>;
+    down({ includeDefaults, includeNetworks, includeVolumes, }?: {
+        includeDefaults?: boolean;
+        includeNetworks?: boolean;
+        includeVolumes?: boolean;
+    }): Promise<void>;
+    static parse(name: string, force?: boolean, dockerCompose?: null | (DockerCompose | string)): Promise<null | DockerComposeService>;
+    static getUrls(ports: PortMap[], alias: string): UrlMap[];
+}
+export declare function dockerComposeGetAllServices(dockerCompose?: null | (string | DockerCompose)): Promise<Record<string, null | DockerComposeService>>;
+export declare function dockerComposeTeardown({ includeDefaults, includeVolumes, includeNetworks, dockerCompose, tracker, }?: {
+    dockerCompose?: null | (string | DockerCompose);
+    includeDefaults?: boolean;
+    includeNetworks?: boolean;
+    includeVolumes?: boolean;
+    tracker?: DockerComposeResourceTracker;
+}): Promise<void>;
+export interface DockerContainerInfo extends UpResult {
+    dockerPort?: null | number;
+    dockerUrl?: null | string;
+    id: string;
+    image: string;
+    name?: null | string;
+    port?: null | number;
+    url?: null | string;
+}
+export declare function dockerComposeRunService(key: string, upOptions?: UpOptions, dockerCompose?: null | string | DockerCompose): Promise<DockerContainerInfo>;
+export {};