@toa.io/extensions.exposition 1.0.0-alpha.269 → 1.0.0-alpha.270

package/source/HTTP/messages.ts

@@ -1,4 +1,5 @@
 import { Readable } from 'node:stream'
+import { createHash } from 'node:crypto'
 import * as contentType from 'content-type'
 import { console } from 'openspan'
 import { formats } from './formats'
@@ -81,6 +82,9 @@ function send (message: OutgoingMessage, context: Context, response: http.Server
 
   const buf = context.encoder.encode(message.body)
 
+  if (message.etag === true && conditional(context, response, buf))
+    return
+
   response
     .setHeader('content-type', context.encoder.type)
     .setHeader('content-length', buf.length.toString())
@@ -88,6 +92,30 @@ function send (message: OutgoingMessage, context: Context, response: http.Server
     .end(buf)
 }
 
+/**
+ * Tags a reply that carries no version with a hash of the body being sent, and answers
+ * `304` when the client already has it. The tag is taken from the encoded body rather
+ * than from a serialization of its own, so it identifies the representation — which is
+ * what `vary` says.
+ */
+function conditional (context: Context, response: http.ServerResponse, buf: Buffer): boolean {
+  const etag = `"${createHash('sha256').update(buf).digest('hex')}"`
+
+  response.setHeader('etag', etag)
+
+  if (context.request.headers['if-none-match'] !== etag)
+    return false
+
+  response
+    .setHeader('content-length', '0')
+    .appendHeader('vary', 'accept')
+
+  response.statusCode = 304
+  response.end()
+
+  return true
+}
+
 function stream (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
   const encoded = message.headers !== undefined && message.headers.has('content-type')
 
@@ -173,6 +201,9 @@ export interface OutgoingMessage {
   status?: number
   headers?: Headers
   body?: any
+
+  /** tag the response with a hash of the encoded body, see `conditional` */
+  etag?: boolean
 }
 
 export interface Query {

package/source/RTD/Directives.ts

@@ -28,6 +28,12 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
 
   create: (name: string, ...rest: any[]) => TDirective
 
+  /**
+   * Puts the directives of one route in the order they must run in. Called once, when
+   * the set is built — the order cannot depend on the request.
+   */
+  arrange?: (directives: TDirective[]) => void
+
   preflight?: (directives: TDirective[],
     request: Context & TExtension,
     parameters: Parameter[]) => Output | Promise<Output>

package/source/directives/auth/Authorization.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert'
 import { match } from 'matchacho'
 import { console } from 'openspan'
-import { minimatch } from 'minimatch'
+import { Minimatch } from 'minimatch'
 import * as http from '../../HTTP'
 import { Anonymous } from './Anonymous'
 import { Id } from './Id'
@@ -61,11 +61,14 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
       () => new Class(value))
   }
 
+  public arrange (directives: Directive[]): void {
+    directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
+  }
+
   public async preflight (directives: Directive[],
     context: Context,
     parameters: Parameter[]): Promise<Output> {
     context.identity = await this.resolve(context.authority, context.request.headers.authorization)
-    directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
 
     for (const directive of directives) {
       const allow = await directive.authorize(context.identity, context, parameters)
@@ -162,7 +165,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
 
     return Object.entries(permissions).some(([pattern, methods]) => {
       return methods.some((method) => method === '*' || method === context.request.method) &&
-        minimatch(context.request.url, pattern)
+        glob(pattern).match(context.request.url)
     })
   }
 
@@ -175,6 +178,29 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   }
 }
 
