open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2026-09-23 03:18:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(ql3): expose cancellation availability summary

Browse Source
This commit is contained in:
whyour
2026-08-19 08:29:45 +08:00
parent 5261c41828
commit 5a979e510e
15 changed files with 952 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/ql3-cluster-admin/src/run-management/runManagement.ts
+113
View File
@@ -13,6 +13,7 @@ import {
type BlockingCancellationDispatchResult,
type RunCancellationDispatchDiagnostic,
type RunCancellationDispatchRearmReceipt,
type RunCancellationDispatchSummary,
} from '@qinglong/cluster-postgres/run-manager';
import type { PostgresPool } from '@qinglong/runtime-core';
import { CANCELLATION_DISPATCH_BLOCKING_RESULTS } from '@qinglong/runtime-core/cancellation-dispatch';
@@ -75,6 +76,14 @@ export interface ClusterRunManagementCancellationInspectRequest {
readonly principal: Readonly<SecurityPrincipal>;
}
export interface ClusterRunManagementCancellationSummaryRequest {
readonly projectId: string;
readonly requestId: string;
readonly auditEventId: string;
readonly failureAuditEventId: string;
readonly principal: Readonly<SecurityPrincipal>;
}
export interface ClusterRunManagementCancellationRearmRequest
extends ClusterRunManagementCancellationInspectRequest {
readonly mutationId: string;
@@ -90,6 +99,9 @@ export interface ClusterRunManagementService {
stop(
request: Readonly<ClusterRunManagementStopRequest>,
): Promise<Readonly<ClusterRunCancellationResult>>;
summarizeCancellation(
request: Readonly<ClusterRunManagementCancellationSummaryRequest>,
): Promise<Readonly<RunCancellationDispatchSummary>>;
inspectCancellation(
request: Readonly<ClusterRunManagementCancellationInspectRequest>,
): Promise<Readonly<RunCancellationDispatchDiagnostic>>;
@@ -233,6 +245,28 @@ function exactCancellationInspectRequest(
}
}
function exactCancellationSummaryRequest(
value: unknown,
): asserts value is Readonly<ClusterRunManagementCancellationSummaryRequest> {
if (
!value ||
typeof value !== 'object' ||
Array.isArray(value) ||
Object.keys(value).sort().join('\0') !==
[
'auditEventId',
'failureAuditEventId',
'principal',
'projectId',
'requestId',
]
.sort()
.join('\0')
) {
throw new ClusterRunManagementRequestError();
}
}
function exactCancellationRearmRequest(
value: unknown,
): asserts value is Readonly<ClusterRunManagementCancellationRearmRequest> {
@@ -502,6 +536,85 @@ export function createClusterRunManagementService(
throw new ClusterRunManagementUnavailableError({ cause: error });
}
},
async summarizeCancellation(
requestValue: Readonly<ClusterRunManagementCancellationSummaryRequest>,
) {
exactCancellationSummaryRequest(requestValue);
const observedAtMs = now();
let principal: Readonly<SecurityPrincipal>;
if (
!Number.isSafeInteger(observedAtMs) ||
observedAtMs < 0 ||
!IDENTIFIER_PATTERN.test(requestValue.projectId) ||
!IDENTIFIER_PATTERN.test(requestValue.requestId) ||
!validUuid(requestValue.auditEventId) ||
!validUuid(requestValue.failureAuditEventId) ||
requestValue.auditEventId === requestValue.failureAuditEventId
) {
throw new ClusterRunManagementRequestError();
}
try {
principal = normalizeSecurityPrincipal(
requestValue.principal,
observedAtMs,
);
} catch {
throw new ClusterRunManagementRequestError();
}
let fence: Readonly<SecurityPolicyFence> | null = null;
try {
const decision = await policy.authorize(
principal,
requestValue.projectId,
'run.read',
);
fence = decision.fence;
if (
decision.effect !== 'allow' ||
!fence ||
fence.bindingVersion === null
) {
throw new ClusterRunManagementAuthorizationError();
}
return await cancellationDispatches.summary({
projectId: requestValue.projectId,
requestId: requestValue.requestId,
auditEventId: requestValue.auditEventId,
principal,
policyFence: fence,
});
} catch (error) {
try {
await audit.record(
normalizeSecurityAuditRecord({
eventId: requestValue.failureAuditEventId,
requestId: requestValue.requestId,
operationId: 'run.cancellation.summary',
projectId: requestValue.projectId,
subject: principal.subject,
authenticationId: principal.authenticationId,
outcome: 'denied',
reasons: [failureReason(error)],
fence,
occurredAtMs: observedAtMs,
}),
);
} catch (auditError) {
throw new ClusterRunManagementUnavailableError({ cause: auditError });
}
if (error instanceof ClusterRunManagementAuthorizationError) throw error;
if (error instanceof InvalidRunCancellationDispatchManagementError) {
throw new ClusterRunManagementRequestError();
}
if (error instanceof RunCancellationDispatchManagementConflictError) {
throw new ClusterRunManagementConflictError();
}
if (error instanceof RunCancellationDispatchManagementUnavailableError) {
throw new ClusterRunManagementUnavailableError({ cause: error });
}
throw new ClusterRunManagementUnavailableError({ cause: error });
}
},
async inspectCancellation(
requestValue: Readonly<ClusterRunManagementCancellationInspectRequest>,
) {
packages/ql3-cluster-admin/src/run-management/runManagementClient.ts
+113
View File
@@ -21,6 +21,7 @@ import {
import {
RUN_CANCELLATION_DISPATCH_DIAGNOSTIC_SCHEMA,
RUN_CANCELLATION_DISPATCH_REARM_RECEIPT_SCHEMA,
RUN_CANCELLATION_DISPATCH_SUMMARY_SCHEMA,
normalizeClusterRunManagementCommand,
type ClusterRunManagementCommand,
type ClusterRunManagementTransportResult,
@@ -115,6 +116,118 @@ export function validateClusterRunManagementClientResult(
envelope as unknown as ClusterRunManagementTransportResult,
);
}
if (command.operation === 'run.cancellation.summary') {
const envelope = exact(value, ['schemaVersion', 'operation', 'summary']);
if (
envelope.schemaVersion !== 1 ||
envelope.operation !== command.operation
) {
invalid();
}
const summary = exact(envelope.summary, [
'schema',
'projectId',
'observedAtMs',
'assessment',
'operatorAction',
'dispatches',
'signals',
'blockingResults',
...(Object.hasOwn(envelope.summary as object, 'oldestBlockedAtMs')
? ['oldestBlockedAtMs']
: []),
]);
const dispatches = exact(summary.dispatches, [
'total',
'pending',
'leased',
'retryWait',
'dispatched',
'blocked',
]);
const signals = exact(summary.signals, ['due', 'expiredLease']);
const blockingResults = exact(summary.blockingResults, [
'identityMismatch',
'pidMismatch',
'unsupported',
'invalid',
]);
const dispatchCounts = [
dispatches.total,
dispatches.pending,
dispatches.leased,
dispatches.retryWait,
dispatches.dispatched,
dispatches.blocked,
];
const blockingCounts = [
blockingResults.identityMismatch,
blockingResults.pidMismatch,
blockingResults.unsupported,
blockingResults.invalid,
];
if (
summary.schema !== RUN_CANCELLATION_DISPATCH_SUMMARY_SCHEMA ||
summary.projectId !== command.request.projectId ||
!safeInteger(summary.observedAtMs) ||
!['clear', 'converging', 'attention_required'].includes(
summary.assessment as string,
) ||
!['none', 'wait', 'inspect'].includes(summary.operatorAction as string) ||
dispatchCounts.some((count) => !safeInteger(count)) ||
!safeInteger(signals.due) ||
!safeInteger(signals.expiredLease) ||
blockingCounts.some((count) => !safeInteger(count)) ||
dispatches.total !==
(dispatches.pending as number) +
(dispatches.leased as number) +
(dispatches.retryWait as number) +
(dispatches.dispatched as number) +
(dispatches.blocked as number) ||
dispatches.blocked !==
(blockingResults.identityMismatch as number) +
(blockingResults.pidMismatch as number) +
(blockingResults.unsupported as number) +
(blockingResults.invalid as number) ||
(signals.due as number) >
(dispatches.pending as number) + (dispatches.retryWait as number) ||
(signals.expiredLease as number) > (dispatches.leased as number) ||
(Object.hasOwn(summary, 'oldestBlockedAtMs') &&
(!safeInteger(summary.oldestBlockedAtMs) ||
(summary.oldestBlockedAtMs as number) >
(summary.observedAtMs as number))) ||
((dispatches.blocked as number) === 0) !==
!Object.hasOwn(summary, 'oldestBlockedAtMs')
) {
invalid();
}
const active =
(dispatches.pending as number) +
(dispatches.leased as number) +
(dispatches.retryWait as number) +
(dispatches.blocked as number);
const expectedAssessment =
(dispatches.blocked as number) > 0
? 'attention_required'
: active > 0
? 'converging'
: 'clear';
const expectedOperatorAction =
(dispatches.blocked as number) > 0
? 'inspect'
: active > 0
? 'wait'
: 'none';
if (
summary.assessment !== expectedAssessment ||
summary.operatorAction !== expectedOperatorAction
) {
invalid();
}
return Object.freeze(
envelope as unknown as ClusterRunManagementTransportResult,
);
}
if (command.operation === 'run.cancellation.inspect') {
const envelope = exact(value, [
'schemaVersion',
packages/ql3-cluster-admin/src/run-management/runManagementTransport.ts
+77 -1
View File
@@ -22,6 +22,10 @@ const STRONG_ASSURANCES = new Set(['multi_factor', 'hardware']);
export const RUN_CANCELLATION_DISPATCH_INSPECT_REQUEST_SCHEMA =
'qinglong/run-cancellation-dispatch-inspect@v1';
export const RUN_CANCELLATION_DISPATCH_SUMMARY_REQUEST_SCHEMA =
'qinglong/run-cancellation-dispatch-summary-request@v1';
export const RUN_CANCELLATION_DISPATCH_SUMMARY_SCHEMA =
'qinglong/run-cancellation-dispatch-summary@v1';
export const RUN_CANCELLATION_DISPATCH_DIAGNOSTIC_SCHEMA =
'qinglong/run-cancellation-dispatch-diagnostic@v1';
export const RUN_CANCELLATION_DISPATCH_REARM_REQUEST_SCHEMA =
@@ -78,6 +82,20 @@ export type ClusterRunManagementCancellationInspectCommand = Readonly<{
}>;
}>;
export type ClusterRunManagementCancellationSummaryCommand = Readonly<{
schemaVersion: 1;
operation: 'run.cancellation.summary';
request: Readonly<{
projectId: string;
requestId: string;
auditEventId: string;
failureAuditEventId: string;
body: Readonly<{
schema: typeof RUN_CANCELLATION_DISPATCH_SUMMARY_REQUEST_SCHEMA;
}>;
}>;
}>;
export type ClusterRunManagementCancellationRearmCommand = Readonly<{
schemaVersion: 1;
operation: 'run.cancellation.rearm';
@@ -104,6 +122,7 @@ export type ClusterRunManagementCancellationRearmCommand = Readonly<{
export type ClusterRunManagementCommand =
| ClusterRunManagementRetryCommand
| ClusterRunManagementStopCommand
| ClusterRunManagementCancellationSummaryCommand
| ClusterRunManagementCancellationInspectCommand
| ClusterRunManagementCancellationRearmCommand;
@@ -129,6 +148,16 @@ export type ClusterRunManagementCancellationInspectTransportResult = Readonly<{
>;
}>;
export type ClusterRunManagementCancellationSummaryTransportResult = Readonly<{
schemaVersion: 1;
operation: 'run.cancellation.summary';
summary: Readonly<
Awaited<ReturnType<ClusterRunManagementService['summarizeCancellation']>> & {
schema: typeof RUN_CANCELLATION_DISPATCH_SUMMARY_SCHEMA;
}
>;
}>;
export type ClusterRunManagementCancellationRearmTransportResult = Readonly<{
schemaVersion: 1;
operation: 'run.cancellation.rearm';
@@ -142,6 +171,7 @@ export type ClusterRunManagementCancellationRearmTransportResult = Readonly<{
export type ClusterRunManagementTransportResult =
| ClusterRunManagementRetryTransportResult
| ClusterRunManagementStopTransportResult
| ClusterRunManagementCancellationSummaryTransportResult
| ClusterRunManagementCancellationInspectTransportResult
| ClusterRunManagementCancellationRearmTransportResult;
@@ -227,6 +257,7 @@ export function normalizeClusterRunManagementCommand(
if (
operation !== 'run.retry' &&
operation !== 'run.stop' &&
operation !== 'run.cancellation.summary' &&
operation !== 'run.cancellation.inspect' &&
operation !== 'run.cancellation.rearm'
) {
@@ -243,7 +274,15 @@ export function normalizeClusterRunManagementCommand(
'failureAuditEventId',
'body',
]
: [
: operation === 'run.cancellation.summary'
? [
'projectId',
'requestId',
'auditEventId',
'failureAuditEventId',
'body',
]
: [
'projectId',
'runId',
'requestId',
@@ -275,6 +314,25 @@ export function normalizeClusterRunManagementCommand(
}),
});
}
if (operation === 'run.cancellation.summary') {
const body = exact(request.body, ['schema']);
if (body.schema !== RUN_CANCELLATION_DISPATCH_SUMMARY_REQUEST_SCHEMA) {
invalid();
}
return Object.freeze({
schemaVersion: 1,
operation,
request: Object.freeze({
projectId: identifier(request.projectId),
requestId: identifier(request.requestId),
auditEventId,
failureAuditEventId,
body: Object.freeze({
schema: RUN_CANCELLATION_DISPATCH_SUMMARY_REQUEST_SCHEMA,
}),
}),
});
}
if (operation === 'run.cancellation.inspect') {
const body = exact(request.body, ['schema']);
if (body.schema !== RUN_CANCELLATION_DISPATCH_INSPECT_REQUEST_SCHEMA) {
@@ -374,6 +432,7 @@ export function createClusterRunManagementTransport(
!options.service ||
typeof options.service.retry !== 'function' ||
typeof options.service.stop !== 'function' ||
typeof options.service.summarizeCancellation !== 'function' ||
typeof options.service.inspectCancellation !== 'function' ||
typeof options.service.rearmCancellation !== 'function' ||
(options.now !== undefined && typeof options.now !== 'function')
@@ -435,6 +494,23 @@ export function createClusterRunManagementTransport(
retry: createRunManualRetryResponseBody(result),
});
}
if (command.operation === 'run.cancellation.summary') {
const result = await options.service.summarizeCancellation({
projectId: command.request.projectId,
requestId: command.request.requestId,
auditEventId: command.request.auditEventId,
failureAuditEventId: command.request.failureAuditEventId,
principal,
});
return Object.freeze({
schemaVersion: 1,
operation: command.operation,
summary: Object.freeze({
schema: RUN_CANCELLATION_DISPATCH_SUMMARY_SCHEMA,
...result,
}),
});
}
if (command.operation === 'run.cancellation.inspect') {
const result = await options.service.inspectCancellation({
projectId: command.request.projectId,