threadwire 0.1.5 → 0.1.6

package/src/delegated-result-admission.js

@@ -0,0 +1,377 @@
+// @ts-check
+
+import {types as utilTypes} from "node:util"
+import {sanitizeOutput} from "./relay.js"
+
+export const CONCLUSION_LIMIT = 16_384
+export const BLOCKER_LIMIT = 1_024
+export const DECISION_REQUEST_LIMIT = 1_024
+export const CONTINUATION_HANDLE_LIMIT = 512
+export const ARTIFACT_HANDLE_LIMIT = 512
+export const REFERENCE_VALUE_LIMIT = 2_048
+export const VALIDATION_SUMMARY_LIMIT = 2_048
+export const MAX_ARTIFACT_HANDLES = 16
+export const MAX_REFERENCES = 16
+export const MAX_ENVELOPE_BYTES = 98_304
+const MAX_VALIDATION_BUDGET = 256
+
+const CANDIDATE_FIELDS = new Set([
+  "state",
+  "exitCode",
+  "conclusion",
+  "blocker",
+  "decisionRequest",
+  "continuationHandle",
+  "artifactHandles",
+  "references",
+  "validationSummary"
+])
+const STATES = new Set(["completed", "failed", "blocked", "needs_decision"])
+
+/**
+ * @typedef {"completed" | "failed" | "blocked" | "needs_decision"} TerminalState
+ * @typedef {{kind: "commit" | "url", value: string}} AdmissionReference
+ * @typedef {{
+ *   state: TerminalState,
+ *   exitCode: number,
+ *   conclusion?: string,
+ *   blocker?: string,
+ *   decisionRequest?: string,
+ *   continuationHandle?: string,
+ *   artifactHandles?: string[],
+ *   references?: AdmissionReference[],
+ *   validationSummary?: string
+ * }} DelegatedResultCandidate
+ */
+
+export class DelegatedResultAdmission {
+  /** @param {{output: NodeJS.WritableStream, metrics?: import("./context-budget-metrics.js").ContextBudgetMetrics}} options */
+  constructor(options) {
+    this.output = options.output
+    this.metrics = options.metrics
+    this.conclusion = ""
+    this.conclusionTruncated = false
+    /** @type {string | undefined} */
+    this.continuationHandle = undefined
+    /** @type {string[]} */
+    this.artifactHandles = []
+    /** @type {AdmissionReference[]} */
+    this.references = []
+    this.completed = false
+  }
+
+  /** @param {string} text */
+  appendConclusion(text) {
+    if (typeof text !== "string") throw new Error("Conclusion text must be a string")
+    if (this.conclusionTruncated) return
+    text = wellFormedString(text)
+    const remaining = CONCLUSION_LIMIT - Array.from(this.conclusion).length
+    const characters = Array.from(text)
+    if (characters.length <= remaining) this.conclusion += text
+    else {
+      this.conclusion += characters.slice(0, Math.max(0, remaining - 1)).join("") + "…"
+      this.conclusionTruncated = true
+    }
+  }
+
+  /** @param {unknown} event */
+  acceptConclusionEvent(event) {
+    if (!isPlainObject(event) || !hasExactEnumerableFields(event, ["type", "text", "streamId"])) {
+      throw new Error("Invalid admitted conclusion event")
+    }
+    if (event.type !== "text-delta" || typeof event.text !== "string" || typeof event.streamId !== "string") {
+      throw new Error("Invalid admitted conclusion event")
+    }
+    this.appendConclusion(event.text)
+  }
+
+  /** @param {string} handle */
+  setContinuationHandle(handle) {
+    this.continuationHandle = validateContinuationHandle(handle)
+  }
+
+  /** @param {string} handle */
+  addArtifactHandle(handle) {
+    this.artifactHandles = optionalArtifactHandles([...this.artifactHandles, handle]) ?? []
+  }
+
+  /** @param {string} handle */
+  removeArtifactHandle(handle) {
+    this.artifactHandles = this.artifactHandles.filter((candidate) => candidate !== handle)
+  }
+
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  preview(terminal) {
+    return this.createEnvelope(terminal)
+  }
+
+  /** @param {AdmissionReference} reference */
+  addReference(reference) {
+    this.references = /** @type {AdmissionReference[]} */ (optionalReferences([...this.references, reference]) ?? [])
+  }
+
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  complete(terminal) {
+    if (this.completed) throw new Error("Delegated result already completed")
+    const envelope = this.createEnvelope(terminal)
+    this.completed = true
+    this.metrics?.recordAdmission(envelope)
+    this.output.write(`${JSON.stringify(envelope)}\n`)
+  }
+
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  createEnvelope(terminal) {
+    const safeConclusion = truncateBoundedString(sanitizeOutput(this.conclusion), CONCLUSION_LIMIT)
+    return createDelegatedResultEnvelope({
+      ...terminal,
+      ...(terminal.state !== "completed" || safeConclusion === undefined ? {} : {conclusion: safeConclusion}),
+      ...(this.continuationHandle === undefined ? {} : {continuationHandle: this.continuationHandle}),
+      ...(this.artifactHandles.length === 0 ? {} : {artifactHandles: this.artifactHandles}),
+      ...(this.references.length === 0 ? {} : {references: this.references})
+    })
+  }
+}
+
+/** @param {unknown} candidate */
+export function createDelegatedResultEnvelope(candidate) {
+  const clonedCandidate = cloneTopLevelCandidate(candidate)
+  for (const field of Reflect.ownKeys(clonedCandidate)) {
+    if (typeof field !== "string" || !CANDIDATE_FIELDS.has(field) || !Object.prototype.propertyIsEnumerable.call(clonedCandidate, field)) {
+      throw new Error(`Unknown delegated result candidate field: ${String(field)}`)
+    }
+  }
+  if (typeof clonedCandidate.state !== "string" || !STATES.has(clonedCandidate.state)) {
+    throw new Error("Invalid delegated result terminal state")
+  }
+  if (!Number.isSafeInteger(clonedCandidate.exitCode) || /** @type {number} */ (clonedCandidate.exitCode) < 0) {
+    throw new Error("Invalid delegated result exitCode")
+  }
+  const conclusion = optionalBoundedString(clonedCandidate.conclusion, "conclusion", CONCLUSION_LIMIT)
+  const blocker = optionalBoundedString(clonedCandidate.blocker, "blocker", BLOCKER_LIMIT)
+  const decisionRequest = optionalBoundedString(clonedCandidate.decisionRequest, "decisionRequest", DECISION_REQUEST_LIMIT)
+  const continuationHandle = clonedCandidate.continuationHandle === undefined ? undefined : validateContinuationHandle(clonedCandidate.continuationHandle)
+  const validationSummary = optionalBoundedString(clonedCandidate.validationSummary, "validationSummary", VALIDATION_SUMMARY_LIMIT)
+  const artifactHandles = optionalArtifactHandles(clonedCandidate.artifactHandles)
+  const references = optionalReferences(clonedCandidate.references)
+
+  const envelope = {
+    version: 1,
+    type: "delegated_result",
+    state: /** @type {TerminalState} */ (clonedCandidate.state),
+    exitCode: /** @type {number} */ (clonedCandidate.exitCode),
+    ...(conclusion === undefined ? {} : {conclusion}),
+    ...(blocker === undefined ? {} : {blocker}),
+    ...(decisionRequest === undefined ? {} : {decisionRequest}),
+    ...(continuationHandle === undefined ? {} : {continuationHandle}),
+    ...(artifactHandles === undefined ? {} : {artifactHandles}),
+    ...(references === undefined ? {} : {references}),
+    ...(validationSummary === undefined ? {} : {validationSummary})
+  }
+  if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > MAX_ENVELOPE_BYTES) {
+    throw new Error("Delegated result candidate exceeds the envelope byte limit")
+  }
+  return envelope
+}
+
+/** @param {unknown} value @param {string} field @param {number} limit */
+function optionalBoundedString(value, field, limit) {
+  return value === undefined ? undefined : boundedString(value, field, limit)
+}
+
+/** @param {unknown} value @param {string} field @param {number} limit */
+function boundedString(value, field, limit) {
+  if (typeof value !== "string" || value.length === 0 || wellFormedString(value) !== value || Array.from(value).length > limit) {
+    throw new Error(`Invalid delegated result ${field}`)
+  }
+  return value
+}
+
+/** @param {string | undefined} value @param {number} limit */
+function truncateBoundedString(value, limit) {
+  if (value === undefined) return undefined
+  const characters = Array.from(value)
+  if (characters.length <= limit) return value
+  if (limit <= 1) return "…"
+  return `${characters.slice(0, limit - 1).join("")}…`
+}
+
+/** @param {unknown} value */
+export function validateContinuationHandle(value) {
+  const handle = boundedString(value, "continuationHandle", CONTINUATION_HANDLE_LIMIT)
+  if (
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)*$/u.test(handle)
+    || /^(?:data|file|ftp|ftps|http|https|javascript|mailto|sftp|ssh|urn|ws|wss):/iu.test(handle)
+  ) {
+    throw new Error("Invalid delegated result continuationHandle")
+  }
+  return handle
+}
+
+/** @param {unknown} value */
+function optionalArtifactHandles(value) {
+  if (value === undefined) return undefined
+  return validateClosedArray(value, "artifactHandles", MAX_ARTIFACT_HANDLES).map((item) => artifactHandle(item))
+}
+
+/** @param {unknown} value */
+function artifactHandle(value) {
+  const handle = boundedString(value, "artifactHandles", ARTIFACT_HANDLE_LIMIT)
+  if (!/^\/?[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u.test(handle)) {
+    throw new Error("Invalid delegated result artifactHandles")
+  }
+  const components = handle.split("/").filter((component) => component.length > 0)
+  if (components.some((component) => component === "." || component === "..")) {
+    throw new Error("Invalid delegated result artifactHandles")
+  }
+  return handle
+}
+
+/** @param {unknown} value */
+function optionalReferences(value) {
+  if (value === undefined) return undefined
+  return validateClosedArray(value, "references", MAX_REFERENCES).map((reference) => {
+    if (!isPlainObject(reference) || !hasExactEnumerableFields(reference, ["kind", "value"])) {
+      throw new Error("Invalid delegated result reference")
+    }
+    if (reference.kind !== "commit" && reference.kind !== "url") throw new Error("Invalid delegated result reference kind")
+    const referenceValue = boundedString(reference.value, "references", REFERENCE_VALUE_LIMIT)
+    if (reference.kind === "commit" && !/^[0-9a-f]{7,64}$/iu.test(referenceValue)) {
+      throw new Error("Invalid delegated result commit reference")
+    }
+    if (reference.kind === "url") validateUrlReference(referenceValue)
+    return {kind: reference.kind, value: referenceValue}
+  })
+}
+
+/**
+ * @param {unknown} value
+ * @param {"artifactHandles" | "references"} field
+ * @param {number} limit
+ * @returns {unknown[]}
+ */
+function validateClosedArray(value, field, limit) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > limit) {
+    throw new Error(`Invalid delegated result ${field}`)
+  }
+  const keys = Reflect.ownKeys(value)
+  if (keys.length !== value.length + 1) throw new Error(`Invalid delegated result ${field}`)
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      throw new Error(`Invalid delegated result ${field}`)
+    }
+  }
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length")
+  if (
+    !lengthDescriptor
+    || !("value" in lengthDescriptor)
+    || lengthDescriptor.value !== value.length
+    || lengthDescriptor.enumerable !== false
+  ) throw new Error(`Invalid delegated result ${field}`)
+  if (keys.some((key) => (
+    key !== "length"
+    && (typeof key !== "string" || !/^(?:0|[1-9]\d*)$/u.test(key) || Number(key) >= value.length)
+  ))) throw new Error(`Invalid delegated result ${field}`)
+  return value
+}
+
+/** @param {string} value */
+function validateUrlReference(value) {
+  if (Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0
+    return codePoint <= 31 || codePoint === 127 || /\s/u.test(character)
+  })) throw new Error("Invalid delegated result URL reference")
+  let parsed
+  try {
+    parsed = new URL(value)
+  } catch {
+    throw new Error("Invalid delegated result URL reference")
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username.length > 0 || parsed.password.length > 0) {
+    throw new Error("Invalid delegated result URL reference")
+  }
+}
+
+/** @param {unknown} candidate @returns {DelegatedResultCandidate} */
+function cloneTopLevelCandidate(candidate) {
+  if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("Delegated result candidate must be a plain object")
+  }
+  if (utilTypes.isProxy(candidate)) throw new Error("Delegated result candidate must not be a proxy")
+  if (!isPlainObject(candidate)) throw new Error("Delegated result candidate must be a plain object")
+  return /** @type {DelegatedResultCandidate} */ (cloneWithinBudget(candidate, {remaining: MAX_VALIDATION_BUDGET, seen: new WeakSet()}))
+}
+
+/**
+ * @param {unknown} value
+ * @param {{remaining: number, seen: WeakSet<object>}} state
+ * @returns {unknown}
+ */
+function cloneWithinBudget(value, state) {
+  state.remaining -= 1
+  if (state.remaining < 0) throw new Error("Delegated result candidate exceeds the validation budget")
+  if (value === null || typeof value !== "object") return value
+  if (utilTypes.isProxy(value)) throw new Error("Delegated result candidate must not contain proxy values")
+  if (!Array.isArray(value) && !isPlainObject(value)) return value
+  if (state.seen.has(value)) throw new Error("Delegated result candidate must not contain cycles")
+  state.seen.add(value)
+  try {
+    return cloneConcreteContainer(value, state)
+  } finally {
+    state.seen.delete(value)
+  }
+}
+
+/**
+ * @param {Record<PropertyKey, unknown> | unknown[]} value
+ * @param {{remaining: number, seen: WeakSet<object>}} state
+ */
+function cloneConcreteContainer(value, state) {
+  const clone = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value))
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (!descriptor) continue
+    if ("get" in descriptor || "set" in descriptor) {
+      throw new Error("Delegated result candidate must not contain accessor descriptors")
+    }
+    Object.defineProperty(clone, key, {
+      ...descriptor,
+      value: Array.isArray(value) && key === "length" ? descriptor.value : cloneWithinBudget(descriptor.value, state)
+    })
+  }
+  return clone
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} expected */
+function hasExactEnumerableFields(value, expected) {
+  const fields = Reflect.ownKeys(value)
+  return fields.length === expected.length && fields.every((field) => (
+    typeof field === "string"
+    && expected.includes(field)
+    && Object.prototype.propertyIsEnumerable.call(value, field)
+  ))
+}
+
+/** @param {string} value */
+function wellFormedString(value) {
+  let result = ""
+  for (let index = 0; index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index)
+    if (codeUnit >= 0xD800 && codeUnit <= 0xDBFF) {
+      const next = value.charCodeAt(index + 1)
+      if (next >= 0xDC00 && next <= 0xDFFF) {
+        result += value.slice(index, index + 2)
+        index += 1
+      } else result += "\uFFFD"
+    } else if (codeUnit >= 0xDC00 && codeUnit <= 0xDFFF) result += "\uFFFD"
+    else result += value.slice(index, index + 1)
+  }
+  return result
+}