@toa.io/extensions.exposition 1.0.0-alpha.26 → 1.0.0-alpha.263

package/features/vary.feature

@@ -1,252 +0,0 @@
-Feature: The Vary directive family
-
-  Scenario Outline: Embedding a `<result>` language code
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          vary:languages: [en, fr]
-          GET:
-            vary:embed:
-              name: language  # embed resolved language code as a `name` property of the operation input
-            endpoint: compute
-      """
-    When the following request is received:
-      """
-      GET /echo/ HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      accept-language: <accept>
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-      content-language: <result>
-      vary: accept-language, accept
-
-      Hello <result>
-      """
-    Examples:
-      | accept | result |
-      | en     | en     |
-      | en_US  | en     |
-      | fr     | fr     |
-      | sw     | en     |
-
-  Scenario: Listing languages on the root
-    Given the annotation:
-    """
-    /:
-      vary:languages: [en, fr]
-    """
-    And the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          GET:
-            anonymous: true
-            vary:embed:
-              name: language
-            endpoint: compute
-      """
-    When the following request is received:
-      """
-      GET /echo/ HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      accept-language: fr
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-      content-language: fr
-      """
-
-  Scenario: Embedding a value of an arbitrary header
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          GET:
-            vary:embed:
-              name: :foo
-            endpoint: compute
-      """
-    When the following request is received:
-      """
-      GET /echo/ HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      foo: bar
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-      vary: foo, accept
-
-      Hello bar
-      """
-
-  Scenario: Embedding a `host` header value
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          GET:
-            vary:embed:
-              name: :Host
-            endpoint: compute
-      """
-    When the following request is received:
-      """
-      GET /echo/ HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      foo: bar
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-      vary: accept
-
-      Hello 127.0.0.1:8000
-      """
-
-  Scenario Outline: Embedding a value from the list of options
-    Given the `echo` is running with the following manifest:
-        """yaml
-        exposition:
-          /:
-            io:output: true
-            vary:languages: [en, fr]
-            GET:
-              vary:embed:
-                name:
-                  - :foo
-                  - :bar
-                  - language
-              endpoint: compute
-        """
-    When the following request is received:
-        """
-        GET /echo/ HTTP/1.1
-      host: nex.toa.io
-        accept: application/yaml
-        <header>: <value>
-        """
-    Then the following reply is sent:
-        """
-        200 OK
-        content-type: application/yaml
-        vary: <header>, accept
-
-        Hello <value>
-        """
-    Examples:
-      | header          | value |
-      | foo             | bar   |
-      | bar             | baz   |
-      | accept-language | en    |
-
-  Scenario: Embedding route parameter
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:friend:
-          io:output: true
-          GET:
-            vary:embed:
-              name: /:friend
-            endpoint: compute
-      """
-    When the following request is received:
-      """
-      GET /echo/Ken/ HTTP/1.1
-      host: nex.toa.io
-      accept: text/plain
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      Hello Ken
-      """
-
-  Scenario: Adding headers used by defined embeddings to CORS permissions
-    Given the `echo` is running with the following manifest:
-        """yaml
-        exposition:
-          /:
-            io:output: true
-            vary:languages: [en, fr]
-            GET:
-              vary:embed:
-                name:
-                  - language
-                  - :foo
-                  - :FOO
-                  - :bar
-              endpoint: compute
-        """
-    When the following request is received:
-        """
-        OPTIONS / HTTP/1.1
-      host: nex.toa.io
-        origin: https://example.com
-        access-control-request-headers: whatever
-        """
-    Then the following reply is sent:
-        """
-        204 No Content
-        access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, accept-language, foo, bar
-        """
-
-  Scenario: Embedding authority
-    Given the annotation:
-      """yaml
-      authorities:
-        one: the.one.com
-        two: the.two.com
-      """
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          GET:
-            vary:embed:
-              name: authority
-            endpoint: compute
-      """
-    When the following request is received:
-      """
-      GET /echo/ HTTP/1.1
-      host: the.one.com
-      accept: text/plain
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      Hello one
-      """
-    When the following request is received:
-      """
-      GET /echo/ HTTP/1.1
-      host: the.two.com
-      accept: text/plain
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      Hello two
-      """

package/schemas/octets/context.cos.yaml

@@ -1 +0,0 @@
-string

package/schemas/octets/fetch.cos.yaml

@@ -1,3 +0,0 @@
-blob: boolean
-meta: boolean
-_: true

package/schemas/octets/permute.cos.yaml

@@ -1 +0,0 @@
-~

package/schemas/octets/store.cos.yaml

@@ -1,3 +0,0 @@
-accept+: string
-workflow+: <string>
-_: true

package/source/directives/octets/Fetch.ts

