@toa.io/extensions.exposition 1.0.0-alpha.151 → 1.0.0-alpha.153

package/schemas/io/throttle.cos.yaml

@@ -0,0 +1,36 @@
+definitions:
+  component: &component
+    type: string
+    enum: [ip, path]
+  condition: &condition
+    type: object
+    properties:
+      status:
+        type: number
+type: object
+properties:
+  key:
+    anyOf:
+      - *component
+      - type: array
+        items: *component
+        minItems: 1
+  condition:
+    anyOf:
+      - *condition
+      - type: array
+        items: *condition
+        minItems: 1
+  requests:
+    type: integer
+    minimum: 1
+  interval: &interval
+    description: Seconds
+    type: integer
+    minimum: 1
+  cooldown: *interval
+required:
+  - key
+  - requests
+  - interval
+  - cooldown

package/source/Directive.test.ts

@@ -11,14 +11,16 @@ const families: Array<jest.MockedObjectDeep<DirectiveFamily>> = [
     mandatory: true,
     create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
     preflight: jest.fn(),
-    settle: jest.fn()
+    settle: jest.fn(),
+    dispose: jest.fn()
   },
   {
     name: 'bar',
     mandatory: false,
     create: jest.fn((_0: string, _1: any, _2: any) => generate() as any),
     preflight: jest.fn(),
-    settle: jest.fn()
+    settle: jest.fn(),
+    dispose: jest.fn()
   }
 ]
 

package/source/Directive.ts

@@ -36,12 +36,18 @@ export class Directives implements RTD.Directives {
       if (set.family.settle !== undefined)
         await set.family.settle(set.directives, context, response)
   }
+
+  public dispose (): void {
+    for (const set of this.sets)
+      set.family.dispose?.(set.directives)
+  }
 }
 
 export class DirectivesFactory implements RTD.DirectiveFactory {
   private readonly remotes: Remotes
   private readonly families: Record<string, RTD.DirectiveFamily> = {}
   private readonly mandatory: string[] = []
+  private readonly instances: Directives[] = []
 
   public constructor (families: RTD.DirectiveFamily[], remotes: Remotes) {
     for (const family of families) {
@@ -88,7 +94,16 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
         directives
       })
 
-    return new Directives(sets)
+    const directives = new Directives(sets)
+
+    this.instances.push(directives)
+
+    return directives
+  }
+
+  public dispose (): void {
+    for (const directives of this.instances)
+      directives.dispose()
   }
 }
 

package/source/Gateway.ts

@@ -65,6 +65,8 @@ export class Gateway extends Connector {
   }
 
   protected override dispose (): void {
+    this.tree.dispose()
+
     console.info('Gateway is closed')
   }
 

package/source/HTTP/Server.ts

@@ -29,7 +29,9 @@ export class Server extends Connector {
 
     this.server.on('clientError', (error, socket) => {
       console.warn('Client connection error', error)
-      socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
+
+      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
+      else socket.destroy()
     })
   }
 
