@prestack/thread 0.0.1 → 0.0.3

package/dist/operations/generators/trial.ts

@@ -0,0 +1,529 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { argv, stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { ANONYMOUS, type Actor } from '../../core/actor.ts'
+import { ROOT, TREE, descend } from '../../core/descend.ts'
+import { exit, invoked } from '../../core/invoked.ts'
+
+import { recordingHttp, type ScriptedAnswer } from '../http.ts'
+import { inMemorySeams, type Sink } from '../memory.ts'
+import { TRIALS_AT, type Operation } from '../operations.ts'
+import { PERMITS_AT } from '../access.ts'
+import type { Result } from '../result.ts'
+import type { Row, Seams } from '../seams.ts'
+import { operations, types } from './seed.ts'
+
+export { TRIALS_AT }
+
+const DISPATCH_AT = 'operations/_dispatch.ts'
+
+const ENTITIES_AT = `${TREE}entities.ts`
+
+const ACCESS_AT = '_threads/access.ts'
+
+const WHEN = 1_767_225_600_000
+
+export interface Scenario {
+  readonly id: string
+
+  readonly describes: string
+
+  readonly input: unknown
+
+  readonly actor?: Actor
+
+  readonly rows?: readonly { readonly entity: string; readonly row: Row }[]
+
+  readonly answers?: Readonly<Record<string, ScriptedAnswer>>
+
+  readonly views?: Readonly<Record<string, readonly unknown[]>>
+}
+
+export interface Trial {
+  readonly operation: string
+  readonly scenario: string
+
+  readonly refused: boolean
+
+  readonly measured: boolean
+
+  readonly result: unknown
+
+  readonly kept: unknown
+
+  readonly observed: unknown
+
+  readonly called: unknown
+}
+
+export interface Outcome {
+  readonly id: string
+  readonly operation: string
+  readonly passed: boolean
+  readonly refused: boolean
+  readonly measured: boolean
+  readonly failures: readonly string[]
+}
+
+export interface Run {
+  readonly outcomes: readonly Outcome[]
+  readonly passed: number
+  readonly failed: number
+  readonly measured: number
+}
+
+const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
+
+function stable(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stable)
+  if (value instanceof Map) return stable(Object.fromEntries(value))
+  if (value instanceof Set) return [...value].map(stable)
+  if (typeof value === 'object' && value !== null) {
+    const found: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort(compare)) {
+      found[key] = stable((value as Record<string, unknown>)[key])
+    }
+    return found
+  }
+  if (typeof value === 'bigint') return String(value)
+  if (typeof value === 'function') return '[function]'
+  if (value === undefined) return null
+  return value
+}
+
+const printed = (value: unknown): string => `${JSON.stringify(stable(value), null, 2)}\n`
+
+const asking = (scenario: Scenario): Actor => ({
+  ...(scenario.actor ?? ANONYMOUS),
+  run: 'trial',
+  replay: `trial_${scenario.id}`,
+})
+
+function seamsFor(
+  one: Operation<unknown>,
+  scenario: Scenario,
+  stood: Readonly<Record<string, string>>,
+  gate?: NonNullable<Seams['permits']>,
+  known?: { readonly entities: ReadonlyMap<string, ReadonlySet<string>>; readonly keys: ReadonlyMap<string, string> },
+): { readonly seams: Seams; readonly sink: Sink; readonly kept: () => unknown; readonly calls: () => unknown } {
+  const made = inMemorySeams({
+    secrets: stood,
+    ...(scenario.views === undefined ? {} : { views: scenario.views }),
+    ...(known === undefined ? {} : { entities: known.entities, keys: known.keys }),
+  })
+
+  const found = made.seams as unknown as Record<string, unknown>
+
+  found['permits'] = gate ?? {
+    check() {
+      return Promise.resolve({ allow: true, because: 'this app derives no gate, so nothing here can refuse' })
+    },
+  }
+  found['clock'] = { now: () => WHEN }
+
+  let drawn = 0
+  found['random'] = {
+    next: () => {
+      drawn += 1
+      return drawn / 100
+    },
+    uuid: () => {
+      drawn += 1
+      return `00000000-0000-4000-8000-${String(drawn).padStart(12, '0')}`
+    },
+  }
+
+  const recorder = recordingHttp(scenario.answers ?? {})
+  found['http'] = recorder
+
+  return { seams: made.seams, sink: made.sink, kept: () => made.store, calls: () => recorder.calls }
+}
+
+function entered(sink: Sink): boolean {
+  return sink.logs.some((one) => {
+    const data = one.data as Record<string, unknown> | undefined
+    return data !== undefined && 'observability' in data
+  })
+}
+
+function denied(result: unknown): boolean {
+  if (typeof result !== 'object' || result === null) return false
+  const held = result as { readonly ok?: unknown; readonly code?: unknown }
+  return held.ok === false && held.code === 'denied'
+}
+
+export async function runScenario(
+  one: Operation<unknown>,
+  scenario: Scenario,
+  dispatch: (
+    operation: Operation<unknown>,
+    input: unknown,
+    actor: Actor,
+    seams: Seams,
+  ) => Promise<Result<unknown>>,
+  stood: Readonly<Record<string, string>> = {},
+  gate?: NonNullable<Seams['permits']>,
+  known?: { readonly entities: ReadonlyMap<string, ReadonlySet<string>>; readonly keys: ReadonlyMap<string, string> },
+): Promise<Trial> {
+
+  const made = seamsFor(one, scenario, stood, gate, known)
+
+  const actor = asking(scenario)
+
+  for (const seeded of scenario.rows ?? []) {
+    const held = made.seams.store
+      if (held === undefined) throw new Error(String(seeded.entity) + " cannot be seeded: these seams keep no rows")
+      await held.insert(actor, seeded.entity, seeded.row)
+  }
+
+  let result: unknown
+  try {
+    result = await dispatch(one, scenario.input, actor, made.seams)
+  } catch (thrown) {
+    result = { threw: thrown instanceof Error ? thrown.message : String(thrown) }
+  }
+
+  return {
+    operation: one.id,
+    scenario: scenario.id,
+    refused: denied(result),
+    measured: entered(made.sink),
+    result,
+    kept: made.kept(),
+    observed: made.sink,
+    called: made.calls(),
+  }
+}
+
+export async function scenariosFor(
+  one: Operation<unknown>,
+  takes: string,
+  granted: readonly string[] = [],
+): Promise<readonly Scenario[] | string> {
+  const from = resolve(ROOT, takes)
+  if (existsSync(from)) {
+    const made = (await import(pathToFileURL(from).href)) as { readonly SCENARIOS?: readonly Scenario[] }
+    const found = made.SCENARIOS
+    if (found !== undefined) {
+      if (found.length === 0) {
+        return `${takes} states an empty \`SCENARIOS\`, so nothing would be measured — remove it, or state one`
+      }
+      const named = new Set(found.map((each) => each.id))
+      if (named.size !== found.length) {
+        return `${takes} states two scenarios with the same id, and a trial is named after the one it ran`
+      }
+      return [...found].sort((a, b) => compare(a.id, b.id))
+    }
+  }
+
+  if (granted.length > 0) {
+    return (
+      `\`${one.id}\` is granted to ${granted.join(', ')}, and no scenario says who runs it. A caller is not ` +
+      `something to derive — a trial run as somebody the grant must allow proves nothing about access. State one ` +
+      `with \`thread run trial ${one.id}\`, which asks for the roles it arrives wearing, and export \`SCENARIOS\` ` +
+      `from ${takes}`
+    )
+  }
+
+  const empty = one.input.safeParse({})
+  if (empty.success) {
+    return [{ id: 'empty', describes: `runs ${one.id} with no input, as whoever arrives having said nothing`, input: {} }]
+  }
+
+  return (
+    `\`${one.id}\` takes an input that no empty object satisfies, and states no scenario to try it ` +
+    `with. Export \`SCENARIOS\` from ${takes} — until then this operation is not proven`
+  )
+}
+
+export function compared(was: readonly Trial[], now: readonly Trial[]): Run {
+  const before = new Map(was.map((one) => [`${one.operation}/${one.scenario}`, one]))
+  const outcomes: Outcome[] = []
+
+  for (const one of now) {
+    const id = `${one.operation}/${one.scenario}`
+    const failures: string[] = []
+    const older = before.get(id)
+
+    if (!one.refused && !one.measured) {
+      failures.push(
+        'the run never entered the operation and nothing denied it, so nothing about the operation was ' +
+          `measured and no refusal was proven either. What it answered was ${JSON.stringify(one.result)}`,
+      )
+    }
+
+    if (one.refused && one.measured) {
+      failures.push(
+        'this app\'s own gate denied the caller and the run REACHED THE OPERATION anyway — dispatch let a ' +
+          'denied request through to the compiled function, which is the gate not holding rather than a trial drifting',
+      )
+    }
+
+    if (older === undefined) {
+      failures.push('no trial holds this scenario. Run `thread trials` and commit the result')
+    } else {
+      for (const part of ['result', 'kept', 'observed'] as const) {
+        const then = printed(older[part])
+        const said = printed(one[part])
+        if (then === said) continue
+        failures.push(
+          `${part} is not what was recorded — the operation's behaviour has changed.\n    was: ${then.trim().slice(0, 400)}\n    now: ${said.trim().slice(0, 400)}`,
+        )
+      }
+    }
+
+    outcomes.push({
+      id,
+      operation: one.operation,
+      passed: failures.length === 0,
+      refused: one.refused,
+      measured: one.measured,
+      failures,
+    })
+  }
+
+  for (const one of was) {
+    const id = `${one.operation}/${one.scenario}`
+    if (now.some((each) => `${each.operation}/${each.scenario}` === id)) continue
+    outcomes.push({
+      id,
+      operation: one.operation,
+      passed: false,
+      refused: one.refused,
+      measured: false,
+      failures: ['this scenario is recorded and no longer runs — an operation or a scenario was removed without the trials being regenerated'],
+    })
+  }
+
+  return {
+    outcomes,
+    passed: outcomes.filter((one) => one.passed).length,
+    failed: outcomes.filter((one) => !one.passed).length,
+    measured: outcomes.filter((one) => one.measured).length,
+  }
+}
+
+export function unproven(run: Run): readonly string[] {
+  const each = new Map<string, Outcome[]>()
+  for (const one of run.outcomes) {
+    const held = each.get(one.operation)
+    if (held === undefined) each.set(one.operation, [one])
+    else held.push(one)
+  }
+
+  const said: string[] = []
+  for (const [operation, outcomes] of [...each].sort((one, two) => compare(one[0], two[0]))) {
+    if (outcomes.some((one) => one.measured)) continue
+
+    const denied = outcomes.filter((one) => one.refused).length
+    const neither = outcomes.length - denied
+    const how = [
+      denied === 0
+        ? ''
+        : `${String(denied)} were denied by this app's own gate, which proves the gate turns somebody away and nothing whatever about the operation`,
+      neither === 0 ? '' : `${String(neither)} neither reached it nor were denied`,
+    ].filter((one) => one !== '')
+
+    said.push(
+      `\`${operation}\` is UNPROVEN — ${String(outcomes.length)} scenario(s) ran and not one of them reached it: ${how.join(', and ')}. ` +
+        'Grant a caller the trial can run as, or give it a scenario the gate admits',
+    )
+  }
+
+  return said
+}
+
+async function standing(): Promise<Readonly<Record<string, string>>> {
+  const at = resolve(ROOT, '_threads/secrets.ts')
+  if (!existsSync(at)) return {}
+  let held: readonly { readonly id: string; readonly sends?: unknown }[]
+  try {
+    const taken = (await import(pathToFileURL(at).href)) as {
+      readonly SECRETS?: readonly { readonly id: string; readonly sends?: unknown }[]
+    }
+    held = taken.SECRETS ?? []
+  } catch {
+    return {}
+  }
+  const found: Record<string, string> = {}
+  for (const one of held) {
+    found[one.id] = one.sends === undefined ? `https://${one.id.replace(/_/g, '-')}.invalid` : `${one.id}-stood-in-for`
+  }
+  return found
+}
+
+export async function record(): Promise<{ readonly trials: readonly Trial[]; readonly refusals: readonly string[] }> {
+  const pass = descend()
+  const known = types(pass)
+  const refusals: string[] = []
+  const trials: Trial[] = []
+
+  const declared = [...operations(pass, known)].filter(([, one]) => one.body !== undefined)
+  if (declared.length === 0) return { trials: [], refusals: [] }
+
+  const stood = await standing()
+
+  const at = resolve(ROOT, DISPATCH_AT)
+  if (!existsSync(at)) {
+    return {
+      trials: [],
+      refusals: [
+        `this app has no ${DISPATCH_AT}. Run \`thread compile\` — an operation runs through dispatch and there is nothing here to run it with`,
+      ],
+    }
+  }
+  const made = (await import(pathToFileURL(at).href)) as {
+    readonly dispatch?: (
+      operation: Operation<unknown>,
+      input: unknown,
+      actor: Actor,
+      seams: Seams,
+    ) => Promise<Result<unknown>>
+  }
+  const dispatch = made.dispatch
+  if (dispatch === undefined) {
+    return { trials: [], refusals: [`${DISPATCH_AT} exports no \`dispatch\`, so nothing here can run an operation`] }
+  }
+
+  const kept = resolve(ROOT, ENTITIES_AT)
+  const entities = new Map<string, ReadonlySet<string>>()
+  const keys = new Map<string, string>()
+  if (existsSync(kept)) {
+    const sheet = (await import(pathToFileURL(kept).href)) as {
+      readonly ENTITIES?: readonly {
+        readonly id: string
+        readonly holds?: readonly { readonly id: string }[]
+        readonly links?: readonly { readonly id: string }[]
+        readonly must?: readonly { readonly unique?: readonly string[] }[]
+      }[]
+    }
+    for (const one of sheet.ENTITIES ?? []) {
+      entities.set(
+        one.id,
+        new Set([...(one.holds ?? []).map((each) => each.id), ...(one.links ?? []).map((each) => `${each.id}_id`)]),
+      )
+      const named = (one.must ?? []).flatMap((each) => (each.unique?.length === 1 ? [each.unique[0] as string] : []))
+      if (named.length === 1) keys.set(one.id, named[0] as string)
+    }
+  }
+
+  const permitted = resolve(ROOT, ACCESS_AT)
+  const may = new Map<string, string[]>()
+  if (existsSync(permitted)) {
+    const sheet = (await import(pathToFileURL(permitted).href)) as {
+      readonly GRANTS?: readonly {
+        readonly may?: readonly string[]
+        readonly to?: { readonly roles?: readonly string[] }
+      }[]
+    }
+    for (const one of sheet.GRANTS ?? []) {
+      for (const id of one.may ?? []) {
+        may.set(id, [...new Set([...(may.get(id) ?? []), ...(one.to?.roles ?? [])])])
+      }
+    }
+  }
+
+  const compiled = resolve(ROOT, PERMITS_AT)
+  const permits = existsSync(compiled)
+    ? ((await import(pathToFileURL(compiled).href)) as {
+        readonly permits?: (actor: Actor, action: string, resource: Row | null) => { allow: boolean; because?: string }
+      }).permits
+    : undefined
+  if (existsSync(compiled) && permits === undefined) {
+    return {
+      trials: [],
+      refusals: [`${PERMITS_AT} exports no \`permits\`, so a trial cannot be answered by the gate this app derives`],
+    }
+  }
+  const gate: NonNullable<Seams['permits']> | undefined =
+    permits === undefined
+      ? undefined
+      : { check: (actor, action, resource) => Promise.resolve(permits(actor, action, resource)) }
+
+  for (const [id, one] of [...declared].sort((a, b) => compare(a[0], b[0]))) {
+    if (one.body === undefined) continue
+    const from = resolve(ROOT, one.body)
+    if (!existsSync(from)) {
+      refusals.push(`\`${id}\` derives ${one.body} and that file is not there. Run \`thread compile\``)
+      continue
+    }
+
+    const held = (await import(pathToFileURL(from).href)) as { readonly operation?: Operation<unknown> }
+    const operation = held.operation
+    if (operation === undefined) {
+      refusals.push(`${one.body} exports no \`operation\`, so \`${id}\` cannot be run`)
+      continue
+    }
+
+    const takes = one.takes[0]?.at
+    if (takes === undefined) {
+      refusals.push(`\`${id}\` names nothing it takes, so nothing states its input or what to try it with`)
+      continue
+    }
+
+    const scenarios = await scenariosFor(operation, takes, may.get(id) ?? [])
+    if (typeof scenarios === 'string') {
+      refusals.push(scenarios)
+      continue
+    }
+
+    for (const scenario of scenarios) {
+      trials.push(await runScenario(operation, scenario, dispatch, stood, gate, { entities, keys }))
+    }
+  }
+
+  return { trials, refusals }
+}
+
+function kept(): readonly Trial[] {
+  const at = resolve(ROOT, TRIALS_AT)
+  if (!existsSync(at)) return []
+  return JSON.parse(readFileSync(at, 'utf8')) as readonly Trial[]
+}
+
+if (invoked(import.meta.url)) {
+  const { trials, refusals } = await record()
+
+  for (const one of refusals) console.error(`trial: ${one}`)
+
+  if (argv.includes('--check')) {
+    const run = compared(kept(), trials)
+    for (const outcome of run.outcomes) {
+      if (outcome.passed) continue
+      for (const failure of outcome.failures) console.error(`trial: ${outcome.id} — ${failure}`)
+    }
+
+    if (run.outcomes.length === 0 && refusals.length === 0) {
+      console.log('trial: this app declares no operation, so there is nothing to prove.')
+      exit(0)
+    }
+
+    const short = unproven(run)
+    for (const one of short) console.error(`trial: ${one}`)
+
+    console.log(
+      `trial: ${String(run.passed)} of ${String(run.outcomes.length)} passed, ${String(run.measured)} measured, ` +
+        `${String(short.length)} operation(s) unproven.`,
+    )
+    exit(run.failed === 0 && refusals.length === 0 && short.length === 0 ? 0 : 1)
+  }
+
+  if (refusals.length > 0) {
+    console.error(
+      `trial: ${String(refusals.length)} refusal(s) above, so ${TRIALS_AT} is left as it was — ` +
+        'a run that was refused has nothing to record, and recording it would erase what does',
+    )
+    exit(1)
+  }
+
+  const at = resolve(ROOT, TRIALS_AT)
+  mkdirSync(dirname(at), { recursive: true })
+  writeFileSync(at, printed(trials))
+  const measured = trials.filter((one) => one.measured).length
+  stdout.write(
+    `trial: wrote ${TRIALS_AT} — ${String(trials.length)} trial(s) from ${String(measured)} run(s) that reached an operation.\n`,
+  )
+  exit(0)
+}

