@specbook/core 0.1.0 → 0.3.0

package/src/spec-config.ts

@@ -3,11 +3,46 @@
  * the CLI's `preview` and the browser viewer, so both read a spec the same way.
  */
 
+import type { OAuthSettings } from './oauth'
+
 const isUrl = (s: string) => /^https?:\/\//i.test(s)
 
 export interface JsonAuthProfile {
   title: string
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
+  /** present when the scheme has an authorization code flow the UI can sign in to */
+  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, address: Address): OAuthSettings | undefined {
+  if (typeof s.openIdConnectUrl !== 'string' || s.openIdConnectUrl === '') return undefined
+  try {
+    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, address: Address): OAuthSettings | undefined {
+  const flow = s.flows?.authorizationCode ?? (s.flow === 'accessCode' ? s : undefined)
+  if (!flow?.authorizationUrl || !flow?.tokenUrl) return undefined
+  const abs = (field: 'authorizationUrl' | 'tokenUrl', u: string) => {
+    try {
+      return address(field, u)
+    } catch {
+      return u
+    }
+  }
+  return {
+    authorizationUrl: abs('authorizationUrl', flow.authorizationUrl),
+    tokenUrl: abs('tokenUrl', flow.tokenUrl),
+    ...(flow.scopes && Object.keys(flow.scopes).length ? { scopes: flow.scopes } : {}),
+  }
 }
 
 export interface SpecAuth {
@@ -16,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) =>
@@ -28,15 +69,47 @@ 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): 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}}}`
     let apply: JsonAuthProfile['apply'] | undefined
     let title = name
+    let oauth: OAuthSettings | undefined
     if (s.type === 'apiKey') {
       const key = s.name as string
       if (s.in === 'header') apply = { headers: { [key]: ref } }
@@ -55,10 +128,12 @@ export function authFromSpec(api: any): SpecAuth {
       title = `${name} (basic auth, paste base64 of user:password)`
     } else if (s.type === 'oauth2' || s.type === 'openIdConnect') {
       apply = { headers: { authorization: `Bearer ${ref}` } }
-      title = `${name} (OAuth, paste an access token)`
+      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
-    out.auth[name] = { title, apply }
+    out.auth[name] = { title, apply, ...(oauth ? { oauth } : {}) }
     out.secrets[secret] = {}
   }
   // the document's top-level `security` says which scheme most operations use
@@ -69,16 +144,138 @@ export function authFromSpec(api: any): SpecAuth {
   return out
 }
 
-/** Where the API lives, from `servers[0]` (OpenAPI 3) or `host`/`basePath` (Swagger 2). */
-export function liveBaseUrl(api: any, source: string): string | undefined {
-  const server = api.servers?.[0]?.url as string | undefined
-  if (server) {
-    if (isUrl(server)) return server.replace(/\/$/, '')
-    if (isUrl(source)) return new URL(server, source).toString().replace(/\/$/, '')
-    return undefined
+/** One server a spec lists, as an environment the UI can switch to. */
+export interface ServerEntry {
+  /** the environment name: `live` for the first, else a slug of its description or host */
+  name: string
+  url: string
+  description?: string
+}
+
+/** `live` plus this many minus one: a spec with a server per region should not bury the picker. */
+export const MAX_SERVERS = 20
+
+const slug = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 24)
+    .replace(/-+$/, '')
+
+/** An absolute address for one `servers` entry: variables at their defaults, a relative URL against `source`. */
+function resolveServer(entry: any, source: string | undefined): string | undefined {
+  if (typeof entry?.url !== 'string') return undefined
+  const url = entry.url
+    .replace(/\{([^}]+)\}/g, (whole: string, key: string) => {
+      const d = entry.variables?.[key]?.default
+      return d === undefined || d === null ? whole : String(d)
+    })
+    .trim()
+  if (/\{[^}]*\}/.test(url)) return undefined
+  if (isUrl(url)) return url.replace(/\/+$/, '')
+  if (source) {
+    try {
+      return new URL(url, source).toString().replace(/\/+$/, '')
+    } catch {
+      /* not an address */
+    }
   }
-  if (api.host)
-    return `${api.schemes?.[0] ?? 'https'}://${api.host}${api.basePath ?? ''}`.replace(/\/$/, '')
-  if (isUrl(source)) return new URL(source).origin
   return undefined
 }
+
+/**
+ * The servers a document lists, as environments. The first is `live` (what a single-server spec has always
+ * had); the rest are named from their description, else their host, and are always a valid environment name.
+ *
+ * `needsBaseUrl` is true when the first server is relative and `source` cannot resolve it: the person is
+ * asked for the address, and what they type is `live`. `omitted` counts usable servers beyond `MAX_SERVERS`.
+ */
+export function openApiServers(
+  api: any,
+  source: string,
+): { servers: ServerEntry[]; needsBaseUrl: boolean; omitted: number } {
+  const src = isUrl(source) ? source : undefined
+  const listed: any[] = Array.isArray(api.servers) ? api.servers : []
+  const servers: ServerEntry[] = []
+  const describe = (e: any) =>
+    typeof e?.description === 'string' && e.description.trim() !== ''
+      ? { description: e.description.trim() as string }
+      : {}
+
+  if (listed.length === 0) {
+    // Swagger 2, or an OpenAPI 3 document that says nothing: the host, else wherever it was fetched from
+    if (api.host)
+      servers.push({
+        name: 'live',
+        url: `${api.schemes?.[0] ?? 'https'}://${api.host}${api.basePath ?? ''}`.replace(
+          /\/+$/,
+          '',
+        ),
+      })
+    else if (src) servers.push({ name: 'live', url: new URL(src).origin })
+    return { servers, needsBaseUrl: false, omitted: 0 }
+  }
+
+  const first = resolveServer(listed[0], src)
+  if (first) servers.push({ name: 'live', url: first, ...describe(listed[0]) })
+  const needsBaseUrl =
+    !first && typeof listed[0]?.url === 'string' && !/^https?:\/\//i.test(listed[0].url)
+
+  const taken = new Set(['mock', 'live'])
+  const seen = new Set(servers.map((x) => x.url))
+  let omitted = 0
+  for (const entry of listed.slice(1)) {
+    const url = resolveServer(entry, src)
+    if (!url || seen.has(url)) continue
+    if (servers.length >= MAX_SERVERS) {
+      omitted++
+      continue
+    }
+    seen.add(url)
+    const host = (() => {
+      try {
+        return new URL(url).host
+      } catch {
+        return ''
+      }
+    })()
+    const base = slug(describe(entry).description ?? '') || slug(host) || 'server'
+    let name = base
+    for (let n = 2; taken.has(name); n++) name = `${base}-${n}`
+    taken.add(name)
+    servers.push({ name, url, ...describe(entry) })
+  }
+  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