@@ -70,6 +72,20 @@ export class Server extends Connector {
   }
 
   private listener (request: http.IncomingMessage, response: http.ServerResponse): void {
+    request.once('error', (error) => {
+      console.warn('Request error', errorAttributes(request, error))
+
+      if (!response.writableEnded)
+        response.destroy()
+    })
+
+    request.socket.once('error', (error) => {
+      console.warn('Socket error', errorAttributes(request, error))
+
+      if (!response.writableEnded)
+        response.destroy()
+    })
+
     const invalid = validate(request)
 
     if (invalid !== null) {
@@ -80,9 +96,6 @@ export class Server extends Connector {
       return
     }
 
-    request.once('error', (error) => console.warn('Request error', errorAttributes(request, error)))
-    request.socket.once('error', (error) => console.warn('Socket error', errorAttributes(request, error)))
-
     if (request.method === undefined || !this.properties.methods.has(request.method)) {
       response.writeHead(501).end()
 
@@ -113,7 +126,6 @@ export class Server extends Connector {
       .finally(() => {
         request.removeAllListeners('error')
         request.socket.removeAllListeners('error')
-        response.removeAllListeners('error')
       })
   }
 
@@ -139,22 +151,36 @@ export class Server extends Connector {
 
   private fail (context: Context, response: http.ServerResponse) {
     return async (exception: Error) => {
-      if (!context.request.complete)
-        await adam(context.request)
-
-      response.statusCode = exception instanceof Exception ? exception.status : 500
-
-      const message: OutgoingMessage = { status: response.statusCode }
-
-      if (context.encoder === null)
-        message.body = undefined
-      else if (exception instanceof ClientError || this.properties.debug)
-        message.body =
-          exception instanceof Exception
-            ? exception.body
-            : exception.stack ?? exception.message
-
-      await write(context, response, message)
+      try {
+        if (!context.request.complete)
+          await adam(context.request)
+
+        if (!response.writableEnded) {
+          response.statusCode = exception instanceof Exception ? exception.status : 500
+
+          const message: OutgoingMessage = { status: response.statusCode }
+
+          // eslint-disable-next-line max-depth
+          if (context.encoder === null)
+            message.body = undefined
+          else if (exception instanceof ClientError || this.properties.debug)
+            message.body =
+              exception instanceof Exception
+                ? exception.body
+                : exception.stack ?? exception.message
+
+          await write(context, response, message)
+        }
+      } catch (final) {
+        console.error('Error in error handler', final)
+
+        if (!response.writableEnded)
+          try {
+            response.writeHead(500).end()
+          } catch (e) {
+            // Nothing more we can do
+          }
+      }
     }
   }
 }

package/source/HTTP/exceptions.ts

@@ -36,18 +36,6 @@ export class NotFound extends ClientError {
   }
 }
 
-export class Conflict extends ClientError {
-  public constructor (body?: any) {
-    super(409, body)
-  }
-}
-
-export class UnprocessableEntity extends ClientError {
-  public constructor (body?: any) {
-    super(422, body)
-  }
-}
-
 export class MethodNotAllowed extends ClientError {
   public constructor () {
     super(405)
@@ -60,9 +48,9 @@ export class NotAcceptable extends ClientError {
   }
 }
 
-export class UnsupportedMediaType extends ClientError {
-  public constructor () {
-    super(415)
+export class Conflict extends ClientError {
+  public constructor (body?: any) {
+    super(409, body)
   }
 }
 
@@ -77,3 +65,21 @@ export class RequestEntityTooLarge extends ClientError {
     super(413, body)
   }
 }
+
+export class UnsupportedMediaType extends ClientError {
+  public constructor () {
+    super(415)
+  }
+}
+
+export class UnprocessableEntity extends ClientError {
+  public constructor (body?: any) {
+    super(422, body)
+  }
+}
+
+export class TooManyRequests extends ClientError {
+  public constructor () {
+    super(429)
+  }
+}

package/source/RTD/Directives.ts

@@ -6,10 +6,12 @@ import type { Output } from '../io'
 export interface Directives {
   preflight: (context: Context, parameters: Parameter[]) => Promise<Output>
   settle: (context: Context, response: OutgoingMessage) => Promise<void>
+  dispose: () => void
 }
 
 export interface DirectiveFactory {
   create: (directives: syntax.Directive[]) => Directives
+  dispose: () => void
 }
 
 export interface DirectiveSet {
@@ -30,4 +32,6 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
   settle?: (directives: TDirective[],
     request: Context & TExtension,
     response: OutgoingMessage) => void | Promise<void>
+
+  dispose?: (directives: TDirective[]) => void
 }

package/source/RTD/Route.ts

@@ -7,6 +7,7 @@ export class Route {
   public readonly variables: number = 0
   public readonly segments: Segment[]
   private readonly node: Node
+  private readonly wildcard: boolean = false
 
   public constructor (segments: Segment[], node: Node) {
     this.root = segments.length === 0
@@ -14,8 +15,10 @@ export class Route {
     this.node = node
 
     for (const segment of segments)
-      if (segment.fragment === null)
+      if (segment.fragment === null) {
         this.variables++
+        this.wildcard ||= segment.wildcard === true
+      }
   }
 
   public match (fragments: string[], parameters: Parameter[]): Match | null {
@@ -27,11 +30,14 @@ export class Route {
 
       if (segment.fragment === null && segment.placeholder !== null)
         parameters.push({ name: segment.placeholder, value: fragments[i] })
+
+      if (segment.fragment === null && segment.wildcard === true)
+        parameters.push({ name: '**', value: fragments.slice(this.segments.length - 1).join('/') })
     }
 
     const exact = this.segments.length === fragments.length
 
-    if (exact && !this.node.intermediate)
+    if ((exact && !this.node.intermediate) || this.wildcard)
       return { node: this.node, parameters }
     else
       return this.matchNested(fragments, parameters)

package/source/RTD/Tree.ts

@@ -39,6 +39,10 @@ export class Tree {
     this.trunk.merge(branch)
   }
 
+  public dispose (): void {
+    this.directives.dispose()
+  }
+
   private createNode
   (node: syntax.Node, protect: boolean, extension?: unknown): Node {
     const context: Context = {

package/source/RTD/segment.ts

@@ -15,6 +15,7 @@ export function fragment (path: string): string[] {
 function parse (segment: string): Segment {
   if (segment[0] === ':') return { fragment: null, placeholder: segment.substring(1) }
   else if (segment === '*') return { fragment: null, placeholder: null }
+  else if (segment === '**') return { fragment: null, placeholder: null, wildcard: true }
   else return { fragment: segment }
 }
 
@@ -23,4 +24,5 @@ export type Segment = {
 } | {
   fragment: null
   placeholder: string | null
+  wildcard?: boolean
 }

package/source/directives/io/Directive.ts

@@ -1,7 +1,10 @@
-import type { Input } from '../../io'
+import type { Input as Context } from '../../io'
+import type * as http from '../../HTTP'
 
 export interface Directive {
-  attach: (context: Input) => void
+  preflight: (context: Context) => void
+  settle?: (context: Context, response: http.OutgoingMessage) => Promise<void> | void
+  dispose?: () => void
 }
 
 export interface Constructor {

package/source/directives/io/IO.ts

@@ -1,7 +1,8 @@
 import { Output } from './Output'
 import { Input } from './Input'
+import { Throttle } from './Throttle'
+import type * as http from '../../HTTP'
 import type { Constructor, Directive } from './Directive'
-import type { Input as Context } from '../../io'
 import type { DirectiveFamily } from '../../RTD'
 
 export class IO implements DirectiveFamily<Directive> {
@@ -19,25 +20,36 @@ export class IO implements DirectiveFamily<Directive> {
     return new Directive(value)
   }
 
-  public preflight (directives: Directive[], context: Context): null {
+  public preflight (directives: Directive[], context: http.Context): null {
     let restricted = false
 
     for (const directive of directives) {
       restricted ||= directive instanceof Output
 
-      directive.attach(context)
+      directive.preflight(context)
     }
 
     if (!restricted)
-      DENIAL.attach(context)
+      DENIAL.preflight(context)
 
     return null
   }
+
+  public async settle (directives: Directive[], context: http.Context, output: http.OutgoingMessage): Promise<void> {
+    for (const directive of directives)
+      await directive.settle?.(context, output)
+  }
+
+  public dispose (directives: Directive[]): void {
+    for (const directive of directives)
+      directive.dispose?.()
+  }
 }
 
 const constructors: Record<string, Constructor> = {
+  input: Input,
   output: Output,
-  input: Input
+  throttle: Throttle
 }
 
 const DENIAL: Output = new Output([])

package/source/directives/io/Input.ts

@@ -15,7 +15,7 @@ export class Input implements Directive {
     schemas.input.validate<Permissions>(permissions, 'Incorrect \'io:input\' format')
   }
 
-  public attach (context: Context): void {
+  public preflight (context: Context): void {
     context.pipelines.body.push((body) => this.check(body))
   }
 

package/source/directives/io/Output.ts

@@ -26,7 +26,7 @@ export class Output implements Directive {
     schemas.output.validate(permissions, 'Incorrect \'io:output\' format')
   }
 
-  public attach (context: Context): void {
+  public preflight (context: Context): void {
     context.pipelines.response.push(this.restriction(context))
   }
 

package/source/directives/io/Throttle.ts

@@ -0,0 +1,32 @@
+import { TooManyRequests } from '../../HTTP'
+import * as schemas from './schemas'
+import { parse, Quotas, type Declaration } from './lib/throttle'
+import type * as http from '../../HTTP'
+import type { Directive } from './Directive'
+
+export class Throttle implements Directive {
+  private readonly quotas: Quotas
+
+  public constructor (declaration: Declaration) {
+    const configuration = parse(declaration)
+
+    this.quotas = Quotas.create(configuration)
+  }
+
+  public static validate (declaration: unknown): asserts declaration is Declaration {
+    schemas.throttle.validate(declaration, 'Incorrect \'io:throttle\' format')
+  }
+
+  public preflight (context: http.Context): void {
+    if (!this.quotas.ok(context))
+      throw new TooManyRequests()
+  }
+
+  public settle (context: http.Context, output: http.OutgoingMessage): void {
+    this.quotas.use(context, output)
+  }
+
+  public dispose (): void {
+    this.quotas.dispose()
+  }
+}

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

@@ -0,0 +1,40 @@
+import { parse, type Configuration } from './Configuration'
+
+const rest: Omit<Configuration, 'key' | 'condition'> = {
+  interval: 1,
+  requests: 1,
+  cooldown: 1
+}
+
+it('should convert key', () => {
+  const result: Partial<Configuration> = {
+    key: [
+      {
+        method: 'ip'
+      }
+    ]
+  }
+
+  expect(parse({ key: 'ip', ...rest })).toMatchObject(result)
+  expect(parse({ key: ['ip'], ...rest })).toMatchObject(result)
+})
+
+it('should convert condition', () => {
+  expect(parse({ key: ['ip', 'path'], condition: { status: '404' }, ...rest })).toMatchObject({
+    condition: [
+      {
+        method: 'status',
+        options: '404'
+      }
+    ]
+  })
+
+  expect(parse({ key: 'ip', condition: { status: '404' }, ...rest })).toMatchObject({
+    condition: [
+      {
+        method: 'status',
+        options: '404'
+      }
+    ]
+  })
+})

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

@@ -0,0 +1,58 @@
+export interface Configuration {
+  key: KeyComponent[]
+  condition?: KeyCondition[]
+  requests: number
+  interval: number
+  cooldown: number
+}
+
+interface Rule<T, K = unknown> {
+  method: T
+  options?: K
+}
+
+export type KeyComponentMethod = 'ip' | 'path'
+export type KeyConditionMethod = 'status'
+
+export type KeyComponent = Rule<KeyComponentMethod>
+export type KeyCondition = Rule<KeyConditionMethod>
+
+type KeyDeclaration = KeyComponentMethod | KeyComponentMethod[]
+
+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, cooldown } = declaration
+
+  return {
+    key: mapKey(key),
+    condition: mapCondition(condition),
+    requests,
+    interval: interval * 1000,
+    cooldown: cooldown * 1000
+  }
+}
+
+function mapKey (declaration: KeyDeclaration): KeyComponent[] {
+  const methods = Array.isArray(declaration) ? declaration : [declaration]
+
+  return methods.map((method) => ({ method }))
+}
+
+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/Interval.ts

@@ -0,0 +1,31 @@
+import assert from 'node:assert'
+import { EventEmitter } from 'node:events'
+
+export class Interval extends EventEmitter {
+  public number: number = 0
+  private interval: ReturnType<typeof setInterval> | null = null
+
+  public constructor (interval: number) {
+    super()
+
+    const number = Math.ceil(Date.now() / interval)
+    const shift = number * interval - Date.now()
+
+    assert.ok(shift >= 0, 'shift must be positive')
+
+    setTimeout(() => this.start(interval), shift)
+  }
+
+  public start (interval: number): void {
+    this.interval = setInterval(() => this.emit('tick'), interval)
+  }
+
+  public dispose (): void {
+    if (this.interval !== null) {
+      clearInterval(this.interval)
+      this.interval = null
+    }
+
+    this.removeAllListeners()
+  }
+}

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

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto'
+import { Components, type Component } from './components'
+import { Conditions, type Condition } from './conditions'
+import type { KeyComponent, KeyCondition } from './Configuration'
+import type { Input as Context, Output } from '../../../../io'
+
+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[]): Keys {
+    const components = componentRules.map((rule) => new Components[rule.method](rule.options))
+    const conditions = conditionRules?.map((rule) => new Conditions[rule.method](rule.options))
+
+    return new this(components, conditions)
+  }
+
+  public get (context: Context): string {
+    const hash = createHash('sha256')
+
+    for (const component of this.components)
+      hash.update(component.get(context))
+
+    return hash.digest('hex')
+  }
+
+  public match (input: Context, output: Output): string | null {
+    const miss = this.conditions?.some((condition) => !condition.match(input, output))
+
+    if (miss === true)
+      return null
+    else
+      return this.get(input)
+  }
+}

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

@@ -0,0 +1,22 @@
+export class Quota {
+  private readonly limit: number = 0
+  private used: number = 0
+
+  public constructor (limit: number) {
+    this.limit = limit
+  }
+
+  public get idle (): boolean {
+    return this.used === 0
+  }
+
+  public use (count = 1): boolean {
+    this.used += count
+
+    return this.used < this.limit
+  }
+
+  public reset (): void {
+    this.used = 0
+  }
+}