@toa.io/extensions.exposition 0.22.0 → 0.23.0-dev.0

package/source/RTD/segment.ts

@@ -14,6 +14,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 return { fragment: segment }
 }
 
@@ -21,5 +22,5 @@ export type Segment = {
   fragment: string
 } | {
   fragment: null
-  placeholder: string
+  placeholder: string | null
 }

package/source/Remotes.ts

@@ -3,6 +3,7 @@ import { type Bootloader } from './Factory'
 
 export class Remotes extends Connector {
   private readonly boot: Bootloader
+  private readonly remotes: Record<string, Promise<Component>> = {}
 
   public constructor (boot: Bootloader) {
     super()
@@ -11,6 +12,13 @@ export class Remotes extends Connector {
 
   public async discover (namespace: string, name: string): Promise<Component> {
     const locator = new Locator(name, namespace)
+
+    this.remotes[locator.id] ??= this.create(locator)
+
+    return await this.remotes[locator.id]
+  }
+
+  private async create (locator: Locator): Promise<Component> {
     const remote = await this.boot.remote(locator)
 
     this.depends(remote)

package/source/directives/auth/Family.ts

@@ -1,32 +1,34 @@
-import { type Component } from '@toa.io/core'
-import { Nope } from 'nopeable'
-import { type Parameter } from '../../RTD'
-import { type Family, type Output } from '../../Directive'
-import { type Remotes } from '../../Remotes'
+import { match } from 'matchacho'
 import * as http from '../../HTTP'
-import {
-  type AuthenticationResult,
-  type Ban,
-  type Directive,
-  type Discovery,
-  type Extension,
-  type Identity,
-  type Input, type Remote,
-  type Schemes
-} from './types'
 import { Anonymous } from './Anonymous'
 import { Id } from './Id'
 import { Role } from './Role'
 import { Rule } from './Rule'
 import { Incept } from './Incept'
+import { Echo } from './Echo'
 import { split } from './split'
-import { PRIMARY, PROVIDERS } from './schemes'
 import { Scheme } from './Scheme'
-import { Echo } from './Echo'
+import { PRIMARY, PROVIDERS } from './schemes'
+import type { Component } from '@toa.io/core'
+import type { Remotes } from '../../Remotes'
+import type { Family, Output } from '../../Directive'
+import type { Parameter } from '../../RTD'
+import type {
+  AuthenticationResult,
+  Ban,
+  Directive,
+  Discovery,
+  Extension,
+  Identity,
+  Input,
+  Remote,
+  Schemes
+} from './types'
 
 class Authorization implements Family<Directive, Extension> {
   public readonly name: string = 'auth'
   public readonly mandatory: boolean = true
+
   private readonly schemes = {} as unknown as Schemes
   private readonly discovery = {} as unknown as Discovery
   private tokens: Component | null = null
@@ -41,10 +43,11 @@ class Authorization implements Family<Directive, Extension> {
     for (const name of REMOTES)
       this.discovery[name] ??= remotes.discover('identity', name)
 
-    if (Class === Role) return new Class(value, this.discovery.roles)
-    else if (Class === Rule) return new Class(value, this.create.bind(this))
-    else if (Class === Incept) return new Class(value, this.discovery)
-    else return new Class(value)
+    return match(Class,
+      Role, () => new Role(value, this.discovery.roles),
+      Rule, () => new Rule(value, this.create.bind(this)),
+      Incept, () => new Incept(value, this.discovery),
+      () => new Class(value))
   }
 
   public async preflight
@@ -107,7 +110,7 @@ class Authorization implements Family<Directive, Extension> {
     const result = await this.schemes[scheme]
       .invoke<AuthenticationResult>('authenticate', { input: credentials })
 
-    if (result instanceof Nope)
+    if (result instanceof Error)
       return null
 
     const identity = result.identity

package/source/directives/auth/Incept.ts

@@ -1,4 +1,4 @@
-import { Nope, type Nopeable } from 'nopeable'
+import { type Maybe } from '@toa.io/types'
 import * as http from '../../HTTP'
 import { type Directive, type Discovery, type Identity, type Input, type Schemes } from './types'
 import { split } from './split'
@@ -31,9 +31,9 @@ export class Incept implements Directive {
     this.schemes[scheme] ??= await this.discovery[provider]
 
     const identity = await this.schemes[scheme]
-      .invoke<Nopeable<Identity>>('create', { input: { id, credentials } })
+      .invoke<Maybe<Identity>>('create', { input: { id, credentials } })
 
-    if (identity instanceof Nope)
+    if (identity instanceof Error)
       throw new http.Conflict(identity)
 
     request.identity = identity

package/source/directives/auth/Rule.ts

@@ -25,4 +25,4 @@ export class Rule implements Directive {
   }
 }
 
-type Create = (name: string, value: any) => Directive
+type Create = (name: string, value: any, ...args: any[]) => Directive

package/source/directives/auth/types.ts

@@ -1,5 +1,5 @@
 import { type Component } from '@toa.io/core'
-import { type Nopeable } from 'nopeable'
+import { type Maybe } from '@toa.io/types'
 import { type Parameter } from '../../RTD'
 import type * as http from '../../HTTP'
 import type * as directive from '../../Directive'
@@ -29,7 +29,7 @@ export interface Ban {
 }
 
 export type Input = directive.Input & Extension
-export type AuthenticationResult = Nopeable<{ identity: Identity, refresh: boolean }>
+export type AuthenticationResult = Maybe<{ identity: Identity, refresh: boolean }>
 
 export type Scheme = 'basic' | 'token'
 export type Remote = 'basic' | 'tokens' | 'roles' | 'bans'

package/source/directives/index.ts

@@ -1,5 +1,6 @@
 import { type Family } from '../Directive'
 import Dev from './dev'
 import Auth from './auth'
+import Octets from './octets'
 
-export const families: Family[] = [Dev, Auth]
+export const families: Family[] = [Auth, Octets, Dev]

package/source/directives/octets/Context.ts

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

package/source/directives/octets/Delete.ts

@@ -0,0 +1,32 @@
+import { NotFound } from '../../HTTP'
+import * as schemas from './schemas'
+import type { Maybe } from '@toa.io/types'
+import type { Component } from '@toa.io/core'
+import type { Output } from '../../Directive'
+
+import type { Directive, Input } from './types'
+
+export class Delete implements Directive {
+  public readonly targeted = true
+
+  private readonly discovery: Promise<Component>
+  private storage: Component | null = null
+
+  public constructor (value: null, discovery: Promise<Component>) {
+    schemas.remove.validate(value)
+
+    this.discovery = discovery
+  }
+
+  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 })
+
+    if (error instanceof Error)
+      throw new NotFound()
+
+    return {}
+  }
+}

package/source/directives/octets/Family.ts

@@ -0,0 +1,68 @@
+import { NotFound } from '../../HTTP'
+import { Context } from './Context'
+import { Store } from './Store'
+import { Fetch } from './Fetch'
+import { List } from './List'
+import { Delete } from './Delete'
+import { Permute } from './Permute'
+import type { Component } from '@toa.io/core'
+import type { Remotes } from '../../Remotes'
+import type { Output, Family } from '../../Directive'
+import type { Directive, Input } from './types'
+
+class Octets implements Family<Directive> {
+  public readonly name: string = 'octets'
+  public readonly mandatory: boolean = false
+
+  private discovery = null as unknown as Promise<Component>
+
+  public create (name: string, value: any, remotes: Remotes): Directive {
+    const Class = DIRECTIVES[name]
+
+    if (Class === undefined)
+      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+
+    this.discovery ??= remotes.discover('octets', 'storage')
+
+    return new Class(value, this.discovery, remotes)
+  }
+
+  public async preflight (directives: Directive[], input: Input): Promise<Output> {
+    let context: Context | null = null
+    let action: Directive | null = null
+
+    for (const directive of directives)
+      if (directive instanceof Context)
+        context ??= directive
+      else if (action === null)
+        action = directive
+      else
+        throw new Error('Octets action is umbiguous.')
+
+    if (action === null)
+      return null
+
+    if (context === null)
+      throw new Error('Octets context is not defined.')
+
+    const targeted = input.path[input.path.length - 1] !== '/'
+
+    if (targeted !== action.targeted)
+      throw new NotFound(`Trailing slash is ${action.targeted ? 'redundant' : 'required'}.`)
+
+    return await action.apply(context.storage, input)
+  }
+}
+
+const DIRECTIVES: Record<string, Constructor> = {
+  context: Context,
+  store: Store,
+  fetch: Fetch,
+  list: List,
+  delete: Delete,
+  permute: Permute
+}
+
+type Constructor = new (value: any, discovery: Promise<Component>, remotes: Remotes) => Directive
+
+export = new Octets()

package/source/directives/octets/Fetch.ts

@@ -0,0 +1,85 @@
+import { posix } from 'node:path'
+import { Forbidden, NotFound } from '../../HTTP'
+import * as schemas from './schemas'
+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 '../../Directive'
+
+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 discovery: Promise<Component>
+  private storage: Component = null as unknown as Component
+
+  public constructor (permissions: Partial<Permissions> | null, discovery: Promise<Component>) {
+    schemas.fetch.validate(permissions)
+
+    Object.assign(this.permissions, permissions)
+    this.discovery = discovery
+  }
+
+  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)
+  }
+
+  private async fetch (storage: string, request: Input): Promise<Output> {
+    const filename = posix.basename(request.url)
+    const variant = filename.includes('.')
+
+    if (!variant && !this.permissions.blob)
+      throw new Forbidden('BLOB variant must be specified.')
+
+    if ('if-none-match' in request.headers)
+      return { status: 304 }
+
+    const input = { storage, path: request.url }
+    const result = await this.storage.invoke<Maybe<FetchResult>>('fetch', { input })
+
+    if (result instanceof Error)
+      throw new NotFound()
+
+    const headers = {
+      'content-type': result.type,
+      'content-length': result.size,
+      etag: result.checksum
+    }
+
+    return { headers, body: result.stream }
+  }
+
+  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 entry = await this.storage.invoke<Maybe<Entry>>('get', { input })
+
+    if (entry instanceof Error)
+      throw new NotFound()
+
+    return { body: entry }
+  }
+}
+
+interface Permissions {
+  blob: boolean
+  meta: boolean
+}
+
+interface FetchResult {
+  stream: Readable
+  checksum: string
+  size: number
+  type: string
+}