@@ -1,100 +0,0 @@
-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'
-
-export class Fetch extends Directive {
-  public readonly targeted = true
-
-  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, input: Input): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    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, 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, input)
-  }
-
-  private async fetch (storage: string, input: Input): Promise<Output> {
-    if ('if-none-match' in input.request.headers)
-      return { status: 304 }
-
-    const result = await this.storage.invoke<Maybe<FetchResult>>('fetch', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-
-    if (result instanceof Error)
-      throw new NotFound()
-
-    const headers = new Headers({
-      'content-type': result.type,
-      'content-length': result.size.toString(),
-      etag: result.checksum
-    })
-
-    return {
-      headers,
-      body: result.stream
-    }
-  }
-
-  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()
-
-    return { body: entry }
-  }
-}
-
-export interface Permissions {
-  blob?: boolean
-  meta?: boolean
-}
-
-interface FetchResult {
-  stream: Readable
-  checksum: string
-  size: number
-  type: string
-}

package/source/directives/octets/List.ts

@@ -1,72 +0,0 @@
-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 { Input } from './types'
-
-export class List extends Directive {
-  public readonly targeted = false
-
-  private readonly permissions: Required<Permissions> = { meta: false }
-  private readonly discovery: Promise<Component>
-  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, input: Input): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    const metadata = input.subtype === 'octets.entries'
-
-    if (metadata && !this.permissions.meta)
-      throw new Forbidden('Metadata is not accessible.')
-
-    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, input.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/Store.ts

@@ -1,126 +0,0 @@
-import { PassThrough } from 'node:stream'
-import { match } from 'matchacho'
-import { BadRequest, UnsupportedMediaType } from '../../HTTP'
-import { cors } from '../cors'
-import * as schemas from './schemas'
-import { Workflow } from './workflows'
-import { Directive } from './Directive'
-import type { Readable } from 'stream'
-import type { Parameter } from '../../RTD'
-import type { Unit } from './workflows'
-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 '../../io'
-import type { Input } from './types'
-
-export class Store extends Directive {
-  public readonly targeted = false
-
-  private readonly accept?: string
-  private readonly workflow?: Workflow
-  private readonly discovery: Record<string, Promise<Component>> = {}
-  private storage: Component | null = null
-
-  public constructor
-  (options: Options | null, discovery: Promise<Component>, remotes: Remotes) {
-    super()
-    schemas.store.validate(options)
-
-    this.accept = match(options?.accept,
-      String, (value: string) => value,
-      Array, (types: string[]) => types.join(','),
-      undefined)
-
-    if (options?.workflow !== undefined)
-      this.workflow = new Workflow(options.workflow, remotes)
-
-    this.discovery.storage = discovery
-
-    cors.allow('content-meta')
-  }
-
-  public async apply (storage: string, input: Input, parameters: Parameter[]): Promise<Output> {
-    this.storage ??= await this.discovery.storage
-
-    const request: StoreRequest = {
-      input: {
-        storage,
-        request: input.request
-      }
-    }
-
-    const meta = input.request.headers['content-meta']
-
-    if (this.accept !== undefined)
-      request.input.accept = this.accept
-
-    if (meta !== undefined)
-      request.input.meta = this.parseMeta(meta)
-
-    const entry = await this.storage.invoke<Entry>('store', request)
-
-    return match<Output>(entry,
-      Error, (error: ErrorType) => this.throw(error),
-      () => this.reply(input, storage, entry, parameters))
-  }
-
-  // eslint-disable-next-line max-params
-  private reply (input: Input, storage: string, entry: Entry, parameters: Parameter[]): Output {
-    const body = this.workflow === undefined
-      ? entry
-      : this.execute(input, storage, entry, parameters)
-
-    return { body }
-  }
-
-  // eslint-disable-next-line max-params
-  private execute
-  (input: Input, storage: string, entry: Entry, parameters: Parameter[]): Readable {
-    const stream = new PassThrough({ objectMode: true })
-
-    stream.push(entry)
-
-    this.workflow!.execute(input, storage, entry, parameters).pipe(stream)
-
-    return stream
-  }
-
-  private throw (error: ErrorType): never {
-    throw match(error.code,
-      'NOT_ACCEPTABLE', () => new UnsupportedMediaType(),
-      'TYPE_MISMATCH', () => new BadRequest(),
-      error)
-  }
-
-  private parseMeta (value: string | string[]): Record<string, string> {
-    if (Array.isArray(value))
-      value = value.join(',')
-
-    const meta: Record<string, string> = {}
-
-    for (const pair of value.split(',')) {
-      const eq = pair.indexOf('=')
-      const key = (eq === -1 ? pair : pair.slice(0, eq)).trim()
-
-      meta[key] = eq === -1 ? 'true' : pair.slice(eq + 1).trim()
-    }
-
-    return meta
-  }
-}
-
-export interface Options {
-  accept?: string | string[]
-  workflow?: Unit[] | Unit
-}
-
-interface StoreRequest {
-  input: {
-    storage: string
-    request: Input['request']
-    accept?: string
-    meta?: Record<string, string>
-  }
-}

