@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.31

package/source/directives/cors/CORS.ts

@@ -3,26 +3,32 @@ import type { Interceptor } from '../../Interception'
 
 export class CORS implements Interceptor {
   public readonly name = 'cors'
-  public readonly mandatory = true
 
-  private readonly allowedHeaders = new Set<string>(['accept', 'authorization', 'content-type'])
+  private readonly requestHeaders = new Set<string>([
+    'accept',
+    'authorization',
+    'content-type',
+    'etag',
+    'if-match',
+    'if-none-match'
+  ])
 
   private readonly headers = new Headers({
     'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE',
     'access-control-allow-credentials': 'true',
-    'access-control-allow-headers': Array.from(this.allowedHeaders).join(', '),
+    'access-control-allow-headers': Array.from(this.requestHeaders).join(', '),
     'access-control-max-age': '3600',
-    'cache-control': 'public, max-age=3600',
+    'cache-control': 'max-age=3600',
     vary: 'origin'
   })
 
   public intercept (input: Input): Output {
-    const origin = input.headers.origin
+    const origin = input.request.headers.origin
 
     if (origin === undefined)
       return null
 
-    if (input.method === 'OPTIONS')
+    if (input.request.method === 'OPTIONS')
       return this.preflightResponse(origin)
 
     input.pipelines.response.push((output) => {
@@ -31,16 +37,18 @@ export class CORS implements Interceptor {
       output.headers.set('access-control-expose-headers',
         'authorization, content-type, content-length, etag')
 
-      if (input.method === 'GET' || input.method === 'HEAD' || input.method === 'OPTIONS')
+      const method = input.request.method
+
+      if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS')
         output.headers.append('vary', 'origin')
     })
 
     return null
   }
 
-  public allowHeader (header: string): void {
-    this.allowedHeaders.add(header.toLowerCase())
-    this.headers.set('access-control-allow-headers', Array.from(this.allowedHeaders).join(', '))
+  public allow (header: string): void {
+    this.requestHeaders.add(header.toLowerCase())
+    this.headers.set('access-control-allow-headers', Array.from(this.requestHeaders).join(', '))
   }
 
   private preflightResponse (origin: string): Output {

package/source/directives/dev/Development.ts

@@ -2,17 +2,17 @@ import { Stub } from './Stub'
 import { Throw } from './Throw'
 import { type Directive } from './types'
 import type { Input, Output } from '../../io'
-import type { Family } from '../../Directive'
+import type { DirectiveFamily } from '../../RTD'
 
-export class Development implements Family<Directive> {
+export class Development implements DirectiveFamily<Directive> {
   public readonly name: string = 'dev'
   public readonly mandatory: boolean = false
 
-  public create (name: string, value: any): Directive {
+  public create (name: string, value: unknown): Directive {
     const Class = constructors[name]
 
     if (Class === undefined)
-      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+      throw new Error(`Directive 'dev:${name}' is not implemented.`)
 
     return new Class(value)
   }

package/source/directives/index.ts

@@ -1,11 +1,13 @@
-import { dev } from './dev'
 import { authorization } from './auth'
 import { cache } from './cache'
-import { octets } from './octets'
 import { cors } from './cors'
+import { dev } from './dev'
+import { octets } from './octets'
+import { io } from './io'
 import { vary } from './vary'
-import type { Family } from '../Directive'
+import { req } from './require'
+import type { DirectiveFamily } from '../RTD'
 import type { Interceptor } from '../Interception'
 
-export const families: Family[] = [authorization, cache, octets, vary, dev]
+export const families: DirectiveFamily[] = [authorization, io, cache, vary, req, octets, dev]
 export const interceptors: Interceptor[] = [cors]

package/source/directives/io/Directive.ts

@@ -0,0 +1,11 @@
+import type { Input } from '../../io'
+
+export interface Directive {
+  attach: (context: Input) => void
+}
+
+export interface Constructor {
+  validate: (value: unknown) => void
+
+  new (value: any): Directive
+}

package/source/directives/io/IO.ts

@@ -0,0 +1,43 @@
+import { Output } from './Output'
+import { Input } from './Input'
+import type { Constructor, Directive } from './Directive'
+import type { Input as Context } from '../../io'
+import type { DirectiveFamily } from '../../RTD'
+
+export class IO implements DirectiveFamily<Directive> {
+  public readonly name = 'io'
+  public readonly mandatory = true
+
+  public create (name: string, value: unknown): Directive {
+    if (!(name in constructors))
+      throw new Error(`Directive 'io:${name}' is not implemented.`)
+
+    const Directive = constructors[name]
+
+    Directive.validate(value)
+
+    return new Directive(value)
+  }
+
+  public preflight (directives: Directive[], context: Context): null {
+    let restricted = false
+
+    for (const directive of directives) {
+      restricted ||= directive instanceof Output
+
+      directive.attach(context)
+    }
+
+    if (!restricted)
+      DENIAL.attach(context)
+
+    return null
+  }
+}
+
+const constructors: Record<string, Constructor> = {
+  output: Output,
+  input: Input
+}
+
+const DENIAL: Output = new Output([])

package/source/directives/io/Input.ts

@@ -0,0 +1,50 @@
+import { BadRequest } from '../../HTTP'
+import * as schemas from './schemas'
+import type { Message } from './Message'
+import type { Directive } from './Directive'
+import type { Input as Context } from '../../io'
+
+export class Input implements Directive {
+  private readonly permissions: Permissions
+
+  public constructor (permissions: Permissions) {
+    this.permissions = permissions
+  }
+
+  public static validate (permissions: unknown): asserts permissions is Permissions {
+    schemas.input.validate(permissions, 'Incorrect \'io:input\' format')
+  }
+
+  public attach (context: Context): void {
+    context.pipelines.body.push((body) => this.check(body))
+  }
+
+  private check (body: unknown): unknown {
+    try {
+      schemas.message.validate(body)
+    } catch {
+      throw new BadRequest('Invalid request body.')
+    }
+
+    const property = this.violation(body)
+
+    if (property !== undefined)
+      throw new BadRequest(`Unexpected input: ${property}.`)
+
+    return body
+  }
+
+  private violation (value: Message | Message[]): string | undefined {
+    if (!Array.isArray(value))
+      return Object.keys(value).find((key) => !this.permissions.includes(key))
+
+    for (const item of value) {
+      const property = this.violation(item)
+
+      if (property !== undefined)
+        return property
+    }
+  }
+}
+
+export type Permissions = string[]

package/source/directives/io/Message.ts

@@ -0,0 +1 @@
+export type Message = Record<string, unknown>

package/source/directives/io/Output.ts

@@ -0,0 +1,69 @@
+import { Stream } from 'node:stream'
+import * as schemas from './schemas'
+import type { Message } from './Message'
+import type { Directive } from './Directive'
+import type { Input as Context } from '../../io'
+import type { OutgoingMessage } from '../../HTTP'
+
+export class Output implements Directive {
+  private readonly disabled: boolean = false
+  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
+  }
+
+  public static validate (permissions: unknown): asserts permissions is Permissions {
+    schemas.output.validate(permissions, 'Incorrect \'io:output\' format')
+  }
+
+  public attach (context: Context): void {
+    context.pipelines.response.push(this.restriction(context))
+  }
+
+  private restriction (context: Context) {
+    return (message: OutgoingMessage): void => {
+      const error = message.status !== undefined && message.status >= 300
+      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 ' +
+            `(${context.request.url}). Response omitted.`)
+
+        delete message.body
+
+        return
+      }
+
+      schemas.message.validate(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))
+      else
+        message.body = this.fit(message.body)
+    }
+  }
+
+  private fit (message: Message): Message | undefined {
+    const entries = Object.entries(message)
+      .filter(([key]) => this.permissions.includes(key))
+
+    return Object.fromEntries(entries)
+  }
+}
+
+export type Permissions = string[] | boolean

package/source/directives/io/index.ts

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

package/source/directives/io/schemas.ts

@@ -0,0 +1,12 @@
+import { resolve } from 'node:path'
+import schemas, { type Schema } from '@toa.io/schemas'
+import type { Permissions as InputPermissions } from './Input'
+import type { Permissions as OutputPermissions } from './Output'
+import type { Message } from './Message'
+
+const path = resolve(__dirname, '../../../schemas/io')
+const namespace = schemas.namespace(path)
+
+export const message: Schema<Message | Message[]> = namespace.schema('message')
+export const input: Schema<InputPermissions> = namespace.schema('input')
+export const output: Schema<OutputPermissions> = namespace.schema('output')

package/source/directives/octets/Context.ts

@@ -1,18 +1,19 @@
 import * as schemas from './schemas'
+import { Directive } from './Directive'
 import type { Output } from '../../io'
-import type { Directive } from './types'
 
-export class Context implements Directive {
+export class Context extends Directive {
   public readonly targeted = false
   public readonly storage: string
 
-  public constructor (value: any) {
+  public constructor (value: unknown) {
+    super()
     schemas.context.validate(value)
 
     this.storage = value
   }
 
-  public apply (): Output {
+  public async apply (): Promise<Output> {
     return null
   }
 }

package/source/directives/octets/Delete.ts

@@ -2,16 +2,17 @@ import { Readable } from 'stream'
 import { NotFound } from '../../HTTP'
 import * as schemas from './schemas'
 import { Workflow } from './workflows'
+import { Directive } from './Directive'
 import type { Parameter } from '../../RTD'
 import type { Unit } from './workflows'
 import type { Maybe } from '@toa.io/types'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io'
-import type { Directive, Input } from './types'
+import type { Input } from './types'
 import type { Remotes } from '../../Remotes'
 import type { Entry } from '@toa.io/extensions.storages'
 
-export class Delete implements Directive {
+export class Delete extends Directive {
   public readonly targeted = true
 
   private readonly workflow?: Workflow
@@ -19,6 +20,7 @@ export class Delete implements Directive {
   private storage: Component | null = null
 
   public constructor (options: Options | null, discovery: Promise<Component>, remotes: Remotes) {
+    super()
     schemas.remove.validate(options)
 
     if (options?.workflow !== undefined)
@@ -27,11 +29,16 @@ export class Delete implements Directive {
     this.discovery = discovery
   }
 
-  public async apply (storage: string, request: Input, parameters: Parameter[]): Promise<Output> {
+  public async apply (storage: string, input: Input, parameters: Parameter[]): Promise<Output> {
     this.storage ??= await this.discovery
 
     const entry = await this.storage.invoke<Maybe<Entry>>('get',
-      { input: { storage, path: request.url } })
+      {
+        input: {
+          storage,
+          path: input.request.url
+        }
+      })
 
     if (entry instanceof Error)
       throw new NotFound()
@@ -40,31 +47,36 @@ export class Delete implements Directive {
 
     if (this.workflow !== undefined) {
       output.status = 202
-      output.body = Readable.from(this.execute(request, storage, entry, parameters))
+      output.body = Readable.from(this.execute(input, storage, entry, parameters))
     } else
-      await this.delete(storage, request)
+      await this.delete(storage, input)
 
     return output
   }
 
-  private async delete (storage: string, request: Input): Promise<void> {
+  private async delete (storage: string, input: Input): Promise<void> {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     await this.storage!.invoke('delete',
-      { input: { storage, path: request.url } })
+      {
+        input: {
+          storage,
+          path: input.request.url
+        }
+      })
   }
 
   // eslint-disable-next-line max-params
   private async * execute
-  (request: Input, storage: string, entry: Entry, parameters: Parameter[]): AsyncGenerator {
+  (input: Input, storage: string, entry: Entry, parameters: Parameter[]): AsyncGenerator {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    for await (const chunk of this.workflow!.execute(request, storage, entry, parameters)) {
+    for await (const chunk of this.workflow!.execute(input, storage, entry, parameters)) {
       yield chunk
 
       if (typeof chunk === 'object' && chunk !== null && 'error' in chunk)
         return
     }
 
-    await this.delete(storage, request)
+    await this.delete(storage, input)
   }
 }
 

package/source/directives/octets/Directive.ts

@@ -0,0 +1,10 @@
+import type { Input } from './types'
+import type { Parameter } from '../../RTD'
+import type * as io from '../../io'
+
+export abstract class Directive {
+  public readonly name = 'octets.' + this.constructor.name.toLowerCase()
+  public abstract readonly targeted: boolean
+
+  public abstract apply (storage: string, input: Input, parameters: Parameter[]): Promise<io.Output>
+}

package/source/directives/octets/Fetch.ts

@@ -1,52 +1,61 @@
 import { posix } from 'node:path'
 import { Forbidden, NotFound } from '../../HTTP'
 import * as schemas from './schemas'
+import { Directive } from './Directive'
 import type { Maybe } from '@toa.io/types'
 import type { Entry } from '@toa.io/extensions.storages'
 import type { Readable } from 'node:stream'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io'
+import type { Input } from './types'
 
-import type { Directive, Input } from './types'
-
-export class Fetch implements Directive {
+export class Fetch extends Directive {
   public readonly targeted = true
 
-  private readonly permissions: Required<Permissions> = { blob: true, meta: false }
+  private readonly permissions: Required<Permissions> = {
+    blob: true,
+    meta: false
+  }
+
   private readonly discovery: Promise<Component>
   private storage: Component = null as unknown as Component
 
   public constructor (permissions: Permissions | null, discovery: Promise<Component>) {
+    super()
     schemas.fetch.validate(permissions)
 
     Object.assign(this.permissions, permissions)
     this.discovery = discovery
   }
 
-  public async apply (storage: string, request: Input): Promise<Output> {
+  public async apply (storage: string, input: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    const variant = posix.basename(request.url).includes('.')
-    const metadata = request.subtype === 'octets.entry'
+    const variant = posix.basename(input.request.url).includes('.')
+    const metadata = input.subtype === 'octets.entry'
 
     if (!variant && metadata)
       if (this.permissions.meta)
-        return this.get(storage, request)
+        return this.get(storage, input)
       else
         throw new Forbidden('Metadata is not accessible.')
 
     if (!variant && !this.permissions.blob)
       throw new Forbidden('BLOB variant must be specified.')
 
-    return await this.fetch(storage, request)
+    return await this.fetch(storage, input)
   }
 
-  private async fetch (storage: string, request: Input): Promise<Output> {
-    if ('if-none-match' in request.headers)
+  private async fetch (storage: string, input: Input): Promise<Output> {
+    if ('if-none-match' in input.request.headers)
       return { status: 304 }
 
-    const input = { storage, path: request.url }
-    const result = await this.storage.invoke<Maybe<FetchResult>>('fetch', { input })
+    const result = await this.storage.invoke<Maybe<FetchResult>>('fetch', {
+      input: {
+        storage,
+        path: input.request.url
+      }
+    })
 
     if (result instanceof Error)
       throw new NotFound()
@@ -57,12 +66,19 @@ export class Fetch implements Directive {
       etag: result.checksum
     })
 
-    return { headers, body: result.stream }
+    return {
+      headers,
+      body: result.stream
+    }
   }
 
-  private async get (storage: string, request: Input): Promise<Output> {
-    const input = { storage, path: request.url }
-    const entry = await this.storage.invoke<Maybe<Entry>>('get', { input })
+  private async get (storage: string, input: Input): Promise<Output> {
+    const entry = await this.storage.invoke<Maybe<Entry>>('get', {
+      input: {
+        storage,
+        path: input.request.url
+      }
+    })
 
     if (entry instanceof Error)
       throw new NotFound()

package/source/directives/octets/List.ts

@@ -1,14 +1,15 @@
 import { posix } from 'node:path'
 import { Forbidden, NotFound } from '../../HTTP'
 import * as schemas from './schemas'
+import { Directive } from './Directive'
 import type { Entry } from '@toa.io/extensions.storages'
 import type { Maybe } from '@toa.io/types'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io'
 
-import type { Directive, Input } from './types'
+import type { Input } from './types'
 
-export class List implements Directive {
+export class List extends Directive {
   public readonly targeted = false
 
   private readonly permissions: Required<Permissions> = { meta: false }
@@ -16,28 +17,33 @@ export class List implements Directive {
   private storage: Component | null = null
 
   public constructor (permissions: Permissions | null, discovery: Promise<Component>) {
+    super()
     schemas.list.validate(permissions)
 
     Object.assign(this.permissions, permissions)
     this.discovery = discovery
   }
 
-  public async apply (storage: string, request: Input): Promise<Output> {
+  public async apply (storage: string, input: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    const metadata = request.subtype === 'octets.entries'
+    const metadata = input.subtype === 'octets.entries'
 
     if (metadata && !this.permissions.meta)
       throw new Forbidden('Metadata is not accessible.')
 
-    const input = { storage, path: request.url }
-    const list = await this.storage.invoke<Maybe<string[]>>('list', { input })
+    const list = await this.storage.invoke<Maybe<string[]>>('list', {
+      input: {
+        storage,
+        path: input.request.url
+      }
+    })
 
     if (list instanceof Error)
       throw new NotFound()
 
     const body = metadata
-      ? await this.expand(storage, request.url, list)
+      ? await this.expand(storage, input.request.url, list)
       : list
 
     return { body }
@@ -47,7 +53,11 @@ export class List implements Directive {
   Promise<Array<Maybe<Entry>>> {
     const promises = list.map(async (id) => {
       const path = posix.join(prefix, id)
-      const input = { storage, path }
+
+      const input = {
+        storage,
+        path
+      }
 
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- ensured in `apply`
       return this.storage!.invoke<Maybe<Entry>>('get', { input })

package/source/directives/octets/Octets.ts

@@ -4,16 +4,15 @@ import { Store } from './Store'
 import { Fetch } from './Fetch'
 import { List } from './List'
 import { Delete } from './Delete'
-import { Permute } from './Permute'
 import { WorkflowDirective } from './Workflow'
+import type { Directive } from './Directive'
 import type { Output } from '../../io'
 import type { Component } from '@toa.io/core'
 import type { Remotes } from '../../Remotes'
-import type { Family } from '../../Directive'
-import type { Directive, Input } from './types'
-import type { Parameter } from '../../RTD'
+import type { Parameter, DirectiveFamily } from '../../RTD'
+import type { Input } from './types'
 
-export class Octets implements Family<Directive> {
+export class Octets implements DirectiveFamily<Directive> {
   public readonly name: string = 'octets'
   public readonly mandatory: boolean = false
 
@@ -23,7 +22,7 @@ export class Octets implements Family<Directive> {
     const Class = DIRECTIVES[name]
 
     if (Class === undefined)
-      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+      throw new Error(`Directive 'octets:${name}' is not implemented.`)
 
     this.discovery ??= remotes.discover('octets', 'storage')
 
@@ -46,15 +45,17 @@ export class Octets implements Family<Directive> {
     if (action === null)
       return null
 
+    // noinspection PointlessBooleanExpressionJS
     if (context === null)
       throw new Error('Octets context is not defined.')
 
-    const targeted = input.path[input.path.length - 1] !== '/'
+    const targeted = input.request.url[input.request.url.length - 1] !== '/'
 
     if (targeted !== action.targeted)
       throw new NotFound(`Trailing slash is ${action.targeted ? 'redundant' : 'required'}.`)
 
-    return await action.apply(context.storage, input, parameters)
+    // noinspection JSObjectNullOrUndefined
+    return await input.timing.capture(action.name, action.apply(context.storage, input, parameters))
   }
 }
 
@@ -64,7 +65,6 @@ const DIRECTIVES: Record<string, Constructor> = {
   fetch: Fetch,
   list: List,
   delete: Delete,
-  permute: Permute,
   workflow: WorkflowDirective
 }