+/**
+ * `minimatch(str, pattern)` compiles the pattern on every call, and a permission is
+ * matched on every request the identity makes. Patterns arrive with an identity, hence
+ * the bound.
+ */
+function glob (pattern: string): Minimatch {
+  let compiled = GLOBS.get(pattern)
+
+  if (compiled === undefined) {
+    if (GLOBS.size >= GLOBS_LIMIT)
+      GLOBS.clear()
+
+    compiled = new Minimatch(pattern)
+
+    GLOBS.set(pattern, compiled)
+  }
+
+  return compiled
+}
+
+const GLOBS = new Map<string, Minimatch>()
+const GLOBS_LIMIT = 1024
+
 const constructors: Record<string, new (value: any, argument?: any) => Directive> = {
   anonymous: Anonymous,
   anyone: Anyone,

package/source/directives/io/Directive.ts

@@ -1,16 +1,17 @@
-import type { Remote } from '@toa.io/core'
+import type { Sync } from './lib/throttle'
 import type { Parameter } from '../../RTD'
 import type { Input as Context } from '../../io'
 import type * as http from '../../HTTP'
 
 export interface Directive {
   preflight: (context: Context, parameters: Parameter[]) => void
-  settle?: (context: Context, response: http.OutgoingMessage) => Promise<void> | void
-  dispose?: () => void
+
+  /** Synchronous by contract: settling holds the response, and none of it needs I/O. */
+  settle?: (context: Context, response: http.OutgoingMessage) => void
 }
 
 export interface Constructor {
   validate: (value: unknown) => void
 
-  new (value: any, counter: Promise<Remote>, route: string): Directive
+  new (value: any, sync: Sync, route: string): Directive
 }

package/source/directives/io/IO.ts

@@ -1,7 +1,7 @@
 import { Output } from './Output'
 import { Input } from './Input'
 import { Throttle } from './Throttle'
-import type { Remote } from '@toa.io/core'
+import { Sync } from './lib/throttle'
 import type * as http from '../../HTTP'
 import type { Parameter, DirectiveFamily } from '../../RTD'
 import type { Remotes } from '../../Remotes'
@@ -11,8 +11,8 @@ export class IO implements DirectiveFamily<Directive> {
   public readonly name = 'io'
   public readonly mandatory = true
 
-  /** Throttling counts through a component, because only a component has a stash aspect. */
-  private counter: Promise<Remote> | null = null
+  /** Throttling reconciles through a component, because only a component has a stash aspect. */
+  private sync: Sync | null = null
 
   // eslint-disable-next-line max-params
   public create (name: string, value: unknown, remotes: Remotes, route: string): Directive {
@@ -25,9 +25,9 @@ export class IO implements DirectiveFamily<Directive> {
 
     // discovering boots the component, so nothing is discovered until something throttles
     if (name === 'throttle')
-      this.counter ??= remotes.discover('exposition', 'stash')
+      this.sync ??= new Sync(remotes.discover('exposition', 'stash'))
 
-    return new Directive(value, this.counter!, route)
+    return new Directive(value, this.sync!, route)
   }
 
   public preflight (directives: Directive[], context: http.Context,
@@ -46,14 +46,19 @@ export class IO implements DirectiveFamily<Directive> {
     return null
   }
 
-  public async settle (directives: Directive[], context: http.Context, output: http.OutgoingMessage): Promise<void> {
+  public settle (directives: Directive[], context: http.Context,
+    output: http.OutgoingMessage): void {
     for (const directive of directives)
-      await directive.settle?.(context, output)
+      directive.settle?.(context, output)
   }
 
-  public dispose (directives: Directive[]): void {
-    for (const directive of directives)
-      directive.dispose?.()
+  /**
+   * The ticker belongs to the family rather than to any route's directives, and the
+   * factory disposes every route it made — so this runs once per route at shutdown,
+   * and disposing an already stopped ticker is what makes that harmless.
+   */
+  public dispose (): void {
+    this.sync?.dispose()
   }
 }
 

package/source/directives/io/Input.ts

@@ -5,10 +5,10 @@ import type { Directive } from './Directive'
 import type { Input as Context } from '../../io'
 
 export class Input implements Directive {
-  private readonly permissions: Permissions
+  private readonly allowed: Set<string>
 
   public constructor (permissions: Permissions) {
-    this.permissions = permissions
+    this.allowed = new Set(permissions)
   }
 
   public static validate (permissions: unknown): asserts permissions is Permissions {
@@ -43,7 +43,7 @@ export class Input implements Directive {
 
   private violation (value: Message | Message[]): string | undefined {
     if (!Array.isArray(value))
-      return Object.keys(value).find((key) => !this.permissions.includes(key))
+      return Object.keys(value).find((key) => !this.allowed.has(key))
 
     for (const item of value) {
       const property = this.violation(item)

package/source/directives/io/Output.ts

@@ -10,6 +10,7 @@ export class Output implements Directive {
   private readonly disabled: boolean = false
   private readonly omitted: boolean = true
   private readonly permissions: string[] = []
+  private readonly allowed: Set<string>
 
   public constructor (permissions: Permissions) {
     if (typeof permissions === 'boolean')
@@ -20,6 +21,8 @@ export class Output implements Directive {
 
     else
       this.permissions = permissions
+
+    this.allowed = new Set(this.permissions)
   }
 
   public static validate (permissions: unknown): asserts permissions is Permissions {
@@ -59,11 +62,16 @@ export class Output implements Directive {
     }
   }
 
-  private fit (message: Message): Message | undefined {
-    const entries = Object.entries(message)
-      .filter(([key]) => this.permissions.includes(key))
+  /** 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 Object.fromEntries(entries)
+    return output
   }
 }
 

package/source/directives/io/Throttle.ts

@@ -1,7 +1,6 @@
 import { TooManyRequests } from '../../HTTP'
 import * as schemas from './schemas'
-import { parse, Quotas, type Declaration } from './lib/throttle'
-import type { Remote } from '@toa.io/core'
+import { parse, Quotas, type Declaration, type Sync } from './lib/throttle'
 import type * as http from '../../HTTP'
 import type { Parameter } from '../../RTD'
 import type { Directive } from './Directive'
@@ -9,10 +8,10 @@ import type { Directive } from './Directive'
 export class Throttle implements Directive {
   private readonly quotas: Quotas
 
-  public constructor (declaration: Declaration, counter: Promise<Remote>, route: string) {
-    const configuration = parse(declaration)
+  public constructor (declaration: Declaration, sync: Sync, route: string) {
+    this.quotas = Quotas.create(parse(declaration), route)
 
-    this.quotas = Quotas.create(configuration, counter, route)
+    sync.register(this.quotas)
   }
 
   public static validate (declaration: unknown): asserts declaration is Declaration {
@@ -20,15 +19,13 @@ export class Throttle implements Directive {
   }
 
   public preflight (context: http.Context, parameters: Parameter[]): void {
-    if (!this.quotas.ok(context, parameters))
-      throw new TooManyRequests()
-  }
+    const retry = this.quotas.check(context, parameters)
 
-  public async settle (context: http.Context, output: http.OutgoingMessage): Promise<void> {
-    await this.quotas.use(context, output)
+    if (retry > 0)
+      throw new TooManyRequests(retry)
   }
 
-  public dispose (): void {
-    this.quotas.dispose()
+  public settle (context: http.Context, output: http.OutgoingMessage): void {
+    this.quotas.use(context, output)
   }
 }

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

@@ -2,8 +2,7 @@ import { parse, type Configuration } from './Configuration'
 
 const rest: Omit<Configuration, 'key' | 'condition'> = {
   interval: 1,
-  requests: 1,
-  cooldown: 1
+  requests: 1
 }
 
 it('should convert key', () => {

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

@@ -3,7 +3,6 @@ export interface Configuration {
   condition?: KeyCondition[]
   requests: number
   interval: number
-  cooldown: number
 }
 
 interface Rule<T, K = unknown> {
@@ -31,14 +30,13 @@ export interface Declaration extends Omit<Configuration, 'key' | 'condition'> {
 }
 
 export function parse (declaration: Declaration): Configuration {
-  const { key, condition, requests, interval, cooldown } = declaration
+  const { key, condition, requests, interval } = declaration
 
   return {
     key: mapKey(key),
     condition: mapCondition(condition),
     requests,
-    interval: interval * 1000,
-    cooldown: cooldown * 1000
+    interval: interval * 1000
   }
 }