@toa.io/extensions.exposition 1.0.0-alpha.285 → 1.0.0-alpha.286

package/source/directives/auth/Scheme.ts

@@ -6,26 +6,26 @@ export class Scheme implements Directive {
   private readonly scheme: string
   private readonly Scheme: string
 
-  public constructor (scheme: string) {
+  public constructor(scheme: string) {
     this.scheme = scheme.toLowerCase()
     this.Scheme = scheme[0].toUpperCase() + scheme.substring(1)
   }
 
-  public authorize (_: Identity | null, context: Context): boolean {
-    if (context.request.headers.authorization === undefined)
-      return false
+  public authorize(_: Identity | null, context: Context): boolean {
+    if (context.request.headers.authorization === undefined) return false
 
     const [scheme] = split(context.request.headers.authorization)
 
     if (scheme !== this.scheme)
-      throw new http.Forbidden(this.Scheme +
-        ' authentication scheme is required to access this resource')
+      throw new http.Forbidden(
+        this.Scheme + ' authentication scheme is required to access this resource'
+      )
 
     return false
   }
 
   /** It admits nobody: it is there to refuse a scheme, not to authorize one. */
-  public admits (): boolean {
+  public admits(): boolean {
     return false
   }
 }

package/source/directives/auth/create.ts

@@ -1,7 +1,7 @@
 import { newid } from '@toa.io/generic'
 import type { Identity } from './types.js'
 
-export function create (credentials?: string): Identity {
+export function create(credentials?: string): Identity {
   return {
     id: newid(),
     scheme: credentials?.split(' ')[0] ?? null,

package/source/directives/auth/schemes.ts

@@ -21,7 +21,7 @@ export const PRIMARY: Remote = 'tokens'
  * The providers of a scheme, or nothing for a scheme that is not one — including a name a
  * plain object answers on its own, like `constructor`.
  */
-export function providers (scheme: string): Remote[] | undefined {
+export function providers(scheme: string): Remote[] | undefined {
   return Object.hasOwn(PROVIDERS, scheme) ? PROVIDERS[scheme as Scheme] : undefined
 }
 

package/source/directives/auth/split.ts

@@ -1,11 +1,10 @@
 import * as http from '../../HTTP/index.js'
 import { type Scheme } from './types.js'
 
-export function split (authorization: string): [Scheme, string] {
+export function split(authorization: string): [Scheme, string] {
   const space = authorization.indexOf(' ')
 
-  if (space === -1)
-    throw new http.Unauthorized('Malformed authorization header')
+  if (space === -1) throw new http.Unauthorized('Malformed authorization header')
 
   const Scheme = authorization.slice(0, space)
   const scheme = Scheme.toLowerCase() as Scheme

package/source/directives/auth/types.ts

@@ -1,5 +1,5 @@
 import { type Component } from '@toa.io/core'
-import { type Maybe } 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'
@@ -55,6 +55,9 @@ export interface Extension {
 
   /** 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 {
@@ -62,7 +65,7 @@ export interface Ban {
 }
 
 export type Context = io.Input & Extension
-export type AuthenticationResult = Maybe<{ identity: Identity, refresh: boolean }>
+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'

package/source/directives/cache/Cache.ts

@@ -1,5 +1,6 @@
 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'
@@ -9,7 +10,7 @@ export class Cache implements DirectiveFamily<Directive> {
   public readonly name: string = 'cache'
   public readonly mandatory: boolean = true
 
-  public create (name: string, value: any): Directive {
+  public create(name: string, value: any): Directive {
     const Class = constructors[name]
 
     if (Class === undefined)
@@ -18,15 +19,23 @@ export class Cache implements DirectiveFamily<Directive> {
     return new Class(value)
   }
 
-  public precall (): Output {
+  public precall(): Output {
     return null
   }
 
-  public async settle (directives: Directive[], context: AuthenticatedContext, response: http.OutgoingMessage): Promise<void> {
+  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
@@ -36,21 +45,47 @@ export class Cache implements DirectiveFamily<Directive> {
       return
     }
 
-    const method = context.request.method
-
-    if (method !== 'GET' && method !== 'HEAD')
-      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)
+    } 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

@@ -6,44 +6,38 @@ export class Control implements Directive {
   private control: string | null = null
   private vary: boolean = false
 
-  public constructor (value: string) {
+  public constructor(value: string) {
     this.value = value
   }
 
-  public static disabled (headers: Headers): boolean {
+  public static disabled(headers: Headers): boolean {
     const value = headers.get('cache-control')
 
-    if (value === null)
-      return false
+    if (value === null) return false
 
     const directives = mask(value)
 
     return (directives & NO_STORE) === NO_STORE
   }
 
-  public set (context: AuthenticatedContext, headers: Headers): void {
+  public set(context: AuthenticatedContext, headers: Headers): void {
     this.control ??= this.resolve(context)
 
-    if (Control.disabled(headers))
-      return
+    if (Control.disabled(headers)) return
 
     headers.set('cache-control', this.control)
 
-    if (this.vary)
-      headers.append('vary', 'authorization')
+    if (this.vary) headers.append('vary', 'authorization')
   }
 
-  protected resolve (request: AuthenticatedContext): string {
-    if (request.identity === null)
-      return this.value
+  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 & PRIVATE) === PRIVATE) this.vary = true
 
-    if ((directives & (PUBLIC | NO_CACHE)) === PUBLIC)
-      return 'no-cache, ' + this.value
+    if ((directives & (PUBLIC | NO_CACHE)) === PUBLIC) return 'no-cache, ' + this.value
 
     if ((directives & (PUBLIC | PRIVATE)) === 0) {
       this.vary = true
@@ -55,26 +49,31 @@ export class Control implements Directive {
   }
 }
 
-function mask (value: string): number {
+function mask(value: string): number {
   const directives = value.match(DIRECTIVES_RX)
 
-  if (directives === null)
-    return 0
+  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)
+    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/ig
+const DIRECTIVES_RX = /\b(private|public|no-cache|no-store)\b/gi
 
 const PUBLIC = 1
 const PRIVATE = 2

package/source/directives/cache/Exact.ts

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

package/source/directives/cache/etag.ts

@@ -0,0 +1,38 @@
+/**
+ * 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/cors/CORS.ts

@@ -24,7 +24,7 @@ export class CORS implements Interceptor {
     vary: 'origin'
   })
 
-  public intercept (input: Input): Output {
+  public intercept(input: Input): Output {
     const origin = input.request.headers.origin
 
     if (origin !== undefined && input.request.method === 'OPTIONS')
@@ -36,8 +36,10 @@ export class CORS implements Interceptor {
       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')
+        output.headers.set(
+          'access-control-expose-headers',
+          'authorization, content-type, content-length, date, etag, last-modified'
+        )
       }
 
       const method = input.request.method
@@ -49,12 +51,12 @@ export class CORS implements Interceptor {
     return null
   }
 
-  public reset (): void {
+  public reset(): void {
     this.requestHeaders = new Set(REQUEST_HEADERS)
     this.headers.set('access-control-allow-headers', this.allowedHeaders())
   }
 
-  public allow (header: string): void {
+  public allow(header: string): void {
     this.requestHeaders.add(header.toLowerCase())
     this.headers.set('access-control-allow-headers', this.allowedHeaders())
   }
@@ -64,11 +66,11 @@ export class CORS implements Interceptor {
    * fixed — an unsorted value would differ between otherwise identical processes,
    * and between one restart and the next.
    */
-  private allowedHeaders (): string {
+  private allowedHeaders(): string {
     return Array.from(this.requestHeaders).sort().join(', ')
   }
 
-  private preflightResponse (origin: string): Output {
+  private preflightResponse(origin: string): Output {
     this.headers.set('access-control-allow-origin', origin)
 
     return {

package/source/directives/dev/Development.ts

@@ -10,16 +10,15 @@ export class Development implements DirectiveFamily<Directive> {
   public readonly name: string = 'dev'
   public readonly mandatory: boolean = false
 
-  public create (name: string, value: unknown): Directive {
+  public create(name: string, value: unknown): Directive {
     const Class = constructors[name]
 
-    if (Class === undefined)
-      throw new Error(`Directive 'dev:${name}' is not implemented`)
+    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> {
+  public async precall(directives: Directive[], input: Input): Promise<Output> {
     let output = null
 
     for (const directive of directives) {

package/source/directives/dev/Faulty.ts

@@ -8,18 +8,23 @@ 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]')
+  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
+  public async apply(): Promise<Output> {
+    if (Math.random() > this.probability) return null
 
     throw new ServiceUnavailable()
   }

package/source/directives/dev/Sleep.ts

@@ -10,7 +10,7 @@ export class Sleep implements Directive {
   private static warned = false
   private readonly maximum: number
 
-  public constructor (value: number) {
+  public constructor(value: number) {
     assert.ok(Number.isInteger(value), '`dev:sleep` directive value must be an integer')
 
     if (!Sleep.warned) {
@@ -22,11 +22,10 @@ export class Sleep implements Directive {
     this.maximum = value
   }
 
-  public async apply (input: Input): Promise<Output> {
+  public async apply(input: Input): Promise<Output> {
     const value = input.request.headers.sleep as string | undefined
 
-    if (value === undefined)
-      return null
+    if (value === undefined) return null
 
     const [min, max] = this.parse(value)
 
@@ -40,12 +39,11 @@ export class Sleep implements Directive {
     return null
   }
 
-  private parse (value: string): [number, number] {
+  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()
+      if (!Array.isArray(pair) || pair.length !== 2) throw new Error()
 
       return pair
     } catch {

package/source/directives/dev/Stub.ts

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

package/source/directives/dev/Throw.ts

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

package/source/directives/flow/Compose.ts

@@ -9,11 +9,11 @@ import type { OutgoingMessage } from '../../HTTP/index.js'
 export class Compose implements Directive {
   private readonly expressions: Expression[]
 
-  public constructor (composition: any) {
+  public constructor(composition: any) {
     this.expressions = build(composition)
   }
 
-  public attach (context: Context): void {
+  public attach(context: Context): void {
     context.pipelines.response.push(async (message: OutgoingMessage) => {
       if (!(message.body instanceof Readable)) {
         console.warn('Response body is not a stream, skipping composition')
@@ -23,8 +23,11 @@ export class Compose implements Directive {
 
       assert.ok(message.body instanceof Readable, 'Response body is not a stream')
 
-      // @ts-expect-error -- objectMode is not defined in the type definition
-      assert.ok(message.body._readableState.objectMode, 'Response stream is not in object mode')
+      assert.ok(
+        // @ts-expect-error -- objectMode is not defined in the type definition
+        message.body._readableState.objectMode,
+        'Response stream is not in object mode'
+      )
 
       const $ = await this.compose(message.body)
 
@@ -32,7 +35,7 @@ export class Compose implements Directive {
     })
   }
 
-  private async compose (stream: Readable): Promise<unknown[]> {
+  private async compose(stream: Readable): Promise<unknown[]> {
     const $: unknown[] = []
 
     stream.on('data', (data) => $.push(data))
@@ -42,7 +45,7 @@ export class Compose implements Directive {
     return $
   }
 
-  private execute ($: unknown[]): unknown {
+  private execute($: unknown[]): unknown {
     let exception: Error | undefined
 
     for (const expression of this.expressions)
@@ -57,36 +60,39 @@ export class Compose implements Directive {
   }
 }
 
-function build (composition: any): Expression[] {
+function build(composition: any): Expression[] {
   return Array.isArray(composition)
     ? composition.map((variant) => compile(variant as object | string))
     : [compile(composition as object | string)]
 }
 
-function compile (composition: object | string): Expression {
-  const text = typeof composition === 'string'
-    ? `return ${composition}`
-    : `return ${json(composition)}`
+function compile(composition: object | string): Expression {
+  const text =
+    typeof composition === 'string'
+      ? `return ${composition}`
+      : `return ${json(composition)}`
 
   // eslint-disable-next-line @typescript-eslint/no-implied-eval,no-new-func
   return new Function('$', text) as Expression
 }
 
-function json (node: object | string): string {
+function json(node: object | string): string {
   if (typeof node === 'string')
-    if (node.startsWith('\\'))
-      return `"${node}"`
-    else
-      return node
+    if (node.startsWith('\\')) return `"${node}"`
+    else return node
 
   if (Array.isArray(node))
     return `[${node.map((v) => json(v as object | string)).join(',')}]`
 
-  if (node.constructor !== Object)
-    return JSON.stringify(node)
+  if (node.constructor !== Object) return JSON.stringify(node)
 
-  return '{' + Object.entries(node)
-    .map(([key, value]) => `"${key}": ${json(value as object | string)}`).join(',') + '}'
+  return (
+    '{' +
+    Object.entries(node)
+      .map(([key, value]) => `"${key}": ${json(value as object | string)}`)
+      .join(',') +
+    '}'
+  )
 }
 
 type Expression = ($: unknown[]) => unknown