@toa.io/extensions.exposition 1.0.0-alpha.291 → 1.0.0-alpha.293

package/source/directives/auth/types.ts

@@ -1,75 +0,0 @@
-import { type Component } from '@toa.io/core'
-import type { Maybe } from '@toa.io/core/types'
-import { type Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type * as http from '../../HTTP/index.js'
-import type * as io from '../../io.js'
-
-export interface Directive {
-  priority?: number
-
-  authorize: (
-    identity: Identity | null,
-    context: Context,
-    parameters: Parameter[]
-  ) => boolean | Promise<boolean>
-
-  /**
-   * Whether this admits the identity where that can be told without a request — which is
-   * what describing a method is. `undefined` says it cannot be told: a directive reading a
-   * route variable's value or the body has neither here, and one that is not implemented
-   * says the same by its absence. Nothing here may have an effect on the request.
-   */
-  admits?: (
-    identity: Identity | null,
-    context: Context
-  ) => boolean | undefined | Promise<boolean | undefined>
-
-  /**
-   * What this directive makes of what the method says about itself, which is the reverse of
-   * what it does to a request: a property it fills from the identity is taken out of the
-   * input, because it is not the caller's to send — and a description that offers one invites
-   * a caller to name an identity that is not theirs. Nothing here may have an effect on the
-   * request.
-   */
-  describe?: (introspection: Introspection) => Introspection
-
-  reply?: (context: Context) => http.OutgoingMessage | null
-
-  settle?: (context: Context, response: http.OutgoingMessage) => Promise<void>
-}
-
-export interface Identity {
-  readonly id: string
-  roles?: string[]
-  permissions?: Record<string, string[]>
-  scheme: string | null // null for transient identities
-
-  /** The component that verified the credentials; none for a transient identity. */
-  provider?: Remote
-  refresh: boolean
-}
-
-export interface Extension {
-  identity: Identity | null
-
-  /** the error code the presented credentials were rejected with, when they were */
-  rejection?: string
-
-  /** whether the identity was checked against the bans while being resolved */
-  vetted?: boolean
-}
-
-export interface Ban {
-  banned: boolean
-}
-
-export type Context = io.Input & Extension
-export type AuthenticationResult = Maybe<{ identity: Identity; refresh: boolean }>
-
-export type Scheme = 'basic' | 'token' | 'bearer' | 'code' | 'otp'
-export type Remote = 'basic' | 'federation' | 'tokens' | 'roles' | 'bans' | 'otp'
-export type Discovery = Record<Remote, Promise<Component>>
-export type Components = Partial<Record<Remote, Component>>
-
-export type Create = (name: string, value: any, ...args: any[]) => Directive

package/source/directives/cache/Cache.ts

@@ -1,92 +0,0 @@
-import { Control } from './Control.js'
-import { Exact } from './Exact.js'
-import { matches, tag } from './etag.js'
-import type { Output } from '../../io.js'
-import type { AuthenticatedContext, Directive } from './types.js'
-import type { DirectiveFamily } from '../../RTD/index.js'
-import type * as http from '../../HTTP/index.js'
-
-export class Cache implements DirectiveFamily<Directive> {
-  public readonly name: string = 'cache'
-  public readonly mandatory: boolean = true
-
-  public create(name: string, value: any): Directive {
-    const Class = constructors[name]
-
-    if (Class === undefined)
-      throw new Error(`Directive 'cache:${name}' is not implemented`)
-
-    return new Class(value)
-  }
-
-  public precall(): Output {
-    return null
-  }
-
-  public async settle(
-    directives: Directive[],
-    context: AuthenticatedContext,
-    response: http.OutgoingMessage
-  ): Promise<void> {
-    const directive = directives[0]
-    const method = context.request.method
-    const safe = method === 'GET' || method === 'HEAD'
-
-    response.headers ??= new Headers()
-
-    validate(context, response, response.headers, safe)
-
-    // `cache:exact` sets what it is given, whatever the method: whether a reply may be
-    // stored at all is not a question about the method's cacheability, and a token
-    // endpoint answers a POST it must not have kept
-    if (directive instanceof Exact) {
-      directive.set(context, response.headers)
-
-      return
-    }
-
-    if (!safe) return
-
-    if (directive === undefined) {
-      if (context.identity !== null && !Control.disabled(response.headers)) {
-        response.headers.set('cache-control', 'private')
-        response.headers.append('vary', 'authorization')
-      }
-    } else directive.set(context, response.headers)
-  }
-}
-
-/**
- * The validators a reply carries: the timestamp as `last-modified`, whatever the method, and
- * on a safe one the version as its `etag`. A client that sends the tag back in `if-none-match`
- * already has the representation and is told so, with the tag as it sent it. A reply without
- * a version has no tag: nothing identifies it but its body, and hashing that on every reply
- * is what a version is for.
- */
-// eslint-disable-next-line max-params
-function validate(
-  context: AuthenticatedContext,
-  response: http.OutgoingMessage,
-  headers: Headers,
-  safe: boolean
-): void {
-  const { version, modified } = response
-
-  if (modified !== undefined)
-    headers.set('last-modified', new Date(modified).toUTCString())
-
-  if (version === undefined || !safe) return
-
-  const sent = context.request.headers['if-none-match']
-
-  if (sent !== undefined && matches(sent, version)) {
-    response.status = 304
-    response.body = undefined
-    headers.set('etag', sent)
-  } else headers.set('etag', tag(version))
-}
-
-const constructors: Record<string, new (value: any) => Directive> = {
-  control: Control,
-  exact: Exact
-}

package/source/directives/cache/Control.ts

@@ -1,81 +0,0 @@
-import { match } from 'matchacho'
-import type { AuthenticatedContext, Directive } from './types.js'
-
-export class Control implements Directive {
-  protected readonly value: string
-  private control: string | null = null
-  private vary: boolean = false
-
-  public constructor(value: string) {
-    this.value = value
-  }
-
-  public static disabled(headers: Headers): boolean {
-    const value = headers.get('cache-control')
-
-    if (value === null) return false
-
-    const directives = mask(value)
-
-    return (directives & NO_STORE) === NO_STORE
-  }
-
-  public set(context: AuthenticatedContext, headers: Headers): void {
-    this.control ??= this.resolve(context)
-
-    if (Control.disabled(headers)) return
-
-    headers.set('cache-control', this.control)
-
-    if (this.vary) headers.append('vary', 'authorization')
-  }
-
-  protected resolve(request: AuthenticatedContext): string {
-    if (request.identity === null) return this.value
-
-    const directives = mask(this.value)
-
-    if ((directives & PRIVATE) === PRIVATE) this.vary = true
-
-    if ((directives & (PUBLIC | NO_CACHE)) === PUBLIC) return 'no-cache, ' + this.value
-
-    if ((directives & (PUBLIC | PRIVATE)) === 0) {
-      this.vary = true
-
-      return 'private, ' + this.value
-    }
-
-    return this.value
-  }
-}
-
-function mask(value: string): number {
-  const directives = value.match(DIRECTIVES_RX)
-
-  if (directives === null) return 0
-
-  let mask = 0
-
-  for (const directive of directives)
-    mask |= match<number>(
-      directive,
-      'private',
-      PRIVATE,
-      'public',
-      PUBLIC,
-      'no-cache',
-      NO_CACHE,
-      'no-store',
-      NO_STORE,
-      0
-    )
-
-  return mask
-}
-
-const DIRECTIVES_RX = /\b(private|public|no-cache|no-store)\b/gi
-
-const PUBLIC = 1
-const PRIVATE = 2
-const NO_CACHE = 4
-const NO_STORE = 8

package/source/directives/cache/Exact.ts

@@ -1,7 +0,0 @@
-import { Control } from './Control.js'
-
-export class Exact extends Control {
-  protected override resolve(): string {
-    return this.value
-  }
-}

package/source/directives/cache/etag.ts

@@ -1,38 +0,0 @@
-/**
- * An entity tag is its version in quotes, `"3"`, or the same marked weak, `W/"3"`. A client
- * sends one back in `if-match` and `if-none-match`; what it sent is compared here as a string
- * and parsed only where a version is needed of it.
- */
-export function tag(version: number): string {
-  return `"${version}"`
-}
-
-/** Whether the tag a client sent names the version, strong or weak. */
-export function matches(sent: string, version: number): boolean {
-  const strong = tag(version)
-
-  return sent === strong || sent === 'W/' + strong
-}
-
-/** The version a tag names, or nothing for a tag that is not one. */
-export function parse(sent: string): number | null {
-  const strong = sent.startsWith('W/') ? sent.slice(2) : sent
-
-  if (
-    strong.length < 3 ||
-    strong.length > 34 ||
-    !strong.startsWith('"') ||
-    !strong.endsWith('"')
-  )
-    return null
-
-  const digits = strong.slice(1, -1)
-
-  for (let i = 0; i < digits.length; i++) {
-    const code = digits.charCodeAt(i)
-
-    if (code < 48 || code > 57) return null
-  }
-
-  return Number.parseInt(digits)
-}

package/source/directives/cache/index.ts

@@ -1,3 +0,0 @@
-import { Cache } from './Cache.js'
-
-export const cache = new Cache()

package/source/directives/cache/types.ts

@@ -1,9 +0,0 @@
-import type { Input } from '../../io.js'
-
-export interface Directive {
-  set: (input: Input, headers: Headers) => void
-}
-
-export interface AuthenticatedContext extends Input {
-  identity?: unknown | null
-}

package/source/directives/cors/CORS.test.ts

@@ -1,75 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { CORS } from './CORS.js'
-import type { Input } from '../../io.js'
-
-const input = (method: string, headers: Record<string, string>): Input =>
-  ({
-    request: { method, headers },
-    pipelines: { body: [], response: [] }
-  }) as unknown as Input
-
-describe('cors', () => {
-  let cors: CORS
-
-  beforeEach(() => {
-    cors = new CORS()
-    cors.reset()
-  })
-
-  it('should answer a preflight', () => {
-    const output = cors.intercept(
-      input('OPTIONS', {
-        origin: 'https://hello.world',
-        'access-control-request-method': 'GET'
-      })
-    )
-
-    assert.equal(output?.status, 204)
-    assert.equal(output?.headers?.get('access-control-allow-origin'), 'https://hello.world')
-  })
-
-  it('should allow OPTIONS, so that one can be preflighted at all', () => {
-    const output = cors.intercept(
-      input('OPTIONS', {
-        origin: 'https://hello.world',
-        'access-control-request-method': 'OPTIONS'
-      })
-    )
-
-    assert.match(output?.headers?.get('access-control-allow-methods') ?? '', /\bOPTIONS\b/)
-  })
-
-  it('should pass an OPTIONS that is not a preflight through', () => {
-    /*
-     * A browser puts `Origin` on every request whose method is not `GET` or `HEAD`, its own
-     * `OPTIONS` included — so answering this one here would put introspection out of reach
-     * of any page. Do not restore the `Origin`-only test.
-     */
-    const output = cors.intercept(input('OPTIONS', { origin: 'https://hello.world' }))
-
-    assert.equal(output, null)
-  })
-
-  it('should decorate a reply that is not a preflight', () => {
-    const request = input('OPTIONS', { origin: 'https://hello.world' })
-
-    cors.intercept(request)
-
-    const message = {}
-
-    for (const transform of request.pipelines.response) transform(message)
-
-    const headers = (message as { headers?: Headers }).headers
-
-    assert.equal(headers?.get('access-control-allow-origin'), 'https://hello.world')
-    assert.equal(headers?.get('access-control-allow-credentials'), 'true')
-    assert.equal(headers?.get('vary'), 'origin')
-  })
-
-  it('should pass a request carrying no origin through', () => {
-    assert.equal(cors.intercept(input('OPTIONS', {})), null)
-    assert.equal(cors.intercept(input('GET', {})), null)
-  })
-})

package/source/directives/cors/CORS.ts

@@ -1,88 +0,0 @@
-import type { Input, Output } from '../../io.js'
-import type { Interceptor } from '../../Interception.js'
-
-/** What is allowed before any directive asks for more. */
-const REQUEST_HEADERS = [
-  'accept',
-  'authorization',
-  'content-type',
-  'if-match',
-  'if-none-match'
-]
-
-export class CORS implements Interceptor {
-  public readonly name = 'cors'
-
-  private requestHeaders = new Set<string>(REQUEST_HEADERS)
-
-  private readonly headers = new Headers({
-    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK, OPTIONS',
-    'access-control-allow-credentials': 'true',
-    'access-control-allow-headers': this.allowedHeaders(),
-    'access-control-max-age': '3600',
-    'cache-control': 'max-age=3600',
-    vary: 'origin'
-  })
-
-  public intercept(input: Input): Output {
-    const origin = input.request.headers.origin
-    const requested = input.request.headers['access-control-request-method']
-
-    /*
-     * A preflight is `OPTIONS` carrying `Access-Control-Request-Method`, and only that. A
-     * browser puts `Origin` on every request whose method is not `GET` or `HEAD` — its own
-     * `OPTIONS` included, same-origin or not — so answering that one here would put
-     * introspection out of reach of any page.
-     */
-    if (origin !== undefined && requested !== undefined && input.request.method === 'OPTIONS')
-      return this.preflightResponse(origin)
-
-    input.pipelines.response.push((output) => {
-      output.headers ??= new Headers()
-
-      if (origin !== undefined) {
-        output.headers.set('access-control-allow-origin', origin)
-        output.headers.set('access-control-allow-credentials', 'true')
-        output.headers.set(
-          'access-control-expose-headers',
-          'authorization, content-type, content-length, date, etag, last-modified'
-        )
-      }
-
-      const method = input.request.method
-
-      if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS')
-        output.headers.append('vary', 'origin')
-    })
-
-    return null
-  }
-
-  public reset(): void {
-    this.requestHeaders = new Set(REQUEST_HEADERS)
-    this.headers.set('access-control-allow-headers', this.allowedHeaders())
-  }
-
-  public allow(header: string): void {
-    this.requestHeaders.add(header.toLowerCase())
-    this.headers.set('access-control-allow-headers', this.allowedHeaders())
-  }
-
-  /**
-   * Sorted, because the set is filled as branches merge and their order is not
-   * fixed — an unsorted value would differ between otherwise identical processes,
-   * and between one restart and the next.
-   */
-  private allowedHeaders(): string {
-    return Array.from(this.requestHeaders).sort().join(', ')
-  }
-
-  private preflightResponse(origin: string): Output {
-    this.headers.set('access-control-allow-origin', origin)
-
-    return {
-      status: 204,
-      headers: this.headers
-    }
-  }
-}

package/source/directives/cors/index.ts

@@ -1,3 +0,0 @@
-import { CORS } from './CORS.js'
-
-export const cors = new CORS()

package/source/directives/dev/Development.ts

@@ -1,41 +0,0 @@
-import { Stub } from './Stub.js'
-import { Throw } from './Throw.js'
-import { Sleep } from './Sleep.js'
-import { Faulty } from './Faulty.js'
-import { type Directive } from './types.js'
-import type { Input, Output } from '../../io.js'
-import type { DirectiveFamily } from '../../RTD/index.js'
-
-export class Development implements DirectiveFamily<Directive> {
-  public readonly name: string = 'dev'
-  public readonly mandatory: boolean = false
-
-  public create(name: string, value: unknown): Directive {
-    const Class = constructors[name]
-
-    if (Class === undefined) throw new Error(`Directive 'dev:${name}' is not implemented`)
-
-    return new Class(value)
-  }
-
-  public async precall(directives: Directive[], input: Input): Promise<Output> {
-    let output = null
-
-    for (const directive of directives) {
-      const out = await directive.apply(input)
-
-      if (out !== null)
-        if (output !== null) throw new Error('`dev` directives ambiguous output')
-        else output = out
-    }
-
-    return output
-  }
-}
-
-const constructors: Record<string, new (value: any) => Directive> = {
-  stub: Stub,
-  throw: Throw,
-  sleep: Sleep,
-  faulty: Faulty
-}

package/source/directives/dev/Faulty.ts

@@ -1,31 +0,0 @@
-import assert from 'node:assert'
-import { ServiceUnavailable } from '../../HTTP/index.js'
-import { cors } from '../cors/index.js'
-import type { Output } from '../../io.js'
-import type { Directive } from './types.js'
-
-export class Faulty implements Directive {
-  private static readonly warned = false
-  private readonly probability: number
-
-  public constructor(probability: number) {
-    assert.ok(
-      typeof probability === 'number',
-      '`dev:faulty` directive value must be a number'
-    )
-    assert.ok(
-      probability > 0 && probability <= 1,
-      '`dev:faulty` directive value must be in the range (0, 1]'
-    )
-
-    this.probability = probability
-
-    cors.allow('faulty')
-  }
-
-  public async apply(): Promise<Output> {
-    if (Math.random() > this.probability) return null
-
-    throw new ServiceUnavailable()
-  }
-}

package/source/directives/dev/Sleep.ts

@@ -1,53 +0,0 @@
-import assert from 'node:assert'
-import { setTimeout } from 'node:timers/promises'
-import { console } from 'openspan'
-import { cors } from '../cors/index.js'
-import { BadRequest } from '../../HTTP/index.js'
-import type { Directive } from './types.js'
-import type { Input, Output } from '../../io.js'
-
-export class Sleep implements Directive {
-  private static warned = false
-  private readonly maximum: number
-
-  public constructor(value: number) {
-    assert.ok(Number.isInteger(value), '`dev:sleep` directive value must be an integer')
-
-    if (!Sleep.warned) {
-      console.warn('Sleep directive is enabled', { maximum: value })
-      Sleep.warned = true
-    }
-
-    cors.allow('sleep')
-    this.maximum = value
-  }
-
-  public async apply(input: Input): Promise<Output> {
-    const value = input.request.headers.sleep as string | undefined
-
-    if (value === undefined) return null
-
-    const [min, max] = this.parse(value)
-
-    if (min < 0 || max < 0 || min > max || max > this.maximum)
-      throw new BadRequest('Invalid sleep duration')
-
-    const duration = Math.floor(Math.random() * (max - min)) + min
-
-    await setTimeout(duration)
-
-    return null
-  }
-
-  private parse(value: string): [number, number] {
-    try {
-      const pair = JSON.parse(value) as [number, number]
-
-      if (!Array.isArray(pair) || pair.length !== 2) throw new Error()
-
-      return pair
-    } catch {
-      throw new BadRequest('Invalid sleep duration value')
-    }
-  }
-}

package/source/directives/dev/Stub.ts

@@ -1,14 +0,0 @@
-import type { Output } from '../../io.js'
-import type { Directive } from './types.js'
-
-export class Stub implements Directive {
-  private readonly value: unknown
-
-  public constructor(value: unknown) {
-    this.value = value
-  }
-
-  public apply(): Output {
-    return { body: this.value }
-  }
-}

package/source/directives/dev/Throw.ts

@@ -1,14 +0,0 @@
-import type { Output } from '../../io.js'
-import type { Directive } from './types.js'
-
-export class Throw implements Directive {
-  private readonly message: string
-
-  public constructor(message: string) {
-    this.message = message
-  }
-
-  public apply(): Output {
-    throw new Error(this.message)
-  }
-}

package/source/directives/dev/index.ts

@@ -1,3 +0,0 @@
-import { Development } from './Development.js'
-
-export const dev = new Development()

package/source/directives/dev/types.ts

@@ -1,5 +0,0 @@
-import type { Input, Output } from '../../io.js'
-
-export interface Directive {
-  apply: (input: Input) => Promise<Output> | Output
-}