hammerkit 1.26.0 → 1.27.0-next.1

package/dist/server/definitions-api.js

@@ -8,45 +8,43 @@ const http_1 = require("./http");
 const oauth_1 = require("./oauth");
 const policy_1 = require("./policy");
 const proposals_1 = require("./proposals");
-const server_config_1 = require("./server-config");
 // A bundle is JSON text with escapes, so the body may be somewhat larger than the files.
 const MAX_PUBLISH_BYTES = bundle_1.MAX_BUNDLE_BYTES * 2;
 /**
- * The published build files:
+ * The published build files, each version named by its hash:
  *
- *   PUT  /v1/definitions/<name>                 publish a bundle, or propose it when the
- *                                               caller may only propose (answers 202)
- *   GET  /v1/definitions                        the names, with their latest version
- *   GET  /v1/definitions/<name>                 the versions of one
- *   GET  /v1/definitions/<name>/<hash|latest>   one version
- *   GET  /v1/definitions/<name>/<hash|latest>/files   the files of one version
- *   POST /v1/definitions/<name>/<hash>/yank     pull a version back (body: optional {reason})
- *   POST /v1/definitions/<name>/<hash>/unyank   let it go on
+ *   POST /v1/definitions                 publish a bundle, or propose it when the caller
+ *                                        may only propose (answers 202); answers its hash.
+ *                                        Beside entry and files the body may carry
+ *                                        `annotations`, which are not part of the hash
+ *   GET  /v1/definitions                 the versions, newest first; `?<key>=<value>`
+ *                                        keeps the ones with those annotations
+ *   GET  /v1/definitions/<hash>          one version
+ *   GET  /v1/definitions/<hash>/files    its files
+ *   POST /v1/definitions/<hash>/yank     pull it back (body: optional {reason})
+ *   POST /v1/definitions/<hash>/unyank   let it go on
  */
 async function handleDefinitions(config, store, proposals, log, principal, req, res, url) {
-    const match = /^\/v1\/definitions(?:\/([^/]+)(?:\/([^/]+)(\/files|\/yank|\/unyank)?)?)?$/.exec(url.pathname);
+    const match = /^\/v1\/definitions(?:\/([^/]+)(\/files|\/yank|\/unyank)?)?$/.exec(url.pathname);
     if (!match) {
         return false;
     }
-    const [, name, version, suffix] = match;
-    const files = suffix === '/files';
+    const [, hash, suffix] = match;
     const grant = (0, policy_1.getGrant)(config.entitlements, principal);
-    if (name !== undefined && !server_config_1.definitionName.safeParse(name).success) {
+    if (hash !== undefined && !bundle_1.HASH_PATTERN.test(hash)) {
         (0, http_1.send)(res, 404, { error: 'not found' });
         return true;
     }
-    if (name !== undefined && version === undefined && req.method === 'PUT') {
-        await publish(config, store, proposals, log, principal, name, req, res);
+    if (hash === undefined && req.method === 'POST') {
+        await publish(config, store, proposals, log, principal, req, res);
         return true;
     }
     if ((suffix === '/yank' || suffix === '/unyank') && req.method === 'POST') {
-        await yank(config, store, log, principal, name, version, suffix === '/unyank', req, res);
+        await yank(config, store, log, principal, hash, suffix === '/unyank', req, res);
         return true;
     }
     if (req.method !== 'GET') {
-        (0, http_1.send)(res, 405, { error: 'method not allowed' }, {
-            allow: suffix === '/yank' || suffix === '/unyank' ? 'POST' : name !== undefined && !version ? 'GET, PUT' : 'GET',
-        });
+        (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: suffix === '/yank' || suffix === '/unyank' ? 'POST' : hash === undefined ? 'GET, POST' : 'GET' });
         return true;
     }
     // what the caller may not see does not exist for them
@@ -54,25 +52,22 @@ async function handleDefinitions(config, store, proposals, log, principal, req,
         (0, http_1.send)(res, 404, { error: 'not found' });
         return true;
     }
-    if (name === undefined) {
+    if (hash === undefined) {
+        const wanted = [...url.searchParams.entries()];
         (0, http_1.send)(res, 200, {
-            definitions: store.names().map((n) => ({ name: n, latest: store.find(n, 'latest')?.hash })),
+            definitions: store
+                .list()
+                .filter((version) => wanted.every(([key, value]) => version.annotations?.[key] === value))
+                .map(toSummary),
         });
         return true;
     }
-    if (version === undefined) {
-        const versions = store.list(name);
-        versions.length > 0
-            ? (0, http_1.send)(res, 200, { name, latest: versions[0].hash, versions })
-            : (0, http_1.send)(res, 404, { error: 'not found' });
-        return true;
-    }
-    const found = version === 'latest' || bundle_1.HASH_PATTERN.test(version) ? store.find(name, version) : undefined;
+    const found = store.find(hash);
     if (!found) {
         (0, http_1.send)(res, 404, { error: 'not found' });
         return true;
     }
-    if (files) {
+    if (suffix === '/files') {
         const bundle = await store.files(found);
         bundle ? (0, http_1.send)(res, 200, bundle) : (0, http_1.send)(res, 404, { error: 'not found' });
     }
@@ -82,22 +77,38 @@ async function handleDefinitions(config, store, proposals, log, principal, req,
     return true;
 }
 exports.handleDefinitions = handleDefinitions;
+// What the list shows of a version: who published it and when, and what it runs as.
+function toSummary(version) {
+    const { hash, entry, publishedAt, publishedBy, approvedBy, annotations, tasks, services, accounts, yanked } = version;
+    return {
+        hash,
+        entry,
+        publishedAt,
+        publishedBy,
+        approvedBy,
+        annotations: annotations ?? {},
+        tasks,
+        services,
+        accounts: accounts ?? [],
+        yanked,
+    };
+}
 const yankSchema = zod_1.z.object({ reason: zod_1.z.string().max(500).optional() }).strict();
 // Yanking is allowed to who publishes the build file or uses an account the version
 // uses; letting a version go on again is the publisher's call.
-async function yank(config, store, log, principal, name, hash, undo, req, res) {
+async function yank(config, store, log, principal, hash, undo, req, res) {
     const grant = (0, policy_1.getGrant)(config.entitlements, principal);
-    const version = bundle_1.HASH_PATTERN.test(hash) ? store.find(name, hash) : undefined;
+    const version = store.find(hash);
     if (!version || !(0, policy_1.maySeeDefinitions)(grant)) {
         (0, http_1.send)(res, 404, { error: 'not found' });
         return;
     }
     if (undo ? !(0, policy_1.mayPublish)(grant) : !(0, policy_1.mayYank)(grant, version)) {
-        log(`refuse ${undo ? 'unyank' : 'yank'} ${name}@${hash} iss=${principal.iss} sub=${principal.sub}`);
+        log(`refuse ${undo ? 'unyank' : 'yank'} ${hash} iss=${principal.iss} sub=${principal.sub}`);
         (0, http_1.send)(res, 403, {
             error: undo
-                ? 'a version is let go on by who publishes the build file'
-                : 'a version is yanked by who publishes the build file or uses an account it uses',
+                ? 'a version is let go on by who publishes build files'
+                : 'a version is yanked by who publishes build files or uses an account it uses',
         });
         return;
     }
@@ -107,18 +118,28 @@ async function yank(config, store, log, principal, name, hash, undo, req, res) {
         (0, http_1.send)(res, 400, { error: `${issue.path.join('.') || 'request'}: ${issue.message}` });
         return;
     }
-    const changed = await store.yank(name, hash, principal, { reason: body.data.reason, undo });
-    log(`${undo ? 'unyank' : 'yank'} ${name}@${hash} iss=${principal.iss} sub=${principal.sub}${body.data.reason ? ` reason=${(0, oauth_1.quote)(body.data.reason)}` : ''}`);
+    const changed = await store.yank(hash, principal, { reason: body.data.reason, undo });
+    log(`${undo ? 'unyank' : 'yank'} ${hash} iss=${principal.iss} sub=${principal.sub}${body.data.reason ? ` reason=${(0, oauth_1.quote)(body.data.reason)}` : ''}`);
     (0, http_1.send)(res, 200, changed);
 }
-async function publish(config, store, proposals, log, principal, name, req, res) {
+async function publish(config, store, proposals, log, principal, req, res) {
     const grant = (0, policy_1.getGrant)(config.entitlements, principal);
     if (!(0, policy_1.mayPublish)(grant) && !(0, policy_1.mayPropose)(grant)) {
         log(`refuse publish iss=${principal.iss} sub=${principal.sub}: no builds permission`);
-        (0, http_1.send)(res, 403, { error: `you may not publish ${name}, it needs builds: propose or publish` });
+        (0, http_1.send)(res, 403, { error: 'you may not publish build files, it needs builds: propose or publish' });
+        return;
+    }
+    const body = await (0, http_1.readJson)(req, MAX_PUBLISH_BYTES);
+    // the annotations ride along with the bundle, they are not part of it
+    const { annotations: said, ...rest } = body && typeof body === 'object' ? body : {};
+    const annotated = bundle_1.annotationsSchema.optional().safeParse(said);
+    if (!annotated.success) {
+        const issue = annotated.error.issues[0];
+        (0, http_1.send)(res, 400, { error: `${['annotations', ...issue.path].join('.')}: ${issue.message}` });
         return;
     }
-    const parsed = bundle_1.bundleSchema.safeParse(await (0, http_1.readJson)(req, MAX_PUBLISH_BYTES));
+    const annotations = annotated.data;
+    const parsed = bundle_1.bundleSchema.safeParse(rest);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
         (0, http_1.send)(res, 400, { error: `${issue.path.join('.') || 'request'}: ${issue.message}` });
@@ -127,8 +148,9 @@ async function publish(config, store, proposals, log, principal, name, req, res)
     try {
         // a version can't run before it is approved, but it has to load, as it would
         // have when published, so the approver is not asked about a broken one
-        const { version, existing } = await store.prepare(name, parsed.data, principal, {
+        const { version, existing } = await store.prepare(parsed.data, principal, {
             noRemote: !(0, policy_1.mayPublish)(grant),
+            annotations,
         });
         if (existing) {
             (0, http_1.send)(res, 200, { ...existing, created: false });
@@ -138,18 +160,18 @@ async function publish(config, store, proposals, log, principal, name, req, res)
         // else proposes it, and somebody who does approves it (four eyes)
         const missing = (version.accounts ?? []).filter((account) => !(0, policy_1.canUse)(grant, account));
         if (!(0, policy_1.mayPublish)(grant) || missing.length > 0) {
-            const { proposal, created } = proposals.propose(version, parsed.data, principal, missing, store.find(name, 'latest')?.hash ?? null);
-            log(`propose ${name} ${proposal.hash} iss=${principal.iss} sub=${principal.sub} created=${created} tasks=${proposal.tasks.length} missing=[${missing.join(',')}]`);
+            const { proposal, created } = proposals.propose(version, parsed.data, principal, missing);
+            log(`propose ${proposal.hash} iss=${principal.iss} sub=${principal.sub} created=${created} tasks=${proposal.tasks.length} missing=[${missing.join(',')}]`);
             (0, http_1.send)(res, created ? 202 : 200, { ...proposal, created });
             return;
         }
-        const { version: published, created } = await store.publish(name, parsed.data, principal);
-        log(`publish ${name} ${published.hash} iss=${principal.iss} sub=${principal.sub} created=${created} tasks=${published.tasks.length}`);
+        const { version: published, created } = await store.publish(parsed.data, principal, { annotations });
+        log(`publish ${published.hash} iss=${principal.iss} sub=${principal.sub} created=${created} tasks=${published.tasks.length}`);
         (0, http_1.send)(res, created ? 201 : 200, { ...published, created });
     }
     catch (e) {
         if (e instanceof definitions_1.DefinitionError) {
-            log(`refuse publish iss=${principal.iss} sub=${principal.sub}: ${name} does not load`);
+            log(`refuse publish iss=${principal.iss} sub=${principal.sub}: the build file does not load`);
             (0, http_1.send)(res, 400, { error: `the build file does not load: ${e.message}` });
             return;
         }

package/dist/server/definitions.js

@@ -9,8 +9,10 @@ const plan_1 = require("./plan");
 var plan_2 = require("./plan");
 Object.defineProperty(exports, "DefinitionError", { enumerable: true, get: function () { return plan_2.DefinitionError; } });
 Object.defineProperty(exports, "inspectBundle", { enumerable: true, get: function () { return plan_2.inspectBundle; } });
-// The published build files: immutable versions, each named by its hash. They
-// are kept in files, so a restart doesn't forget what runs were started from.
+// The published build files: immutable versions, each named by its hash and by
+// nothing else, so whoever publishes can't make one look like the follower of
+// another. They are kept in files, so a restart doesn't forget what runs were
+// started from.
 class DefinitionStore {
     constructor(directory, 
     // the environment a build file is read with: on a server, the hosted one
@@ -22,42 +24,43 @@ class DefinitionStore {
         this.now = options.now ?? Date.now;
     }
     async load() {
-        let names = [];
+        let entries = [];
         try {
-            names = await (0, promises_1.readdir)(this.directory);
+            entries = await (0, promises_1.readdir)(this.directory);
         }
         catch {
             return; // nothing was published yet
         }
-        for (const name of names) {
-            for (const file of await (0, promises_1.readdir)((0, path_1.join)(this.directory, name))) {
-                if (!file.endsWith('.json')) {
-                    continue;
+        for (const entry of entries) {
+            const path = (0, path_1.join)(this.directory, entry);
+            if ((await (0, promises_1.stat)(path)).isDirectory()) {
+                // a name of an older server: its versions are versions like any other
+                for (const file of await (0, promises_1.readdir)(path)) {
+                    await this.read((0, path_1.join)(path, file), true);
                 }
-                const stored = JSON.parse(await (0, promises_1.readFile)((0, path_1.join)(this.directory, name, file), 'utf8'));
-                this.add(stored.version);
+            }
+            else {
+                await this.read(path, false);
             }
         }
     }
-    names() {
-        return [...this.versions.keys()].sort();
-    }
     // newest first
-    list(name) {
-        return this.has(name) ? [...this.versions.get(name)] : [];
+    list() {
+        return [...this.versions.values()]
+            .map((stored) => stored.version)
+            .sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
     }
-    // a hash, or `latest` for the version published last that is not yanked
-    find(name, hash) {
-        const versions = this.list(name);
-        return hash === 'latest' ? versions.find((v) => !v.yanked) : versions.find((v) => v.hash === hash);
+    find(hash) {
+        return this.versions.get(hash)?.version;
     }
     /**
      * Pulls a version back (or, with `undo`, lets it go on). The version is rewritten in
      * place, its files stay: a run that was started from it has them.
      */
-    async yank(name, hash, by, options = {}) {
-        const version = this.versions.get(name)?.find((v) => v.hash === hash);
-        if (!version || Boolean(version.yanked) === !options.undo) {
+    async yank(hash, by, options = {}) {
+        const stored = this.versions.get(hash);
+        const version = stored?.version;
+        if (!stored || !version || Boolean(version.yanked) === !options.undo) {
             return version;
         }
         const bundle = await this.files(version);
@@ -75,18 +78,21 @@ class DefinitionStore {
                 ...(options.reason ? { reason: options.reason } : {}),
             };
         }
-        const file = this.file(name, hash);
-        const temporary = `${file}.${(0, crypto_1.randomBytes)(8).toString('hex')}.tmp`;
-        await (0, promises_1.writeFile)(temporary, JSON.stringify({ version: next, bundle }), { flag: 'wx' });
-        await (0, promises_1.rename)(temporary, file);
+        // a version of an older server is written as `<hex>.json`, which counts over the
+        // copies it may have under several names
+        const file = this.fileOf(hash);
+        await this.write(file, next, bundle);
+        stored.file = file;
+        stored.legacy = false;
         // the same object, so whoever holds the version sees it
         Object.keys(version).forEach((key) => delete version[key]);
         Object.assign(version, next);
         return version;
     }
     async files(version) {
+        const stored = this.versions.get(version.hash);
         try {
-            return JSON.parse(await (0, promises_1.readFile)(this.file(version.name, version.hash), 'utf8')).bundle;
+            return stored ? JSON.parse(await (0, promises_1.readFile)(stored.file, 'utf8')).bundle : undefined;
         }
         catch {
             return undefined;
@@ -94,11 +100,11 @@ class DefinitionStore {
     }
     // Reads a bundle the way a run would and says what it would be as a version;
     // `existing` is the published version with the same hash, if there is one.
-    async prepare(name, bundle, publisher, 
+    async prepare(bundle, publisher, 
     // a proposal is read before anybody trusts it: it may not make the server fetch
     options = {}) {
         const hash = (0, bundle_1.hashBundle)(bundle);
-        const existing = this.find(name, hash);
+        const existing = this.find(hash);
         if (existing) {
             return { version: existing, existing };
         }
@@ -108,11 +114,13 @@ class DefinitionStore {
         });
         return {
             version: {
-                name,
                 hash,
                 entry: bundle.entry,
                 publishedAt: new Date(this.now()).toISOString(),
                 publishedBy: { iss: publisher.iss, sub: publisher.sub },
+                ...(options.annotations && Object.keys(options.annotations).length > 0
+                    ? { annotations: { ...options.annotations } }
+                    : {}),
                 tasks,
                 services,
                 inputs,
@@ -121,9 +129,11 @@ class DefinitionStore {
             },
         };
     }
-    // Publishing what already is there changes nothing and says so.
-    async publish(name, bundle, publisher, approvedBy) {
-        const prepared = await this.prepare(name, bundle, publisher);
+    // Publishing what already is there changes nothing and says so, its annotations
+    // included: they stay those of the first publish.
+    async publish(bundle, publisher, options = {}) {
+        const { approvedBy } = options;
+        const prepared = await this.prepare(bundle, publisher, { annotations: options.annotations });
         if (prepared.existing) {
             return { version: prepared.existing, created: false };
         }
@@ -132,28 +142,43 @@ class DefinitionStore {
             publishedAt: new Date(this.now()).toISOString(),
             ...(approvedBy ? { approvedBy: { iss: approvedBy.iss, sub: approvedBy.sub } } : {}),
         };
-        const file = this.file(name, version.hash);
-        await (0, promises_1.mkdir)((0, path_1.dirname)(file), { recursive: true });
-        const temporary = `${file}.${(0, crypto_1.randomBytes)(8).toString('hex')}.tmp`;
-        await (0, promises_1.writeFile)(temporary, JSON.stringify({ version, bundle }), { flag: 'wx' });
-        await (0, promises_1.rename)(temporary, file);
-        this.add(version);
+        if (!bundle_1.HASH_PATTERN.test(version.hash)) {
+            throw new plan_1.DefinitionError('invalid hash');
+        }
+        const file = this.fileOf(version.hash);
+        await (0, promises_1.mkdir)(this.directory, { recursive: true });
+        await this.write(file, version, bundle);
+        this.versions.set(version.hash, { version, file, legacy: false });
         return { version, created: true };
     }
-    has(name) {
-        return this.versions.has(name);
+    fileOf(hash) {
+        return (0, path_1.join)(this.directory, `${hash.slice('sha256:'.length)}.json`);
     }
-    add(version) {
-        const versions = this.versions.get(version.name) ?? [];
-        versions.unshift(version);
-        versions.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
-        this.versions.set(version.name, versions);
-    }
-    file(name, hash) {
-        if (!bundle_1.HASH_PATTERN.test(hash)) {
-            throw new plan_1.DefinitionError('invalid hash');
+    async read(file, legacy) {
+        if (!file.endsWith('.json')) {
+            return;
+        }
+        const { version } = JSON.parse(await (0, promises_1.readFile)(file, 'utf8'));
+        // the name an older server kept with it means nothing now
+        delete version.name;
+        const stored = this.versions.get(version.hash);
+        if (stored && !stored.legacy) {
+            return; // `<hex>.json` is what was written last
+        }
+        // published under two names, it is still one version: yanked under either name, it
+        // stays yanked, else the first one counts
+        const known = stored?.version;
+        const first = !legacy ||
+            !known ||
+            (Boolean(version.yanked) === Boolean(known.yanked) && version.publishedAt < known.publishedAt);
+        if (first || (version.yanked && !known?.yanked)) {
+            this.versions.set(version.hash, { version, file, legacy });
         }
-        return (0, path_1.join)(this.directory, name, `${hash.slice('sha256:'.length)}.json`);
+    }
+    async write(file, version, bundle) {
+        const temporary = `${file}.${(0, crypto_1.randomBytes)(8).toString('hex')}.tmp`;
+        await (0, promises_1.writeFile)(temporary, JSON.stringify({ version, bundle }), { flag: 'wx' });
+        await (0, promises_1.rename)(temporary, file);
     }
 }
 exports.DefinitionStore = DefinitionStore;