package/dist/operations/http.ts

@@ -0,0 +1,164 @@
+import { payloadBytes } from './metering.ts'
+import { ValidationError } from './result.ts'
+import type { Http, HttpRequest, HttpResponse } from './seams.ts'
+
+export const HTTP_CALL_ACTION = 'http.call'
+
+export class HttpNotConfiguredError extends Error {
+  constructor() {
+    super(
+      'no outward seam is configured. `http.call` needs `seams.http`, which is the transport an app ' +
+        'wires — which hosts it may reach is declared in its tree and is not this seam\'s business.',
+    )
+    this.name = 'HttpNotConfiguredError'
+  }
+}
+
+export class OutwardTransportError extends Error {
+  constructor(
+    readonly target: string,
+    cause: unknown,
+  ) {
+    super(`outward call to "${target}" never reached it: ${cause instanceof Error ? cause.message : String(cause)}`)
+    this.name = 'OutwardTransportError'
+  }
+}
+
+export function outwardUrl(target: string, address: string, path: string): URL {
+  let base: URL
+  try {
+    base = new URL(address)
+  } catch {
+    throw new ValidationError(`the address resolved for "${target}" is not an absolute URL: ${JSON.stringify(address)}`)
+  }
+  if (base.protocol !== 'https:') {
+    throw new ValidationError(`outward calls go over https only, and "${target}" resolved to ${base.protocol.replace(':', '')}`)
+  }
+  if (base.search !== '' || base.hash !== '') {
+    throw new ValidationError(`the address for "${target}" carries a query or a fragment — those belong to the call`)
+  }
+  if (!path.startsWith('/')) {
+    throw new ValidationError(`an outward path starts with "/", and "${path}" does not`)
+  }
+  if (path.startsWith('//')) {
+    throw new ValidationError(`the path "${path}" is protocol-relative, which points at another host`)
+  }
+  const url = new URL(`${base.origin}${base.pathname.replace(/\/$/, '')}${path}`)
+  if (url.origin !== base.origin) {
+    throw new ValidationError(`the path "${path}" resolves to ${url.origin}, which is not where "${target}" is`)
+  }
+  return url
+}
+
+function requestBytes(headers: Readonly<Record<string, string>>, body: Uint8Array | undefined): number {
+  return payloadBytes(headers) + (body === undefined ? 0 : body.byteLength)
+}
+
+function wireBody(body: Uint8Array): ArrayBuffer {
+  const copy = new ArrayBuffer(body.byteLength)
+  new Uint8Array(copy).set(body)
+  return copy
+}
+
+export interface HttpSeamOptions {
+  readonly transport?: typeof fetch
+
+  readonly timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+export function httpSeam(options: HttpSeamOptions = {}): Http {
+  const send = options.transport ?? fetch
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  return {
+    async call(request: HttpRequest): Promise<HttpResponse> {
+      const url = outwardUrl(request.target, request.address, request.path)
+
+      const headers: Record<string, string> = { ...request.headers }
+      if (request.contentType !== undefined) headers['content-type'] = request.contentType
+      if (request.idempotencyKey !== undefined) headers['idempotency-key'] = request.idempotencyKey
+
+      const bytesSent = requestBytes(headers, request.body)
+      const startedAt = Date.now()
+
+      let response: Response
+      try {
+        response = await send(url.toString(), {
+          method: request.method,
+          headers,
+          ...(request.body === undefined ? {} : { body: wireBody(request.body) }),
+          signal: AbortSignal.timeout(timeoutMs),
+        })
+      } catch (error) {
+
+        throw new OutwardTransportError(request.target, error)
+      }
+
+      const body = new Uint8Array(await response.arrayBuffer())
+      const responseHeaders = Object.fromEntries(response.headers.entries())
+
+      return {
+        status: response.status,
+        headers: responseHeaders,
+        body,
+        bytesSent,
+        bytesReceived: payloadBytes(responseHeaders) + body.byteLength,
+        durationMs: Date.now() - startedAt,
+      }
+    },
+  }
+}
+
+export interface RecordedCall {
+  readonly target: string
+  readonly method: string
+  readonly path: string
+  readonly headers: Readonly<Record<string, string>>
+  readonly body: string
+}
+
+export interface ScriptedAnswer {
+  readonly status: number
+  readonly headers?: Readonly<Record<string, string>>
+  readonly body?: string
+}
+
+const REDACTED = '(sent)'
+
+export function recordingHttp(
+  script: Readonly<Record<string, ScriptedAnswer>> = {},
+): Http & { readonly calls: readonly RecordedCall[] } {
+  const calls: RecordedCall[] = []
+  const decoder = new TextDecoder()
+
+  return {
+    calls,
+    async call(request) {
+      outwardUrl(request.target, request.address, request.path)
+
+      const body = request.body === undefined ? '' : decoder.decode(request.body)
+      calls.push({
+        target: request.target,
+        method: request.method,
+        path: request.path,
+        headers: Object.fromEntries(Object.keys(request.headers ?? {}).map((one) => [one, REDACTED])),
+        body,
+      })
+
+      const answer = script[`${request.method} ${request.path}`] ?? { status: 404, body: '{"message":"not scripted"}' }
+      const answered = new TextEncoder().encode(answer.body ?? '')
+      const headers = answer.headers ?? {}
+      return {
+        status: answer.status,
+        headers,
+        body: answered,
+        bytesSent: requestBytes({ ...request.headers }, request.body),
+        bytesReceived: payloadBytes(headers) + answered.byteLength,
+
+        durationMs: 0,
+      }
+    },
+  }
+}