hammerkit 1.11.1 → 1.12.0

package/build.schema.json

@@ -208,6 +208,37 @@
                       "description": "secret from env:NAME or file:path, injected as env or a read-only file"
                     }
                   },
+                  "resources": {
+                    "type": "object",
+                    "properties": {
+                      "cpus": {
+                        "type": [
+                          "number",
+                          "string"
+                        ]
+                      },
+                      "memory": {
+                        "type": "string"
+                      },
+                      "requests": {
+                        "type": "object",
+                        "properties": {
+                          "cpus": {
+                            "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/resources/properties/cpus"
+                          },
+                          "memory": {
+                            "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/resources/properties/memory"
+                          }
+                        },
+                        "additionalProperties": false
+                      },
+                      "limits": {
+                        "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/resources/properties/requests"
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "cpu and memory requests and limits"
+                  },
                   "image": {
                     "type": "string"
                   },
@@ -269,6 +300,9 @@
                   "secrets": {
                     "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/secrets"
                   },
+                  "resources": {
+                    "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/resources"
+                  },
                   "platform": {
                     "type": "object",
                     "properties": {
@@ -392,6 +426,10 @@
                     "items": {
                       "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/secrets/items"
                     }
+                  },
+                  "resources": {
+                    "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/resources",
+                    "description": "cpu and memory requests and limits"
                   }
                 },
                 "required": [

package/dist/cli.js

@@ -7,6 +7,7 @@ const get_logger_1 = require("./console/get-logger");
 const event_cache_1 = require("./executer/event-cache");
 const validate_1 = require("./planner/validate");
 const process_manager_1 = require("./executer/process-manager");
+const resource_budget_1 = require("./executer/resource-budget");
 const update_service_status_1 = require("./service/update-service-status");
 const check_for_loop_1 = require("./executer/scheduler/check-for-loop");
 const state_1 = require("./executer/state");
@@ -29,7 +30,6 @@ class Cli {
         this.environment = environment;
     }
     setup(type, options) {
-        const processManager = new process_manager_1.ProcessManager(options?.workers ?? 0);
         const logMode = options?.logMode ?? (ci_1.isCI ? 'live' : 'interactive');
         const workTree = (0, reset_work_tree_1.resetWorkTree)(this.workTree, type);
         const processWorkTree = new state_1.State(workTree, {
@@ -43,6 +43,11 @@ class Cli {
             state: processWorkTree,
             start: async () => {
                 (0, check_for_loop_1.checkForLoop)(workTree);
+                const capacity = (0, plan_work_tasks_1.hasError)(workTree) ? null : await (0, resource_budget_1.getResourceCapacity)(workTree, this.environment);
+                if (capacity && type !== 'down' && (options?.resourceCheck ?? true)) {
+                    rejectOversizedWork(workTree, capacity, type === 'up');
+                }
+                const processManager = new process_manager_1.ProcessManager(options?.workers ?? 0, capacity ? new resource_budget_1.ResourceBudget(capacity, workTree.environment) : null);
                 if (!(0, plan_work_tasks_1.hasError)(workTree)) {
                     await (0, update_service_status_1.updateServiceStatus)(workTree);
                     await (0, execute_work_tree_1.executeWorkTree)(workTree, this.environment, {
@@ -58,6 +63,7 @@ class Cli {
                         timeout: options?.timeout ?? null,
                         skipDeps: options?.skipDeps ?? true,
                         wait: options?.wait ?? 'ready',
+                        resourceCheck: options?.resourceCheck ?? true,
                     });
                 }
                 const result = (0, get_scheduler_execute_result_1.getSchedulerExecuteResult)(workTree);
@@ -66,6 +72,11 @@ class Cli {
             },
         };
     }
+    // The worker count when none is given: 4, or unbounded when every task and
+    // service requests cpus and memory, so the requests alone bound the run.
+    defaultWorkers() {
+        return (0, resource_budget_1.requestsEverything)(this.workTree) ? 0 : 4;
+    }
     up(options) {
         return this.setup('up', options);
     }
@@ -168,4 +179,11 @@ function getCli(workTree, environment) {
     return new Cli(workTree, environment);
 }
 exports.getCli = getCli;
+// Fails the run before anything starts when a task, with the services it
+// needs, requests more than the host has: it could never run.
+function rejectOversizedWork(workTree, capacity, up) {
+    for (const { item, message } of (0, resource_budget_1.findOversizedWork)(workTree, capacity, up)) {
+        item.state.set({ type: 'error', errorMessage: `${message} (--skip-resource-check runs anyway)`, stateKey: null });
+    }
+}
 //# sourceMappingURL=cli.js.map

package/dist/executer/await-completed-dependencies.js

@@ -16,12 +16,18 @@ async function awaitRequirement(svc, abort, options = { untilAllDone: false }) {
     return Promise.race([ready, allDone]);
 }
 exports.awaitRequirement = awaitRequirement;
-// Resolve true once any dependent is `ready` — it missed the cache and is about
-// to run, so it needs this task's outputs — and false once every dependent
-// finished without needing it (all cache hits, or skipped themselves).
+// Resolve true once any dependent needs this task's outputs — a task that is
+// `ready` (it missed the cache and is about to run), a service that is
+// `starting` (a task needing it runs) — and false once every dependent
+// finished without needing it: tasks that were cache hits or skipped, services
+// that never started.
 async function awaitDependentNeed(dependents, abort) {
-    const ready = Promise.race(dependents.map((dependent) => (0, state_resolver_1.awaitState)('await-dependent', dependent.state, (s) => s.type === 'ready', abort))).then(() => true);
-    const allDone = Promise.all(dependents.map((dependent) => (0, state_resolver_1.awaitState)('await-dependent-done', dependent.state, (s) => s.type === 'completed' || s.type === 'error' || s.type === 'crash' || s.type === 'canceled', abort))).then(() => false);
+    const ready = Promise.race(dependents.map((dependent) => (0, work_item_1.isWorkTaskItem)(dependent)
+        ? (0, state_resolver_1.awaitState)('await-dependent', dependent.state, (s) => s.type === 'ready', abort)
+        : (0, state_resolver_1.awaitState)('await-dependent', dependent.state, (s) => s.type === 'starting' || s.type === 'ready' || s.type === 'running', abort))).then(() => true);
+    const allDone = Promise.all(dependents.map((dependent) => (0, work_item_1.isWorkTaskItem)(dependent)
+        ? (0, state_resolver_1.awaitState)('await-dependent-done', dependent.state, (s) => s.type === 'completed' || s.type === 'error' || s.type === 'crash' || s.type === 'canceled', abort)
+        : (0, state_resolver_1.awaitState)('await-dependent-done', dependent.state, (s) => s.type === 'end' || s.type === 'error' || s.type === 'canceled', abort))).then(() => false);
     return Promise.race([ready, allDone]);
 }
 exports.awaitDependentNeed = awaitDependentNeed;

package/dist/executer/docker-resources.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDockerResources = exports.getDockerResources = void 0;
+// The host config limits of a container with these resources; none without.
+// A memory request below the limit is a soft reservation; Docker has no CPU
+// request, the run schedules by it (see ResourceBudget). Docker refuses more CPUs than the host has, while a limit at or above the
+// host's count limits nothing: such a container runs unlimited, with a
+// warning, instead of failing or being clamped to fewer CPUs.
+function getDockerResources(resources, hostCpus, status) {
+    if (!resources) {
+        return {};
+    }
+    const { limits, requests } = resources;
+    const config = {};
+    if (limits.cpus !== null) {
+        if (hostCpus !== null && limits.cpus > hostCpus) {
+            status.write('warn', `cpus ${limits.cpus} exceeds the ${hostCpus} cpus of the docker host, running without a cpu limit`);
+        }
+        else {
+            config.NanoCpus = Math.round(limits.cpus * 1e9);
+        }
+    }
+    if (limits.memory !== null) {
+        config.Memory = limits.memory;
+    }
+    if (requests.memory !== null && (limits.memory === null || requests.memory < limits.memory)) {
+        config.MemoryReservation = requests.memory;
+    }
+    return config;
+}
+exports.getDockerResources = getDockerResources;
+// The limits for the docker host, asking it for its CPU count only when a
+// CPU limit is declared.
+async function resolveDockerResources(docker, resources, status) {
+    const hostCpus = resources?.limits.cpus != null ? await getDockerHostCpus(docker) : null;
+    return getDockerResources(resources, hostCpus, status);
+}
+exports.resolveDockerResources = resolveDockerResources;
+async function getDockerHostCpus(docker) {
+    const info = await docker.info();
+    return typeof info.NCPU === 'number' && info.NCPU > 0 ? info.NCPU : null;
+}
+//# sourceMappingURL=docker-resources.js.map

package/dist/executer/docker-service.js

@@ -20,8 +20,9 @@ const replace_env_variables_1 = require("../environment/replace-env-variables");
 const get_service_containers_1 = require("./get-service-containers");
 const work_instance_id_1 = require("../planner/work-instance-id");
 const work_healthcheck_1 = require("../planner/work-healthcheck");
+const docker_resources_1 = require("./docker-resources");
 const HEALTHCHECK_INTERVAL_MS = 1000;
-function buildServiceCreateOptions(item, options, network, secrets) {
+function buildServiceCreateOptions(item, options, network, secrets, resources = {}) {
     const envs = (0, replace_env_variables_1.getEnvironmentVariables)(item.data.envs);
     const command = (0, work_service_1.getServiceCommand)(item.data);
     return {
@@ -64,6 +65,7 @@ function buildServiceCreateOptions(item, options, network, secrets) {
                     return map;
                 }, {})
                 : {},
+            ...resources,
         },
     };
 }
@@ -81,7 +83,8 @@ async function dockerService(docker, item, options, environment) {
         const network = (0, docker_task_1.getNeedsNetwork)(serviceContainers, item.needs);
         item.status.write('debug', `create container with image ${item.data.image}`);
         const secrets = await (0, container_secrets_1.prepareContainerSecrets)(item.data.secrets, (0, work_instance_id_1.getWorkInstanceId)(item), environment);
-        container = await docker.createContainer(buildServiceCreateOptions(item, options, network, secrets));
+        const resources = await (0, docker_resources_1.resolveDockerResources)(docker, item.data.resources, item.status);
+        container = await docker.createContainer(buildServiceCreateOptions(item, options, network, secrets, resources));
         const stream = await container.attach({ stream: true, stdout: true, stderr: true });
         (0, stream_1.logStream)(item.status, stream);
         await container.start();

package/dist/executer/docker-task.js

@@ -17,6 +17,7 @@ const work_instance_id_1 = require("../planner/work-instance-id");
 const get_outputs_to_reset_1 = require("../planner/utils/get-outputs-to-reset");
 const container_secrets_1 = require("./container-secrets");
 const container_task_state_1 = require("./container-task-state");
+const docker_resources_1 = require("./docker-resources");
 function getNeedsNetwork(serviceContainers, needs) {
     const links = [];
     const hosts = [];
@@ -35,7 +36,7 @@ function getNeedsNetwork(serviceContainers, needs) {
     return { links, hosts };
 }
 exports.getNeedsNetwork = getNeedsNetwork;
-function buildCreateOptions(item, stateKey, serviceContainers, environment, secrets) {
+function buildCreateOptions(item, stateKey, serviceContainers, environment, secrets, resources = {}) {
     const network = getNeedsNetwork(serviceContainers, item.needs);
     const binds = (0, get_container_binds_1.getContainerBinds)(item);
     const envs = (0, replace_env_variables_1.getEnvironmentVariables)(item.data.envs);
@@ -66,6 +67,7 @@ function buildCreateOptions(item, stateKey, serviceContainers, environment, secr
             ExtraHosts: network.hosts,
             Links: network.links,
             AutoRemove: true,
+            ...resources,
         },
     };
 }
@@ -89,7 +91,8 @@ async function dockerTask(docker, item, environment, options) {
         (0, abort_1.checkForAbort)(options.abort);
         const serviceContainers = (0, get_service_containers_1.getServiceContainers)(item.needs);
         const secrets = await (0, container_secrets_1.prepareContainerSecrets)(item.data.secrets, (0, work_instance_id_1.getWorkInstanceId)(item), environment);
-        const containerOptions = buildCreateOptions(item, options.stateKey, serviceContainers, environment, secrets);
+        const resources = await (0, docker_resources_1.resolveDockerResources)(docker, item.data.resources, item.status);
+        const containerOptions = buildCreateOptions(item, options.stateKey, serviceContainers, environment, secrets, resources);
         (0, print_container_options_1.printContainerOptions)(item.status, containerOptions);
         const succeeded = await (0, using_container_1.usingContainer)(docker, item, containerOptions, async (container) => {
             await (0, execution_steps_1.setUserPermissions)(item, container, environment);

package/dist/executer/dry-run.js

@@ -48,6 +48,7 @@ async function planDryRun(workTree, defaultCacheMethod, environment) {
             taskName: task.name,
             status: explanation?.status ?? 'miss',
             causes: explanation?.causes ?? [],
+            ...(task.data.type === 'local-task' && task.data.resources ? { unenforcedResources: true } : {}),
         });
     }
     return { entries, cycle: null };
@@ -66,7 +67,8 @@ function printDryRun(environment, plan) {
                 ? colors_1.default.grey('uncacheable')
                 : colors_1.default.yellow('cache miss');
         const causes = entry.causes.length > 0 ? colors_1.default.grey(` (${entry.causes.map(explain_1.describeCause).join(', ')})`) : '';
-        environment.stdout.write(`  ${index + 1}. ${entry.taskName}: ${label}${causes}\n`);
+        const resources = entry.unenforcedResources ? colors_1.default.grey(' [resources not enforced for a local task]') : '';
+        environment.stdout.write(`  ${index + 1}. ${entry.taskName}: ${label}${causes}${resources}\n`);
     });
 }
 exports.printDryRun = printDryRun;

package/dist/executer/execute-work-service.js

@@ -50,16 +50,22 @@ async function executeWorkService(work, environment, options) {
                 });
             }
             const init = getServiceInit(work);
-            await work.runtime.execute(environment, {
-                cache: cacheState,
-                abort,
-                state: init ? gateOnInit(work, init) : work.state,
-                stateKey: cacheState.stateKey,
-                daemon: options.daemon,
-                publishPorts: options.type === 'up' || work.requiredBy.some(isLocalTaskItem) || (!!init && isLocalTaskItem(init.task)),
-                // an init needs a healthy service, so a service with one is always awaited
-                waitForReady: options.wait === 'ready' || work.requiredBy.length > 0 || !!init,
-            });
+            const release = options.processManager.service(work);
+            try {
+                await work.runtime.execute(environment, {
+                    cache: cacheState,
+                    abort,
+                    state: init ? gateOnInit(work, init) : work.state,
+                    stateKey: cacheState.stateKey,
+                    daemon: options.daemon,
+                    publishPorts: options.type === 'up' || work.requiredBy.some(isLocalTaskItem) || (!!init && isLocalTaskItem(init.task)),
+                    // an init needs a healthy service, so a service with one is always awaited
+                    waitForReady: options.wait === 'ready' || work.requiredBy.length > 0 || !!init,
+                });
+            }
+            finally {
+                release();
+            }
         });
     }
     catch (e) {

package/dist/executer/execute-work-task.js

@@ -38,14 +38,14 @@ function onlyGroupsCacheHits(work) {
         work.deps.every((dep) => dep.state.current.type === 'completed' && dep.state.current.cached));
 }
 async function executeWorkTask(work, environment, options, 
-// when set, the task was not requested and only runs if one of these tasks
-// depending on it misses the cache (see executeWorkTree)
+// when set, the task was not requested and only runs if one of these items
+// depending on it needs it (see executeWorkTree)
 dependents = null) {
     try {
         if (dependents) {
             const needed = await (0, await_completed_dependencies_1.awaitDependentNeed)(dependents, environment.abortCtrl.signal);
             if (!needed) {
-                work.status.write('debug', `${work.name} skipped, every task depending on it was a cache hit`);
+                work.status.write('debug', `${work.name} skipped, nothing depending on it had to run`);
                 work.state.set({ type: 'completed', cached: false, skipped: true, duration: 0, stateKey: '' });
                 return;
             }

package/dist/executer/execute-work-tree.js

@@ -51,26 +51,29 @@ function mirrorServicesToInitViews(work) {
         });
     }
 }
-// For every task that may be skipped when nothing needs it, the tasks in this
-// run that depend on it. Requested tasks always run; so does anything a service
-// depends on, and everything in watch mode or with skipping turned off.
+// For every task that may be skipped when nothing needs it, the tasks and
+// services in this run that depend on it. Requested tasks always run; a
+// service's dependency runs once the service starts. Everything runs in watch
+// mode, under `up` and with skipping turned off.
 function skippableDependents(work, options) {
     const result = new Map();
     if (options.type !== 'execute' || !options.skipDeps || options.watch || !work.requested) {
         return result;
     }
-    const neededByService = new Set();
-    for (const service of (0, plan_work_tasks_1.iterateWorkServices)(work)) {
-        for (const dep of service.deps) {
-            neededByService.add(dep.name);
+    // a dependency of nothing in the run (its service needs no one here) has no
+    // dependents left, and is skipped
+    for (const task of (0, plan_work_tasks_1.iterateWorkTasks)(work)) {
+        if (!work.requested.includes(task.name) && !(0, execute_init_task_1.findInitOf)(task)) {
+            result.set(task.name, []);
         }
     }
-    for (const task of (0, plan_work_tasks_1.iterateWorkTasks)(work)) {
-        for (const dep of task.deps) {
-            if (work.requested.includes(dep.name) || neededByService.has(dep.name)) {
+    const items = [...(0, plan_work_tasks_1.iterateWorkTasks)(work), ...(0, plan_work_tasks_1.iterateWorkServices)(work)];
+    for (const item of items) {
+        for (const dep of item.deps) {
+            if (work.requested.includes(dep.name)) {
                 continue;
             }
-            result.set(dep.name, [...(result.get(dep.name) ?? []), task]);
+            result.set(dep.name, [...(result.get(dep.name) ?? []), item]);
         }
     }
     return result;

package/dist/executer/print-container-options.js

@@ -9,6 +9,15 @@ function printContainerOptions(status, containerOptions) {
     for (const mount of containerOptions.HostConfig?.Binds || []) {
         status.write('debug', `bind ${mount}`);
     }
+    if (containerOptions.HostConfig?.NanoCpus) {
+        status.write('debug', `limit cpus to ${containerOptions.HostConfig.NanoCpus / 1e9}`);
+    }
+    if (containerOptions.HostConfig?.Memory) {
+        status.write('debug', `limit memory to ${containerOptions.HostConfig.Memory} bytes`);
+    }
+    if (containerOptions.HostConfig?.MemoryReservation) {
+        status.write('debug', `reserve memory ${containerOptions.HostConfig.MemoryReservation} bytes`);
+    }
     for (const link of containerOptions.HostConfig?.Links || []) {
         status.write('debug', `link ${link}`);
     }

package/dist/executer/process-manager.js

@@ -3,13 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProcessManager = void 0;
 const log_1 = require("../log");
 class ProcessManager {
-    constructor(workerLimit) {
+    // With a budget a task also starts only once its requests fit next to what
+    // runs already; one starts regardless when nothing else runs, so a run
+    // whose services alone fill the budget, or a task bigger than it, still
+    // makes progress.
+    constructor(workerLimit, budget = null) {
         this.workerLimit = workerLimit;
+        this.budget = budget;
         this.processes = [];
         this.pendingProcesses = [];
     }
     task(item, factory) {
         return new Promise((resolve, reject) => {
+            if (this.budget) {
+                this.pendingProcesses.push({ item, factory, resolve, reject });
+                this.startFitting();
+                return;
+            }
             const hasFreeWorker = this.workerLimit === 0 || this.workerLimit > this.processes.length;
             if (hasFreeWorker) {
                 this.startProcess({ factory, item, resolve, reject });
@@ -19,7 +29,29 @@ class ProcessManager {
             }
         });
     }
+    // A running service holds its requests until it ends; it never waits, the
+    // tasks needing it do.
+    service(item) {
+        const budget = this.budget;
+        if (!budget) {
+            return () => undefined;
+        }
+        const requests = budget.requestsOf(item);
+        budget.acquire(requests);
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                budget.release(requests);
+                this.startFitting();
+            }
+        };
+    }
     enqueuePendingProcesses() {
+        if (this.budget) {
+            this.startFitting();
+            return;
+        }
         const nextProcess = this.pendingProcesses[0];
         if (nextProcess) {
             const hasBlockingProcess = this.processes.some((p) => p.id === nextProcess.item.name);
@@ -32,7 +64,28 @@ class ProcessManager {
             this.startProcess(pendingProcess);
         }
     }
-    startProcess(pendingProcess) {
+    // In order, every pending task that fits; a later, smaller one may start
+    // while an earlier one waits for room.
+    startFitting() {
+        for (const pending of [...this.pendingProcesses]) {
+            if (this.workerLimit !== 0 && this.processes.length >= this.workerLimit) {
+                return;
+            }
+            if (this.processes.some((p) => p.id === pending.item.name)) {
+                continue;
+            }
+            const requests = this.budget.requestsOf(pending.item);
+            if (this.processes.length > 0 && !this.budget.fits(requests)) {
+                continue;
+            }
+            this.pendingProcesses.splice(this.pendingProcesses.indexOf(pending), 1);
+            this.startProcess(pending, requests);
+        }
+    }
+    startProcess(pendingProcess, requests = null) {
+        if (requests) {
+            this.budget?.acquire(requests);
+        }
         const item = {
             id: pendingProcess.item.name,
             promise: pendingProcess
@@ -47,6 +100,9 @@ class ProcessManager {
                 .finally(() => {
                 const index = this.processes.indexOf(item);
                 this.processes.splice(index, 1);
+                if (requests) {
+                    this.budget?.release(requests);
+                }
                 this.enqueuePendingProcesses();
             }),
         };

package/dist/executer/resource-budget.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findOversizedWork = exports.getResourceCapacity = exports.requestsEverything = exports.ResourceBudget = exports.formatAmount = exports.getRequests = exports.runsOnHost = void 0;
+const os_1 = require("os");
+const plan_work_tasks_1 = require("../planner/utils/plan-work-tasks");
+const work_resources_1 = require("../planner/work-resources");
+const execute_docker_1 = require("./execute-docker");
+const units_1 = require("../utils/units");
+const log_1 = require("../log");
+const NONE = { millicores: 0, memory: 0 };
+// Whether an item runs on the machine the run's budget covers: local tasks
+// always, containers when they run on Docker. On Kubernetes the cluster
+// schedules by requests itself, and a kubernetes service only forwards.
+function runsOnHost(item, environment) {
+    if (item.data.type === 'local-task') {
+        return true;
+    }
+    if (item.data.type === 'container-task' || item.data.type === 'container-service') {
+        return environment.type === 'docker';
+    }
+    return false;
+}
+exports.runsOnHost = runsOnHost;
+function getRequests(item, environment) {
+    const resources = 'resources' in item.data ? item.data.resources : null;
+    if (!resources || !runsOnHost(item, environment)) {
+        return NONE;
+    }
+    return {
+        millicores: Math.round((resources.requests.cpus ?? 0) * 1000),
+        memory: resources.requests.memory ?? 0,
+    };
+}
+exports.getRequests = getRequests;
+function add(a, b) {
+    return { millicores: a.millicores + b.millicores, memory: a.memory + b.memory };
+}
+function fitsIn(amount, capacity) {
+    return amount.millicores <= capacity.millicores && amount.memory <= capacity.memory;
+}
+function formatAmount(amount) {
+    return (0, work_resources_1.formatQuantities)({ cpus: amount.millicores / 1000, memory: amount.memory });
+}
+exports.formatAmount = formatAmount;
+// The requests of the work running on the host, against its capacity.
+class ResourceBudget {
+    constructor(capacity, environment) {
+        this.capacity = capacity;
+        this.environment = environment;
+        this.used = NONE;
+    }
+    requestsOf(item) {
+        return getRequests(item, this.environment);
+    }
+    fits(amount) {
+        return fitsIn(add(this.used, amount), this.capacity);
+    }
+    acquire(amount) {
+        this.used = add(this.used, amount);
+    }
+    release(amount) {
+        this.used = { millicores: this.used.millicores - amount.millicores, memory: this.used.memory - amount.memory };
+    }
+}
+exports.ResourceBudget = ResourceBudget;
+function hasRequests(workTree) {
+    const items = [...(0, plan_work_tasks_1.iterateWorkTasks)(workTree), ...(0, plan_work_tasks_1.iterateWorkServices)(workTree)];
+    return items.some((item) => {
+        const requests = getRequests(item, workTree.environment);
+        return requests.millicores > 0 || requests.memory > 0;
+    });
+}
+// Every task and container service on the host requests both cpus and
+// memory: the run is then bounded by its requests instead of a worker count.
+function requestsEverything(workTree) {
+    const items = [...(0, plan_work_tasks_1.iterateWorkTasks)(workTree), ...(0, plan_work_tasks_1.iterateWorkServices)(workTree)].filter((item) => runsOnHost(item, workTree.environment));
+    return (items.length > 0 &&
+        items.every((item) => {
+            const requests = 'resources' in item.data ? item.data.resources?.requests : null;
+            return !!requests && requests.cpus !== null && requests.memory !== null;
+        }));
+}
+exports.requestsEverything = requestsEverything;
+// What the run may request at once: HAMMERKIT_CPUS / HAMMERKIT_MEMORY when
+// set, else the Docker host's when containers run there, else this
+// machine's. Null when nothing requests resources, so such a run never asks.
+async function getResourceCapacity(workTree, environment) {
+    if (!hasRequests(workTree)) {
+        return null;
+    }
+    const capacity = await getDetectedCapacity(workTree, environment);
+    const cpus = environment.processEnvs.HAMMERKIT_CPUS;
+    const memory = environment.processEnvs.HAMMERKIT_MEMORY;
+    try {
+        return {
+            millicores: cpus ? Math.round((0, units_1.parseCpus)(cpus) * 1000) : capacity.millicores,
+            memory: memory ? (0, units_1.parseSize)(memory) : capacity.memory,
+            source: cpus || memory ? 'HAMMERKIT_CPUS/HAMMERKIT_MEMORY' : capacity.source,
+        };
+    }
+    catch (e) {
+        throw new Error(`HAMMERKIT_CPUS/HAMMERKIT_MEMORY: ${(0, log_1.getErrorMessage)(e)}`);
+    }
+}
+exports.getResourceCapacity = getResourceCapacity;
+async function getDetectedCapacity(workTree, environment) {
+    const host = { millicores: (0, os_1.cpus)().length * 1000, memory: (0, os_1.totalmem)(), source: 'this machine' };
+    const containers = [...(0, plan_work_tasks_1.iterateWorkTasks)(workTree), ...(0, plan_work_tasks_1.iterateWorkServices)(workTree)].some((item) => item.data.type !== 'local-task' && runsOnHost(item, workTree.environment));
+    if (!containers || workTree.environment.type !== 'docker') {
+        return host;
+    }
+    try {
+        const info = await (0, execute_docker_1.getContainerCli)(workTree.environment).info();
+        if (info.NCPU > 0 && info.MemTotal > 0) {
+            return { millicores: info.NCPU * 1000, memory: info.MemTotal, source: 'the docker host' };
+        }
+    }
+    catch (e) {
+        environment.status
+            .context({ type: 'cli', name: 'hammerkit' })
+            .write('debug', `unable to read the docker host's resources: ${(0, log_1.getErrorMessage)(e)}`);
+    }
+    return host;
+}
+// Everything a task has running while it runs: itself and every service it
+// needs, directly or through other services.
+function getFootprint(task, environment) {
+    const services = new Map();
+    const visit = (item) => {
+        for (const need of item.needs) {
+            if (!services.has(need.service.name)) {
+                services.set(need.service.name, need.service);
+                visit(need.service);
+            }
+        }
+    };
+    visit(task);
+    return [...services.values()].reduce((sum, service) => add(sum, getRequests(service, environment)), {
+        ...getRequests(task, environment),
+    });
+}
+// The work that can never fit, whatever runs after what: a task whose
+// requests and those of the services it needs together exceed the capacity,
+// and for `up` the services, which all run at once.
+function findOversizedWork(workTree, capacity, up) {
+    const describe = (what, amount) => `${what} request ${formatAmount(amount)} but ${capacity.source} has ${formatAmount(capacity)}`;
+    const problems = [];
+    for (const task of (0, plan_work_tasks_1.iterateWorkTasks)(workTree)) {
+        const footprint = getFootprint(task, workTree.environment);
+        if (!fitsIn(footprint, capacity)) {
+            problems.push({
+                item: task,
+                message: describe(task.needs.length > 0 ? 'the task and the services it needs' : 'the task', footprint),
+            });
+        }
+    }
+    if (up) {
+        const services = [...(0, plan_work_tasks_1.iterateWorkServices)(workTree)];
+        const total = services.reduce((sum, service) => add(sum, getRequests(service, workTree.environment)), NONE);
+        if (!fitsIn(total, capacity)) {
+            for (const service of services) {
+                problems.push({ item: service, message: describe('the services together', total) });
+            }
+        }
+    }
+    return problems;
+}
+exports.findOversizedWork = findOversizedWork;
+//# sourceMappingURL=resource-budget.js.map

package/dist/kubernetes/container-resources.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKubernetesResources = void 0;
+// A container's `resources` for its declared requests and limits; nothing
+// without, so the spec stays as before. A request beyond the cluster's
+// capacity leaves the pod Pending, which the running-state wait surfaces.
+function getKubernetesResources(resources) {
+    if (!resources) {
+        return {};
+    }
+    const requirements = {};
+    const requests = toQuantities(resources.requests);
+    const limits = toQuantities(resources.limits);
+    if (requests) {
+        requirements.requests = requests;
+    }
+    if (limits) {
+        requirements.limits = limits;
+    }
+    return { resources: requirements };
+}
+exports.getKubernetesResources = getKubernetesResources;
+function toQuantities(quantities) {
+    const result = {};
+    if (quantities.cpus !== null) {
+        result.cpu = `${Math.round(quantities.cpus * 1000)}m`;
+    }
+    if (quantities.memory !== null) {
+        result.memory = `${quantities.memory}`;
+    }
+    return Object.keys(result).length > 0 ? result : null;
+}
+//# sourceMappingURL=container-resources.js.map

package/dist/kubernetes/ensure-kubernetes-deployment-exists.js

@@ -11,6 +11,7 @@ const replace_env_variables_1 = require("../environment/replace-env-variables");
 const await_running_state_1 = require("./await-running-state");
 const resources_1 = require("./resources");
 const work_healthcheck_1 = require("../planner/work-healthcheck");
+const container_resources_1 = require("./container-resources");
 async function ensureKubernetesDeploymentExists(instance, env, service, persistence, secrets, stateKey) {
     const hostAliases = [];
     for (const need of service.needs) {
@@ -89,6 +90,7 @@ async function ensureKubernetesDeploymentExists(instance, env, service, persiste
                             })),
                             readinessProbe: probe,
                             livenessProbe: probe,
+                            ...(0, container_resources_1.getKubernetesResources)(service.data.resources),
                             volumeMounts: [...persistence.mounts.map((m) => m.mount), ...secrets.mounts],
                         },
                         {

package/dist/planner/service-definition.js

@@ -33,6 +33,8 @@ function getServiceDefinitionHash(item) {
         needs: item.needs
             .filter((need) => (0, work_service_1.isContainerWorkService)(need.service.data))
             .map((need) => `${need.name}=${getServiceDefinitionHash(need.service)}`),
+        // only when declared, so a service without keeps its hash
+        ...(service.resources ? { resources: service.resources } : {}),
     };
     return (0, crypto_1.createHash)('sha1').update(JSON.stringify(definition)).digest('hex');
 }

package/dist/planner/utils/append-work-service.js

@@ -22,6 +22,7 @@ const get_work_runtime_1 = require("./get-work-runtime");
 const resolve_cache_1 = require("../../cache/resolve-cache");
 const units_1 = require("../../utils/units");
 const log_1 = require("../../log");
+const work_resources_1 = require("../work-resources");
 function appendWorkService(workTree, service, environment, context) {
     const workService = parseService(workTree, service, environment, context);
     if (!workTree.services[workService.name]) {
@@ -114,6 +115,7 @@ function parseService(workTree, service, environment, context) {
             // set once the service is planned, see appendServiceInit
             init: null,
             secrets: (0, work_secret_1.parseWorkSecrets)(service.cwd, context.projectRoot, service.schema.secrets, envs, environment),
+            resources: (0, work_resources_1.parseWorkResources)(service.schema.resources),
         };
     }
 }
@@ -139,7 +141,8 @@ function appendServiceInit(workTree, service, item, environment, context) {
         task.needs.push({ name: item.name, service: view });
     }
     removeRequirer(item, task.name);
-    task.data.caching = { ...task.data.caching, method: 'none' };
+    // explicit, so neither the default method nor `--cache` turns it back on
+    task.data.caching = { ...task.data.caching, method: 'none', implicit: false };
     if (task.data.timeout === null) {
         task.data.timeout = getInitTimeout(undefined, environment);
     }

package/dist/planner/utils/append-work-task.js

@@ -18,6 +18,7 @@ const lazy_resolver_1 = require("../../executer/lazy-resolver");
 const get_work_runtime_1 = require("./get-work-runtime");
 const resolve_cache_1 = require("../../cache/resolve-cache");
 const units_1 = require("../../utils/units");
+const work_resources_1 = require("../work-resources");
 function appendWorkTask(workTree, cwd, referenceTask, environment, context) {
     const task = parseTask(cwd, referenceTask, environment, context);
     if (!workTree.tasks[task.name]) {
@@ -69,6 +70,7 @@ function parseTask(cwd, task, environment, context) {
         continuous: task.schema.continuous ?? false,
         timeout: task.schema.timeout ? (0, units_1.parseDuration)(task.schema.timeout) : null,
         secrets: (0, work_secret_1.parseWorkSecrets)(cwd, context.projectRoot, task.schema.secrets, envs, environment),
+        resources: (0, work_resources_1.parseWorkResources)(task.schema.resources),
     };
     if ((0, build_file_task_schema_1.isBuildFileContainerTaskSchema)(task.schema)) {
         return {

package/dist/planner/validate.js

@@ -47,6 +47,9 @@ async function* validate(workTree, context) {
         if (!task.description) {
             yield { type: 'warn', message: `missing description`, item: task };
         }
+        if (task.type === 'local-task' && task.resources) {
+            yield { type: 'warn', message: 'resources are not enforced for a local task', item: task };
+        }
         if ((!task.cmds || task.cmds.length === 0) && (!item.deps || item.deps.length === 0)) {
             yield { type: 'warn', message: `task is empty`, item: task };
         }

package/dist/planner/work-resources.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatQuantities = exports.parseWorkResources = void 0;
+const units_1 = require("../utils/units");
+function parseWorkResources(schema) {
+    if (!schema) {
+        return null;
+    }
+    const shorthand = schema.cpus !== undefined || schema.memory !== undefined;
+    const limits = parseQuantities(shorthand ? schema : schema.limits);
+    const requests = parseQuantities(schema.requests);
+    const resources = {
+        limits,
+        requests: {
+            cpus: requests.cpus ?? limits.cpus,
+            memory: requests.memory ?? limits.memory,
+        },
+    };
+    return isEmpty(resources.requests) && isEmpty(resources.limits) ? null : resources;
+}
+exports.parseWorkResources = parseWorkResources;
+function parseQuantities(schema) {
+    return {
+        cpus: schema?.cpus !== undefined ? (0, units_1.parseCpus)(schema.cpus) : null,
+        memory: schema?.memory !== undefined ? (0, units_1.parseSize)(schema.memory) : null,
+    };
+}
+function isEmpty(quantities) {
+    return quantities.cpus === null && quantities.memory === null;
+}
+function formatQuantities(quantities) {
+    return [
+        quantities.cpus !== null ? `${quantities.cpus} cpus` : null,
+        quantities.memory !== null ? `${(0, units_1.formatSize)(quantities.memory)} memory` : null,
+    ]
+        .filter((part) => part !== null)
+        .join(', ');
+}
+exports.formatQuantities = formatQuantities;
+//# sourceMappingURL=work-resources.js.map

package/dist/planner/work-runtime-kubernetes.js

@@ -25,6 +25,7 @@ const version_1 = require("../version");
 const restore_kubernetes_data_1 = require("../kubernetes/restore-kubernetes-data");
 const store_kubernetes_data_1 = require("../kubernetes/store-kubernetes-data");
 const remove_persistent_data_1 = require("../kubernetes/remove-persistent-data");
+const container_resources_1 = require("../kubernetes/container-resources");
 const secrets_1 = require("../kubernetes/secrets");
 async function listJobNames(instance, kubernetes, task) {
     const jobs = await instance.batchApi.listNamespacedJob({
@@ -117,6 +118,7 @@ function kubernetesTaskRuntime(task, kubernetes) {
                                         ],
                                         name: `cmd-${++i}`,
                                         volumeMounts: [...persistence.mounts.map((m) => m.mount), ...secrets.mounts],
+                                        ...(0, container_resources_1.getKubernetesResources)(task.data.resources),
                                     },
                                 ],
                                 volumes: [...persistence.volumes, ...secrets.volumes],

package/dist/program.js

@@ -421,7 +421,8 @@ async function getProgram(environment, argv) {
             .description('start services(s)')
             .addOption(new commander_1.Option('-f, --filter <labels...>', 'filter task and services with labels'))
             .addOption(new commander_1.Option('-e, --exclude <labels...>', 'exclude task and services with labels'))
-            .addOption(new commander_1.Option('-c, --concurrency <number>', 'parallel worker count').argParser(parseInt).default(4))
+            .addOption(new commander_1.Option('-c, --concurrency <number>', 'parallel worker count (default 4, unbounded when every task and service requests cpus and memory)').argParser(parseInt))
+            .addOption(new commander_1.Option('--skip-resource-check', 'start even when a task with its services requests more than the host has'))
             .addOption(new commander_1.Option('-w, --watch', 'watch tasks').default(false))
             .addOption(new commander_1.Option('-d, --daemon', 'run services in background').default(false))
             .addOption(new commander_1.Option('--wait <mode>', 'with --daemon, return once services are ready or once they started')
@@ -443,7 +444,8 @@ async function getProgram(environment, argv) {
                 const result = await cli.runUp({
                     cacheDefault: options.cache,
                     watch: options.watch,
-                    workers: options.concurrency,
+                    workers: options.concurrency ?? cli.defaultWorkers(),
+                    resourceCheck: !options.skipResourceCheck,
                     logMode: options.log,
                     daemon: options.daemon,
                     wait: options.wait,
@@ -493,7 +495,8 @@ async function getProgram(environment, argv) {
             .description('execute task')
             .addOption(new commander_1.Option('-f, --filter <labels...>', 'filter task and services with labels'))
             .addOption(new commander_1.Option('-e, --exclude <labels...>', 'exclude task and services with labels'))
-            .addOption(new commander_1.Option('-c, --concurrency <number>', 'parallel worker count').argParser(parseInt).default(4))
+            .addOption(new commander_1.Option('-c, --concurrency <number>', 'parallel worker count (default 4, unbounded when every task and service requests cpus and memory)').argParser(parseInt))
+            .addOption(new commander_1.Option('--skip-resource-check', 'start even when a task with its services requests more than the host has'))
             .addOption(new commander_1.Option('-w, --watch', 'watch tasks').default(false))
             .addOption(new commander_1.Option('--env <name>', 'environment'))
             .addOption(new commander_1.Option('-l, --log <mode>', 'log mode')
@@ -508,7 +511,7 @@ async function getProgram(environment, argv) {
             .addOption(new commander_1.Option('--dry-run', 'print the execution plan with predicted cache hits/misses without running').default(false))
             .addOption(new commander_1.Option('--cache-read-only', `restore from cache backends but never push to them (or set ${read_only_1.CACHE_READ_ONLY_ENV}=1)`).default(false))
             .addOption(new commander_1.Option('--timeout <duration>', 'fail tasks without their own timeout after this long (e.g. 10m)').argParser(units_1.parseDuration))
-            .addOption(new commander_1.Option('--no-skip-deps', 'run dependencies even when every task needing them is a cache hit'))
+            .addOption(new commander_1.Option('--no-skip-deps', 'run dependencies even when nothing needing them has to run'))
             .action(async (task, options) => {
             try {
                 // For machine-readable JSON, suppress the human progress logger (which
@@ -534,7 +537,8 @@ async function getProgram(environment, argv) {
                 const result = await cli.runExec({
                     cacheDefault: options.cache,
                     watch: options.watch,
-                    workers: options.concurrency,
+                    workers: options.concurrency ?? cli.defaultWorkers(),
+                    resourceCheck: !options.skipResourceCheck,
                     logMode: options.log,
                     explain: options.explain,
                     cacheReadOnly: (0, read_only_1.isCacheReadOnly)(options.cacheReadOnly, environment.processEnvs),

package/dist/schema/build-file-base-task-schema.js

@@ -10,6 +10,7 @@ const build_file_task_command_schema_1 = require("./build-file-task-command-sche
 const build_file_volume_schema_1 = require("./build-file-volume-schema");
 const duration_schema_1 = require("./duration-schema");
 const build_file_secret_schema_1 = require("./build-file-secret-schema");
+const resources_schema_1 = require("./resources-schema");
 exports.buildFileBaseTaskSchema = (0, zod_1.object)({
     deps: (0, zod_1.array)((0, zod_1.string)()).optional(),
     needs: (0, zod_1.array)(build_file_need_schema_1.buildFileNeedSchema).optional(),
@@ -29,5 +30,7 @@ exports.buildFileBaseTaskSchema = (0, zod_1.object)({
     // runs longer. Does not affect the cache key (ADR-0002).
     timeout: duration_schema_1.durationSchema.optional(),
     secrets: (0, zod_1.array)(build_file_secret_schema_1.buildFileSecretSchema).optional(),
+    // CPU and memory limits of the container; a local task is not limited
+    resources: resources_schema_1.resourcesSchema.optional(),
 });
 //# sourceMappingURL=build-file-base-task-schema.js.map

package/dist/schema/build-file-container-service-schema.js

@@ -7,6 +7,7 @@ const build_file_need_schema_1 = require("./build-file-need-schema");
 const labels_schema_1 = require("./labels-schema");
 const build_file_service_container_healthcheck_1 = require("./build-file-service-container-healthcheck");
 const build_file_secret_schema_1 = require("./build-file-secret-schema");
+const resources_schema_1 = require("./resources-schema");
 exports.buildFileContainerServiceSchema = (0, zod_1.object)({
     image: (0, zod_1.string)(),
     description: (0, zod_1.string)().optional(),
@@ -35,6 +36,7 @@ exports.buildFileContainerServiceSchema = (0, zod_1.object)({
     // passed; the service counts as ready for dependents only after it succeeded
     init: (0, zod_1.string)().describe('task run once the service is healthy, before dependents start').optional(),
     secrets: (0, zod_1.array)(build_file_secret_schema_1.buildFileSecretSchema).optional(),
+    resources: resources_schema_1.resourcesSchema.optional(),
 })
     .strict()
     .describe('container service');

package/dist/schema/resources-schema.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourcesSchema = exports.MIN_MEMORY_BYTES = void 0;
+const zod_1 = require("zod");
+const units_1 = require("../utils/units");
+// Docker refuses a container with less memory than this
+exports.MIN_MEMORY_BYTES = 6 * 1024 ** 2;
+function isCpus(value) {
+    try {
+        (0, units_1.parseCpus)(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isMemory(value) {
+    try {
+        return (0, units_1.parseSize)(value) >= exports.MIN_MEMORY_BYTES;
+    }
+    catch {
+        return false;
+    }
+}
+const cpusSchema = (0, zod_1.union)([(0, zod_1.number)(), (0, zod_1.string)()]).refine(isCpus, (value) => ({
+    message: `invalid cpus "${value}", expected cores or millicores, e.g. 2, 0.5 or 500m`,
+}));
+const memorySchema = (0, zod_1.string)().refine(isMemory, (value) => ({
+    message: `invalid memory "${value}", expected at least 6Mi, e.g. 512Mi or 2Gi`,
+}));
+const quantitiesSchema = (0, zod_1.object)({
+    cpus: cpusSchema.optional(),
+    memory: memorySchema.optional(),
+}).strict();
+// CPU and memory in Kubernetes notation: `{cpus, memory}` limits the
+// container and requests the same, `{requests, limits}` sets them apart (a
+// request without a limit is not capped). Requests are what the run schedules
+// by. Not part of the cache key (ADR-0002).
+exports.resourcesSchema = (0, zod_1.object)({
+    cpus: cpusSchema.optional(),
+    memory: memorySchema.optional(),
+    requests: quantitiesSchema.optional(),
+    limits: quantitiesSchema.optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const shorthand = value.cpus !== undefined || value.memory !== undefined;
+    if (shorthand && (value.requests || value.limits)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'set either cpus/memory or requests/limits, not both',
+        });
+        return;
+    }
+    for (const key of ['cpus', 'memory']) {
+        const request = value.requests?.[key];
+        const limit = value.limits?.[key];
+        if (request === undefined || limit === undefined || !isQuantity(key, request) || !isQuantity(key, limit)) {
+            continue;
+        }
+        if (parseQuantity(key, request) > parseQuantity(key, limit)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['requests', key],
+                message: `requested ${key} ${request} exceeds the limit ${limit}`,
+            });
+        }
+    }
+})
+    .describe('cpu and memory requests and limits');
+function isQuantity(key, value) {
+    return key === 'cpus' ? isCpus(value) : typeof value === 'string' && isMemory(value);
+}
+function parseQuantity(key, value) {
+    return key === 'cpus' ? (0, units_1.parseCpus)(value) : (0, units_1.parseSize)(`${value}`);
+}
+//# sourceMappingURL=resources-schema.js.map

package/dist/utils/units.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatSize = exports.parseSize = exports.formatDuration = exports.parseDuration = void 0;
+exports.parseCpus = exports.formatSize = exports.parseSize = exports.formatDuration = exports.parseDuration = void 0;
 const DURATION_UNITS = {
     ms: 1,
     s: 1000,
@@ -84,4 +84,17 @@ function formatSize(bytes) {
     return `${bytes}B`;
 }
 exports.formatSize = formatSize;
+// Parse a CPU quantity in Kubernetes notation, `2`, `0.5` or `500m`
+// (millicores), into cores. Kubernetes' precision is a millicore, so anything
+// finer, and zero, is rejected.
+function parseCpus(value) {
+    const text = `${value}`;
+    const match = /^(\d+(?:\.\d+)?)(m)?$/.exec(text);
+    const millicores = match ? parseFloat(match[1]) * (match[2] ? 1 : 1000) : NaN;
+    if (!Number.isInteger(millicores) || millicores <= 0) {
+        throw new Error(`invalid cpus "${text}", expected cores or millicores, e.g. 2, 0.5 or 500m`);
+    }
+    return millicores / 1000;
+}
+exports.parseCpus = parseCpus;
 //# sourceMappingURL=units.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hammerkit",
   "description": "Containerized build tool with incremental caching that runs the same build file locally, in Docker and on Kubernetes.",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "keywords": [
     "build",
     "build-tool",