firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/simulation-intents.js

@@ -0,0 +1,406 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, opendir, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { withBootstrapProcessLock } from './bootstrap-process-lock.js';
+import { isNativeSetupReceipt } from '../../contracts/planning-contracts.js';
+const HASH = /^[a-f0-9]{64}$/;
+const REQUEST_PAGE_SIZE = 25;
+const ACCEPTANCE_READ_LIMIT = 25;
+const invalid = () => new CliError('simulation_intent_invalid', 'The exact saved setup request changed. It was not repeated or replaced.');
+function canonical(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isSafeInteger(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':'
+            + canonical(value[key])).join(',') + '}';
+    throw invalid();
+}
+const hash = (value) => createHash('sha256').update(canonical(value)).digest('hex');
+function keys(value, expected) {
+    return !!value && !Array.isArray(value) && typeof value === 'object'
+        && Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+function positive(value) { return Number.isSafeInteger(value) && Number(value) > 0; }
+function choice(value) {
+    if (keys(value, ['location']) && value.location === 'managed')
+        return;
+    if (keys(value, ['location', 'grant_id']) && value.location === 'local' && typeof value.grant_id === 'string') {
+        identifier(value.grant_id);
+        return;
+    }
+    throw invalid();
+}
+function bodyFor(kind, body) {
+    if (kind === 'validation') {
+        const local = body.execution_location === 'local';
+        const startup = body.validation_scope === 'target_startup_only';
+        if (!keys(body, ['configuration_revision', 'execution_location', ...(local ? ['local_grant_id'] : []),
+            ...(startup ? ['validation_scope', 'acknowledge_external_effects', 'acknowledge_startup_calls', 'world_revision', 'source_id', 'source_revision', 'startup_actor_id'] : [])])
+            || !Number.isSafeInteger(body.configuration_revision) || Number(body.configuration_revision) < 0
+            || startup && (body.acknowledge_external_effects !== true || body.acknowledge_startup_calls !== true)
+            || startup && (!positive(body.world_revision) || typeof body.source_id !== 'string'
+                || typeof body.source_revision !== 'string' || !body.source_revision.length || body.source_revision.length > 256)
+            || !['managed', 'local'].includes(String(body.execution_location)))
+            throw invalid();
+        if (local)
+            identifier(String(body.local_grant_id));
+        if (startup) {
+            identifier(String(body.source_id));
+            identifier(String(body.startup_actor_id));
+        }
+    }
+    else if (kind === 'admission') {
+        if (!keys(body, ['plan_id', 'recipe_sha256', 'usage_quote_id']) || !HASH.test(String(body.recipe_sha256)))
+            throw invalid();
+        identifier(String(body.plan_id));
+        identifier(String(body.usage_quote_id));
+    }
+    else if (kind === 'plan') {
+        if (!keys(body, ['previous_plan_id', 'world_revision', 'configuration_revision', 'selection_revision', 'evaluation_revision',
+            'share_evaluation_evidence', 'run_saved_criteria', 'selector', 'repetitions', 'parallelism', 'trial_seconds', 'execution', 'mask_browser_form_values',
+            ...('external_effects' in body ? ['external_effects'] : []), ...('record_browser' in body ? ['record_browser'] : []),
+            ...('record_voice' in body ? ['record_voice'] : []), ...('dataset_id' in body ? ['dataset_id'] : []),
+            ...('record_desktop' in body ? ['record_desktop'] : []), ...('acknowledge_desktop_screen_content' in body ? ['acknowledge_desktop_screen_content'] : []),
+            ...('share_evaluation_explanation' in body ? ['share_evaluation_explanation'] : []),
+            ...('driver_input_authorized' in body ? ['driver_input_authorized'] : []),
+            ...('driver_contract_sha256' in body ? ['driver_contract_sha256'] : []),
+            ...('application_checkpoint_id' in body ? ['application_checkpoint_id'] : []),
+            ...('acknowledge_fresh_world_state' in body ? ['acknowledge_fresh_world_state'] : []),
+            ...('share_application_checkpoint_with_device' in body ? ['share_application_checkpoint_with_device'] : []),
+            ...('coordinated_checkpoint_id' in body ? ['coordinated_checkpoint_id'] : []),
+            ...('acknowledge_supported_checkpoint_scope' in body ? ['acknowledge_supported_checkpoint_scope'] : []),
+            ...('share_coordinated_checkpoint_with_device' in body ? ['share_coordinated_checkpoint_with_device'] : []),
+            ...('share_dataset_with_device' in body ? ['share_dataset_with_device'] : [])])
+            || !positive(body.world_revision) || !Number.isSafeInteger(body.configuration_revision) || Number(body.configuration_revision) < 0
+            || !['repetitions', 'parallelism', 'trial_seconds'].every(key => positive(body[key]))
+            || typeof body.selection_revision !== 'string' || !/^[a-z0-9-]{1,128}$/.test(body.selection_revision)
+            || typeof body.evaluation_revision !== 'string' || !HASH.test(body.evaluation_revision)
+            || typeof body.share_evaluation_evidence !== 'boolean' || typeof body.run_saved_criteria !== 'boolean'
+            || 'share_evaluation_explanation' in body && typeof body.share_evaluation_explanation !== 'boolean'
+            || body.share_evaluation_explanation === true && body.share_evaluation_evidence !== true
+            || typeof body.mask_browser_form_values !== 'boolean'
+            || 'driver_input_authorized' in body && typeof body.driver_input_authorized !== 'boolean'
+            || body.driver_input_authorized === true && !HASH.test(String(body.driver_contract_sha256))
+            || body.driver_input_authorized !== true && body.driver_contract_sha256 != null
+            || 'record_browser' in body && typeof body.record_browser !== 'boolean'
+            || 'record_voice' in body && typeof body.record_voice !== 'boolean'
+            || 'record_desktop' in body && typeof body.record_desktop !== 'boolean'
+            || 'acknowledge_desktop_screen_content' in body && typeof body.acknowledge_desktop_screen_content !== 'boolean'
+            || (body.record_desktop ?? false) !== (body.acknowledge_desktop_screen_content ?? false)
+            || 'share_dataset_with_device' in body && typeof body.share_dataset_with_device !== 'boolean')
+            throw invalid();
+        if (body.previous_plan_id !== null)
+            identifier(String(body.previous_plan_id));
+        if (body.dataset_id !== undefined && body.dataset_id !== null) {
+            if (typeof body.dataset_id !== 'string')
+                throw invalid();
+            identifier(body.dataset_id);
+        }
+        choice(body.execution);
+        for (const name of ['application_checkpoint_id', 'coordinated_checkpoint_id']) {
+            if (body[name] !== undefined && body[name] !== null) {
+                if (typeof body[name] !== 'string')
+                    throw invalid();
+                identifier(body[name]);
+            }
+        }
+        for (const name of ['acknowledge_fresh_world_state', 'share_application_checkpoint_with_device',
+            'acknowledge_supported_checkpoint_scope', 'share_coordinated_checkpoint_with_device'])
+            if (name in body && typeof body[name] !== 'boolean')
+                throw invalid();
+        const app = body.application_checkpoint_id != null, paired = body.coordinated_checkpoint_id != null;
+        const local = body.execution.location === 'local';
+        if (app && paired || (app || paired) && (body.dataset_id != null || body.external_effects != null)
+            || app !== Boolean(body.acknowledge_fresh_world_state) || paired !== Boolean(body.acknowledge_supported_checkpoint_scope)
+            || body.share_application_checkpoint_with_device === true && (!app || !local)
+            || body.share_coordinated_checkpoint_with_device === true && (!paired || !local)
+            || local && app && body.share_application_checkpoint_with_device !== true
+            || local && paired && body.share_coordinated_checkpoint_with_device !== true)
+            throw invalid();
+        if ('external_effects' in body) {
+            const consent = body.external_effects;
+            if (!keys(consent, ['actor_id', 'acknowledge_effects', 'acknowledge_shared_state'])
+                || consent.acknowledge_effects !== true || consent.acknowledge_shared_state !== true || typeof consent.actor_id !== 'string')
+                throw invalid();
+            identifier(consent.actor_id);
+        }
+        const selector = body.selector;
+        if (!keys(selector, ['mode', 'query', 'ids', 'excluded']) || !['ids', 'all_matching'].includes(String(selector.mode))
+            || selector.query !== '' || !Array.isArray(selector.ids) || !Array.isArray(selector.excluded))
+            throw invalid();
+        for (const value of [...selector.ids, ...selector.excluded])
+            identifier(String(value));
+    }
+    else
+        throw invalid();
+    if (Buffer.byteLength(canonical(body)) > 2 * 1024 ** 2)
+        throw invalid();
+}
+function digest(context, kind, body) {
+    bodyFor(kind, body);
+    if (kind === 'validation' && body.validation_scope === 'target_startup_only' && body.startup_actor_id !== context.owner)
+        throw invalid();
+    if (kind === 'plan') {
+        if (body.external_effects && body.external_effects.actor_id !== context.owner)
+            throw invalid();
+        return hash({ actor_id: context.owner, data: body });
+    }
+    if (kind === 'admission')
+        return hash({ actor_id: context.owner, plan_id: body.plan_id, recipe_sha256: body.recipe_sha256 });
+    return hash({ actor_id: context.owner, configuration_revision: body.configuration_revision,
+        ...(body.validation_scope === 'target_startup_only' ? { validation_scope: body.validation_scope,
+            acknowledge_external_effects: body.acknowledge_external_effects, acknowledge_startup_calls: body.acknowledge_startup_calls,
+            world_revision: body.world_revision, source_id: body.source_id, source_revision: body.source_revision, startup_actor_id: body.startup_actor_id } : {}),
+        ...(body.execution_location === 'local' ? { execution_location: 'local', local_grant_id: body.local_grant_id } : {}) });
+}
+const prefix = (context) => `simulation-intent-${identifier(context.owner)}-${identifier(context.workspace)}-${identifier(context.world)}-`;
+const fileFor = async (context, key) => join(await privateDirectory(), prefix(context) + identifier(key) + '.json');
+async function persist(value, initial = false) {
+    const context = { ...value, prefix: '' }, path = await fileFor(context, value.key);
+    const pathToWrite = initial ? path : path + '.' + randomUUID() + '.tmp';
+    const file = await open(pathToWrite, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    if (!initial)
+        await rename(pathToWrite, path);
+}
+export async function loadIntent(context, key) {
+    const path = await fileFor(context, key), before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.mode & 0o077 || before.size > 3 * 1024 ** 2
+        || process.getuid && before.uid !== process.getuid())
+        throw invalid();
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size)
+            throw invalid();
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (value.schema !== 'firedrill.cli-simulation-intent.v1' || value.key !== identifier(key) || value.owner !== context.owner
+            || value.workspace !== context.workspace || value.world !== context.world
+            || !['dispatched', 'not_received', 'pending', 'accepted', 'withdrawn', 'admitted', 'canceled'].includes(value.state)
+            || !Number.isFinite(Date.parse(value.created_at)) || value.digest !== digest(context, value.kind, value.body))
+            throw invalid();
+        return value;
+    }
+    catch {
+        throw invalid();
+    }
+    finally {
+        await file.close();
+    }
+}
+function readPath(context, intent) {
+    return intent.kind === 'admission'
+        ? `${context.prefix}/campaign-admission?plan_id=${identifier(String(intent.body.plan_id))}&request_key=${intent.key}`
+        : `${context.prefix}/native-simulation-setup/${intent.kind}/${intent.key}`;
+}
+function match(context, intent, value) {
+    const allowed = intent.kind === 'admission' ? ['not_received', 'pending', 'admitted', 'canceled'] : ['not_received', 'pending', 'accepted', 'withdrawn'];
+    if (!value || !allowed.includes(value.state) || value.request_digest !== null && value.request_digest !== intent.digest)
+        throw invalid();
+    if (intent.kind === 'admission') {
+        if (isNativeSetupReceipt(value) || value.plan_id !== intent.body.plan_id)
+            throw invalid();
+        if (value.usage_quote_id !== null && value.usage_quote_id !== intent.body.usage_quote_id)
+            throw invalid();
+        if (value.campaign_id)
+            identifier(value.campaign_id);
+    }
+    else {
+        if (!isNativeSetupReceipt(value) || value.request_key !== intent.key || value.world_id !== context.world || value.kind !== intent.kind
+            || value.state === 'accepted' && (!value.resource_id || typeof value.resource_available !== 'boolean'))
+            throw invalid();
+        if (value.resource_id)
+            identifier(value.resource_id);
+        if (value.state === 'accepted' && value.resource_available) {
+            if (intent.kind === 'validation' && value.execution_location !== intent.body.execution_location)
+                throw invalid();
+            if (intent.kind === 'validation' && value.execution_location === 'local') {
+                if (value.local_grant_id !== intent.body.local_grant_id || !value.local_device_key)
+                    throw invalid();
+                identifier(value.local_device_key);
+            }
+            const plan = value.plan;
+            if (intent.kind === 'plan' && (!plan || plan.id !== value.resource_id || !HASH.test(plan.recipe_sha256)
+                || typeof plan.current !== 'boolean'))
+                throw invalid();
+        }
+    }
+    if (!['not_received', 'withdrawn'].includes(value.state) && !value.request_digest)
+        throw invalid();
+}
+async function record(context, intent, value) {
+    match(context, intent, value);
+    intent.state = value.state;
+    await persist(intent);
+    return value;
+}
+export async function inspectIntent(context, key, signal) {
+    const intent = await loadIntent(context, key);
+    const value = await api(readPath(context, intent), { actor: context.owner, workspace: context.workspace, signal });
+    return { intent, receipt: await record(context, intent, value) };
+}
+export async function withdrawIntent(context, key, signal) {
+    const intent = await loadIntent(context, key), auth = { actor: context.owner, workspace: context.workspace, signal };
+    let value;
+    try {
+        value = intent.kind === 'admission'
+            ? await api(`${context.prefix}/campaign-admission`, { ...auth, method: 'POST', idempotencyKey: intent.key,
+                body: { plan_id: intent.body.plan_id, action: 'cancel' } })
+            : await api(readPath(context, intent), { ...auth, method: 'DELETE' });
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || !['connection_uncertain', 'response_unavailable'].includes(error.code))
+            throw error;
+        value = await api(readPath(context, intent), auth);
+    }
+    return { intent, receipt: await record(context, intent, value) };
+}
+async function* intentKeys(context, signal) {
+    const scope = prefix(context), directory = await opendir(await privateDirectory());
+    // Directory iteration holds one batch, not the complete private history.
+    // Partial writes use .tmp names and are never accepted as request journals.
+    for await (const entry of directory) {
+        signal.throwIfAborted();
+        if (!entry.name.startsWith(scope) || !entry.name.endsWith('.json'))
+            continue;
+        const key = entry.name.slice(scope.length, -5);
+        if (!entry.isFile() || identifier(key) !== key)
+            throw invalid();
+        yield key;
+    }
+}
+export async function intentPage(context, after, signal) {
+    const cursor = after === undefined ? undefined : identifier(after);
+    const selected = [];
+    // UUID order is deliberate and stated in the response. Only the next page
+    // plus one lookahead key is retained, independent of directory entry order.
+    for await (const key of intentKeys(context, signal)) {
+        if (cursor && key <= cursor || selected.includes(key))
+            continue;
+        const position = selected.findIndex(value => key < value);
+        selected.splice(position < 0 ? selected.length : position, 0, key);
+        if (selected.length > REQUEST_PAGE_SIZE + 1)
+            selected.pop();
+    }
+    const hasMore = selected.length > REQUEST_PAGE_SIZE;
+    const results = [];
+    for (const key of selected.slice(0, REQUEST_PAGE_SIZE)) {
+        signal.throwIfAborted();
+        results.push(await inspectIntent(context, key, signal));
+    }
+    return { results, page_size: REQUEST_PAGE_SIZE, order: 'request_id',
+        next_after: hasMore ? results[results.length - 1].intent.key : null };
+}
+async function firstPendingIntent(context, signal) {
+    let acceptanceReads = 0;
+    for await (const key of intentKeys(context, signal)) {
+        const intent = await loadIntent(context, key);
+        if (['accepted', 'admitted', 'withdrawn', 'canceled'].includes(intent.state))
+            continue;
+        if (acceptanceReads >= ACCEPTANCE_READ_LIMIT) {
+            throw new CliError('simulation_intent_review_required', `More saved setup requests need a current receipt. Inspect request ${key} with firedrill simulation request status ${key}, or page firedrill simulation requests. No new request was created.`);
+        }
+        acceptanceReads += 1;
+        const current = await inspectIntent(context, key, signal);
+        if (['not_received', 'pending'].includes(current.receipt.state))
+            return current;
+    }
+    return null;
+}
+async function intentLock(context, signal, work) {
+    const lock = join(await privateDirectory(), prefix(context) + 'lock');
+    return withBootstrapProcessLock(lock, signal, work);
+}
+async function sendOriginal(context, intent, signal, output) {
+    signal.throwIfAborted();
+    try {
+        await api(intent.kind === 'validation' ? `${context.prefix}/validation` : intent.kind === 'plan' ? `${context.prefix}/simulation-plan` : `${context.prefix}/campaigns`, {
+            actor: context.owner, workspace: context.workspace, signal, method: 'POST', idempotencyKey: intent.key,
+            body: intent.kind === 'admission' ? { plan_id: intent.body.plan_id, usage_quote_id: intent.body.usage_quote_id } : intent.body
+        });
+    }
+    catch (error) {
+        // At most one original POST in this explicit command. An unknown reply only
+        // reads original acceptance; it never repeats a target or selects a new key.
+        if (signal.aborted)
+            throw error;
+        const current = await inspectIntent(context, intent.key, signal);
+        output('simulation_request_receipt', current.receipt, `Setup request ${intent.key}: ${current.receipt.state}.`);
+        if (current.receipt.state !== 'accepted' && current.receipt.state !== 'admitted')
+            throw error;
+        return current;
+    }
+    return inspectIntent(context, intent.key, signal);
+}
+export async function continueIntent(context, key, signal, output) {
+    return intentLock(context, signal, async (active) => {
+        signal = active;
+        const current = await inspectIntent(context, key, signal);
+        if (!['not_received', 'pending'].includes(current.receipt.state))
+            return current;
+        output('simulation_request', { request_key: current.intent.key, kind: current.intent.kind }, `Continuing original setup request ${current.intent.key}.`);
+        return sendOriginal(context, current.intent, signal, output);
+    });
+}
+export async function optionalIntent(context, key) {
+    try {
+        return await loadIntent(context, identifier(key));
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function createIntent(context, kind, body, signal, output, exactKey) {
+    return intentLock(context, signal, async (active) => {
+        signal = active;
+        const key = exactKey === undefined ? undefined : identifier(exactKey);
+        // Reconcile the original journal before the general unresolved-request scan.
+        // Never replace its historical body/digest or collide with its exclusive file.
+        const original = key ? await optionalIntent(context, key) : null;
+        if (original) {
+            if (original.kind !== kind || original.digest !== digest(context, kind, body))
+                throw invalid();
+            const current = await inspectIntent(context, original.key, signal);
+            if (!['not_received', 'pending'].includes(current.receipt.state))
+                return current;
+            output('simulation_request', { request_key: original.key, kind }, `Continuing original setup request ${original.key}.`);
+            return sendOriginal(context, original, signal, output);
+        }
+        const intent = { schema: 'firedrill.cli-simulation-intent.v1', owner: context.owner, workspace: context.workspace,
+            world: context.world, key: key ?? randomUUID(), kind, body, digest: digest(context, kind, body), state: 'dispatched', created_at: new Date().toISOString() };
+        // An original may have been accepted from another client or before this
+        // journal reached disk. Confirm its digest before retaining or posting.
+        const existing = key ? await api(readPath(context, intent), { actor: context.owner, workspace: context.workspace, signal }) : null;
+        if (existing)
+            match(context, intent, existing);
+        if (!existing || existing.state === 'not_received') {
+            const unresolved = await firstPendingIntent(context, signal);
+            if (unresolved)
+                throw new CliError('simulation_intent_unresolved', `Inspect, continue or withdraw setup request ${unresolved.intent.key} before creating another.`);
+        }
+        if (existing)
+            intent.state = existing.state;
+        await persist(intent, true);
+        output('simulation_request', { request_key: intent.key, kind }, `Saved setup request ${intent.key}. Recover with firedrill simulation request status ${intent.key}.`);
+        if (existing && !['not_received', 'pending'].includes(existing.state))
+            return { intent, receipt: existing };
+        return sendOriginal(context, intent, signal, output);
+    });
+}