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

package/source/directives/io/Output.ts

@@ -1,81 +0,0 @@
-import { Stream } from 'node:stream'
-import { console } from 'openspan'
-import * as schemas from './schemas.js'
-import type { Message } from './Message.js'
-import type { Directive } from './Directive.js'
-import type { Input as Context } from '../../io.js'
-import type { OutgoingMessage } from '../../HTTP/index.js'
-
-export class Output implements Directive {
-  /** whether the reply passes whole, which is when the schema is the operation's own */
-  public readonly disabled: boolean = false
-
-  /** what a reply may carry, which is therefore what the output schema states */
-  public readonly allowed: Set<string>
-  private readonly omitted: boolean = true
-  private readonly permissions: string[] = []
-
-  public constructor(permissions: Permissions) {
-    if (typeof permissions === 'boolean')
-      if (permissions) this.disabled = true
-      else this.omitted = false
-    else this.permissions = permissions
-
-    this.allowed = new Set(this.permissions)
-  }
-
-  public static validate(permissions: unknown): asserts permissions is Permissions {
-    schemas.output.validate(permissions, "Incorrect 'io:output' format")
-  }
-
-  public precall(context: Context): void {
-    context.pipelines.response.push(this.restriction(context))
-  }
-
-  private restriction(context: Context) {
-    return (message: OutgoingMessage): void => {
-      // what the gateway built is its own — a code and a message — and a restriction has
-      // nothing to say about it; everything else is a reply the operation returned, and is
-      // restricted whatever status it carries
-      const error = message.authentic === true
-      const stream = message.body instanceof Stream
-      const none = message.body === undefined || message.body === null
-
-      if (this.disabled || error || stream || none) return
-
-      if (typeof message.body !== 'object' || this.permissions.length === 0) {
-        if (this.omitted)
-          console.warn(
-            "Permissions for 'io:output' are not specified properly, response omitted",
-            { path: context.url.pathname }
-          )
-
-        delete message.body
-
-        return
-      }
-
-      schemas.message.validate<Message>(
-        message.body,
-        "'io:output' expects response to be an object or array of objects"
-      )
-
-      if (Array.isArray(message.body))
-        message.body = message.body.map((entity) => this.fit(entity as Message))
-      else message.body = this.fit(message.body)
-    }
-  }
-
-  /** Runs per entity of a collection, hence the set and the absence of intermediates. */
-  private fit(message: Message): Message {
-    const output: Message = {}
-
-    // the keys of the entity, so that the response keeps the order it was built in
-    for (const key of Object.keys(message))
-      if (this.allowed.has(key)) output[key] = message[key]
-
-    return output
-  }
-}
-
-export type Permissions = string[] | boolean

package/source/directives/io/Status.test.ts

@@ -1,88 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Status } from './Status.js'
-import { Output } from './Output.js'
-import type { Input as Context } from '../../io.js'
-import type { OutgoingMessage } from '../../HTTP/index.js'
-
-const status = new Status('status')
-
-function context(): Context {
-  return {
-    pipelines: { body: [], response: [] },
-    url: { pathname: '/' }
-  } as unknown as Context
-}
-
-it('should take the status from the property and remove it', () => {
-  const response: OutgoingMessage = { body: { status: 400, error: 'invalid_request' } }
-
-  status.settle(context(), response)
-
-  assert.equal(response.status, 400)
-  assert.deepEqual(response.body, { error: 'invalid_request' })
-})
-
-it('should leave a reply that states no status alone', () => {
-  const response: OutgoingMessage = { body: { id: 'x' } }
-
-  status.settle(context(), response)
-
-  assert.equal(response.status, undefined)
-  assert.deepEqual(response.body, { id: 'x' })
-})
-
-it('should refuse a status that is not one', () => {
-  for (const value of ['400', null, {}, true])
-    assert.throws(() => {
-      status.settle(context(), { body: { status: value } } as OutgoingMessage)
-    }, /`io:status` expects 'status' to be a number/)
-})
-
-it('should refuse a declaration that is not a property name', () => {
-  for (const value of [1, null, {}, ['status']])
-    assert.throws(() => Status.validate(value), /`io:status` must be a string/)
-})
-
-it('should have a reply it named the status of restricted, whatever that status is', () => {
-  for (const stated of [200, 400]) {
-    const ctx = context()
-    const output = new Output(['code', 'error'])
-
-    output.precall(ctx, [])
-
-    const response: OutgoingMessage = {
-      body: { status: stated, code: 'SplxlO', error: 'invalid_grant', secret: 'x' }
-    }
-
-    status.settle(ctx, response)
-
-    for (const transform of ctx.pipelines.response) transform(response)
-
-    assert.equal(response.status, stated)
-    assert.deepEqual(response.body, { code: 'SplxlO', error: 'invalid_grant' })
-  }
-})
-
-it('should leave a failure the gateway built alone, on such a route too', () => {
-  const ctx = context()
-  const output = new Output(['code'])
-
-  output.precall(ctx, [])
-
-  // what `Server.fail` builds out of an exception, on a route that also declares `io:status`
-  const response: OutgoingMessage = {
-    status: 422,
-    authentic: true,
-    body: { code: 'NOT_FOUND', message: 'nope' }
-  }
-
-  for (const transform of ctx.pipelines.response) transform(response)
-
-  assert.deepEqual(
-    response.body,
-    { code: 'NOT_FOUND', message: 'nope' },
-    'a code and a message are not what a restriction has anything to say about'
-  )
-})

