endia 0.0.1 → 0.0.2

package/README.md

@@ -6,6 +6,16 @@ The package needs Node 20 or later and ships ES modules with TypeScript declarat
 
 ## Example
 
+`ledger/Endiafile` holds a recipe of two stages; each stage begins with a `FROM`, and `AS` names it:
+
+```dockerfile
+FROM eastindia/development:latest AS tools
+RUN choco install -y git
+
+FROM tools AS app
+COPY publish/ C:/app/
+```
+
 ```js
 import { EastIndiaClient } from "endia";
 
@@ -17,5 +27,9 @@ const build = await client.images.build({ folder: "./ledger" }, { tags: ["lab/le
 const built = await build.result({ onLog: (text) => process.stdout.write(text) });
 console.log(built.digest);
 
+// A recipe of several stages: target names the stage to build, here the first.
+const tools = await (await client.images.build({ folder: "./ledger" }, { target: "tools", tags: ["lab/tools:1"] })).result();
+console.log(tools.stages?.map((stage) => [stage.name, stage.cacheHit]));
+
 client.close();
 ```

package/dist/contract/images.d.ts

@@ -102,16 +102,29 @@ export interface RemovalEntry {
     /** The digest of the image that was deleted, or null when the event is a removed tag. */
     readonly deleted?: string | null;
 }
-/** The result of a finished build: the image it made or reused, the tags that now name that image, and whether an image with the same build key already existed. */
+/** The result of a finished build: the image it made or reused for its target stage, the tags that now name that image, whether anything was built, and what each stage on the way to the target gave. */
 export interface BuildResult {
     /** The digest of the image, in the form `sha256:` followed by 64 hexadecimal digits. */
     readonly digest: string;
     /** The tags that were requested, each of which now names the image; empty when the build asked for none. */
     readonly tags: readonly string[];
-    /** The build key: a SHA-256 hash of everything that decides the build's result. A later build with the same key reuses this image. */
+    /** The target stage's build key: a SHA-256 hash of everything that decides its result. A later build with the same key reuses this image. */
     readonly buildKey: string;
-    /** Whether an image with the same build key already existed, so that nothing was built. */
+    /** Whether every stage was found in the cache, so that nothing was built. */
     readonly cacheHit: boolean;
     /** How long the build took, in seconds, from the start of the operation's work to the last tag moved. */
     readonly seconds: number;
+    /** Each stage the build made or found, from the lowest, built on an image, to the target. A recipe of one stage gives one. A service older than multi-stage builds leaves it out. */
+    readonly stages?: readonly BuildStageResult[];
+}
+/** What one stage of a build gave: the image, for the target stage, or a build-cache entry, for a stage below it. A stage is the part of a recipe from one `FROM` to the next; a build-cache entry is a stage's committed result that is not an image, which a later build whose stage has the same build key reuses. */
+export interface BuildStageResult {
+    /** The name that the stage's `FROM ... AS` gives it, in lower case, or null for a stage without one. */
+    readonly name: string | null;
+    /** The digest of the stage's result, in the form `sha256:` followed by 64 hexadecimal digits. */
+    readonly digest: string;
+    /** The stage's build key: a SHA-256 hash of everything that decides the stage's result. */
+    readonly buildKey: string;
+    /** Whether an image or build-cache entry with the stage's build key already existed, so that the stage was not built. */
+    readonly cacheHit: boolean;
 }

package/dist/contract/space.d.ts

@@ -1,5 +1,5 @@
 import type { Timestamp } from "./common.js";