package/source/directives/octets/List.ts

@@ -0,0 +1,32 @@
+import { NotFound } from '../../HTTP'
+import * as schemas from './schemas'
+import type { Maybe } from '@toa.io/types'
+import type { Component } from '@toa.io/core'
+import type { Output } from '../../Directive'
+
+import type { Directive, Input } from './types'
+
+export class List implements Directive {
+  public readonly targeted = false
+
+  private readonly discovery: Promise<Component>
+  private storage: Component | null = null
+
+  public constructor (value: null, discovery: Promise<Component>) {
+    schemas.remove.validate(value)
+
+    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 })
+
+    if (list instanceof Error)
+      throw new NotFound()
+
+    return { body: list }
+  }
+}

package/source/directives/octets/Permute.ts

@@ -0,0 +1,37 @@
+import { NotAcceptable, NotFound } from '../../HTTP'
+import * as schemas from './schemas'
+import type { Maybe } from '@toa.io/types'
+import type { Component } from '@toa.io/core'
+import type { Output } from '../../Directive'
+
+import type { Directive, Input } from './types'
+
+export class Permute implements Directive {
+  public readonly targeted = false
+
+  private readonly discovery: Promise<Component>
+  private storage: Component | null = null
+
+  public constructor (value: null, discovery: Promise<Component>) {
+    schemas.remove.validate(value)
+
+    this.discovery = discovery
+  }
+
+  public async apply (storage: string, request: Input): Promise<Output> {
+    this.storage ??= await this.discovery
+
+    if (request.encoder === null)
+      throw new NotAcceptable()
+
+    const path = request.path
+    const list = await request.parse()
+    const input = { storage, path, list }
+    const error = await this.storage.invoke<Maybe<unknown>>('permute', { input })
+
+    if (error instanceof Error)
+      throw new NotFound()
+
+    return {}
+  }
+}