package/source/directives/io/Status.ts

@@ -1,47 +0,0 @@
-import assert from 'node:assert'
-import type { Directive } from './Directive.js'
-import type * as http from '../../HTTP/index.js'
-
-/**
- * The status of the reply, taken from a property of what the operation returned and removed
- * from it — an outcome the operation knows and the transport does not, like a protocol that
- * states its error as a body rather than as a status of its own.
- *
- * Settled rather than transformed, so the status is set before anything reads it. A reply of
- * 300 or above is left as the operation built it, which `io:output` does not restrict: a
- * failure and a success are different shapes, and one list of permitted properties does not
- * describe both.
- */
-export class Status implements Directive {
-  private readonly property: string
-
-  public constructor(property: unknown) {
-    this.property = property as string
-  }
-
-  public static validate(value: unknown): asserts value is string {
-    assert.ok(typeof value === 'string', '`io:status` must be a string')
-  }
-
-  public precall(): void {
-    // nothing to do until the operation has answered
-  }
-
-  public settle(_: unknown, response: http.OutgoingMessage): void {
-    const body: unknown = response.body
-
-    if (body === null || typeof body !== 'object' || !(this.property in body)) return
-
-    const value: unknown = (body as Record<string, unknown>)[this.property]
-
-    assert.ok(
-      typeof value === 'number',
-      `\`io:status\` expects '${this.property}' to be a number`
-    )
-
-    response.status = value
-
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    delete (body as Record<string, unknown>)[this.property]
-  }
-}

package/source/directives/io/Throttle.ts

@@ -1,30 +0,0 @@
-import { TooManyRequests } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { parse, Quotas, type Declaration, type Sync } from './lib/throttle/index.js'
-import type * as http from '../../HTTP/index.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Directive } from './Directive.js'
-
-export class Throttle implements Directive {
-  private readonly quotas: Quotas
-
-  public constructor(declaration: Declaration, sync: Sync, route: string) {
-    this.quotas = Quotas.create(parse(declaration), route)
-
-    sync.register(this.quotas)
-  }
-
-  public static validate(declaration: unknown): asserts declaration is Declaration {
-    schemas.throttle.validate(declaration, "Incorrect 'io:throttle' format")
-  }
-
-  public precall(context: http.Context, parameters: Parameter[]): void {
-    const retry = this.quotas.check(context, parameters)
-
-    if (retry > 0) throw new TooManyRequests(retry)
-  }
-
-  public settle(context: http.Context, output: http.OutgoingMessage): void {
-    this.quotas.use(context, output)
-  }
-}

package/source/directives/io/index.ts

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

package/source/directives/io/lib/throttle/Configuration.test.ts

@@ -1,72 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { parse, type Configuration } from './Configuration.js'
-
-const rest: Omit<Configuration, 'key' | 'condition'> = {
-  interval: 1,
-  requests: 1
-}
-
-it('should convert key', () => {
-  const result: Partial<Configuration> = {
-    key: [
-      {
-        method: 'ip'
-      }
-    ]
-  }
-
-  assert.partialDeepStrictEqual(parse({ key: 'ip', ...rest }), result)
-  assert.partialDeepStrictEqual(parse({ key: ['ip'], ...rest }), result)
-})
-
-it('should convert condition', () => {
-  assert.partialDeepStrictEqual(
-    parse({ key: ['ip', 'path'], condition: { status: '404' }, ...rest }),
-    {
-      condition: [
-        {
-          method: 'status',
-          options: '404'
-        }
-      ]
-    }
-  )
-
-  assert.partialDeepStrictEqual(
-    parse({ key: 'ip', condition: { status: '404' }, ...rest }),
-    {
-      condition: [
-        {
-          method: 'status',
-          options: '404'
-        }
-      ]
-    }
-  )
-})
-
-it('should convert a key component that takes an argument', () => {
-  assert.partialDeepStrictEqual(parse({ key: { segment: 'id' }, ...rest }), {
-    key: [
-      {
-        method: 'segment',
-        options: 'id'
-      }
-    ]
-  })
-})
-
-it('should convert a mixed key', () => {
-  assert.partialDeepStrictEqual(
-    parse({ key: ['route', { segment: 'id' }, 'identity'], ...rest }),
-    {
-      key: [
-        { method: 'route' },
-        { method: 'segment', options: 'id' },
-        { method: 'identity' }
-      ]
-    }
-  )
-})

