hammerkit 1.27.0-next.13 → 1.27.0-next.15

package/dist/server/kubernetes-backend.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.awaitRunObjectsGone = exports.removeRunObjects = exports.CallerNamespaces = exports.getVolumeScope = exports.KubernetesExecutor = exports.getRunRoleBinding = exports.getNamespacePolicies = exports.getClusterAccess = exports.isCallerNamespace = exports.getCallerNamespace = void 0;
+exports.awaitRunObjectsGone = exports.removeRunObjects = exports.CallerNamespaces = exports.getVolumeScope = exports.KubernetesExecutor = exports.getRunRoleBinding = exports.removeServiceRunNamespace = exports.getServerIngressPolicy = exports.getNamespacePolicies = exports.getClusterAccess = exports.isCallerNamespace = exports.SERVICE_RUN_LABEL = exports.getServiceRunNamespace = exports.getCallerNamespace = void 0;
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -34,6 +34,19 @@ function getCallerNamespace(prefix, owner) {
     return `${prefix}${(0, crypto_1.createHash)('sha256').update(`${owner.iss}\0${owner.sub}`).digest('hex').slice(0, 16)}`;
 }
 exports.getCallerNamespace = getCallerNamespace;
+/**
+ * The namespace of a service run: one of its own, as the services stay up for hours while
+ * the caller's other runs go on in theirs (one at a time, each removing what the one
+ * before left).
+ */
+function getServiceRunNamespace(prefix, run, wakes = 0) {
+    // a woken run starts in a namespace of its own, the one it slept in may still be removed
+    const name = wakes > 0 ? `up\0${run}\0${wakes}` : `up\0${run}`;
+    return `${prefix}${(0, crypto_1.createHash)('sha256').update(name).digest('hex').slice(0, 16)}`;
+}
+exports.getServiceRunNamespace = getServiceRunNamespace;
+// the label of the namespace of a service run: the run label value of its run
+exports.SERVICE_RUN_LABEL = 'hammerkit.dev/service-run';
 // Whether a namespace is one getCallerNamespace makes with this prefix: a server named `hk`
 // passes over the namespaces of a server named `hk-test` on the same cluster.
 function isCallerNamespace(prefix, name) {
@@ -145,6 +158,64 @@ function getNamespacePolicies(namespace, deniedEgress, allowedEgress = []) {
     ];
 }
 exports.getNamespacePolicies = getNamespacePolicies;