-/** The answer to `endia system df`, as `docker system df` answers: what the images, machines and named volumes hold on disk, which of it is in use and which `system prune` would delete, and how much room the image folder's volume has left. */
+/** The answer to `endia system df`, as `docker system df` answers: what the images, machines, named volumes and build cache hold on disk, which of it is in use and which `system prune` would delete, and how much room the image folder's volume has left. */
 export interface DiskUsage {
     /** Every image. */
     readonly images: readonly ImageUsage[];
@@ -7,6 +7,8 @@ export interface DiskUsage {
     readonly machines: readonly MachineUsage[];
     /** Every named volume. */
     readonly volumes: readonly VolumeUsage[];
+    /** Every build-cache entry. A service older than multi-stage builds leaves it out. */
+    readonly buildCache?: readonly BuildCacheUsage[];
     /** The image folder's volume: its free space, its capacity and the space EastIndia keeps free on it. */
     readonly imageFolder: ImageFolderSpace;
     /** The storage root: what its records take and the free space on its volume. */
@@ -49,6 +51,23 @@ export interface VolumeUsage {
     /** The machine the volume is attached to, or null. */
     readonly attachedTo: string | null;
 }
+/** One build-cache entry as `system df` counts it: the committed result of a recipe's stage that a build made below its target. It is not an image; a later build whose stage has the same build key reuses it. */
+export interface BuildCacheUsage {
+    /** The entry's digest. */
+    readonly id: string;
+    /** The digest of the image or build-cache entry the entry is built on. */
+    readonly parentId: string | null;
+    /** When a build made the entry. */
+    readonly created: Timestamp;
+    /** When a build last made or found the entry. */
+    readonly lastUsed: Timestamp;
+    /** The size on disk of the entry's own disk file. */
+    readonly sizeBytes: number;
+    /** Whether an image, machine or other entry is built on the entry, or a running build has made or found it. `system df` counts such entries as active. */
+    readonly inUse: boolean;
+    /** Whether `builder prune` would delete the entry. */
+    readonly reclaimable: boolean;
+}
 /** The room left on the image folder's volume, where every disk lives. */
 export interface ImageFolderSpace {
     /** The image folder's full path. */
@@ -75,6 +94,8 @@ export interface PruneResult {
     readonly deletedMachines: readonly string[];
     /** The images deleted, by digest. */
     readonly deletedImages: readonly string[];
+    /** The build-cache entries deleted, by digest: the results of recipe stages below a build's target that nothing used. A service older than multi-stage builds leaves it out. */
+    readonly deletedBuildCache?: readonly string[];
     /** The named volumes deleted, by name. */
     readonly deletedVolumes: readonly string[];
     /** The number of finished operations deleted, those older than `operationRetentionDays`. */
@@ -84,3 +105,10 @@ export interface PruneResult {
     /** The size of the files deleted. */
     readonly reclaimedBytes: number;
 }
+/** The result of a `builder prune` operation: the build-cache entries it deleted and the space that freed. */
+export interface BuilderPruneResult {
+    /** The build-cache entries deleted, by digest, in the order deleted. */
+    readonly deletedBuildCache: readonly string[];
+    /** The size of the disk files deleted. */
+    readonly reclaimedBytes: number;
+}

package/dist/groups/images.d.ts

@@ -1,8 +1,9 @@
 import type { Readable } from "node:stream";
 import type { Filters } from "../contract/common.js";
 import type { BuildResult, ImageDetail, ImageSummary, RemovalEntry, TagResult } from "../contract/images.js";
+import type { BuilderPruneResult } from "../contract/space.js";
 import type { OperationHandle } from "./operations.js";
-/** What a build makes and how: the tags, the build arguments and labels, and the builder's resources. */
+/** What a build makes and how: the tags, the build arguments and labels, the stage to build, and the builder's resources. */
 export interface BuildOptions {
     /** The tags the new image carries, such as `lab/dotnet:10`. */
     readonly tags?: readonly string[];
@@ -11,7 +12,24 @@ export interface BuildOptions {
     /** The labels added to the image, by key. */
     readonly labels?: Readonly<Record<string, string>>;
     /**
-     * Whether to build even when an image with the same build key exists. The build key is a SHA-256 hash of everything that decides
+     * The recipe's stage to build, named by its `FROM ... AS`, as `endia build --target` names it; the tags name that stage's result.
+     * The stages it is built on are built too, or found in the cache. When undefined, the build makes the recipe's last stage.
+     *
+     * @example
+     * For the recipe
+     * ```
+     * FROM eastindia/development:latest AS tools
+     * RUN choco install -y git
+     *
+     * FROM tools AS app
+     * COPY publish/ C:/app/
+     * ```
+     * `client.images.build({ folder: "./lab-image" }, { target: "tools", tags: ["lab/tools:1"] })` builds and tags the first stage
+     * alone. A later build without `target` finds that stage in the cache and builds only `app`.
+     */
+    readonly target?: string;
+    /**
+     * Whether to build every stage even when an image with the same build key exists. The build key is a SHA-256 hash of everything that decides
      * a build's result, such as the parent image, every step and the content of every copied file; a build that finds an image with
      * its key reuses that image.
      */
@@ -40,8 +58,8 @@ export interface ArchiveContext {
     readonly recipe?: string;
 }
 /**
- * The image routes: build, list, inspect, tag and remove. A build returns an `OperationHandle`, because the service builds in the
- * background.
+ * The image routes: build, list, inspect, tag and remove, and the prune of the build cache that builds leave. A build and a prune
+ * each return an `OperationHandle`, because the service does that work in the background.
  */
 export declare class ImagesClient {
     private readonly connection;
@@ -94,5 +112,19 @@ export declare class ImagesClient {
         readonly force?: boolean;
         readonly signal?: AbortSignal;
     }): Promise<RemovalEntry[]>;
+    /**
+     * Deletes the unused build cache: `endia builder prune`. A build-cache entry is the committed result of a recipe's stage that a
+     * build made below its target. An entry is unused when no image, machine or other entry is built on it and no running build has
+     * made or found it. The prune deletes every unused entry, repeating until none remains, and leaves the entries that running
+     * builds use.
+     *
+     * @param options - `all` is Docker's `--all`. It deletes the same entries, because once a build has finished the build cache holds
+     * nothing that a build still uses.
+     * @returns The prune's operation; its result names the entries deleted and the space freed.
+     */
+    pruneBuildCache(options?: {
+        readonly all?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<OperationHandle<BuilderPruneResult>>;
     private sendBuild;
 }

package/dist/groups/images.js

@@ -3,8 +3,8 @@ import { Routes } from "../routes.js";
 import { jsonBody, tarBody } from "../transport/api-connection.js";
 import { QueryText } from "../transport/query-text.js";
 /**
- * The image routes: build, list, inspect, tag and remove. A build returns an `OperationHandle`, because the service builds in the
- * background.
+ * The image routes: build, list, inspect, tag and remove, and the prune of the build cache that builds leave. A build and a prune
+ * each return an `OperationHandle`, because the service does that work in the background.
  */
 export class ImagesClient {
     connection;
@@ -78,12 +78,28 @@ export class ImagesClient {
         const query = new QueryText().addFlag("force", options.force);
         return this.connection.change({ method: "DELETE", path: Routes.image(reference) + query.toString(), signal: options.signal });
     }
+    /**
+     * Deletes the unused build cache: `endia builder prune`. A build-cache entry is the committed result of a recipe's stage that a
+     * build made below its target. An entry is unused when no image, machine or other entry is built on it and no running build has
+     * made or found it. The prune deletes every unused entry, repeating until none remains, and leaves the entries that running
+     * builds use.
+     *
+     * @param options - `all` is Docker's `--all`. It deletes the same entries, because once a build has finished the build cache holds
+     * nothing that a build still uses.
+     * @returns The prune's operation; its result names the entries deleted and the space freed.
+     */
+    async pruneBuildCache(options = {}) {
+        const query = new QueryText().addFlag("all", options.all);
+        const accepted = await this.connection.change({ method: "POST", path: Routes.builderPrune + query.toString(), signal: options.signal });
+        return this.operations.handle(accepted);
+    }
     async sendBuild(body, recipe, options) {
         const query = new QueryText()
             .addEach("t", options.tags)
             .add("dockerfile", recipe)
             .addJson("buildargs", options.buildArgs)
             .addJson("labels", options.labels)
+            .add("target", options.target)
             .add("memory", options.memory)
             .add("cpus", options.cpus)
             .addFlag("nocache", options.noCache);

package/dist/groups/system.d.ts

@@ -5,16 +5,21 @@ export declare class SystemClient {
     private readonly connection;
     private readonly operations;
     /**
-     * Reads what images, machines and volumes take on disk, and the free space: `endia system df`.
+     * Reads what images, machines, volumes and the build cache take on disk, and the free space: `endia system df`.
      *
      * @param signal - Cancels the request.
      * @returns The disk use.
      */
     diskUsage(signal?: AbortSignal): Promise<DiskUsage>;
     /**
-     * Deletes what nothing uses: `endia system prune`. In order, it deletes every machine in state `exited` or `created`, every
-     * image with no tag, no children and no machine, the finished operations older than the service's retention, and the host objects
-     * whose owner no longer exists. It deletes what every caller of the service made, not only this caller's.
+     * Deletes what nothing uses: `endia system prune`. It deletes, in this order:
+     * 1. every machine in state `exited` or `created`;
+     * 2. every image with no tag, no children and no machine;
+     * 3. the unused build cache, the entries that `images.pruneBuildCache` deletes;
+     * 4. the finished operations older than the service's retention;
+     * 5. the host objects whose owner no longer exists.
+     *
+     * It deletes what every caller of the service made, not only this caller's.
      *
      * @param options - `all` deletes every image that no machine uses and no image is built on, tagged or not. `volumes` is Docker's
      * option for anonymous volumes; EastIndia has none, so it deletes nothing more.

package/dist/groups/system.js

@@ -10,7 +10,7 @@ export class SystemClient {
         this.operations = operations;
     }
     /**
-     * Reads what images, machines and volumes take on disk, and the free space: `endia system df`.
+     * Reads what images, machines, volumes and the build cache take on disk, and the free space: `endia system df`.
      *
      * @param signal - Cancels the request.
      * @returns The disk use.
@@ -19,9 +19,14 @@ export class SystemClient {
         return this.connection.read(Routes.systemDf, signal);
     }
     /**
-     * Deletes what nothing uses: `endia system prune`. In order, it deletes every machine in state `exited` or `created`, every
-     * image with no tag, no children and no machine, the finished operations older than the service's retention, and the host objects
-     * whose owner no longer exists. It deletes what every caller of the service made, not only this caller's.
+     * Deletes what nothing uses: `endia system prune`. It deletes, in this order:
+     * 1. every machine in state `exited` or `created`;
+     * 2. every image with no tag, no children and no machine;
+     * 3. the unused build cache, the entries that `images.pruneBuildCache` deletes;
+     * 4. the finished operations older than the service's retention;
+     * 5. the host objects whose owner no longer exists.
+     *
+     * It deletes what every caller of the service made, not only this caller's.
      *
      * @param options - `all` deletes every image that no machine uses and no image is built on, tagged or not. `volumes` is Docker's
      * option for anonymous volumes; EastIndia has none, so it deletes nothing more.

package/dist/routes.d.ts

@@ -8,6 +8,7 @@ export declare const Routes: {
     readonly hostStats: "/v1/host/stats";
     readonly systemDf: "/v1/system/df";
     readonly systemPrune: "/v1/system/prune";
+    readonly builderPrune: "/v1/builder/prune";
     readonly images: "/v1/images";
     readonly build: "/v1/images/build";
     readonly baseImport: "/v1/bases/import";

package/dist/routes.js

@@ -8,6 +8,7 @@ export const Routes = {
     hostStats: "/v1/host/stats",
     systemDf: "/v1/system/df",
     systemPrune: "/v1/system/prune",
+    builderPrune: "/v1/builder/prune",
     images: "/v1/images",
     build: "/v1/images/build",
     baseImport: "/v1/bases/import",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "endia",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Client for EastIndia, which runs Windows desktop test machines that tests drive like Docker containers. Early preview.",
 	"license": "Apache-2.0",
 	"author": "teaToolkit",