package/source/directives/io/lib/throttle/Configuration.ts

@@ -1,68 +0,0 @@
-export interface Configuration {
-  key: KeyComponent[]
-  condition?: KeyCondition[]
-  requests: number
-  interval: number
-}
-
-interface Rule<T, K = unknown> {
-  method: T
-  options?: K
-}
-
-export type KeyComponentMethod = 'ip' | 'path' | 'route' | 'identity' | 'segment'
-export type KeyConditionMethod = 'status'
-
-export type KeyComponent = Rule<KeyComponentMethod>
-export type KeyCondition = Rule<KeyConditionMethod>
-
-/** A bare component, or the one that takes an argument. */
-type KeyEntry = KeyComponentMethod | { segment: string }
-type KeyDeclaration = KeyEntry | KeyEntry[]
-
-type ConditionDeclaration =
-  | Record<KeyConditionMethod, unknown>
-  | Array<Record<KeyConditionMethod, unknown>>
-
-export interface Declaration extends Omit<Configuration, 'key' | 'condition'> {
-  key: KeyDeclaration
-  condition?: ConditionDeclaration
-}
-
-export function parse(declaration: Declaration): Configuration {
-  const { key, condition, requests, interval } = declaration
-
-  return {
-    key: mapKey(key),
-    condition: mapCondition(condition),
-    requests,
-    interval: interval * 1000
-  }
-}
-
-function mapKey(declaration: KeyDeclaration): KeyComponent[] {
-  const entries = Array.isArray(declaration) ? declaration : [declaration]
-
-  // a bare `path`, or `segment: id` for the ones that take an argument
-  return entries.flatMap((entry): KeyComponent[] =>
-    typeof entry === 'string'
-      ? [{ method: entry }]
-      : Object.entries(entry).map(([method, options]) => ({
-          method: method as KeyComponentMethod,
-          options
-        }))
-  )
-}
-
-function mapCondition(declaration?: ConditionDeclaration): KeyCondition[] | undefined {
-  if (declaration === undefined) return
-
-  // reduce to a single object, then map entries to rules
-  const conditions = Array.isArray(declaration) ? declaration : [declaration]
-  const single = conditions.reduce((acc, condition) => ({ ...acc, ...condition }), {})
-
-  return Object.entries(single).map(([method, options]) => ({
-    method,
-    options
-  })) as KeyCondition[]
-}

package/source/directives/io/lib/throttle/Keys.ts

@@ -1,53 +0,0 @@
-import { createHash } from 'node:crypto'
-import { Components, type Component } from './components/index.js'
-import { Conditions, type Condition } from './conditions/index.js'
-import type { KeyComponent, KeyCondition } from './Configuration.js'
-import type { Parameter } from '../../../../RTD/index.js'
-import type { Input as Context, Output } from '../../../../io.js'
-
-const NONE: Parameter[] = []
-
-export class Keys {
-  private readonly components: Component[]
-  private readonly conditions?: Condition[]
-
-  public constructor(components: Component[], conditions?: Condition[]) {
-    this.components = components
-    this.conditions = conditions
-  }
-
-  public static create(
-    componentRules: KeyComponent[],
-    conditionRules?: KeyCondition[],
-    route: string = ''
-  ): Keys {
-    const components = componentRules.map(
-      (rule) => new Components[rule.method](rule.options, route)
-    )
-
-    const conditions = conditionRules?.map(
-      (rule) => new Conditions[rule.method](rule.options)
-    )
-
-    return new this(components, conditions)
-  }
-
-  /** The key of the request, or nothing when a component cannot key it. */
-  public get(context: Context, parameters: Parameter[] = NONE): string | undefined {
-    const hash = createHash('sha256')
-
-    for (const component of this.components) {
-      const part = component.get(context, parameters)
-
-      if (part === undefined) return
-
-      hash.update(part)
-    }
-
-    return hash.digest('hex')
-  }
-
-  public matches(input: Context, output: Output): boolean {
-    return this.conditions?.some((condition) => !condition.match(input, output)) !== true
-  }
-}