@toa.io/extensions.exposition 0.24.0-alpha.21 → 0.24.0-alpha.23

package/source/HTTP/Server.ts

@@ -7,17 +7,21 @@ import Negotiator from 'negotiator'
 import { read, write, type IncomingMessage, type OutgoingMessage } from './messages'
 import { ClientError, Exception } from './exceptions'
 import { formats, types } from './formats'
-import type { Format } from './formats'
 import type * as http from 'node:http'
 import type { Express, Request, Response, NextFunction } from 'express'
 
 export class Server extends Connector {
   private server?: http.Server
+  private readonly app: Express
+  private readonly debug: boolean
+  private readonly requestedPort: number
 
-  private constructor (private readonly app: Express,
-    private readonly debug: boolean,
-    private readonly requestedPort: number) {
+  private constructor (app: Express, debug: boolean, port: number) {
     super()
+
+    this.app = app
+    this.debug = debug
+    this.requestedPort = port
   }
 
   public get port (): number {
@@ -39,7 +43,6 @@ export class Server extends Connector {
     const app = express()
 
     app.disable('x-powered-by')
-    // app.use(cors(CORS))
     app.use(supportedMethods(properties.methods))
 
     return new Server(app, properties.debug, properties.port)
@@ -80,7 +83,8 @@ export class Server extends Connector {
   private extend (request: Request): IncomingMessage {
     const message = request as IncomingMessage
 
-    message.encoder = negotiate(request)
+    negotiate(request, message)
+
     message.pipelines = { body: [], response: [] }
 
     message.parse = async <T> (): Promise<T> => {
@@ -97,9 +101,6 @@ export class Server extends Connector {
 
   private success (request: IncomingMessage, response: Response) {
     return (message: OutgoingMessage) => {
-      for (const transform of request.pipelines.response)
-        transform(message)
-
       let status = message.status
 
       if (status === undefined)
@@ -109,12 +110,7 @@ export class Server extends Connector {
         else status = 200
 
       response.status(status)
-      message.headers?.forEach((value, key) => response.set(key, value))
-
-      if (message.body !== undefined && message.body !== null)
-        write(request, response, message)
-      else
-        response.end()
+      write(request, response, message)
     }
   }
 
@@ -129,16 +125,15 @@ export class Server extends Connector {
 
       response.status(status)
 
-      const outputAllowed = exception instanceof ClientError || this.debug
+      const message: OutgoingMessage = {}
+      const verbose = exception instanceof ClientError || this.debug
 
-      if (outputAllowed) {
-        const body = exception instanceof Exception
+      if (verbose)
+        message.body = exception instanceof Exception
           ? exception.body
           : (exception.stack ?? exception.message)
 
-        write(request, response, { body })
-      } else
-        response.end()
+      write(request, response, message)
     }
   }
 }
@@ -150,11 +145,23 @@ function supportedMethods (methods: Set<string>) {
   }
 }
 
-function negotiate (request: Request): Format | null {
+function negotiate (request: Request, message: IncomingMessage): void {
+  if (request.headers.accept !== undefined) {
+    const match = SUBTYPE.exec(request.headers.accept)
+
+    if (match !== null) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const { type, subtype, suffix } = match.groups!
+
+      request.headers.accept = `${type}/${suffix}`
+      message.subtype = subtype
+    }
+  }
+
   const negotiator = new Negotiator(request)
   const mediaType = negotiator.mediaType(types)
 
-  return mediaType === undefined ? null : formats[mediaType]
+  message.encoder = mediaType === undefined ? null : formats[mediaType]
 }
 
 // https://github.com/whatwg/fetch/issues/1254
@@ -182,3 +189,5 @@ interface Properties {
 }
 
 export type Processing = (input: IncomingMessage) => Promise<OutgoingMessage>
+
+const SUBTYPE = /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/

package/source/HTTP/messages.ts

@@ -9,6 +9,11 @@ import type { Format } from './formats'
 
 export function write
 (request: IncomingMessage, response: Response, message: OutgoingMessage): void {
+  for (const transform of request.pipelines.response)
+    transform(message)
+
+  message.headers?.forEach((value, key) => response.set(key, value))
+
   if (message.body instanceof Readable)
     stream(message, request, response)
   else
@@ -36,7 +41,7 @@ export async function read (request: Request): Promise<any> {
 }
 
 function send (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
-  if (message.body === undefined) {
+  if (message.body === undefined || message.body === null) {
     response.end()
 
     return
@@ -99,6 +104,7 @@ export interface IncomingMessage extends Request {
   query: Query
   parse: <T> () => Promise<T>
   encoder: Format | null
+  subtype: string | null
   pipelines: {
     body: Array<(input: unknown) => unknown>
     response: Array<(output: OutgoingMessage) => void>

package/source/directives/cors/CORS.ts

@@ -1,9 +1,7 @@
-import type { OutgoingMessage } from '../../HTTP'
 import type { Input, Output } from '../../io'
-import type { Family } from '../../Directive'
 import type { Interceptor } from '../../Interception'
 
-export class CORS implements Family, Interceptor {
+export class CORS implements Interceptor {
   public readonly name = 'cors'
   public readonly mandatory = true
 
@@ -18,35 +16,39 @@ export class CORS implements Family, Interceptor {
     vary: 'origin'
   })
 
-  public create (): null {
-    return null
-  }
+  public intercept (input: Input): Output {
+    const origin = input.headers.origin
 
-  public settle (_: unknown[], input: Input, output: OutgoingMessage): void {
-    if (input.headers.origin === undefined)
-      return
+    if (origin === undefined)
+      return null
 
-    output.headers ??= new Headers()
-    output.headers.set('access-control-allow-origin', input.headers.origin)
-    output.headers.set('access-control-expose-headers',
-      'authorization, content-type, content-length, etag')
-    output.headers.append('vary', 'origin')
-  }
+    if (input.method === 'OPTIONS')
+      return this.preflightResponse(origin)
 
-  public intercept (input: Input): Output {
-    if (input.method !== 'OPTIONS' || input.headers.origin === undefined)
-      return null
+    input.pipelines.response.push((output) => {
+      output.headers ??= new Headers()
+      output.headers.set('access-control-allow-origin', origin)
+      output.headers.set('access-control-expose-headers',
+        'authorization, content-type, content-length, etag')
 
-    this.headers.set('access-control-allow-origin', input.headers.origin)
+      if (input.method === 'GET' || input.method === 'HEAD' || input.method === 'OPTIONS')
+        output.headers.append('vary', 'origin')
+    })
 
-    return {
-      status: 204,
-      headers: this.headers
-    }
+    return null
   }
 
   public allowHeader (header: string): void {
     this.allowedHeaders.add(header.toLowerCase())
     this.headers.set('access-control-allow-headers', Array.from(this.allowedHeaders).join(', '))
   }
+
+  private preflightResponse (origin: string): Output {
+    this.headers.set('access-control-allow-origin', origin)
+
+    return {
+      status: 204,
+      headers: this.headers
+    }
+  }
 }

package/source/directives/index.ts

@@ -7,5 +7,5 @@ import { vary } from './vary'
 import type { Family } from '../Directive'
 import type { Interceptor } from '../Interception'
 
-export const families: Family[] = [authorization, cache, octets, cors, vary, dev]
+export const families: Family[] = [authorization, cache, octets, vary, dev]
 export const interceptors: Interceptor[] = [cors]

package/source/directives/octets/Delete.ts

@@ -1,18 +1,27 @@
+import { Readable } from 'stream'
 import { NotFound } from '../../HTTP'
 import * as schemas from './schemas'
+import { Workflow } from './workflow'
+import type { Unit } from './workflow'
 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 { Remotes } from '../../Remotes'
+import type { Entry } from '@toa.io/extensions.storages'
 
 export class Delete implements Directive {
   public readonly targeted = true
 
+  private readonly workflow?: Workflow
   private readonly discovery: Promise<Component>
   private storage: Component | null = null
 
-  public constructor (value: null, discovery: Promise<Component>) {
-    schemas.remove.validate(value)
+  public constructor (options: Options | null, discovery: Promise<Component>, remotes: Remotes) {
+    schemas.remove.validate(options)
+
+    if (options?.workflow !== undefined)
+      this.workflow = new Workflow(options.workflow, remotes)
 
     this.discovery = discovery
   }
@@ -20,12 +29,42 @@ export class Delete implements Directive {
   public async apply (storage: string, request: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    const input = { storage, path: request.path }
-    const error = await this.storage.invoke<Maybe<unknown>>('delete', { input })
+    const entry = await this.storage.invoke<Maybe<Entry>>('get',
+      { input: { storage, path: request.url } })
 
-    if (error instanceof Error)
+    if (entry instanceof Error)
       throw new NotFound()
 
-    return {}
+    const output: Output = {}
+
+    if (this.workflow !== undefined) {
+      output.status = 202
+      output.body = Readable.from(this.execute(request, storage, entry))
+    } else
+      await this.delete(storage, request)
+
+    return output
   }
+
+  private async delete (storage: string, request: Input): Promise<void> {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    await this.storage!.invoke('delete',
+      { input: { storage, path: request.url } })
+  }
+
+  private async * execute (request: Input, storage: string, entry: Entry): AsyncGenerator {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    for await (const chunk of this.workflow!.execute(request, storage, entry)) {
+      yield chunk
+
+      if (typeof chunk === 'object' && chunk !== null && 'error' in chunk)
+        return
+    }
+
+    await this.delete(storage, request)
+  }
+}
+
+export interface Options {
+  workflow?: Unit[] | Unit
 }

package/source/directives/octets/Fetch.ts

@@ -12,11 +12,11 @@ import type { Directive, Input } from './types'
 export class Fetch implements Directive {
   public readonly targeted = true
 
-  private readonly permissions: 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: Partial<Permissions> | null, discovery: Promise<Component>) {
+  public constructor (permissions: Permissions | null, discovery: Promise<Component>) {
     schemas.fetch.validate(permissions)
 
     Object.assign(this.permissions, permissions)
@@ -26,19 +26,22 @@ export class Fetch implements Directive {
   public async apply (storage: string, request: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    if (request.url.slice(-5) === ':meta')
-      return await this.get(storage, request)
-    else
-      return await this.fetch(storage, request)
-  }
+    const variant = posix.basename(request.url).includes('.')
+    const metadata = request.subtype === 'octets.entry'
 
-  private async fetch (storage: string, request: Input): Promise<Output> {
-    const filename = posix.basename(request.url)
-    const variant = filename.includes('.')
+    if (!variant && metadata)
+      if (this.permissions.meta)
+        return this.get(storage, request)
+      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)
+  }
+
+  private async fetch (storage: string, request: Input): Promise<Output> {
     if ('if-none-match' in request.headers)
       return { status: 304 }
 
@@ -58,11 +61,7 @@ export class Fetch implements Directive {
   }
 
   private async get (storage: string, request: Input): Promise<Output> {
-    if (!this.permissions.meta)
-      throw new Forbidden('Metadata is not accessible.')
-
-    const path = request.url.slice(0, -5)
-    const input = { storage, path }
+    const input = { storage, path: request.url }
     const entry = await this.storage.invoke<Maybe<Entry>>('get', { input })
 
     if (entry instanceof Error)
@@ -72,9 +71,9 @@ export class Fetch implements Directive {
   }
 }
 
-interface Permissions {
-  blob: boolean
-  meta: boolean
+export interface Permissions {
+  blob?: boolean
+  meta?: boolean
 }
 
 interface FetchResult {

package/source/directives/octets/List.ts

@@ -1,5 +1,7 @@
-import { NotFound } from '../../HTTP'
+import { posix } from 'node:path'
+import { Forbidden, NotFound } from '../../HTTP'
 import * as schemas from './schemas'
+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'
@@ -9,24 +11,52 @@ import type { Directive, Input } from './types'
 export class List implements Directive {
   public readonly targeted = false
 
+  private readonly permissions: Required<Permissions> = { meta: false }
   private readonly discovery: Promise<Component>
   private storage: Component | null = null
 
-  public constructor (value: null, discovery: Promise<Component>) {
-    schemas.remove.validate(value)
+  public constructor (permissions: Permissions | null, discovery: Promise<Component>) {
+    schemas.list.validate(permissions)
 
+    Object.assign(this.permissions, permissions)
     this.discovery = discovery
   }
 
   public async apply (storage: string, request: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    const input = { storage, path: request.path }
-    const list = await this.storage.invoke<Maybe<unknown>>('list', { input })
+    const metadata = request.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 })
 
     if (list instanceof Error)
       throw new NotFound()
 
-    return { body: list }
+    const body = metadata
+      ? await this.expand(storage, request.url, list)
+      : list
+
+    return { body }
   }
+
+  private async expand (storage: string, prefix: string, list: string[]):
+  Promise<Array<Maybe<Entry>>> {
+    const promises = list.map(async (id) => {
+      const path = posix.join(prefix, id)
+      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 })
+    })
+
+    return await Promise.all(promises)
+  }
+}
+
+export interface Permissions {
+  meta?: boolean
 }

package/source/directives/octets/Permute.ts

@@ -13,7 +13,7 @@ export class Permute implements Directive {
   private storage: Component | null = null
 
   public constructor (value: null, discovery: Promise<Component>) {
-    schemas.remove.validate(value)
+    schemas.permute.validate(value)
 
     this.discovery = discovery
   }
@@ -24,7 +24,7 @@ export class Permute implements Directive {
     if (request.encoder === null)
       throw new NotAcceptable()
 
-    const path = request.path
+    const path = request.url
     const list = await request.parse()
     const input = { storage, path, list }
     const error = await this.storage.invoke<Maybe<unknown>>('permute', { input })

package/source/directives/octets/Store.ts

@@ -1,10 +1,9 @@
-import { Readable } from 'node:stream'
-import { posix } from 'node:path'
 import { match } from 'matchacho'
-import { promex } from '@toa.io/generic'
 import { BadRequest, UnsupportedMediaType } from '../../HTTP'
+import { cors } from '../cors'
 import * as schemas from './schemas'
-import type { Maybe } from '@toa.io/types'
+import { Workflow } from './workflow'
+import type { Unit } from './workflow'
 import type { Entry } from '@toa.io/extensions.storages'
 import type { Remotes } from '../../Remotes'
 import type { ErrorType } from 'error-value'
@@ -15,11 +14,9 @@ import type { Directive, Input } from './types'
 export class Store implements Directive {
   public readonly targeted = false
 
-  private readonly accept: string | undefined
-  private readonly workflow: Workflow | undefined
+  private readonly accept?: string
+  private readonly workflow?: Workflow
   private readonly discovery: Record<string, Promise<Component>> = {}
-  private readonly remotes: Remotes
-  private readonly components: Record<string, Component> = {}
   private storage: Component | null = null
 
   public constructor
@@ -31,19 +28,26 @@ export class Store implements Directive {
       Array, (types: string[]) => types.join(','),
       undefined)
 
-    this.workflow = match(options?.workflow,
-      Array, (units: Unit[]) => units,
-      Object, (unit: Unit) => [unit],
-      undefined)
+    if (options?.workflow !== undefined)
+      this.workflow = new Workflow(options.workflow, remotes)
 
     this.discovery.storage = discovery
-    this.remotes = remotes
+
+    cors.allowHeader('content-meta')
   }
 
   public async apply (storage: string, request: Input): Promise<Output> {
     this.storage ??= await this.discovery.storage
 
-    const input = { storage, request, accept: this.accept }
+    const input: StoreInput = { storage, request }
+    const meta = request.headers['content-meta']
+
+    if (this.accept !== undefined)
+      input.accept = this.accept
+
+    if (meta !== undefined)
+      input.meta = this.parseMeta(meta)
+
     const entry = await this.storage.invoke<Entry>('store', { input })
 
     return match<Output>(entry,
@@ -54,7 +58,7 @@ export class Store implements Directive {
   private reply (request: Input, storage: string, entry: Entry): Output {
     const body = this.workflow === undefined
       ? entry
-      : Readable.from(this.execute(request, storage, entry))
+      : this.workflow.execute(request, storage, entry)
 
     return { body }
   }
@@ -66,93 +70,31 @@ export class Store implements Directive {
       error)
   }
 
-  /* eslint-disable no-useless-return, max-depth */
-
-  /**
-   * Execute workflow units sequentially, steps within a unit in parallel.
-   * Yield results as soon as they come.
-   *
-   * If you need to change this, it may take a while.
-   */
-  private async * execute (request: Input, storage: string, entry: Entry): AsyncGenerator {
-    yield entry
-
-    const path = posix.join(request.path, entry.id)
-    let interrupted = false
-
-    for (const unit of this.workflow!) {
-      if (interrupted)
-        break
-
-      const steps = Object.keys(unit)
-
-      // unit result promises queue
-      const results = Array.from(steps, promex<unknown>)
-      let next = 0
-
-      // execute steps in parallel
-      for (const step of steps)
-        // these promises are indirectly awaited in the yield loop
-        void (async () => {
-          const endpoint = unit[step]
-          const context: Context = { storage, path, entry }
-          const result = await this.call(endpoint, context)
-
-          if (interrupted)
-            return
-
-          // as a result is received, resolve the next promise from the queue
-          const promise = results[next++]
-
-          if (result instanceof Error) {
-            interrupted = true
-            promise.resolve({ error: { step, ...result } })
-
-            // cancel pending promises
-            results[next].resolve(null)
-          } else
-            promise.resolve({ [step]: result ?? null })
-        })().catch((e) => results[next].reject(e))
-
-      // yield results from the queue as they come
-      for (const promise of results) {
-        const result = await promise
-
-        if (result === null) // canceled promise
-          break
-        else
-          yield result
-      }
-    }
-  }
-
-  private async call (endpoint: string, context: Context): Promise<Maybe<unknown>> {
-    const [operation, component, namespace = 'default'] = endpoint.split('.').reverse()
-    const key = `${namespace}.${component}`
+  private parseMeta (value: string | string[]): Record<string, string> {
+    if (Array.isArray(value))
+      value = value.join(',')
 
-    this.components[key] ??= await this.discover(key, namespace, component)
+    const meta: Record<string, string> = {}
 
-    return await this.components[key].invoke(operation, { input: context })
-  }
+    for (const pair of value.split(',')) {
+      const eq = pair.indexOf('=')
+      const key = (eq === -1 ? pair : pair.slice(0, eq)).trim()
 
-  private async discover (key: string, namespace: string, component: string): Promise<Component> {
-    if (this.discovery[key] === undefined)
-      this.discovery[key] = this.remotes.discover(namespace, component)
+      meta[key] = eq === -1 ? 'true' : pair.slice(eq + 1).trim()
+    }
 
-    return await this.discovery[key]
+    return meta
   }
 }
 
-type Unit = Record<string, string>
-type Workflow = Unit[]
-
-interface Options {
-  accept: string | string[]
-  workflow: Workflow | Unit
+export interface Options {
+  accept?: string | string[]
+  workflow?: Unit[] | Unit
 }
 
-interface Context {
+interface StoreInput {
   storage: string
-  path: string
-  entry: Entry
+  request: Input
+  accept?: string
+  meta?: Record<string, string>
 }

package/source/directives/octets/schemas.ts

@@ -1,12 +1,17 @@
 import { resolve } from 'node:path'
 import schemas from '@toa.io/schemas'
+import type { Permissions as FetchPermissions } from './Fetch'
+import type { Permissions as ListPermissions } from './List'
+import type { Options as StoreOptions } from './Store'
+import type { Options as DeleteOptions } from './Delete'
+import type { Schema } from '@toa.io/schemas'
 
 const path = resolve(__dirname, '../../../schemas/octets')
 const namespace = schemas.namespace(path)
 
-export const context = namespace.schema('context')
-export const store = namespace.schema('store')
-export const fetch = namespace.schema('fetch')
-export const remove = namespace.schema('delete')
-export const list = namespace.schema('list')
-export const permute = namespace.schema('permute')
+export const context: Schema<string> = namespace.schema('context')
+export const store: Schema<StoreOptions | null> = namespace.schema('store')
+export const fetch: Schema<FetchPermissions | null> = namespace.schema('fetch')
+export const remove: Schema<DeleteOptions | null> = namespace.schema('delete')
+export const list: Schema<ListPermissions | null> = namespace.schema('list')
+export const permute: Schema<null> = namespace.schema('permute')