feat(ql3): establish 3.0 incubation baseline

2026-09-20 16:07:11 +08:00 · 2026-08-12 00:25:26 +08:00
parent 4bf92dcfeb
commit c699c32461
2817 changed files with 779642 additions and 653 deletions
@@ -0,0 +1,242 @@
+import path from 'path';
+import type {
+  ExecutionNumericLimit,
+  ExecutionResourcePolicy,
+  ExecutionSpec,
+} from './execution';
+import { InvalidExecutionSpecError } from './executorErrors';
+
+export const MAX_EXECUTION_TIMEOUT_MS = 7 * 24 * 60 * 60 * 1000;
+export const MAX_TERMINATION_GRACE_MS = 5 * 60 * 1000;
+export const MAX_EXECUTION_ARGUMENTS = 4096;
+export const MAX_EXECUTION_COMMAND_BYTES = 128 * 1024;
+
+function invalid(message: string): never {
+  throw new InvalidExecutionSpecError(message);
+}
+
+function assertNonEmptyIdentifier(value: string, name: string): void {
+  if (
+    typeof value !== 'string' ||
+    value.length < 1 ||
+    value.length > 255 ||
+    /[\u0000-\u001f\u007f]/.test(value)
+  ) {
+    invalid(
+      `${name} must be between 1 and 255 characters and contain no control characters`,
+    );
+  }
+}
+
+function assertSafeDuration(
+  value: number,
+  name: string,
+  maximum: number,
+  allowZero: boolean,
+): void {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < (allowZero ? 0 : 1) ||
+    value > maximum
+  ) {
+    invalid(
+      `${name} must be a safe integer between ${
+        allowZero ? 0 : 1
+      } and ${maximum}`,
+    );
+  }
+}
+
+function assertEnforcement(
+  value: unknown,
+  name: string,
+): asserts value is 'required' | 'best_effort' {
+  if (value !== 'required' && value !== 'best_effort') {
+    invalid(`${name} enforcement is invalid`);
+  }
+}
+
+function assertNumericLimit(
+  value: ExecutionNumericLimit | undefined,
+  name: string,
+): void {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    invalid(`${name} must be an object`);
+  }
+  if (!Number.isSafeInteger(value.value) || value.value < 1) {
+    invalid(`${name} must be a positive safe integer`);
+  }
+  assertEnforcement(value.enforcement, name);
+}
+
+function assertResourcePolicy(
+  policy: ExecutionResourcePolicy | undefined,
+): void {
+  if (policy === undefined) return;
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+    invalid('resourcePolicy must be an object');
+  }
+  assertNumericLimit(policy.memoryBytes, 'memoryBytes');
+  assertNumericLimit(policy.cpuMillisPerSecond, 'cpuMillisPerSecond');
+  if (policy.filesystemIsolation !== undefined) {
+    assertEnforcement(policy.filesystemIsolation, 'filesystemIsolation');
+  }
+  if (policy.networkIsolation !== undefined) {
+    assertEnforcement(policy.networkIsolation, 'networkIsolation');
+  }
+}
+
+function commandSize(spec: ExecutionSpec): number {
+  if (spec.command.kind === 'shell') {
+    return Buffer.byteLength(spec.command.command, 'utf8');
+  }
+  return (
+    Buffer.byteLength(spec.command.file, 'utf8') +
+    spec.command.args.reduce(
+      (total, argument) => total + Buffer.byteLength(argument, 'utf8'),
+      0,
+    )
+  );
+}
+
+export function assertExecutionSpec(spec: ExecutionSpec): void {
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+    invalid('ExecutionSpec must be an object');
+  }
+  assertNonEmptyIdentifier(spec.runId, 'runId');
+  assertNonEmptyIdentifier(spec.attemptId, 'attemptId');
+  assertNonEmptyIdentifier(spec.projectId, 'projectId');
+  assertNonEmptyIdentifier(spec.taskId, 'taskId');
+  assertNonEmptyIdentifier(spec.taskRevision, 'taskRevision');
+  assertSafeDuration(
+    spec.terminationGraceMs,
+    'terminationGraceMs',
+    MAX_TERMINATION_GRACE_MS,
+    true,
+  );
+  if (spec.timeoutMs !== undefined) {
+    assertSafeDuration(
+      spec.timeoutMs,
+      'timeoutMs',
+      MAX_EXECUTION_TIMEOUT_MS,
+      false,
+    );
+  }
+  if (
+    spec.environmentPolicy !== 'inherit' &&
+    spec.environmentPolicy !== 'isolated'
+  ) {
+    invalid('environmentPolicy is invalid');
+  }
+  if (
+    spec.workingDirectory !== undefined &&
+    (typeof spec.workingDirectory !== 'string' ||
+      spec.workingDirectory.includes('\0') ||
+      !path.isAbsolute(spec.workingDirectory))
+  ) {
+    invalid('workingDirectory must be an absolute path containing no NUL');
+  }
+  if (!spec.command || typeof spec.command !== 'object') {
+    invalid('command must be an object');
+  }
+  if (spec.command.kind === 'argv') {
+    if (
+      typeof spec.command.file !== 'string' ||
+      !spec.command.file ||
+      spec.command.file.includes('\0')
+    ) {
+      invalid('argv command file must be non-empty and contain no NUL');
+    }
+    if (!Array.isArray(spec.command.args)) {
+      invalid('argv command args must be an array');
+    }
+    if (spec.command.args.length > MAX_EXECUTION_ARGUMENTS) {
+      invalid('argv command has too many arguments');
+    }
+    if (
+      spec.command.args.some(
+        (argument) => typeof argument !== 'string' || argument.includes('\0'),
+      )
+    ) {
+      invalid('argv command arguments must be strings containing no NUL');
+    }
+  } else if (spec.command.kind === 'shell') {
+    if (
+      typeof spec.command.command !== 'string' ||
+      !spec.command.command ||
+      spec.command.command.includes('\0')
+    ) {
+      invalid('shell command must be non-empty and contain no NUL');
+    }
+    if (
+      spec.command.shell !== undefined &&
+      (typeof spec.command.shell !== 'string' ||
+        !path.isAbsolute(spec.command.shell) ||
+        spec.command.shell.includes('\0'))
+    ) {
+      invalid('shell must be an absolute path containing no NUL');
+    }
+  } else {
+    invalid('command kind is invalid');
+  }
+  if (commandSize(spec) > MAX_EXECUTION_COMMAND_BYTES) {
+    invalid('execution command is too large');
+  }
+  assertResourcePolicy(spec.resourcePolicy);
+}
+
+export function cloneExecutionSpec(spec: ExecutionSpec): ExecutionSpec {
+  assertExecutionSpec(spec);
+  return {
+    runId: spec.runId,
+    attemptId: spec.attemptId,
+    projectId: spec.projectId,
+    taskId: spec.taskId,
+    taskRevision: spec.taskRevision,
+    command:
+      spec.command.kind === 'argv'
+        ? {
+            kind: 'argv',
+            file: spec.command.file,
+            args: [...spec.command.args],
+          }
+        : {
+            kind: 'shell',
+            command: spec.command.command,
+            ...(spec.command.shell === undefined
+              ? {}
+              : { shell: spec.command.shell }),
+          },
+    ...(spec.workingDirectory === undefined
+      ? {}
+      : { workingDirectory: spec.workingDirectory }),
+    environmentPolicy: spec.environmentPolicy,
+    ...(spec.timeoutMs === undefined ? {} : { timeoutMs: spec.timeoutMs }),
+    terminationGraceMs: spec.terminationGraceMs,
+    ...(spec.resourcePolicy === undefined
+      ? {}
+      : {
+          resourcePolicy: {
+            ...(spec.resourcePolicy.memoryBytes === undefined
+              ? {}
+              : { memoryBytes: { ...spec.resourcePolicy.memoryBytes } }),
+            ...(spec.resourcePolicy.cpuMillisPerSecond === undefined
+              ? {}
+              : {
+                  cpuMillisPerSecond: {
+                    ...spec.resourcePolicy.cpuMillisPerSecond,
+                  },
+                }),
+            ...(spec.resourcePolicy.filesystemIsolation === undefined
+              ? {}
+              : {
+                  filesystemIsolation: spec.resourcePolicy.filesystemIsolation,
+                }),
+            ...(spec.resourcePolicy.networkIsolation === undefined
+              ? {}
+              : { networkIsolation: spec.resourcePolicy.networkIsolation }),
+          },
+        }),
+  };
+}