+/**
+ * What lets the server into the namespace of a service run, to the ports of its endpoints:
+ * policies add up, so this one opens the pods to the server's namespace besides what the
+ * others let in, limited ones too.
+ */
+// The server reaches the ports of the endpoints, from its own namespace, and no other port:
+// what else the run starts (a database) stays for the pods of the run.
+function getServerIngressPolicy(namespace, server, ports) {
+    return {
+        apiVersion: 'networking.k8s.io/v1',
+        kind: 'NetworkPolicy',
+        metadata: {
+            name: 'hammerkit-server-ingress',
+            namespace,
+            annotations: { 'hammerkit.dev/version': (0, version_1.getVersion)() },
+            labels: { [MANAGED_LABEL]: 'true' },
+        },
+        spec: {
+            podSelector: {},
+            policyTypes: ['Ingress'],
+            ingress: ports.length > 0
+                ? [
+                    {
+                        _from: [{ namespaceSelector: { matchLabels: { 'kubernetes.io/metadata.name': server } } }],
+                        ports: [...new Set(ports)].map((port) => ({ protocol: 'TCP', port })),
+                    },
+                ]
+                : [],
+        },
+    };
+}
+exports.getServerIngressPolicy = getServerIngressPolicy;
+// The namespace of a service run goes with all it holds; waits up to `timeout` for it.
+async function removeServiceRunNamespace(instance, namespace, timeout) {
+    try {
+        await instance.coreApi.deleteNamespace({ name: namespace, propagationPolicy: 'Background' });
+    }
+    catch (e) {
+        if ((0, apply_1.statusCodeOf)(e) === 404) {
+            return;
+        }
+        throw e;
+    }
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        try {
+            await instance.coreApi.readNamespace({ name: namespace });
+        }
+        catch (e) {
+            if ((0, apply_1.statusCodeOf)(e) === 404) {
+                return;
+            }
+            throw e;
+        }
+        await (0, sleep_1.sleep)(1000);
+    }
+}
+exports.removeServiceRunNamespace = removeServiceRunNamespace;
 /**
  * The server's rights in a caller's namespace: the operator's ClusterRole, bound there
  * only, so the server needs no rights on Secrets or pods anywhere else.
@@ -191,6 +262,9 @@ class KubernetesExecutor {
         // the namespaces where no run of this process left anything: what a run makes goes at its
         // end, unless its release failed
         this.tidy = new Set();
+        // the namespaces of the service runs that execute, and whether those of earlier ones went
+        this.serviceRuns = new Set();
+        this.serviceRunsSwept = false;
         this.access = getClusterAccess(config.backend, processEnvs);
         this.instance = (0, kubernetes_instance_1.createKubernetesInstances)({
             type: 'kubernetes',
@@ -212,6 +286,13 @@ class KubernetesExecutor {
         this.host = new executor_1.HostExecutor({ ...options, placement: this.placement() });
     }
     async execute(run, context) {
+        if (run.up) {
+            if (run.source.type === 'sandbox') {
+                throw new Error('on a cluster a service run starts from a branch, push the sandbox and start it from there');
+            }
+            // in a namespace of its own, apart from the caller's runs and their claims
+            return this.host.execute(run, context);
+        }
         const namespace = getCallerNamespace(this.config.backend.namespacePrefix, run.owner);
         const label = (0, job_placement_1.getRunLabelValue)(run.id);
         let runs = this.active.get(namespace);
@@ -230,11 +311,15 @@ class KubernetesExecutor {
             }
         }
     }
+    namespaceOf(run) {
+        const prefix = this.config.backend.namespacePrefix;
+        return run.up ? getServiceRunNamespace(prefix, run.id, run.wakes) : getCallerNamespace(prefix, run.owner);
+    }
     // The runs of a scope share its kept claims, which one of them may change at a time:
     // what a task finds in one is what the last run left there. Without kept claims, runs
     // share no object and nothing is held.
     exclusive(run) {
-        if (this.keep === 0) {
+        if (this.keep === 0 || run.up) {
             return undefined;
         }
         return `${getCallerNamespace(this.config.backend.namespacePrefix, run.owner)}/${getVolumeScope(run)}`;
@@ -263,10 +348,25 @@ class KubernetesExecutor {
         return execution;
     }
     placement() {
-        const backend = this.config.backend;
         return {
             prepare: async (run, context, work) => {
-                const namespace = getCallerNamespace(backend.namespacePrefix, run.owner);
+                const namespace = this.namespaceOf(run);
+                if (run.up) {
+                    if (context.signal.aborted) {
+                        throw new Error('the run was cancelled');
+                    }
+                    this.serviceRuns.add(namespace);
+                    this.sweepServiceRuns();
+                    // reached by the server at the Services of its endpoints
+                    await this.namespaces.prepare(namespace, {
+                        serviceRun: (0, job_placement_1.getRunLabelValue)(run.id),
+                        server: this.namespace,
+                        ports: (run.up.endpoints ?? []).map((endpoint) => endpoint.port),
+                        quota: this.config.runs.up.quota,
+                    });
+                    context.emit({ type: 'log', task: 'hammerkit', stream: 'stdout', text: `runs in the namespace ${namespace}` });
+                    return { kubernetes: this.environmentOf(run, namespace), env: this.access.env };
+                }
                 const label = (0, job_placement_1.getRunLabelValue)(run.id);
                 await this.enqueue(namespace, async () => {
                     if (context.signal.aborted) {
@@ -294,32 +394,41 @@ class KubernetesExecutor {
                 });
                 this.sweepLeftClaims();
                 context.emit({ type: 'log', task: 'hammerkit', stream: 'stdout', text: `runs in the namespace ${namespace}` });
-                const kubernetes = {
-                    type: 'kubernetes',
-                    namespace,
-                    kubeConfig: this.access.kubeConfig,
-                    context: this.access.context,
-                    httpRoutes: [],
-                    storageClass: backend.storageClass,
-                    volumeSize: backend.volumeSize,
-                    maxVolumeSize: (0, server_config_1.getMaxVolumeSize)(backend),
-                    networkPolicyEnforced: backend.networkPolicy === 'enforced',
-                    server: {
-                        run: run.id,
-                        namespace: this.namespace,
-                        pools: backend.pools,
-                        providers: backend.providers,
-                        accounts: Object.fromEntries(Object.entries(this.config.accounts).flatMap(([name, account]) => account.kubernetes ? [[name, account.kubernetes]] : [])),
-                        ...(work?.claim
-                            ? { workspace: getWorkspace(work.root, work.claim, namespace, backend.sandboxes.runner) }
-                            : {}),
-                        ...(this.keep > 0 ? { volumeScope: getVolumeScope(run) } : {}),
-                    },
-                };
-                return { kubernetes, env: this.access.env };
+                return { kubernetes: this.environmentOf(run, namespace, work), env: this.access.env };
             },
             release: async (run, context) => {
-                const namespace = getCallerNamespace(backend.namespacePrefix, run.owner);
+                const namespace = this.namespaceOf(run);
+                if (run.up) {
+                    try {
+                        await removeServiceRunNamespace(this.instance, namespace, RELEASE_TIMEOUT);
+                    }
+                    catch (e) {
+                        // at least nothing of it runs on: its objects are the server's to remove (runRole)
+                        const forbidden = (0, apply_1.statusCodeOf)(e) === 403;
+                        const text = forbidden
+                            ? `the server may not delete the namespace ${namespace}, its ClusterRole needs delete on namespaces (see the backend docs); removing what runs in it`
+                            : `the namespace ${namespace} could not be removed: ${(0, log_1.getErrorMessage)(e)}`;
+                        this.log?.(text);
+                        context.emit({ type: 'log', task: 'hammerkit', stream: 'stderr', text });
+                        try {
+                            await removeRunObjects(this.instance, namespace, job_placement_1.RUN_LABEL, RELEASE_TIMEOUT);
+                        }
+                        catch (inner) {
+                            context.emit({
+                                type: 'log',
+                                task: 'hammerkit',
+                                stream: 'stderr',
+                                text: `what the run made in ${namespace} could not be removed: ${(0, log_1.getErrorMessage)(inner)}`,
+                            });
+                        }
+                        // the next look removes the namespace
+                        this.serviceRunsSwept = false;
+                    }
+                    finally {
+                        this.serviceRuns.delete(namespace);
+                    }
+                    return;
+                }
                 try {
                     const selector = `${job_placement_1.RUN_LABEL}=${(0, job_placement_1.getRunLabelValue)(run.id)}`;
                     await removeRunObjects(this.instance, namespace, selector, RELEASE_TIMEOUT);
@@ -352,6 +461,57 @@ class KubernetesExecutor {
             },
         };
     }
+    // The cluster as the process of a run sees it: the namespace its tasks and services go in.
+    environmentOf(run, namespace, work) {
+        const backend = this.config.backend;
+        return {
+            type: 'kubernetes',
+            namespace,
+            kubeConfig: this.access.kubeConfig,
+            context: this.access.context,
+            httpRoutes: [],
+            storageClass: backend.storageClass,
+            volumeSize: backend.volumeSize,
+            maxVolumeSize: (0, server_config_1.getMaxVolumeSize)(backend),
+            networkPolicyEnforced: backend.networkPolicy === 'enforced',
+            server: {
+                run: run.id,
+                namespace: this.namespace,
+                pools: backend.pools,
+                providers: backend.providers,
+                accounts: Object.fromEntries(Object.entries(this.config.accounts).flatMap(([name, account]) => account.kubernetes ? [[name, account.kubernetes]] : [])),
+                ...(work?.claim ? { workspace: getWorkspace(work.root, work.claim, namespace, backend.sandboxes.runner) } : {}),
+                // the claims of a service run go with its namespace
+                ...(this.keep > 0 && !run.up ? { volumeScope: getVolumeScope(run) } : {}),
+            },
+        };
+    }
+    // Once, on the first service run: the namespaces of service runs the server left when it
+    // stopped, whose services went with it
+    // Once when the server starts, and on the next service run after a namespace could not be
+    // removed: the namespaces of service runs that none of the server's runs is in, whose
+    // services went with the process of a server that stopped
+    sweepServiceRuns() {
+        if (this.serviceRunsSwept) {
+            return;
+        }
+        this.serviceRunsSwept = true;
+        Promise.resolve()
+            .then(() => this.instance.coreApi.listNamespace({ labelSelector: `${MANAGED_LABEL}=true,${exports.SERVICE_RUN_LABEL}` }))
+            .then(async (namespaces) => {
+            for (const namespace of namespaces.items) {
+                const name = namespace.metadata?.name;
+                if (name &&
+                    isCallerNamespace(this.config.backend.namespacePrefix, name) &&
+                    !this.serviceRuns.has(name) &&
+                    !namespace.metadata?.deletionTimestamp) {
+                    this.log?.(`removing the namespace ${name} of a service run from before the server started`);
+                    await removeServiceRunNamespace(this.instance, name, 0);
+                }
+            }
+        })
+            .catch((e) => this.log?.(`the namespaces of service runs could not be removed: ${(0, log_1.getErrorMessage)(e)}`));
+    }
     // The kept claims of a namespace that expired go at the soonest expiry the server knows
     // of, but those of a scope a run of the caller executes in
     sweepLater(namespace, delay) {
@@ -390,7 +550,7 @@ class KubernetesExecutor {
         }
         this.swept = true;
         Promise.resolve()
-            .then(() => this.instance.coreApi.listNamespace({ labelSelector: `${MANAGED_LABEL}=true` }))
+            .then(() => this.instance.coreApi.listNamespace({ labelSelector: `${MANAGED_LABEL}=true,!${exports.SERVICE_RUN_LABEL}` }))
             .then((namespaces) => {
             for (const namespace of namespaces.items) {
                 const name = namespace.metadata?.name;
@@ -436,7 +596,10 @@ class CallerNamespaces {
     // a namespace it did not set up in the last `NAMESPACE_SETUP_REUSE_MS` (it reads the
     // config once, at its start), so the namespace follows the config; a namespace made anew
     // since (deleted and made again) is set up again at once.
-    async prepare(namespace) {
+    async prepare(namespace, 
+    // a service run's own namespace: its label, the namespace of the server that reaches its
+    // endpoints, and its quota
+    serviceRun) {
         const backend = this.backend;
         let existing;
         try {
@@ -469,6 +632,7 @@ class CallerNamespaces {
                             labels: {
                                 [MANAGED_LABEL]: 'true',
                                 'hammerkit.dev/caller': namespace,
+                                ...(serviceRun ? { [exports.SERVICE_RUN_LABEL]: serviceRun.serviceRun } : {}),
                                 // no privileged pods, host paths or host network, whatever a build asks
                                 'pod-security.kubernetes.io/enforce': 'baseline',
                             },
@@ -486,7 +650,10 @@ class CallerNamespaces {
         const [first, ...policies] = getNamespacePolicies(namespace, backend.deniedEgress, backend.allowedEgress);
         // the API server may refuse what the binding allows for a moment after it was made
         await untilAllowed(() => (0, apply_1.replace)(this.instance, first));
-        for (const policy of policies) {
+        for (const policy of [
+            ...policies,
+            ...(serviceRun ? [getServerIngressPolicy(namespace, serviceRun.server, serviceRun.ports)] : []),
+        ]) {
             await (0, apply_1.replace)(this.instance, policy);
         }
         const metadata = {
@@ -499,7 +666,7 @@ class CallerNamespaces {
             apiVersion: 'v1',
             kind: 'ResourceQuota',
             metadata,
-            spec: { hard: backend.quota },
+            spec: { hard: serviceRun?.quota ?? backend.quota },
         };
         const defaults = backend.defaultResources;
         const limits = {
@@ -517,7 +684,7 @@ class CallerNamespaces {
             },
         };
         for (const [object, wanted] of [
-            [quota, !!backend.quota],
+            [quota, !!(serviceRun?.quota ?? backend.quota)],
             [limits, !!defaults],
         ]) {
             if (wanted) {

package/dist/server/plan.js

@@ -284,6 +284,7 @@ function toPlan(root, item) {
     const isTask = data.type === 'local-task' || data.type === 'container-task';
     return {
         kind: isTask ? 'task' : 'service',
+        ...(data.description ? { description: data.description } : {}),
         runtime: data.type === 'local-task' ? 'local' : 'docker',
         ...((0, work_task_1.isContainerWorkTask)(data) || (0, work_service_1.isContainerWorkService)(data) ? { image: data.image } : {}),
         cmds: 'cmds' in data ? data.cmds.map((cmd) => cmd.cmd) : 'cmd' in data && data.cmd ? [data.cmd.cmd] : [],

package/dist/server/policy.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decideRun = exports.sandboxRepos = exports.decideSandbox = exports.sandboxPushBranches = exports.sandboxBranchType = exports.getGrant = exports.usedAccounts = exports.mayYank = exports.canUse = exports.maySeeDefinitions = exports.mayPublish = exports.mayPropose = exports.mayRun = exports.matches = void 0;
+exports.decideRun = exports.sandboxRepos = exports.decideSandbox = exports.sandboxPushBranches = exports.sandboxBranchType = exports.endpointLevel = exports.getGrant = exports.usedAccounts = exports.mayYank = exports.canUse = exports.maySeeDefinitions = exports.mayPublish = exports.mayPropose = exports.mayRun = exports.matches = void 0;
 const repo_1 = require("./repo");
 const BUILDS_ORDER = ['run', 'propose', 'publish'];
 function matches(entitlement, principal) {
@@ -55,6 +55,7 @@ function getGrant(entitlements, principal) {
     const accounts = {};
     const repos = [];
     const sandboxes = [];
+    const endpoints = [];
     let builds = null;
     entitlements.forEach((entitlement, index) => {
         if (!matches(entitlement, principal)) {
@@ -85,10 +86,31 @@ function getGrant(entitlements, principal) {
                 known.branches[pattern] = higherType(known.branches[pattern], type);
             }
         }
+        for (const endpoint of entitlement.endpoints ?? []) {
+            const known = endpoints.find((entry) => entry.repo === endpoint.repo);
+            if (!known) {
+                endpoints.push({ ...endpoint });
+            }
+            else if (endpoint.level === 'publish') {
+                known.level = 'publish';
+            }
+        }
     });
-    return { accounts, repos, builds, sandboxes, matched };
+    return { accounts, repos, builds, sandboxes, endpoints, matched };
 }
 exports.getGrant = getGrant;
+// What the caller may do with the endpoints of service runs of a repository: the higher
+// level of the entries whose `repo` covers it, null for nothing.
+function endpointLevel(grant, repo) {
+    let found = null;
+    for (const endpoint of grant.endpoints) {
+        if ((0, repo_1.matchesRepo)(endpoint.repo, repo) && found !== 'publish') {
+            found = endpoint.level;
+        }
+    }
+    return found;
+}
+exports.endpointLevel = endpointLevel;
 const BRANCH_TYPES = ['pull', 'push'];
 function higherType(a, b) {
     return a !== undefined && BRANCH_TYPES.indexOf(a) > BRANCH_TYPES.indexOf(b) ? a : b;

package/dist/server/repo-access.js

@@ -105,6 +105,11 @@ class RepoAccess {
         env.GIT_CONFIG_GLOBAL = '/dev/null';
         return { env, values: credentials.values };
     }
+    // A secret only the server reads, as an account no caller may use: the client secret of
+    // the sign-in at endpoints, read like the credential of a source.
+    serverSecret(secret) {
+        return this.token(secret);
+    }
     async token(secret) {
         const key = `${secret.account}\0${secret.from}`;
         const known = this.tokens.get(key);

package/dist/server/run-plan.js

@@ -1,15 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.refuseArguments = exports.planRun = exports.getRunScopes = void 0;
+exports.describeArguments = exports.refuseArguments = exports.planRun = exports.getRunScopes = void 0;
 const parse_label_arguments_1 = require("../parser/parse-label-arguments");
 const plan_1 = require("./plan");
 function labels(values) {
     return values && values.length > 0 ? (0, parse_label_arguments_1.parseLabelArguments)(values) : undefined;
 }
-// The tasks in the order they were named, one scope each; by labels when none is.
+// The tasks in the order they were named, one scope each; by labels when none is. A
+// service run is one scope of its services.
 // The arguments, if any, go to the one task named (the request allows no more). That
 // task runs uncached unless the request names a `cache` method, as `run --cache` does.
-function getRunScopes(tasks, options) {
+function getRunScopes(tasks, options, services = []) {
+    if (services.length > 0) {
+        return [{ name: services.join(', '), scope: { serviceNames: services, environmentName: options.env ?? null } }];
+    }
     const args = options.args && options.args.length > 0
         ? { values: options.args, services: false, cache: options.cache !== undefined }
         : undefined;
@@ -37,7 +41,7 @@ exports.getRunScopes = getRunScopes;
  */
 async function planRun(bundle, run, environment, policy) {
     const plan = {};
-    for (const { scope } of getRunScopes(run.tasks, run.options)) {
+    for (const { scope } of getRunScopes(run.tasks, run.options, run.up?.services ?? run.services)) {
         Object.assign(plan, (await (0, plan_1.planBundle)(bundle, environment, { scope, policy })).plan);
     }
     return {
@@ -87,4 +91,34 @@ function refuseArguments(run, plan, policy = {}) {
     return null;
 }
 exports.refuseArguments = refuseArguments;
+/**
+ * For each task of a version, whether a run of it alone may pass arguments: null when it may,
+ * else why not, as {@link refuseArguments} answers a run. The plan is the one of the whole
+ * version: a task's run is the task with its dependencies and services.
+ */
+function describeArguments(plan, policy = {}) {
+    const described = {};
+    for (const [name, entry] of Object.entries(plan)) {
+        if (entry.kind !== 'task') {
+            continue;
+        }
+        const run = {};
+        const visit = (item) => {
+            if (run[item] || !plan[item]) {
+                return;
+            }
+            run[item] = plan[item];
+            for (const next of [...plan[item].deps, ...plan[item].needs]) {
+                visit(next);
+            }
+        };
+        visit(name);
+        described[name] =
+            entry.command === null
+                ? `${name} has no command to take arguments`
+                : refuseArguments({ tasks: [name], options: { args: ['-'] } }, run, policy);
+    }
+    return described;
+}
+exports.describeArguments = describeArguments;
 //# sourceMappingURL=run-plan.js.map

package/dist/server/run-request.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runRequestSchema = exports.runOptionsSchema = exports.MAX_ARGS_BYTES = exports.MAX_ARGS = void 0;
+exports.runRequestSchema = exports.runOptionsSchema = exports.MAX_ARGS_BYTES = exports.MAX_ARGS = exports.MAX_ENDPOINTS = exports.SERVICE_RUN_NAME_PATTERN = void 0;
 const zod_1 = require("zod");
 const units_1 = require("../utils/units");
 const bundle_1 = require("../remote/bundle");
 const repo_1 = require("./repo");
 const runs_1 = require("./runs");
 const name = zod_1.z.string().min(1).max(200);
+// The name of a service run, one DNS label: the hosts of its endpoints carry it, and a run of
+// the same caller with the same name replaces it
+exports.SERVICE_RUN_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$/;
+// endpoints one service run may publish
+exports.MAX_ENDPOINTS = 5;
 // what one run may pass after `--`
 exports.MAX_ARGS = 100;
 exports.MAX_ARGS_BYTES = 16 * 1024;
@@ -93,12 +98,49 @@ exports.runRequestSchema = zod_1.z
             .strict(),
     ]),
     options: exports.runOptionsSchema.default({}),
+    // a service run: these services of the build file, started as `hammerkit up` starts
+    // them and kept up until `ttl` ends or the run is cancelled, instead of tasks
+    services: zod_1.z.array(name).max(20).default([]),
+    // how long the services stay once they are ready, whether they sleep in between or not;
+    // `runs.up.ttl` when left out. At its end they are removed.
+    ttl: duration.optional(),
+    // how long the services stay up without a request to one of the endpoints, then they
+    // sleep until the next request wakes them; `runs.up.sleepTtl` when left out
+    sleepTtl: duration.optional(),
+    // a second service run of the caller with the same name replaces the first; the branch
+    // of the source when left out
+    name: zod_1.z
+        .string()
+        .regex(exports.SERVICE_RUN_NAME_PATTERN, 'expected lower case letters, digits and -, at most 40, as a DNS label')
+        .optional(),
+    // ports of the run's services published at hosts of their own, behind the server's sign-in
+    endpoints: zod_1.z
+        .array(zod_1.z.object({ service: name, port: zod_1.z.number().int().min(1).max(65535) }).strict())
+        .max(exports.MAX_ENDPOINTS)
+        .default([]),
 })
     .strict()