package/source/directives/vary/Directive.ts

@@ -1,7 +0,0 @@
-import type { Properties } from './Properties'
-import type { Input } from '../../io'
-import type { Parameter } from '../../RTD'
-
-export interface Directive {
-  preflight: (context: Input, properties: Properties, parameters: Parameter[]) => void
-}

package/source/directives/vary/Embed.ts

@@ -1,68 +0,0 @@
-import assert from 'node:assert'
-import { Header, embeddings, Parameter } from './embeddings'
-import type { Embedding } from './embeddings'
-import type { Input } from '../../io'
-import type { Directive } from './Directive'
-import type { Properties } from './Properties'
-import type * as RTD from '../../RTD'
-
-export class Embed implements Directive {
-  private readonly embeddings: Array<[string, Embedding[]]> = []
-
-  public constructor (map: Record<string, string | string[]>) {
-    for (const [key, values] of Object.entries(map)) {
-      const names = Array.isArray(values) ? values : [values]
-
-      const instances = names.map((name) => {
-        if (name[0] === ':')
-          return new Header(name.slice(1))
-
-        if (name.slice(0, 2) === '/:')
-          return new Parameter(name.slice(2))
-
-        assert.ok(name in embeddings, `Unknown embedding: ${name}`)
-
-        return new embeddings[name]()
-      })
-
-      this.embeddings.push([key, instances])
-    }
-  }
-
-  public preflight (context: Input, properties: Properties, parameters: RTD.Parameter[]): void {
-    const values: Record<string, unknown> = {}
-
-    for (const [key, instances] of this.embeddings)
-      values[key] = this.resolve(instances, context, properties, parameters)
-
-    context.pipelines.body.push(this.embedding(values))
-  }
-
-  // eslint-disable-next-line max-params
-  private resolve (instances: Embedding[],
-    input: Input,
-    properties: Properties,
-    parameters: RTD.Parameter[]): unknown {
-    let value
-
-    for (const instance of instances) {
-      value = instance.resolve(input, properties, parameters)
-
-      if (value !== undefined)
-        break
-    }
-
-    return value
-  }
-
-  private embedding (values: Record<string, unknown>) {
-    return (body: unknown): object => {
-      if (body === undefined || body === null || typeof body !== 'object')
-        return values
-
-      Object.assign(body, values)
-
-      return body
-    }
-  }
-}

package/source/directives/vary/Vary.ts

@@ -1,50 +0,0 @@
-import { match } from 'matchacho'
-import { properties, Property } from './Properties'
-import { Embed } from './Embed'
-import type { Properties } from './Properties'
-import type { Directive } from './Directive'
-import type { DirectiveFamily, Parameter } from '../../RTD'
-import type { Input, Output } from '../../io'
-
-export class Vary implements DirectiveFamily {
-  public readonly name = 'vary'
-  public readonly mandatory = false
-
-  public create (name: string, value: unknown): Property | Directive {
-    return match(name,
-      () => name in properties, (name: PN) => new Property(name, value as PV),
-      () => name in directives, (name: keyof typeof directives) => new directives[name](value),
-      () => {
-        throw new Error(`Directive 'vary:${name}' is not implemented.`)
-      })
-  }
-
-  public preflight (instances: Array<Directive | Property>,
-    context: Input,
-    parameters: Parameter[]): Output {
-    /*
-    To stop constructing `properties` object on each request, Directive Families must be refactored
-    from singleton factories to per-Node instances on the Tree.
-     */
-    const properties: Properties = {}
-    const directives: Directive[] = []
-
-    for (const instance of instances)
-      if (instance instanceof Property)
-        properties[instance.name] = instance.value
-      else
-        directives.push(instance)
-
-    for (const directive of directives)
-      directive.preflight(context, properties, parameters)
-
-    return null
-  }
-}
-
-type PN = keyof Properties
-type PV = Properties[PN]
-
-const directives: Record<string, new (value: any) => Directive> = {
-  embed: Embed
-}

package/source/directives/vary/embeddings/Authority.ts

@@ -1,8 +0,0 @@
-import type { Embedding } from './Embedding'
-import type { Input } from '../../../io'
-
-export class Authority implements Embedding {
-  public resolve (context: Input): string {
-    return context.authority
-  }
-}