feat(ql3): add optional console run drilldown

This commit is contained in:
whyour
2026-08-20 09:23:19 +08:00
parent cf21e984cb
commit 0a5f1448f1
29 changed files with 1193 additions and 68 deletions
@@ -224,6 +224,30 @@ test('normalizes Copilot and fixed Project observation operations without arbitr
}),
{ code: 'QL3_CLUSTER_COPILOT_CONSOLE_READ_REQUEST_INVALID' },
);
assert.deepEqual(
normalizeClusterCopilotConsoleReadRequest({
schema: CLUSTER_COPILOT_CONSOLE_READ_REQUEST_SCHEMA,
operation: 'run_cancellation_status',
projectId: 'project-main',
requestId: 'console-read-status',
}),
{
schema: CLUSTER_COPILOT_CONSOLE_READ_REQUEST_SCHEMA,
operation: 'run_cancellation_status',
projectId: 'project-main',
requestId: 'console-read-status',
},
);
assert.throws(
() =>
clusterCopilotConsoleProjectReadPath({
schema: CLUSTER_COPILOT_CONSOLE_READ_REQUEST_SCHEMA,
operation: 'run_cancellation_status',
projectId: 'project-main',
requestId: 'console-read-status',
}),
{ code: 'QL3_CLUSTER_COPILOT_CONSOLE_READ_REQUEST_INVALID' },
);
assert.throws(
() =>
normalizeClusterCopilotConsoleReadRequest({
@@ -527,6 +551,72 @@ test('forwards one exact bounded Run list read and exposes no path field', async
assert.equal(Object.hasOwn(requests[0], 'url'), false);
});
test('routes only the three fixed Run management reads and validates their cursors', async (t) => {
const reads = [];
const { server, headers } = await fixture(async (read) => {
reads.push(read);
return {
schemaVersion: 1,
requestId: read.requestId,
result: { operation: read.operation },
};
});
t.after(() => server.close());
const cases = [
[
'/api/v1/run-management/cancellation-status',
{
schema: CLUSTER_COPILOT_CONSOLE_READ_REQUEST_SCHEMA,
operation: 'run_cancellation_status',
projectId: 'project-main',
requestId: 'console-status-1',
},
],
[
'/api/v1/run-management/blocked-cancellations',
{
schema: CLUSTER_COPILOT_CONSOLE_READ_REQUEST_SCHEMA,
operation: 'run_cancellation_blocked_list',
projectId: 'project-main',
requestId: 'console-blocked-1',
cursor: null,
},
],
[
'/api/v1/run-management/cancellation-inspect',
{
schema: CLUSTER_COPILOT_CONSOLE_READ_REQUEST_SCHEMA,
operation: 'run_cancellation_inspect',
projectId: 'project-main',
requestId: 'console-inspect-1',
runId: 'run-1',
},
],
];
for (const [path, body] of cases) {
const response = await request(server.origin, {
method: 'POST',
path,
headers,
body,
});
assert.equal(response.statusCode, 200);
}
assert.deepEqual(
reads,
cases.map(([, body]) => body),
);
const invalidCursor = await request(server.origin, {
method: 'POST',
path: '/api/v1/run-management/blocked-cancellations',
headers,
body: { ...cases[1][1], cursor: 'opaque-unversioned' },
});
assert.equal(invalidCursor.statusCode, 400);
assert.equal(reads.length, 3);
});
test('returns model text as JSON data only after an explicit output read', async (t) => {
const { server, headers } = await fixture(async (command) => {
assert.equal(command.operation, 'output');
@@ -34,6 +34,11 @@ const consoleOperations = [
'workflow_event_list',
'workflow_step_list',
];
const runManagementOperations = [
'run_cancellation_status',
'run_cancellation_blocked_list',
'run_cancellation_inspect',
];
function privateFile(directory, name, contents) {
const filePath = path.join(directory, name);
@@ -106,6 +111,41 @@ function get(origin) {
});
}
function post(origin, token, path, body) {
const url = new URL(origin);
const bytes = Buffer.from(JSON.stringify(body), 'utf8');
return new Promise((resolve, reject) => {
const request = httpRequest(
{
hostname: '127.0.0.1',
port: Number(url.port),
method: 'POST',
path,
agent: false,
headers: {
authorization: `QL3-Console ${token}`,
origin,
'content-type': 'application/json; charset=utf-8',
'content-length': String(bytes.byteLength),
},
},
(response) => {
const chunks = [];
response.on('data', (chunk) => chunks.push(chunk));
response.on('end', () => {
const text = Buffer.concat(chunks).toString('utf8');
resolve({
statusCode: response.statusCode,
body: JSON.parse(text),
});
});
},
);
request.once('error', reject);
request.end(bytes);
});
}
async function fixture(t) {
const directory = fs.realpathSync(
fs.mkdtempSync(path.join(os.tmpdir(), 'ql3-copilot-console-cli-')),
@@ -120,18 +160,61 @@ async function fixture(t) {
maxVersion: 'TLSv1.3',
},
(request, response) => {
requests.push({
method: request.method,
path: request.url,
authorization: request.headers.authorization,
tls: request.socket.getProtocol(),
const chunks = [];
request.on('data', (chunk) => chunks.push(chunk));
request.on('end', () => {
const command =
chunks.length === 0
? null
: JSON.parse(Buffer.concat(chunks).toString('utf8'));
requests.push({
method: request.method,
path: request.url,
authorization: request.headers.authorization,
tls: request.socket.getProtocol(),
command,
});
const body =
command?.operation === 'run.cancellation.summary'
? {
schemaVersion: 1,
requestId: command.request.requestId,
result: {
schemaVersion: 1,
operation: 'run.cancellation.summary',
summary: {
schema: 'qinglong/run-cancellation-dispatch-summary@v1',
projectId: command.request.projectId,
observedAtMs: 1_700_000_000_000,
assessment: 'attention_required',
operatorAction: 'inspect',
dispatches: {
total: 1,
pending: 0,
leased: 0,
retryWait: 0,
dispatched: 0,
blocked: 1,
},
signals: { due: 0, expiredLease: 0 },
blockingResults: {
identityMismatch: 1,
pidMismatch: 0,
unsupported: 0,
invalid: 0,
},
oldestBlockedAtMs: 1_699_999_999_000,
},
},
}
: { status: 'ready' };
const bytes = Buffer.from(JSON.stringify(body), 'utf8');
response.writeHead(200, {
'content-type': 'application/json; charset=utf-8',
'content-length': String(bytes.byteLength),
});
response.end(bytes);
});
const bytes = Buffer.from('{"status":"ready"}', 'utf8');
response.writeHead(200, {
'content-type': 'application/json; charset=utf-8',
'content-length': String(bytes.byteLength),
});
response.end(bytes);
},
);
await new Promise((resolve, reject) => {
@@ -160,14 +243,43 @@ async function fixture(t) {
requestTimeoutMs: 2_000,
}),
);
const clientCertificateFile = privateFile(
directory,
'run-client.crt',
fs.readFileSync(path.join(tlsFixture, 'client-cert.pem')),
);
const clientPrivateKeyFile = privateFile(
directory,
'run-client.key',
fs.readFileSync(path.join(tlsFixture, 'client-key.pem')),
);
const runManagementConfigFile = privateFile(
directory,
'run-client.json',
JSON.stringify({
schemaVersion: 1,
endpoint: `https://localhost:${
server.address().port
}/api/v3/runs/management`,
servername: 'localhost',
caFile,
clientCertificateFile,
clientPrivateKeyFile,
requestTimeoutMs: 2_000,
}),
);
const sessionToken = randomBytes(32).toString('base64url');
return {
requests,
configFile,
credentialFile: privateFile(directory, 'credential', credential),
sessionFile: privateFile(
sessionFile: privateFile(directory, 'session', sessionToken),
sessionToken,
runManagementConfigFile,
runManagementAssertionFile: privateFile(
directory,
'session',
randomBytes(32).toString('base64url'),
'run-assertion.jwt',
'eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiJvcGVyYXRvci0xIn0.c2lnbmF0dXJl',
),
};
}
@@ -178,6 +290,7 @@ test('CLI exposes deterministic help and a low-sensitive failure surface', async
' ql3-copilot-console --config /absolute/client.json --credential /absolute/credential --session /absolute/session [--port=0..65535]',
' ql3-copilot-console --check --config /absolute/client.json --credential /absolute/credential --session /absolute/session',
' ql3-copilot-console --container-published-loopback --port=1024..65535 --config /absolute/client.json --credential /absolute/credential --session /absolute/session [--check]',
' Optional Run reads: --run-management-config /absolute/run-client.json --run-management-assertion /absolute/assertion.jwt',
'',
'Native mode binds 127.0.0.1. Container mode requires host-loopback port publication.',
'The browser session key remains in a separate owner-private 0600 file.',
@@ -231,6 +344,7 @@ test('preflight proves private authority and unauthenticated TLS 1.3 readiness',
publishedHostAddress: '127.0.0.1',
browserCredential: 'forbidden',
clusterCredential: 'server_only',
runManagementAuthority: 'disabled',
operations: consoleOperations,
mutation: false,
});
@@ -240,10 +354,52 @@ test('preflight proves private authority and unauthenticated TLS 1.3 readiness',
path: '/readyz',
authorization: undefined,
tls: 'TLSv1.3',
command: null,
},
]);
});
test('preflight enables exactly three optional Run management reads only when both private files are explicit', async (t) => {
const value = await fixture(t);
const result = await runCli([
'--check',
'--config',
value.configFile,
'--credential',
value.credentialFile,
'--session',
value.sessionFile,
'--run-management-config',
value.runManagementConfigFile,
'--run-management-assertion',
value.runManagementAssertionFile,
]);
assert.equal(result.status, 0, result.stderr);
const fact = JSON.parse(result.stdout);
assert.equal(fact.runManagementAuthority, 'server_only');
assert.deepEqual(fact.operations, [
'inspect',
'output',
...runManagementOperations,
...consoleOperations.slice(2),
]);
assert.equal(fact.mutation, false);
assert.equal(value.requests.length, 1);
const incomplete = await runCli([
'--config',
value.configFile,
'--credential',
value.credentialFile,
'--session',
value.sessionFile,
'--run-management-config',
value.runManagementConfigFile,
]);
assert.equal(incomplete.status, 64);
assert.doesNotMatch(incomplete.stderr, /ql3-copilot-console-cli-/);
});
test('serve mode starts an ephemeral loopback origin and shuts down cleanly', async (t) => {
const value = await fixture(t);
const child = spawn(
@@ -269,6 +425,7 @@ test('serve mode starts an ephemeral loopback origin and shuts down cleanly', as
assert.match(started.origin, /^http:\/\/127\.0\.0\.1:[0-9]+$/);
assert.deepEqual(started.operations, consoleOperations);
assert.equal(started.mutation, false);
assert.equal(started.runManagementAuthority, 'disabled');
assert.equal(started.networkBoundary, 'host-loopback');
assert.equal(started.publishedHostAddress, '127.0.0.1');
const shell = await get(started.origin);
@@ -282,6 +439,66 @@ test('serve mode starts an ephemeral loopback origin and shuts down cleanly', as
assert.deepEqual(result, { status: 0, signal: null });
});
test('serve mode forwards one explicit status click through the optional mTLS Run authority', async (t) => {
const value = await fixture(t);
const child = spawn(
process.execPath,
[
cliPath,
'--config',
value.configFile,
'--credential',
value.credentialFile,
'--session',
value.sessionFile,
'--run-management-config',
value.runManagementConfigFile,
'--run-management-assertion',
value.runManagementAssertionFile,
'--port=0',
],
{ cwd: packageRoot, stdio: ['ignore', 'pipe', 'pipe'] },
);
t.after(() => {
if (child.exitCode === null && child.signalCode === null)
child.kill('SIGKILL');
});
const started = JSON.parse(await firstLine(child.stdout));
assert.equal(started.runManagementAuthority, 'server_only');
const response = await post(
started.origin,
value.sessionToken,
'/api/v1/run-management/cancellation-status',
{
schema: 'qinglong/cluster-copilot-console-read-request@v1',
operation: 'run_cancellation_status',
projectId: 'project-main',
requestId: 'console-status-1',
},
);
assert.equal(response.statusCode, 200);
assert.equal(
response.body.result.result.schema,
'qinglong/run-cancellation-status@v1',
);
assert.equal(response.body.result.result.assessment, 'attention_required');
assert.equal(response.body.result.result.operatorAction, 'inspect');
assert.equal(response.body.result.result.dispatches.blocked, 1);
const management = value.requests.find(
(request) => request.path === '/api/v3/runs/management',
);
assert.equal(management.method, 'POST');
assert.equal(management.command.operation, 'run.cancellation.summary');
assert.equal(management.command.request.requestId, 'console-status-1');
assert.match(management.authorization, /^Bearer [A-Za-z0-9_-]+\./);
child.kill('SIGTERM');
const exit = await new Promise((resolve, reject) => {
child.once('error', reject);
child.once('close', (status, signal) => resolve({ status, signal }));
});
assert.deepEqual(exit, { status: 0, signal: null });
});
test('container mode requires an explicit publish port before any authority read', async () => {
const result = await runCli([
'--container-published-loopback',
@@ -175,6 +175,64 @@ test('resets the undisclosed alias table for every bundle', async () => {
);
});
test('redacts optional Run management observations while preserving fixed availability facts', async () => {
const bundle = await createClusterConsoleEvidenceBundle(
[
{
operation: 'run_cancellation_status',
observedAtMs: 1_700_000_003_000,
request: {
schema: requestSchema,
operation: 'run_cancellation_status',
projectId: 'project-sensitive',
requestId: 'console-request-sensitive',
},
fact: {
schemaVersion: 1,
schema: 'qinglong/run-cancellation-status@v1',
component: 'qinglong3-run-management-client',
event: 'cancellation_status_observed',
requestId: 'console-request-sensitive',
projectId: 'project-sensitive',
observedAtMs: 1_700_000_003_000,
assessment: 'attention_required',
operatorAction: 'inspect',
severity: 'critical',
exitCode: 20,
dispatches: {
total: 1,
pending: 0,
leased: 0,
retryWait: 0,
dispatched: 0,
blocked: 1,
},
signals: { due: 0, expiredLease: 0 },
blockingResults: {
identityMismatch: 1,
pidMismatch: 0,
unsupported: 0,
invalid: 0,
},
oldestBlockedAtMs: 1_700_000_002_000,
},
},
],
1_700_000_004_000,
webcrypto,
);
const entry = bundle.entries[0];
assert.equal(entry.operation, 'run_cancellation_status');
assert.equal(entry.target.projectId, 'project-001');
assert.equal(entry.fact.projectId, 'project-001');
assert.equal(entry.fact.assessment, 'attention_required');
assert.equal(entry.fact.operatorAction, 'inspect');
assert.equal(entry.fact.dispatches.blocked, 1);
assert.equal(entry.fact.blockingResults.identityMismatch, 1);
assert.equal(entry.fact.component, undefined);
assert.doesNotMatch(JSON.stringify(bundle), /project-sensitive/);
});
test('fails closed on widened records, unsafe JSON and every capacity ceiling', async () => {
const error = { code: 'QL3_CLUSTER_CONSOLE_EVIDENCE_BUNDLE_INVALID' };
assert.throws(() => measureClusterConsoleEvidenceRecord(null), error);
@@ -123,6 +123,20 @@ test('cross-verifies every fixed Console read operation', async (t) => {
const requests = {
inspect: { projectId: 'p-1', requestId: 'q-1', sourceRunId: 'r-1' },
output: { projectId: 'p-2', requestId: 'q-2', sourceRunId: 'r-2' },
run_cancellation_status: {
projectId: 'p-management',
requestId: 'q-management-status',
},
run_cancellation_blocked_list: {
cursor: null,
projectId: 'p-management',
requestId: 'q-management-blocked',
},
run_cancellation_inspect: {
projectId: 'p-management',
requestId: 'q-management-inspect',
runId: 'r-management',
},
run_list: {
afterCreatedAtMs: null,
afterRunId: null,
@@ -218,7 +232,7 @@ test('cross-verifies every fixed Console read operation', async (t) => {
);
const result = verifyClusterConsoleEvidenceBundleFile(filePath);
assert.equal(result.status, 'verified');
assert.equal(result.bundle.entryCount, 13);
assert.equal(result.bundle.entryCount, 16);
});
test('CLI is secret-free on success, invalid input and usage errors', async (t) => {
@@ -0,0 +1,93 @@
'use strict';
const assert = require('node:assert/strict');
const test = require('node:test');
const {
createRunCancellationInspectionCommand,
projectRunCancellationInspection,
} = require('../dist/run-management/runCancellationInspection.js');
const uuids = [
'console-request-1',
'019f9400-0000-4000-8000-000000000001',
'019f9400-0000-4000-8000-000000000002',
];
test('creates one read-only cancellation inspection command with caller-bound request identity', () => {
let index = 0;
const command = createRunCancellationInspectionCommand(
'project-1',
'run-1',
() => uuids[index++],
);
assert.deepEqual(command, {
schemaVersion: 1,
operation: 'run.cancellation.inspect',
request: {
projectId: 'project-1',
runId: 'run-1',
requestId: 'console-request-1',
auditEventId: '019f9400-0000-4000-8000-000000000001',
failureAuditEventId: '019f9400-0000-4000-8000-000000000002',
body: {
schema: 'qinglong/run-cancellation-dispatch-inspect@v1',
},
},
});
});
test('projects a validated diagnostic without transport-only nesting', () => {
const observation = projectRunCancellationInspection({
schemaVersion: 1,
requestId: 'console-request-1',
result: {
schemaVersion: 1,
operation: 'run.cancellation.inspect',
diagnostic: {
schema: 'qinglong/run-cancellation-dispatch-diagnostic@v1',
projectId: 'project-1',
runId: 'run-1',
runStatus: 'running',
runVersion: 7,
eventSequence: 9,
cancelRequestedAtMs: 1_700_000_000_000,
cancelReason: 'user',
operatorAction: 'rearm',
dispatch: {
attemptId: 'attempt-1',
status: 'blocked',
version: 3,
dispatchCount: 2,
lastResult: 'identity_mismatch',
createdAtMs: 1_699_999_990_000,
updatedAtMs: 1_700_000_000_000,
},
},
},
});
assert.equal(observation.schema, 'qinglong/run-cancellation-inspection@v1');
assert.equal(observation.requestId, 'console-request-1');
assert.equal(observation.projectId, 'project-1');
assert.equal(observation.runId, 'run-1');
assert.equal(observation.operatorAction, 'rearm');
assert.equal(observation.dispatch.lastResult, 'identity_mismatch');
assert.equal(Object.isFrozen(observation), true);
assert.equal(Object.hasOwn(observation, 'diagnostic'), false);
});
test('rejects a non-inspection result before projection', () => {
assert.throws(
() =>
projectRunCancellationInspection({
schemaVersion: 1,
requestId: 'console-request-1',
result: {
schemaVersion: 1,
operation: 'run.cancellation.summary',
summary: {},
},
}),
/requires an inspect result/,
);
});