package/source/directives/octets/Store.ts

@@ -0,0 +1,158 @@
+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 * as schemas from './schemas'
+import type { Maybe } from '@toa.io/types'
+import type { Entry } from '@toa.io/extensions.storages'
+import type { Remotes } from '../../Remotes'
+import type { ErrorType } from 'error-value'
+import type { Component } from '@toa.io/core'
+import type { Output } from '../../Directive'
+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 discovery: Record<string, Promise<Component>> = {}
+  private readonly remotes: Remotes
+  private readonly components: Record<string, Component> = {}
+  private storage: Component | null = null
+
+  public constructor
+  (options: Options | null, discovery: Promise<Component>, remotes: Remotes) {
+    schemas.store.validate(options)
+
+    this.accept = match(options?.accept,
+      String, (value: string) => value,
+      Array, (types: string[]) => types.join(','),
+      undefined)
+
+    this.workflow = match(options?.workflow,
+      Array, (units: Unit[]) => units,
+      Object, (unit: Unit) => [unit],
+      undefined)
+
+    this.discovery.storage = discovery
+    this.remotes = remotes
+  }
+
+  public async apply (storage: string, request: Input): Promise<Output> {
+    this.storage ??= await this.discovery.storage
+
+    const input = { storage, request, accept: this.accept }
+    const entry = await this.storage.invoke('store', { input })
+
+    return match<Output>(entry,
+      Error, (error: ErrorType) => this.throw(error),
+      () => this.reply(request, storage, entry))
+  }
+
+  private reply (request: Input, storage: string, entry: Entry): Output {
+    const body = this.workflow === undefined
+      ? entry
+      : Readable.from(this.execute(request, storage, entry))
+
+    return { body }
+  }
+
+  private throw (error: ErrorType): never {
+    throw match(error.code,
+      'NOT_ACCEPTABLE', () => new UnsupportedMediaType(),
+      'TYPE_MISMATCH', () => new BadRequest(),
+      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 as 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}`
+
+    this.components[key] ??= await this.discover(key, namespace, component)
+
+    return await this.components[key].invoke(operation, { input: context })
+  }
+
+  private async discover (key: string, namespace: string, component: string): Promise<Component> {
+    if (this.discovery[key] === undefined)
+      this.discovery[key] = this.remotes.discover(namespace, component)
+
+    return await this.discovery[key]
+  }
+}
+
+type Unit = Record<string, string>
+type Workflow = Unit[]
+
+interface Options {
+  accept: string | string[]
+  workflow: Workflow | Unit
+}
+
+interface Context {
+  storage: string
+  path: string
+  entry: Entry
+}

package/source/directives/octets/index.ts

@@ -0,0 +1,3 @@
+import Family from './Family'
+
+export = Family

package/source/directives/octets/schemas.ts

@@ -0,0 +1,12 @@
+import { resolve } from 'node:path'
+import schemas 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')

package/source/directives/octets/types.ts

@@ -0,0 +1,13 @@
+import type * as directive from '../../Directive'
+
+export interface Directive {
+  readonly targeted: boolean
+
+  apply: (storage: string, input: Input) => directive.Output | Promise<directive.Output>
+}
+
+export interface Extension {
+  octets?: string
+}
+
+export type Input = directive.Input & Extension