-    .refine((request) => request.tasks.length > 0 || (request.options.filter ?? []).length > 0, {
+    .refine((request) => request.services.length > 0 || request.tasks.length > 0 || (request.options.filter ?? []).length > 0, {
     message: 'name at least one task, or filter by labels',
     path: ['tasks'],
 })
+    .refine((request) => request.services.length === 0 || request.tasks.length === 0, {
+    message: 'a run names tasks or services, not both',
+    path: ['services'],
+})
+    .refine((request) => request.services.length === 0 ||
+    ((request.options.filter ?? []).length === 0 && (request.options.exclude ?? []).length === 0), { message: 'a service run names its services, labels do not select them', path: ['options', 'filter'] })
+    .refine((request) => request.services.length === 0 || (request.options.args ?? []).length === 0, {
+    message: 'a service run takes no arguments',
+    path: ['options', 'args'],
+})
+    .refine((request) => request.services.length > 0 ||
+    (request.ttl === undefined &&
+        request.sleepTtl === undefined &&
+        request.name === undefined &&
+        request.endpoints.length === 0), { message: 'ttl, sleepTtl, name and endpoints are for a run of services', path: ['services'] })
+    .refine((request) => new Set(request.endpoints.map((endpoint) => `${endpoint.service}:${endpoint.port}`)).size ===
+    request.endpoints.length, { message: 'an endpoint is named twice', path: ['endpoints'] })
     .refine((request) => (request.options.args ?? []).length === 0 || request.tasks.length === 1, {
     message: 'arguments go to one task, name exactly one in tasks',
     path: ['options', 'args'],