@toa.io/extensions.exposition 1.0.0-alpha.19 → 1.0.0-alpha.190

package/features/vary.feature

@@ -1,203 +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
-      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
-      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
-      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
-      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
-        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
-      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
-        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
-        """

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/HTTP/Server.test.ts

@@ -1,126 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { Connector } from '@toa.io/core'
-import { type Processing, Server } from './Server'
-import { type OutgoingMessage } from './messages'
-import { BadRequest } from './exceptions'
-
-let server: Server
-
-beforeAll(() => {
-  server = Server.create({ port: 0 })
-})
-
-it('should instance of connector', async () => {
-  expect(server).toBeInstanceOf(Connector)
-})
-
-it('should start HTTP server', async () => {
-  await server.connect()
-
-  expect(server.connected).toBeTruthy()
-  expect(server.port).toBeGreaterThan(0)
-})
-
-it('should register request handler', async () => {
-  const process: Processing = jest.fn().mockResolvedValue(undefined)
-
-  server.attach(process)
-
-  const res = await fetch(`http://localhost:${server.port}`)
-
-  await res.text()
-
-  expect(process).toHaveBeenCalledTimes(1)
-})
-
-it('should send 501 on unknown method', async () => {
-  const head = await fetch(`http://localhost:${server.port}/`, { method: 'COPY' })
-
-  await head.text()
-  expect(head.status).toBe(501)
-})
-
-it('should stop HTTP server', async () => {
-  await server.connect()
-  await server.disconnect()
-  expect(server.connected).toBeFalsy()
-})
-
-describe('result', () => {
-  beforeEach(async () => {
-    server = Server.create({ port: 0 })
-    await server.connect()
-  })
-
-  afterEach(async () => {
-    await server.disconnect()
-  })
-
-  it('should send status code 200 if the result has a value', async () => {
-    server.attach(async (): Promise<OutgoingMessage> => ({
-      headers: new Headers(), body: randomUUID()
-    }))
-
-    const res = await fetch(`http://localhost:${server.port}/`)
-
-    await res.text()
-    expect(res.status).toBe(200)
-  })
-
-  it('should send status code 204 if the result has no value', async () => {
-    server.attach(async (): Promise<OutgoingMessage> => ({ headers: new Headers() }))
-
-    const res = await fetch(`http://localhost:${server.port}/`)
-
-    await res.text()
-    expect(res.status).toBe(204)
-  })
-
-  it('should send result', async () => {
-    const body = { [randomUUID()]: randomUUID() }
-
-    server.attach(async (): Promise<OutgoingMessage> =>
-      ({ headers: new Headers(), body }))
-
-    const res = await fetch(`http://localhost:${server.port}/`,
-      { headers: { accept: 'application/json' } })
-
-    const result = await res.json()
-
-    expect(result).toEqual(body)
-  })
-
-  it('should return 500 on exception', async () => {
-    server.attach(jest.fn().mockRejectedValue(new Error('Bad')))
-
-    const res = await fetch(`http://localhost:${server.port}/`)
-
-    await res.text()
-    expect(res.status).toBe(500)
-  })
-
-  it('should send client error', async () => {
-    const message = randomUUID()
-
-    server.attach(jest.fn().mockRejectedValueOnce(new BadRequest(message)))
-
-    const res = await fetch(`http://localhost:${server.port}/`)
-    const text = await res.text()
-
-    expect(res.status).toBe(400)
-    expect(text).toContain(message)
-  })
-})
-
-describe('options', () => {
-  it('should send 501 on unspecified method', async () => {
-    server = Server.create({ methods: new Set(['COPY']), port: 0 })
-    await server.connect()
-
-    const res = await fetch(`http://localhost:${server.port}/`)
-
-    await res.text()
-    await server.disconnect()
-    expect(res.status).toBe(501)
-  })
-})

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/Permute.ts

@@ -1,44 +0,0 @@
-import { NotAcceptable, NotFound } from '../../HTTP'
-import * as schemas from './schemas'
-import { Directive } from './Directive'
-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 Permute extends Directive {
-  public readonly targeted = false
-
-  private readonly discovery: Promise<Component>
-  private storage: Component | null = null
-
-  public constructor (value: null, discovery: Promise<Component>) {
-    super()
-    schemas.permute.validate(value)
-
-    this.discovery = discovery
-  }
-
-  public async apply (storage: string, input: Input): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    if (input.encoder === null)
-      throw new NotAcceptable()
-
-    const path = input.request.url
-    const list = await input.body()
-
-    const error = await this.storage.invoke<Maybe<unknown>>('permute', {
-      input: {
-        storage,
-        path,
-        list
-      }
-    })
-
-    if (error instanceof Error)
-      throw new NotFound()
-
-    return {}
-  }
-}

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/Embedding.ts

@@ -1,7 +0,0 @@
-import type { Properties } from '../Properties'
-import type { Input } from '../../../io'
-import type { Parameter } from '../../../RTD'
-
-export interface Embedding {
-  resolve: (input: Input, properties: Properties, parameters: Parameter[]) => string | undefined
-}