hammerkit 1.22.0 → 1.24.0

package/dist/server/runs.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unavailableExecutor = exports.RunRegistry = exports.RUN_ID_PATTERN = exports.RunError = exports.isFinal = void 0;
+const crypto_1 = require("crypto");
+const FINAL_STATES = ['succeeded', 'failed', 'cancelled', 'rejected'];
+function isFinal(state) {
+    return FINAL_STATES.includes(state);
+}
+exports.isFinal = isFinal;
+class RunError extends Error {
+}
+exports.RunError = RunError;
+exports.RUN_ID_PATTERN = /^run_[A-Za-z0-9_-]{16}$/;
+// Where runs are kept while the server is up. Everything is scoped to the
+// caller that submitted the run: the same id asked for by someone else is
+// "not found", so ids can't be used to find out which runs exist.
+class RunRegistry {
+    constructor(options) {
+        this.options = options;
+        this.entries = new Map();
+        this.queue = [];
+        this.running = 0;
+        this.closed = false;
+        this.maxConcurrent = options.maxConcurrent ?? 4;
+        this.keep = options.keep ?? 200;
+        this.maxEvents = options.maxEvents ?? 5000;
+        this.maxWaiting = options.maxWaiting ?? 100;
+        this.approvalTimeout = options.approvalTimeout ?? 60 * 60 * 1000;
+        this.now = options.now ?? Date.now;
+    }
+    // A run that needs an approval waits for it, the others are queued at once.
+    submit(owner, spec, needsApproval = false) {
+        if (this.closed) {
+            throw new RunError('the server is shutting down');
+        }
+        const waiting = needsApproval;
+        if (waiting && this.waiting().length >= this.maxWaiting) {
+            throw new RunError('too many runs are waiting for an approval');
+        }
+        const run = {
+            ...spec,
+            id: `run_${(0, crypto_1.randomBytes)(12).toString('base64url')}`,
+            owner: { iss: owner.iss, sub: owner.sub },
+            state: waiting ? 'awaiting-approval' : 'queued',
+            createdAt: this.timestamp(),
+        };
+        const entry = { run, events: [], listeners: new Set(), abort: new AbortController(), truncated: false };
+        this.entries.set(run.id, entry);
+        this.record(entry, { type: 'state', state: run.state });
+        if (waiting) {
+            run.approval = {
+                expiresAt: new Date(this.now() + this.approvalTimeout).toISOString(),
+            };
+            entry.timer = setTimeout(() => this.expire(entry), this.approvalTimeout);
+            entry.timer.unref();
+        }
+        else {
+            this.queue.push(entry);
+        }
+        this.evict();
+        // what the caller is told is the run as accepted, even when it starts at once
+        const accepted = this.copy(run);
+        this.dispatch();
+        return accepted;
+    }
+    get(owner, id) {
+        const entry = this.find(owner, id);
+        return entry ? this.copy(entry.run) : undefined;
+    }
+    // newest first
+    list(owner) {
+        return [...this.entries.values()]
+            .filter((entry) => this.owns(owner, entry))
+            .map((entry) => this.copy(entry.run))
+            .reverse();
+    }
+    // A queued run is cancelled at once; a running one when its executor stops.
+    cancel(owner, id) {
+        const entry = this.find(owner, id);
+        if (!entry) {
+            return undefined;
+        }
+        if (entry.run.state === 'queued') {
+            this.queue.splice(this.queue.indexOf(entry), 1);
+            this.finish(entry, 'cancelled');
+        }
+        else if (entry.run.state === 'awaiting-approval') {
+            this.finish(entry, 'cancelled');
+        }
+        else if (entry.run.state === 'running') {
+            entry.abort.abort();
+        }
+        return this.copy(entry.run);
+    }
+    // The runs that wait for an approval, of anybody, oldest first. Who may see
+    // them is for the caller to decide.
+    waiting() {
+        return [...this.entries.values()]
+            .filter((entry) => entry.run.state === 'awaiting-approval')
+            .map((entry) => this.copy(entry.run));
+    }
+    // One run that waits (or waited), if `canDecide` says the decider is admin of
+    // its account.
+    getForApproval(id, canDecide) {
+        const entry = this.entries.get(id);
+        if (!entry || !this.mayDecide(entry, canDecide)) {
+            return undefined;
+        }
+        return this.copy(entry.run);
+    }
+    // An approval queues the run, a rejection ends it. Nobody decides on their own run.
+    decide(decider, id, outcome, canDecide, reason) {
+        const entry = this.entries.get(id);
+        if (!entry || !this.mayDecide(entry, canDecide)) {
+            return { status: 'not-found' };
+        }
+        if (this.owns(decider, entry)) {
+            return { status: 'own-run' };
+        }
+        if (entry.run.state !== 'awaiting-approval' || !entry.run.approval) {
+            return { status: 'not-waiting', state: entry.run.state };
+        }
+        const by = { iss: decider.iss, sub: decider.sub };
+        this.record(entry, { type: 'approval', outcome, by, ...(reason ? { reason } : {}) });
+        if (outcome === 'rejected') {
+            this.finish(entry, 'rejected', `rejected by ${by.sub}${reason ? `: ${reason}` : ''}`);
+            return { status: 'ok', run: this.copy(entry.run) };
+        }
+        entry.run.approval.approvedBy = by;
+        entry.run.approval.approvedAt = this.timestamp();
+        this.clearTimer(entry);
+        entry.run.state = 'queued';
+        this.record(entry, { type: 'state', state: 'queued' });
+        this.queue.push(entry);
+        const approved = this.copy(entry.run);
+        this.dispatch();
+        return { status: 'ok', run: approved };
+    }
+    // The events after `after` (0 for all), and a way to follow new ones. The
+    // listener is not called for a run that is already over.
+    watch(owner, id, after, listener) {
+        const entry = this.find(owner, id);
+        if (!entry) {
+            return undefined;
+        }
+        const events = entry.events.filter((event) => event.seq > after);
+        const finished = FINAL_STATES.includes(entry.run.state);
+        if (!finished) {
+            entry.listeners.add(listener);
+        }
+        return { events, finished, stop: () => entry.listeners.delete(listener) };
+    }
+    // Stops accepting runs and aborts the ones in flight.
+    async close() {
+        this.closed = true;
+        for (const entry of this.queue.splice(0)) {
+            this.finish(entry, 'cancelled');
+        }
+        for (const entry of this.entries.values()) {
+            if (entry.run.state === 'awaiting-approval') {
+                this.finish(entry, 'cancelled');
+            }
+        }
+        for (const entry of this.entries.values()) {
+            if (entry.run.state === 'running') {
+                entry.abort.abort();
+            }
+        }
+        while (this.running > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    find(owner, id) {
+        const entry = this.entries.get(id);
+        return entry && this.owns(owner, entry) ? entry : undefined;
+    }
+    mayDecide(entry, canDecide) {
+        return entry.run.approval !== undefined && canDecide(entry.run.account);
+    }
+    expire(entry) {
+        if (entry.run.state === 'awaiting-approval') {
+            this.finish(entry, 'rejected', 'nobody approved it in time');
+        }
+    }
+    clearTimer(entry) {
+        if (entry.timer) {
+            clearTimeout(entry.timer);
+            entry.timer = undefined;
+        }
+    }
+    owns(owner, entry) {
+        return entry.run.owner.iss === owner.iss && entry.run.owner.sub === owner.sub;
+    }
+    copy(run) {
+        return {
+            ...run,
+            tasks: [...run.tasks],
+            definition: { ...run.definition },
+            source: { ...run.source },
+            options: JSON.parse(JSON.stringify(run.options)),
+            owner: { ...run.owner },
+            ...(run.approval ? { approval: JSON.parse(JSON.stringify(run.approval)) } : {}),
+        };
+    }
+    timestamp() {
+        return new Date(this.now()).toISOString();
+    }
+    dispatch() {
+        while (this.running < this.maxConcurrent && this.queue.length > 0) {
+            const entry = this.queue.shift();
+            this.running++;
+            this.execute(entry).finally(() => {
+                this.running--;
+                this.dispatch();
+            });
+        }
+    }
+    async execute(entry) {
+        entry.run.state = 'running';
+        entry.run.startedAt = this.timestamp();
+        this.record(entry, { type: 'state', state: 'running' });
+        try {
+            await this.options.executor.execute(this.copy(entry.run), {
+                emit: (event) => this.record(entry, event),
+                signal: entry.abort.signal,
+            });
+            this.finish(entry, entry.abort.signal.aborted ? 'cancelled' : 'succeeded');
+        }
+        catch (e) {
+            this.finish(entry, entry.abort.signal.aborted ? 'cancelled' : 'failed', entry.abort.signal.aborted ? undefined : e instanceof Error ? e.message : String(e));
+        }
+    }
+    finish(entry, state, error) {
+        this.clearTimer(entry);
+        entry.run.state = state;
+        entry.run.finishedAt = this.timestamp();
+        if (error) {
+            entry.run.error = error;
+        }
+        this.record(entry, { type: 'state', state, ...(error ? { error } : {}) }, true);
+        entry.listeners.clear();
+        this.evict();
+    }
+    record(entry, event, force = false) {
+        // an executor that keeps talking can't fill the memory of the server; the
+        // state changes, which are few, are always kept
+        if (!force && event.type !== 'state' && entry.events.length >= this.maxEvents) {
+            if (!entry.truncated) {
+                entry.truncated = true;
+                this.push(entry, { type: 'truncated' });
+            }
+            return;
+        }
+        this.push(entry, event);
+    }
+    push(entry, event) {
+        const stored = { ...event, seq: entry.events.length + 1, time: this.timestamp() };
+        entry.events.push(stored);
+        for (const listener of entry.listeners) {
+            listener(stored);
+        }
+    }
+    // Only finished runs are dropped, oldest first.
+    evict() {
+        const finished = [...this.entries.values()].filter((entry) => FINAL_STATES.includes(entry.run.state));
+        for (const entry of finished.slice(0, Math.max(0, finished.length - this.keep))) {
+            this.entries.delete(entry.run.id);
+        }
+    }
+}
+exports.RunRegistry = RunRegistry;
+// Used until a backend is wired in: runs are accepted, recorded and failed with
+// a reason, so the API can be used and tested without pretending to execute.
+exports.unavailableExecutor = {
+    async execute() {
+        throw new Error('this server has no backend that can execute runs yet');
+    },
+};
+//# sourceMappingURL=runs.js.map

package/dist/server/server-command.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerServerCommand = void 0;
+const commander_1 = require("commander");
+const log_1 = require("../log");
+const server_config_1 = require("./server-config");
+const server_1 = require("./server");
+// Runs this machine as a hammerkit server until interrupted. Like `remote`, it
+// only needs its own config file, not a build file.
+function registerServerCommand(program, environment) {
+    program
+        .command('server')
+        .description('serve this machine to remote runs (experimental)')
+        .addOption(new commander_1.Option('-c, --config <file>', 'server config file').env('HAMMERKIT_SERVER_CONFIG'))
+        .action(async (options) => {
+        try {
+            if (!options.config) {
+                throw new Error('pass the server config with --config or HAMMERKIT_SERVER_CONFIG');
+            }
+            const config = await (0, server_config_1.readServerConfig)(environment, options.config);
+            const server = await (0, server_1.startServer)(config, environment, {
+                log: (line) => environment.stdout.write(`${line}\n`),
+            });
+            environment.stdout.write(`hammerkit server listening on ${server.url}\n`);
+            await new Promise((resolve) => {
+                if (environment.abortCtrl.signal.aborted) {
+                    resolve();
+                }
+                environment.abortCtrl.signal.addEventListener('abort', () => resolve(), { once: true });
+            });
+            await server.close();
+            environment.stdout.write('hammerkit server stopped\n');
+        }
+        catch (e) {
+            if (e instanceof commander_1.CommanderError) {
+                throw e;
+            }
+            program.error(`Server was not successful: ${(0, log_1.getErrorMessage)(e)}`, { exitCode: 1 });
+        }
+    });
+}
+exports.registerServerCommand = registerServerCommand;
+//# sourceMappingURL=server-command.js.map

package/dist/server/server-config.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPlatform = exports.readServerConfig = exports.serverConfigSchema = exports.entitlementSchema = exports.definitionName = exports.issuerSchema = exports.serverPlatformSchema = void 0;
+const zod_1 = require("zod");
+const yaml_1 = require("yaml");
+const log_1 = require("../log");
+const units_1 = require("../utils/units");
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1'];
+exports.serverPlatformSchema = zod_1.z
+    .object({
+    os: zod_1.z.enum(['linux', 'macos', 'windows']),
+    arch: zod_1.z.enum(['amd64', 'arm64']),
+})
+    .strict();
+// The issuer is compared with the `iss` of a token as written, and its keys are
+// fetched from it, so it has to be https (http only for local testing).
+const issuerUrlSchema = zod_1.z.string().refine((value) => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'https:' ||
+            (url.protocol === 'http:' && LOOPBACK_HOSTS.includes(url.hostname.replace(/^\[|\]$/g, ''))));
+    }
+    catch {
+        return false;
+    }
+}, 'issuer must be an https url (http only for localhost)');
+exports.issuerSchema = zod_1.z
+    .object({
+    issuer: issuerUrlSchema,
+    audience: zod_1.z.string().min(1),
+    // the claim listing the groups of the caller
+    groupsClaim: zod_1.z.string().min(1).default('groups'),
+    // the public OAuth client `remote login` signs in with (device authorization
+    // grant); without one this issuer can only be used with a token obtained
+    // elsewhere, such as a CI job's or an agent's own
+    clientId: zod_1.z.string().min(1).optional(),
+    // what the login asks for, such as `openid api://hammerkit/.default`
+    scope: zod_1.z.string().min(1).default('openid'),
+})
+    .strict();
+// What a published build file is called: the project, as a build file author names it.
+exports.definitionName = zod_1.z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9._-]{0,63}$/i, 'use letters, digits, ".", "_" and "-", starting with a letter or digit');
+const subjectSchema = zod_1.z.object({ iss: zod_1.z.string().min(1), sub: zod_1.z.string().min(1) }).strict();
+const groupSchema = zod_1.z.object({ iss: zod_1.z.string().min(1), name: zod_1.z.string().min(1) }).strict();
+const claimsSchema = zod_1.z.object({ iss: zod_1.z.string().min(1), match: zod_1.z.record(zod_1.z.string()) }).strict();
+// Who: the person or client (`subject`), everyone in a group of an issuer
+// (`group`), or any token of an issuer whose claims match (`claims`, for CI jobs:
+// repository, ref, environment). Only validated token claims are matched.
+const whoShape = {
+    subject: subjectSchema.optional(),
+    group: groupSchema.optional(),
+    claims: claimsSchema.optional(),
+};
+function checkWho(who, ctx) {
+    const named = [who.subject, who.group, who.claims].filter((w) => w !== undefined);
+    if (named.length !== 1) {
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'name exactly one of subject, group or claims' });
+    }
+    if (who.claims && Object.keys(who.claims.match).length === 0) {
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ['claims', 'match'], message: 'match at least one claim' });
+    }
+}
+exports.entitlementSchema = zod_1.z
+    .object({
+    ...whoShape,
+    // admin: runs on these accounts at once, and approves the runs others
+    // request on them
+    accounts: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    // may request runs on these accounts, which wait until an admin of the account
+    // (someone with it in `accounts`) approves them
+    request: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+    // the build files (by name) the caller may publish, `*` for any; a separate
+    // permission from running them, so who defines work and who runs it can differ
+    publish: zod_1.z.array(zod_1.z.union([zod_1.z.literal('*'), exports.definitionName])).optional(),
+    // the build files the caller may propose a new version of: it can not run until
+    // someone who may `publish` that name approves it
+    propose: zod_1.z.array(zod_1.z.union([zod_1.z.literal('*'), exports.definitionName])).optional(),
+    // the account used when the caller names none; one of accounts or request
+    default: zod_1.z.string().min(1).optional(),
+    // where the code may come from: the caller's working tree or a git ref
+    source: zod_1.z
+        .array(zod_1.z.enum(['upload', 'ref']))
+        .min(1)
+        .optional(),
+})
+    .strict()
+    .superRefine((entitlement, ctx) => {
+    checkWho(entitlement, ctx);
+    if (entitlement.accounts.length === 0 &&
+        (entitlement.request ?? []).length === 0 &&
+        (entitlement.propose ?? []).length === 0 &&
+        (entitlement.publish ?? []).length === 0) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'name accounts to use or request, or build files to publish or propose',
+        });
+    }
+    if (entitlement.default &&
+        ![...entitlement.accounts, ...(entitlement.request ?? [])].includes(entitlement.default)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['default'],
+            message: 'default has to be one of accounts or request',
+        });
+    }
+});
+const duration = zod_1.z.string().refine((value) => {
+    try {
+        return (0, units_1.parseDuration)(value) > 0;
+    }
+    catch {
+        return false;
+    }
+}, 'expected a duration like 30m, 1h or 1d');
+// The server config is written by an operator and reviewed like code, so a typo
+// is an error and not a silently ignored key.
+exports.serverConfigSchema = zod_1.z
+    .object({
+    listen: zod_1.z
+        .object({
+        host: zod_1.z.string().min(1).default('127.0.0.1'),
+        port: zod_1.z.number().int().min(0).max(65535).default(8480),
+    })
+        .strict()
+        .default({}),
+    // paths of a certificate and key
+    tls: zod_1.z
+        .object({ cert: zod_1.z.string().min(1), key: zod_1.z.string().min(1) })
+        .strict()
+        .optional(),
+    // plain http carries OAuth tokens, so it is only accepted on the loopback
+    // interface, or when a proxy in front terminates TLS and this says so
+    behindTlsProxy: zod_1.z.boolean().default(false),
+    // the OAuth issuers whose tokens the server accepts, and the audience those
+    // tokens have to carry
+    issuers: zod_1.z.array(exports.issuerSchema).min(1, 'at least one issuer is needed, OAuth is the only way to call the server'),
+    // who may use which service account; default deny, so no entry means no account
+    entitlements: zod_1.z.array(exports.entitlementSchema).default([]),
+    approvals: zod_1.z
+        .object({
+        // how long a run waits for its approval before it is rejected
+        timeout: duration.default('1h'),
+        // runs waiting at the same time, more are refused
+        maxWaiting: zod_1.z.number().int().min(1).default(100),
+    })
+        .strict()
+        .default({}),
+    // where a run gets its code from: the repository of each build file, by its name.
+    // The caller names a branch, tag or commit of it, never a repository.
+    sources: zod_1.z
+        .record(exports.definitionName, zod_1.z
+        .object({
+        git: zod_1.z
+            .string()
+            .min(1)
+            .refine((value) => !value.startsWith('-'), 'a repository can not look like an option'),
+    })
+        .strict())
+        .default({}),
+    // where the server keeps what must survive a restart: the published build files
+    storage: zod_1.z
+        .object({ directory: zod_1.z.string().min(1).optional() })
+        .strict()
+        .default({}),
+    // limits of the run registry
+    runs: zod_1.z
+        .object({
+        // runs that execute at the same time, the others wait in queue
+        maxConcurrent: zod_1.z.number().int().min(1).default(4),
+        // finished runs that are kept for their state and logs
+        keep: zod_1.z.number().int().min(1).default(200),
+    })
+        .strict()
+        .default({}),
+    backend: zod_1.z
+        .object({
+        type: zod_1.z.literal('host'),
+        // what this machine offers; detected when left out
+        platform: exports.serverPlatformSchema.optional(),
+    })
+        .strict()
+        .default({ type: 'host' }),
+})
+    .strict()
+    .superRefine((config, ctx) => {
+    const issuers = config.issuers.map((i) => i.issuer);
+    config.entitlements.forEach((entitlement, index) => {
+        const iss = (entitlement.subject ?? entitlement.group ?? entitlement.claims)?.iss;
+        if (iss && !issuers.includes(iss)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['entitlements', index],
+                message: `issuer ${iss} is not one of the accepted issuers`,
+            });
+        }
+    });
+    if (!config.tls && !config.behindTlsProxy && !LOOPBACK_HOSTS.includes(config.listen.host)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['listen', 'host'],
+            message: `plain http on ${config.listen.host} would send tokens in the clear, set tls or behindTlsProxy: true`,
+        });
+    }
+});
+async function readServerConfig(environment, path) {
+    if (!(await environment.file.exists(path))) {
+        throw new Error(`unable to read ${path}: no such file`);
+    }
+    let raw;
+    try {
+        raw = (0, yaml_1.parse)(await environment.file.read(path));
+    }
+    catch (e) {
+        throw new Error(`unable to read ${path}: ${(0, log_1.getErrorMessage)(e)}`);
+    }
+    const result = exports.serverConfigSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const where = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+        throw new Error(`invalid ${path}: ${where}${issue.message}`);
+    }
+    return result.data;
+}
+exports.readServerConfig = readServerConfig;
+function detectPlatform() {
+    const os = { darwin: 'macos', win32: 'windows' }[process.platform] ?? 'linux';
+    const arch = process.arch === 'arm64' ? 'arm64' : 'amd64';
+    return { os, arch };
+}
+exports.detectPlatform = detectPlatform;
+//# sourceMappingURL=server-config.js.map