@specbook/core 0.2.0 → 0.3.0

package/src/runner/transport.ts

@@ -16,11 +16,11 @@ export interface PreparedRequest {
   /** Array style per form field, from the spec's `encoding` object. */
   formArrays?: Record<string, FormArrays>
   timeoutMs?: number
-  /** Mock status the caller wants served (mock env only). */
+  /** Mock status the caller wants served, e.g. the UI's "Respond with" (mock env only). */
   mockStatus?: number
   /** In-process hints for the mock transport; never serialized or substituted. */
   mock?: {
-    config?: import('../types').MockInput<any, any>
+    hook?: import('../types').MockHook<any, any>
     vars: Record<string, unknown>
     pathParams: Record<string, unknown>
     rawQuery: Record<string, unknown>
@@ -46,6 +46,18 @@ export function buildUrl(base: string, req: PreparedRequest): string {
   return `${base.replace(/\/+$/, '')}${req.url}${q ? `?${q}` : ''}`
 }
 
+/** A config `baseUrl` may be relative (`/api/v1`): it is resolved against the page. */
+export function absoluteBase(baseUrl: string, pageHref?: string): string {
+  try {
+    return new URL(baseUrl, pageHref).toString()
+  } catch {
+    return baseUrl
+  }
+}
+
+/** How long a request waits for an answer when nothing says otherwise. */
+export const DEFAULT_TIMEOUT_MS = 30_000
+
 export interface FetchTransportOptions {
   baseUrl: (service: string) => string
   fetch?: typeof fetch
@@ -53,6 +65,8 @@ export interface FetchTransportOptions {
 
 export function createFetchTransport(opts: FetchTransportOptions): Transport {
   return async (req, signal) => {
+    // a run stopped before this request left: nothing is sent, and no 'abort' will ever be heard from a signal that has fired
+    if (signal?.aborted) throw new Error('Stopped before the API answered.')
     const f = opts.fetch ?? fetch
     const headers: Record<string, string> = { ...req.headers }
     let body: BodyInit | undefined
@@ -61,10 +75,15 @@ export function createFetchTransport(opts: FetchTransportOptions): Transport {
       body = enc.body
       if (enc.contentType) headers['content-type'] ??= enc.contentType
     }
-    if (req.mockStatus !== undefined) headers['x-specbook-mock-status'] = String(req.mockStatus)
 
     const ctl = new AbortController()
-    const timer = req.timeoutMs ? setTimeout(() => ctl.abort(), req.timeoutMs) : undefined
+    let timedOut = false
+    const timer = req.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true
+          ctl.abort()
+        }, req.timeoutMs)
+      : undefined
     signal?.addEventListener('abort', () => ctl.abort())
     try {
       const res = await f(buildUrl(opts.baseUrl(req.service), req), {
@@ -88,6 +107,12 @@ export function createFetchTransport(opts: FetchTransportOptions): Transport {
         }
       }
       return { status: res.status, headers: outHeaders, text, body: parsed }
+    } catch (e) {
+      // an abort that the request's own timeout caused says so, not "This operation was aborted"
+      if (timedOut) throw new Error(`Timed out after ${req.timeoutMs}ms: no answer from the API.`)
+      // a person pressing Stop, or the run's own deadline: say so, not "This operation was aborted"
+      if (signal?.aborted) throw new Error('Stopped before the API answered.')
+      throw e
     } finally {
       if (timer) clearTimeout(timer)
     }

package/src/secrets.ts

@@ -67,9 +67,38 @@ export async function resolveSecrets(
   return out
 }
 
-/** Masks with `***`, longest first so a secret containing another is hidden whole; values under 4 chars are skipped to avoid masking ordinary text */
+/** Secrets shorter than this are not masked: they would blank out ordinary text. */
+const MIN_MASKED = 3
+
+/**
+ * A secret as it can appear in a URL, a JSON string or a Basic-auth style base64 value, besides itself: what a server
+ * echoes back or an error message quotes is not always the raw value.
+ */
+export function maskVariants(secret: string): string[] {
+  const out = new Set<string>([secret])
+  const add = (f: () => string) => {
+    try {
+      out.add(f())
+    } catch {
+      /* not encodable: the raw value is still masked */
+    }
+  }
+  add(() => encodeURIComponent(secret))
+  add(() => encodeURI(secret))
+  add(() => JSON.stringify(secret).slice(1, -1))
+  add(() => btoa(String.fromCharCode(...new TextEncoder().encode(secret))))
+  return [...out]
+}
+
+/**
+ * Masks with `***`, longest first so a secret containing another is hidden whole. Every secret is masked in its
+ * raw, URL-encoded, JSON-escaped and base64 forms; values under 3 characters are skipped to avoid masking
+ * ordinary text.
+ */
 export function maskDeep<T>(value: T, secrets: Iterable<string>): T {
-  const list = [...secrets].filter((s) => s.length >= 4).sort((a, b) => b.length - a.length)
+  const list = [
+    ...new Set([...secrets].filter((s) => s.length >= MIN_MASKED).flatMap(maskVariants)),
+  ].sort((a, b) => b.length - a.length)
   if (list.length === 0) return value
   const maskStr = (s: string) => list.reduce((acc, v) => acc.split(v).join('***'), s)
   const walk = (v: unknown): unknown => {

package/src/sequence.ts

@@ -2,7 +2,7 @@ import type { Controls, InferControls } from './controls'
 import type { Assert, AssertMode, AuthProfileName, RequestDef } from './types'
 
 export interface StepCtx<P, C> {
-  params: P
+  inputs: P
   captured: C
   vars: Record<string, unknown>
   env: string
@@ -34,7 +34,7 @@ export interface SequenceMeta {
   tags?: string[]
   /** Heading the flow is listed under in the catalog; flows without one are under "Default". */
   group?: string
-  params?: Controls
+  inputs?: Controls
   auth?: AuthProfileName | false
   assertMode?: AssertMode
   continueOnFailure?: boolean
@@ -55,7 +55,7 @@ export interface Sequence<P = {}, C = {}> {
     name: string,
     fn: (ctx: StepCtx<P, C>, h: { assert: Assert }) => void | Promise<void>,
   ): Sequence<P, C>
-  /** Pause for user input; the chosen values merge into ctx.params. */
+  /** Pause for user input; the chosen values merge into ctx.inputs. */
   input<R extends Controls>(
     name: string,
     controls: (ctx: StepCtx<P, C>) => R,
@@ -77,7 +77,7 @@ function build(meta: SequenceMeta, nodes: readonly StepNode[]): Sequence<any, an
 }
 
 export function sequence<P extends Controls = {}>(
-  meta: Omit<SequenceMeta, 'params'> & { params?: P },
+  meta: Omit<SequenceMeta, 'inputs'> & { inputs?: P },
 ): Sequence<InferControls<P>, {}> {
   return build(meta, [])
 }

package/src/spec-config.ts

@@ -14,30 +14,33 @@ export interface JsonAuthProfile {
   oauth?: OAuthSettings
 }
 
+/** Gives the address a profile field should carry for a raw URL from the document. */
+type Address = (field: 'authorizationUrl' | 'tokenUrl' | 'openIdConnectUrl', raw: string) => string
+
 /** An OpenID Connect scheme: the discovery document says where to sign in. */
-function discovery(s: any, base: string | undefined): OAuthSettings | undefined {
+function discovery(s: any, address: Address): OAuthSettings | undefined {
   if (typeof s.openIdConnectUrl !== 'string' || s.openIdConnectUrl === '') return undefined
   try {
-    return { openIdConnectUrl: new URL(s.openIdConnectUrl, base).toString() }
+    return { openIdConnectUrl: address('openIdConnectUrl', s.openIdConnectUrl) }
   } catch {
     return undefined
   }
 }
 
 /** The authorization code flow of an OAuth scheme (OpenAPI 3 `flows`, or Swagger 2 `accessCode`). */
-function codeFlow(s: any, base: string | undefined): OAuthSettings | undefined {
+function codeFlow(s: any, address: Address): OAuthSettings | undefined {
   const flow = s.flows?.authorizationCode ?? (s.flow === 'accessCode' ? s : undefined)
   if (!flow?.authorizationUrl || !flow?.tokenUrl) return undefined
-  const abs = (u: string) => {
+  const abs = (field: 'authorizationUrl' | 'tokenUrl', u: string) => {
     try {
-      return new URL(u, base).toString()
+      return address(field, u)
     } catch {
       return u
     }
   }
   return {
-    authorizationUrl: abs(flow.authorizationUrl),
-    tokenUrl: abs(flow.tokenUrl),
+    authorizationUrl: abs('authorizationUrl', flow.authorizationUrl),
+    tokenUrl: abs('tokenUrl', flow.tokenUrl),
     ...(flow.scopes && Object.keys(flow.scopes).length ? { scopes: flow.scopes } : {}),
   }
 }
@@ -48,6 +51,12 @@ export interface SpecAuth {
   secrets: Record<string, Record<string, never>>
   /** the profile requests use unless they say otherwise */
   defaultProfile?: string
+  /**
+   * Sign-in addresses the document gives relative to its servers become variables, so each environment
+   * signs in at its own server: the `live` values here, and one entry per other environment below.
+   */
+  vars: Record<string, string>
+  environmentVars: Record<string, Record<string, string>>
 }
 
 const secretName = (scheme: string) =>
@@ -60,10 +69,41 @@ const secretName = (scheme: string) =>
  * Turns a document's security schemes into auth profiles whose secrets are filled in at run time, so
  * previewing a protected API only needs the user to paste a key. OAuth-style schemes take an access token.
  */
-export function authFromSpec(api: any, source?: string): SpecAuth {
+export function authFromSpec(api: any, source?: string, servers?: ServerEntry[]): SpecAuth {
   const schemes: Record<string, any> =
     api.components?.securitySchemes ?? api.securityDefinitions ?? {}
-  const out: SpecAuth = { auth: {}, secrets: {} }
+  const out: SpecAuth = { auth: {}, secrets: {}, vars: {}, environmentVars: {} }
+  const pageBase = source && isUrl(source) ? source : undefined
+  const resolve = (raw: string, base: string | undefined) => new URL(raw, base).toString()
+  // a relative address follows the server (OpenAPI 3.1): one variable per scheme and field, set per environment
+  const addressFor =
+    (scheme: string): Address =>
+    (field, raw) => {
+      if (!servers?.length || isUrl(raw)) return resolve(raw, pageBase)
+      const name = `${secretName(scheme)
+        .toLowerCase()
+        .replace(/_(.)/g, (_, c) => c.toUpperCase())}${field[0]?.toUpperCase()}${field.slice(1)}`
+      let any = false
+      for (const sv of servers) {
+        try {
+          const abs = resolve(raw, sv.url.endsWith('/') ? sv.url : `${sv.url}/`)
+          if (sv.name === 'live') out.vars[name] = abs
+          else out.environmentVars[sv.name] = { ...out.environmentVars[sv.name], [name]: abs }
+          any = true
+        } catch {
+          /* this server cannot resolve it */
+        }
+      }
+      if (!any) return resolve(raw, pageBase)
+      if (out.vars[name] === undefined) {
+        try {
+          out.vars[name] = resolve(raw, pageBase)
+        } catch {
+          out.vars[name] = raw
+        }
+      }
+      return `{{${name}}}`
+    }
   for (const [name, s] of Object.entries(schemes)) {
     const secret = secretName(name)
     const ref = `{{secrets.${secret}}}`
@@ -88,8 +128,8 @@ export function authFromSpec(api: any, source?: string): SpecAuth {
       title = `${name} (basic auth, paste base64 of user:password)`
     } else if (s.type === 'oauth2' || s.type === 'openIdConnect') {
       apply = { headers: { authorization: `Bearer ${ref}` } }
-      const base = source && isUrl(source) ? source : undefined
-      oauth = s.type === 'oauth2' ? codeFlow(s, base) : discovery(s, base)
+      const address = addressFor(name)
+      oauth = s.type === 'oauth2' ? codeFlow(s, address) : discovery(s, address)
       title = `${name} (OAuth, ${oauth ? 'sign in or ' : ''}paste an access token)`
     }
     if (!apply) continue
@@ -209,6 +249,32 @@ export function openApiServers(
   return { servers, needsBaseUrl, omitted }
 }
 
+/**
+ * What a document's servers become in a config: the first server's address as the variable `varName`, the
+ * others as the same variable in an environment of their own, and a `baseUrl` that reads it.
+ */
+export function environmentsFromServers(
+  servers: ServerEntry[],
+  varName: string,
+): {
+  vars: Record<string, string>
+  environments: Record<string, { description?: string; vars?: Record<string, string> }>
+  baseUrl: string
+} {
+  const vars: Record<string, string> = {}
+  const environments: Record<string, { description?: string; vars?: Record<string, string> }> = {}
+  for (const s of servers) {
+    const description = s.description ? { description: s.description } : {}
+    if (s.name === 'live') {
+      vars[varName] = s.url
+      if (s.description) environments.live = description
+    } else {
+      environments[s.name] = { ...description, vars: { [varName]: s.url } }
+    }
+  }
+  return { vars, environments, baseUrl: `{{${varName}}}` }
+}
+
 /** Where the API lives, from `servers[0]` (OpenAPI 3) or `host`/`basePath` (Swagger 2). */
 export function liveBaseUrl(api: any, source: string): string | undefined {
   return openApiServers(api, source).servers.find((s) => s.name === 'live')?.url

package/src/types.ts

@@ -63,11 +63,6 @@ export type DeepPartial<T> = T extends readonly (infer U)[]
 
 export type Source<T> = Templated<T> | (() => Promise<{ default: Templated<T> }>)
 
-/** Mock overrides are deep-merged over the generated example, so they only need the fields that matter. */
-export type PartialSource<T> =
-  | DeepPartial<Templated<T>>
-  | (() => Promise<{ default: DeepPartial<Templated<T>> }>)
-
 export type Init = Record<string, unknown>
 export type ResolvedInit<I> = { [K in keyof I]: I[K] extends () => infer R ? R : I[K] }
 
@@ -109,6 +104,10 @@ export interface RequestInput<T extends OpTypes, I extends Init = Init, C = {}>
   data?: Source<T['body']>
   encoding?: Encoding
   timeoutMs?: number
+  /** A request that only reads (a POST search, a GraphQL query): allowed in a read-only run. */
+  safe?: boolean
+  /** Labels to select this request by (`specbook test --tag monitor`) and to group it by in the UI. */
+  tags?: string[]
   capture?: { [K in keyof C]: (res: ResponseOf<T>, vars: ResolvedInit<I>) => C[K] }
   assert?: (
     res: ResponseOf<T>,
@@ -120,39 +119,50 @@ export interface RequestInput<T extends OpTypes, I extends Init = Init, C = {}>
       req: RenderedRequest
     },
   ) => void | Promise<void>
-  mock?: MockInput<T, I>
   auth?: AuthProfileName | false
   assertMode?: AssertMode
 }
 
-export interface MockResponse<B> {
-  data?: PartialSource<B>
-  init?: Init
-  headers?: Record<string, string>
-  delayMs?: number
+/** What the request being answered looks like to a mock: its values, as they were sent. */
+export interface MockReq<I> {
+  vars: ResolvedInit<I> & Record<string, unknown>
+  body: unknown
+  query: unknown
+  path: unknown
+  headers: Record<string, string>
 }
 
-export interface MockInput<T extends OpTypes, I> {
-  /**
-   * Echo request values into the generated response (fields it shares with the body, the path id).
-   * Default true; explicit `responses` always win.
-   */
-  reflect?: boolean
-  status?: keyof T['responses'] & number
-  responses?: {
-    [S in keyof T['responses'] & number]?:
-      | PartialSource<T['responses'][S]>
-      | MockResponse<T['responses'][S]>
+/**
+ * The answer a mock is about to give, one shape per status the operation declares so that checking `res.status` narrows
+ * `res.data`. Change `data`, `headers` and `delayMs` in place, or `respond` with another status.
+ */
+export type MockRes<T extends OpTypes> = {
+  [S in keyof T['responses'] & number]: {
+    status: S
+    data: T['responses'][S]
+    headers: Record<string, string>
+    /** Wait this long before answering. */
+    delayMs: number
+    /**
+     * Answer with another status the operation declares: its generated example, with `data` merged over it. Request values
+     * are echoed into a 2xx example as usual.
+     */
+    respond<R extends keyof T['responses'] & number>(
+      status: R,
+      data?: DeepPartial<T['responses'][R]>,
+    ): void
   }
-  when?: (req: {
-    vars: ResolvedInit<I>
-    body: unknown
-    query: unknown
-    path: unknown
-  }) => (keyof T['responses'] & number) | undefined
-}
+}[keyof T['responses'] & number]
+
+/** Runs when the `mock` environment answers this request, after the example is chosen, filled from the request and rendered. */
+export type MockHook<T extends OpTypes, I> = (
+  req: MockReq<I>,
+  res: MockRes<T>,
+) => void | Promise<void>
 
 export interface RequestOverrides<T extends OpTypes, I, C2> {
+  /** Added to the request's own tags. */
+  tags?: string[]
   vars?: Partial<ResolvedInit<I>> & Record<string, unknown>
   path?: Partial<Templated<T['params']['path']>>
   query?: Partial<Templated<T['params']['query']>>
@@ -160,7 +170,6 @@ export interface RequestOverrides<T extends OpTypes, I, C2> {
   data?: DeepPartial<Templated<T['body']>>
   capture?: { [K in keyof C2]: (res: ResponseOf<T>) => C2[K] }
   assert?: RequestInput<T, any, any>['assert']
-  mock?: { status?: keyof T['responses'] & number }
   auth?: AuthProfileName | false
   assertMode?: AssertMode
 }
@@ -171,8 +180,10 @@ export interface RequestDef<T extends OpTypes = AnyOp, I extends Init = Init, C
   readonly input: RequestInput<T, I, C>
   /** Deep-merge patches applied to the rendered data template, in order. */
   readonly dataPatches: readonly unknown[]
-  /** Explicit `.with({ vars })`; beats captures and params, only UI overrides are higher. */
+  /** Explicit `.with({ vars })`; beats captures and inputs, only UI overrides are higher. */
   readonly varOverrides: Readonly<Record<string, unknown>>
+  /** Set by `withMock`: how the mock environment answers this request. */
+  readonly mockHook?: MockHook<T, I>
   /** Phantom: lets sequence steps infer the captured type. */
   readonly _captured?: C
   with<C2 = {}>(o: RequestOverrides<T, I, C2>): RequestDef<T, I, C & C2>
@@ -208,7 +219,7 @@ export interface RenderedRequest {
 /** Where a placeholder's value came from, highest precedence first. */
 export interface VarUse {
   key: string
-  source: 'override' | 'capture' | 'param' | 'init' | 'config'
+  source: 'override' | 'capture' | 'input' | 'init' | 'config'
   /** Step that produced it, for captures. */
   step?: string
   /** A capture replaced a value of another type (e.g. a string id in an integer slot). */
@@ -241,6 +252,12 @@ export interface RunResult {
   seed?: number
   usedDrafts: boolean
   tags: string[]
+  /** The project file the request or flow comes from, relative to the project; set by the CLI. */
+  file?: string
+  /** How many times it was run when retries were allowed (1 = no retry); set by the CLI. */
+  attempts?: number
+  /** It failed, then passed on a retry; set by the CLI. */
+  flaky?: boolean
   status: 'pass' | 'fail' | 'error'
   startedAt: string
   durationMs: number