@specbook/core 0.1.0 → 0.3.0

package/src/mock.ts

@@ -1,8 +1,8 @@
-// In-process mock transport: serves request-level mock overrides, falling back to generated examples.
+// In-process mock transport: answers from the generated examples, filled in from the request that was sent, and lets a
+// request's `withMock` hook change the answer.
 import { reflectRequest } from './mock-reflect'
 import type { PreparedRequest, RawResponse, Transport } from './runner/transport'
 import { deepMerge, render } from './template'
-import type { MockResponse } from './types'
 
 export interface MockExampleLoader {
   /** Statuses that have an example for this operation, in spec order. */
@@ -12,48 +12,35 @@ export interface MockExampleLoader {
 
 export interface MockTransportOptions {
   loader: MockExampleLoader
-  sleep?: (ms: number) => Promise<void>
+  /** Waits a mock's `delayMs`. The default can be ended early by the run's signal: a person pressing Stop. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>
 }
 
-const isMockResponse = (v: unknown): v is MockResponse<unknown> =>
-  v !== null &&
-  typeof v === 'object' &&
-  ('data' in (v as object) ||
-    'init' in (v as object) ||
-    'headers' in (v as object) ||
-    'delayMs' in (v as object))
+const is2xx = (s: number) => s >= 200 && s < 300
 
-function evalInit(init: Record<string, unknown> | undefined) {
-  return Object.fromEntries(
-    Object.entries(init ?? {}).map(([k, v]) => [
-      k,
-      typeof v === 'function' ? (v as () => unknown)() : v,
-    ]),
-  )
-}
+/** The loader may hand out one object to every caller, and a hook edits what it is given. */
+const copy = <T>(v: T): T => (v === undefined ? v : (JSON.parse(JSON.stringify(v)) as T))
 
 export function createMockTransport(opts: MockTransportOptions): Transport {
-  const sleep = opts.sleep ?? ((ms) => new Promise<void>((r) => setTimeout(r, ms)))
-  return async (req: PreparedRequest): Promise<RawResponse> => {
+  const sleep =
+    opts.sleep ??
+    ((ms: number, signal?: AbortSignal) =>
+      new Promise<void>((done, stop) => {
+        if (signal?.aborted) return stop(new Error('Stopped before the API answered.'))
+        const timer = setTimeout(done, ms)
+        signal?.addEventListener(
+          'abort',
+          () => {
+            clearTimeout(timer)
+            stop(new Error('Stopped before the API answered.'))
+          },
+          { once: true },
+        )
+      }))
+  return async (req: PreparedRequest, signal?: AbortSignal): Promise<RawResponse> => {
     const hints = req.mock
-    const cfg = hints?.config
-    const known = await opts.loader.statuses(req.service, req.opId)
-    const overridden = Object.keys(cfg?.responses ?? {}).map(Number)
-    const all = [...new Set([...known, ...overridden])]
-
-    const fromWhen = cfg?.when?.({
-      vars: (hints?.vars ?? {}) as never,
-      body: req.body,
-      query: hints?.rawQuery,
-      path: hints?.pathParams,
-    })
-    const status =
-      req.mockStatus ??
-      fromWhen ??
-      cfg?.status ??
-      all.find((s) => s >= 200 && s < 300) ??
-      all[0] ??
-      200
+    const all = await opts.loader.statuses(req.service, req.opId)
+    const status = req.mockStatus ?? all.find(is2xx) ?? all[0] ?? 200
 
     // Secured operations answer 401 when no credential header was applied.
     if (
@@ -67,42 +54,65 @@ export function createMockTransport(opts: MockTransportOptions): Transport {
       return json(401, body)
     }
 
-    const override = (cfg?.responses as Record<number, unknown> | undefined)?.[status]
-    let delay = 0
-    let headers: Record<string, string> = {}
-    let scope = { ...(hints?.vars ?? {}), ...(hints?.pathParams ?? {}), ...(hints?.rawQuery ?? {}) }
-    let template: unknown = await opts.loader.example(req.service, req.opId, status)
+    const scope = {
+      ...(hints?.vars ?? {}),
+      ...(hints?.pathParams ?? {}),
+      ...(hints?.rawQuery ?? {}),
+    }
     // The generated example answers the request that was sent, so a created thing has the fields you posted.
-    if (status >= 200 && status < 300 && cfg?.reflect !== false)
-      template = reflectRequest(template, {
-        body: req.body,
-        path: hints?.pathParams,
-        query: hints?.rawQuery,
-      })
     // A declared status without a response schema (e.g. Petstore's 404) has no example: empty body.
-    if (override !== undefined) {
-      // Overrides are layered over the generated example (objects merge, arrays/scalars replace).
-      let data: unknown
-      if (isMockResponse(override)) {
-        data = await resolveSource(override.data)
-        scope = { ...scope, ...evalInit(override.init) }
-        headers = override.headers ? render(override.headers, scope) : {}
-        delay = override.delayMs ?? 0
-      } else {
-        data = await resolveSource(override)
-      }
-      if (data !== undefined) template = deepMerge(template, data)
+    const answer = async (s: number) => {
+      let template: unknown = copy(await opts.loader.example(req.service, req.opId, s))
+      if (is2xx(s))
+        template = reflectRequest(template, {
+          body: req.body,
+          path: hints?.pathParams,
+          query: hints?.rawQuery,
+        })
+      return template === undefined ? undefined : render(template, scope)
+    }
+
+    const res: {
+      status: number
+      data: unknown
+      headers: Record<string, string>
+      delayMs: number
+      respond(status: number, data?: unknown): void
+    } = {
+      status,
+      data: await answer(status),
+      headers: {},
+      delayMs: 0,
+      respond: (s, data) => {
+        pending = { status: s, data }
+      },
+    }
+    let pending: { status: number; data?: unknown } | undefined
+
+    if (hints?.hook) {
+      await hints.hook(
+        {
+          vars: (hints.vars ?? {}) as never,
+          body: req.body,
+          query: hints.rawQuery,
+          path: hints.pathParams,
+          headers: req.headers,
+        },
+        res as never,
+      )
+    }
+    if (pending) {
+      const base = await answer(pending.status)
+      res.status = pending.status
+      res.data = pending.data === undefined ? base : deepMerge(base, pending.data)
     }
-    if (delay) await sleep(delay)
-    const body = template === undefined ? undefined : render(template, scope)
-    return { ...json(status, body), headers: { 'content-type': 'application/json', ...headers } }
-  }
-}
 
-async function resolveSource(src: unknown): Promise<unknown> {
-  if (typeof src === 'function')
-    return (await (src as () => Promise<{ default: unknown }>)()).default
-  return src
+    if (res.delayMs) await sleep(res.delayMs, signal)
+    return {
+      ...json(res.status, res.data),
+      headers: { 'content-type': 'application/json', ...res.headers },
+    }
+  }
 }
 
 function json(status: number, body: unknown): RawResponse {

package/src/oauth.ts

@@ -0,0 +1,164 @@
+/**
+ * OAuth 2.0 authorization code with PKCE (RFC 7636), as pure helpers over Web Crypto so the browser and
+ * Node run the same code. Nothing here stores anything: a verifier is held by the caller, in memory.
+ */
+
+export class OAuthError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'OAuthError'
+  }
+}
+
+/** The endpoints are written out: an OAuth 2.0 authorization code flow. */
+export interface OAuthEndpoints {
+  authorizationUrl: string
+  tokenUrl: string
+  /** scope name -> description */
+  scopes?: Record<string, string>
+  /** a public identifier; pre-fills the sign-in prompt */
+  clientId?: string
+}
+
+/** The endpoints are found in an OpenID Connect discovery document. */
+export interface OAuthDiscovery {
+  openIdConnectUrl: string
+  scopes?: Record<string, string>
+  clientId?: string
+}
+
+/** What a spec or a config profile declares for an interactive sign-in. */
+export type OAuthSettings = OAuthEndpoints | OAuthDiscovery
+
+export const isDiscovery = (o: OAuthSettings): o is OAuthDiscovery => 'openIdConnectUrl' in o
+
+/** Endpoints read from a discovery document. */
+export interface DiscoveredEndpoints {
+  authorizationUrl: string
+  tokenUrl: string
+  /** scope name -> '' (a discovery document lists names only) */
+  scopes: Record<string, string>
+}
+
+/**
+ * The two endpoints a sign-in needs, from `/.well-known/openid-configuration`. Only the access token is
+ * used, so nothing else in the document (ID-token signing keys, `nonce` support) matters here.
+ */
+export function parseDiscovery(json: unknown): DiscoveredEndpoints {
+  const d = (json && typeof json === 'object' ? json : {}) as Record<string, unknown>
+  const url = (v: unknown) => (typeof v === 'string' && /^https?:\/\//i.test(v) ? v : undefined)
+  const authorizationUrl = url(d.authorization_endpoint)
+  const tokenUrl = url(d.token_endpoint)
+  if (!authorizationUrl || !tokenUrl)
+    throw new OAuthError('The provider’s discovery document has no authorization or token endpoint')
+  const supported = Array.isArray(d.scopes_supported)
+    ? d.scopes_supported.filter((x): x is string => typeof x === 'string')
+    : []
+  // `openid` is what makes it an OpenID Connect request; list it first even when the document omits it
+  const names = ['openid', ...supported.filter((x) => x !== 'openid')]
+  return { authorizationUrl, tokenUrl, scopes: Object.fromEntries(names.map((n) => [n, ''])) }
+}
+
+const base64url = (bytes: Uint8Array): string => {
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+const random = (bytes: number) => base64url(crypto.getRandomValues(new Uint8Array(bytes)))
+
+/** `code_challenge` for a verifier: BASE64URL(SHA-256(verifier)). */
+export async function challengeFor(verifier: string): Promise<string> {
+  // WebCrypto's `subtle` exists only on a secure page (https, or localhost); a viewer served over plain
+  // http, or framed inside such a page, has none. Say so, rather than fail on `undefined.digest`.
+  if (!globalThis.crypto?.subtle)
+    throw new OAuthError(
+      'Sign-in needs a secure page (https, or localhost). Open the viewer over https, or paste an access token.',
+    )
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  return base64url(new Uint8Array(digest))
+}
+
+/** A fresh verifier (64 characters from the unreserved set) and its S256 challenge. */
+export async function createPkce(): Promise<{ verifier: string; challenge: string }> {
+  const verifier = random(48)
+  return { verifier, challenge: await challengeFor(verifier) }
+}
+
+export const newState = (): string => random(24)
+
+export function authorizeUrl(o: {
+  authorizationUrl: string
+  clientId: string
+  redirectUri: string
+  scopes?: string[]
+  state: string
+  challenge: string
+}): string {
+  const url = new URL(o.authorizationUrl)
+  url.searchParams.set('response_type', 'code')
+  url.searchParams.set('client_id', o.clientId)
+  url.searchParams.set('redirect_uri', o.redirectUri)
+  if (o.scopes?.length) url.searchParams.set('scope', o.scopes.join(' '))
+  url.searchParams.set('state', o.state)
+  url.searchParams.set('code_challenge', o.challenge)
+  url.searchParams.set('code_challenge_method', 'S256')
+  return url.toString()
+}
+
+/** The code from the redirect, once `state` has been checked; throws what the server or the check said. */
+export function parseCallback(
+  params: URLSearchParams | Record<string, string | null | undefined>,
+  expectedState: string,
+): { code: string } {
+  const get = (k: string) =>
+    (params instanceof URLSearchParams ? params.get(k) : params[k]) ?? undefined
+  const error = get('error')
+  if (error) {
+    const detail = get('error_description')
+    throw new OAuthError(`Sign-in was refused: ${detail ? `${error} (${detail})` : error}`)
+  }
+  if (get('state') !== expectedState)
+    throw new OAuthError('Sign-in was rejected: the response did not match this request (state)')
+  const code = get('code')
+  if (!code) throw new OAuthError('Sign-in returned no authorization code')
+  return { code }
+}
+
+/** The form fields of the code exchange. A public client sends the verifier and no client secret. */
+export function tokenRequestFields(o: {
+  code: string
+  verifier: string
+  clientId: string
+  redirectUri: string
+}): Record<string, string> {
+  return {
+    grant_type: 'authorization_code',
+    code: o.code,
+    redirect_uri: o.redirectUri,
+    client_id: o.clientId,
+    code_verifier: o.verifier,
+  }
+}
+
+export const tokenRequestBody = (o: Parameters<typeof tokenRequestFields>[0]): string =>
+  new URLSearchParams(tokenRequestFields(o)).toString()
+
+export function parseTokenResponse(json: unknown): {
+  accessToken: string
+  expiresIn?: number
+  scope?: string
+} {
+  const r = (json && typeof json === 'object' ? json : {}) as Record<string, unknown>
+  if (typeof r.error === 'string') {
+    const detail = typeof r.error_description === 'string' ? ` (${r.error_description})` : ''
+    throw new OAuthError(`The token endpoint refused the code: ${r.error}${detail}`)
+  }
+  if (typeof r.access_token !== 'string' || r.access_token === '')
+    throw new OAuthError('The token endpoint returned no access token')
+  return {
+    accessToken: r.access_token,
+    ...(typeof r.expires_in === 'number' ? { expiresIn: r.expires_in } : {}),
+    ...(typeof r.scope === 'string' ? { scope: r.scope } : {}),
+  }
+}

package/src/reporters/ci.ts

@@ -0,0 +1,53 @@
+// Where a run happens, from the environment a CI system sets, for the report's header and its links.
+
+export interface CiInfo {
+  provider: string
+  runUrl?: string
+  sha?: string
+  branch?: string
+}
+
+export function detectCi(env: Record<string, string | undefined>): CiInfo | undefined {
+  if (env.GITHUB_ACTIONS === 'true') {
+    const server = env.GITHUB_SERVER_URL ?? 'https://github.com'
+    return {
+      provider: 'github-actions',
+      runUrl:
+        env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID
+          ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`
+          : undefined,
+      sha: env.GITHUB_SHA,
+      branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME,
+    }
+  }
+  if (env.GITLAB_CI === 'true')
+    return {
+      provider: 'gitlab-ci',
+      runUrl: env.CI_PIPELINE_URL,
+      sha: env.CI_COMMIT_SHA,
+      branch: env.CI_COMMIT_REF_NAME,
+    }
+  if (env.CIRCLECI === 'true')
+    return {
+      provider: 'circleci',
+      runUrl: env.CIRCLE_BUILD_URL,
+      sha: env.CIRCLE_SHA1,
+      branch: env.CIRCLE_BRANCH,
+    }
+  if (env.BUILDKITE === 'true')
+    return {
+      provider: 'buildkite',
+      runUrl: env.BUILDKITE_BUILD_URL,
+      sha: env.BUILDKITE_COMMIT,
+      branch: env.BUILDKITE_BRANCH,
+    }
+  if (env.JENKINS_URL)
+    return {
+      provider: 'jenkins',
+      runUrl: env.BUILD_URL,
+      sha: env.GIT_COMMIT,
+      branch: env.GIT_BRANCH,
+    }
+  if (env.CI) return { provider: 'ci' }
+  return undefined
+}

package/src/reporters/color.ts

@@ -0,0 +1,34 @@
+// Terminal colors, only when they will be seen: a TTY or a CI log that renders them, not NO_COLOR, or FORCE_COLOR.
+
+export interface Colors {
+  red(s: string): string
+  green(s: string): string
+  yellow(s: string): string
+  cyan(s: string): string
+  dim(s: string): string
+  bold(s: string): string
+}
+
+/** CI systems whose logs render color though the stream is not a terminal. */
+const COLOR_CI = ['GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'BUILDKITE']
+
+/** Whether to color output: FORCE_COLOR wins, then NO_COLOR, then an interactive terminal or a CI log that shows color. */
+export function colorEnabled(env: Record<string, string | undefined>, isTTY: boolean): boolean {
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== '0') return true
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false
+  if (COLOR_CI.some((k) => env[k] && env[k] !== 'false')) return true
+  return isTTY && env.TERM !== 'dumb'
+}
+
+export function createColors(enabled: boolean): Colors {
+  const wrap = (open: number, close: number) => (s: string) =>
+    enabled ? `\u001b[${open}m${s}\u001b[${close}m` : s
+  return {
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    cyan: wrap(36, 39),
+    dim: wrap(2, 22),
+    bold: wrap(1, 22),
+  }
+}

package/src/reporters/envelope.ts

@@ -0,0 +1,63 @@
+// The JSON report: the results with what a monitoring system needs to know about the run around them.
+
+import type { RunResult } from '../types'
+import type { CiInfo } from './ci'
+
+export interface ReportMeta {
+  env: string
+  /** version of the specbook that ran it */
+  specbook?: string
+  node?: string
+  os?: string
+  git?: { sha?: string; branch?: string }
+  ci?: CiInfo
+  /** `bundle.json` details when run from a bundle */
+  bundle?: { sha?: string; createdAt?: string }
+  /** service → origin of the address its calls went to */
+  services?: Record<string, string>
+  startedAt: string
+  finishedAt: string
+}
+
+export interface ReportTotals {
+  flows: { passed: number; failed: number; errored: number; flaky: number }
+  steps: { passed: number; failed: number; skipped: number }
+  assertions: { passed: number; failed: number }
+}
+
+export interface RunReport extends ReportMeta {
+  schemaVersion: 2
+  durationMs: number
+  totals: ReportTotals
+  results: RunResult[]
+}
+
+export function reportTotals(results: RunResult[]): ReportTotals {
+  const t: ReportTotals = {
+    flows: { passed: 0, failed: 0, errored: 0, flaky: 0 },
+    steps: { passed: 0, failed: 0, skipped: 0 },
+    assertions: { passed: 0, failed: 0 },
+  }
+  for (const r of results) {
+    if (r.status === 'pass') t.flows.passed++
+    else if (r.status === 'error') t.flows.errored++
+    else t.flows.failed++
+    if (r.flaky) t.flows.flaky++
+    t.steps.passed += r.totals.passed
+    t.steps.failed += r.totals.failed
+    t.steps.skipped += r.totals.skipped
+    t.assertions.passed += r.totals.assertions.passed
+    t.assertions.failed += r.totals.assertions.failed
+  }
+  return t
+}
+
+export function buildReport(results: RunResult[], meta: ReportMeta): RunReport {
+  return {
+    schemaVersion: 2,
+    ...meta,
+    durationMs: Math.max(0, Date.parse(meta.finishedAt) - Date.parse(meta.startedAt)),
+    totals: reportTotals(results),
+    results,
+  }
+}