@toa.io/extensions.exposition 1.0.0-alpha.292 → 1.0.0-alpha.293

package/source/directives/octets/Delete.ts

@@ -1,96 +0,0 @@
-import { Readable } from 'stream'
-import { NotFound } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { Workflow } from './workflows/index.js'
-import { Directive } from './Directive.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Unit, Location } from './workflows/index.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Input } from './types.js'
-import type { Remotes } from '../../Remotes.js'
-import type { Entry } from '@toa.io/extensions.storages'
-
-export class Delete extends Directive {
-  public readonly targeted = true
-
-  private readonly workflow?: Workflow
-  private readonly discovery: Promise<Component>
-  private storage!: Component
-
-  public constructor(
-    options: Options | null,
-    discovery: Promise<Component>,
-    remotes: Remotes
-  ) {
-    super()
-    schemas.remove.validate(options)
-
-    if (options?.workflow !== undefined)
-      this.workflow = new Workflow(options.workflow, remotes)
-
-    this.discovery = discovery
-  }
-
-  public async apply(
-    storage: string,
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    const output: Output = {}
-
-    if (this.workflow !== undefined) {
-      const entry = await this.storage.invoke<Maybe<Entry>>('head', {
-        input: {
-          storage,
-          path: input.request.url
-        }
-      })
-
-      if (entry instanceof Error) throw new NotFound()
-
-      output.status = 202
-      output.body = Readable.from(this.execute(input, storage, entry, parameters))
-    } else await this.delete(storage, input)
-
-    return output
-  }
-
-  private async delete(storage: string, input: Input): Promise<void> {
-    await this.storage.invoke('delete', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-  }
-
-  // eslint-disable-next-line max-params
-  private async *execute(
-    input: Input,
-    storage: string,
-    entry: Entry,
-    parameters: Parameter[]
-  ): AsyncGenerator {
-    const location: Location = {
-      storage,
-      authority: input.authority,
-      path: input.request.url
-    }
-
-    for await (const chunk of this.workflow!.execute(location, entry, parameters)) {
-      yield chunk
-
-      if (typeof chunk === 'object' && chunk !== null && 'error' in chunk) return
-    }
-
-    await this.delete(storage, input)
-  }
-}
-
-export interface Options {
-  workflow?: Unit[] | Unit
-}

package/source/directives/octets/Directive.ts

@@ -1,21 +0,0 @@
-import type { Input } from './types.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type * as io from '../../io.js'
-
-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>
-
-  /**
-   * What a caller has to know to make the request. Only sending a file takes anything a
-   * schema does not already say; reading one and deleting one take nothing.
-   */
-  public describe?(introspection: Introspection): void
-}

package/source/directives/octets/Get.ts

@@ -1,88 +0,0 @@
-import { Forbidden, NotFound } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { Directive } from './Directive.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Entry, Stream } from '@toa.io/extensions.storages'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Input } from './types.js'
-
-export class Get extends Directive {
-  public readonly targeted = true
-
-  private readonly options: Required<Options> = {
-    meta: false
-  }
-
-  private readonly discovery: Promise<Component>
-  private storage!: Component
-
-  public constructor(options: Options | null, discovery: Promise<Component>) {
-    super()
-
-    schemas.get.validate(options)
-    Object.assign(this.options, options)
-
-    this.discovery = discovery
-  }
-
-  public async apply(storage: string, input: Input): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    if (input.subtype === 'octets.entry')
-      if (this.options.meta) return this.head(storage, input)
-      else throw new Forbidden('Metadata is not accessible')
-    else return await this.get(storage, input)
-  }
-
-  private async get(storage: string, input: Input): Promise<Output> {
-    if ('if-none-match' in input.request.headers) return { status: 304 }
-
-    const endpoint = input.request.method === 'GET' ? 'get' : 'head'
-
-    const entry = await this.storage.invoke<Maybe<Stream>>(endpoint, {
-      input: {
-        storage,
-        path: input.request.url,
-        range: input.request.headers.range,
-        agent: input.request.headers['user-agent']
-      }
-    })
-
-    if (entry instanceof Error) throw new NotFound()
-
-    const headers = new Headers({
-      'content-type': entry.type,
-      etag: `"${entry.checksum}"`
-    })
-
-    if (entry.range !== undefined) headers.set('content-range', entry.range)
-
-    // an absent content-length is what says the length is unknown; naming the encoding
-    // is redundant over HTTP/1.1 and forbidden over HTTP/2
-    if (entry.size !== null) headers.set('content-length', entry.size.toString())
-
-    return {
-      status: entry.partial === true ? 206 : 200,
-      headers,
-      body: endpoint === 'get' ? entry.stream : undefined
-    }
-  }
-
-  private async head(storage: string, input: Input): Promise<Output> {
-    const entry = await this.storage.invoke<Maybe<Entry>>('head', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-
-    if (entry instanceof Error) throw new NotFound()
-
-    return { body: entry }
-  }
-}
-
-export interface Options {
-  meta?: boolean
-}

package/source/directives/octets/Octets.ts

@@ -1,82 +0,0 @@
-import { NotFound } from '../../HTTP/index.js'
-import { Context } from './Context.js'
-import { Put } from './Put.js'
-import { Get } from './Get.js'
-import { Delete } from './Delete.js'
-import { WorkflowDirective } from './Workflow.js'
-import type { Directive } from './Directive.js'
-import type { Output } from '../../io.js'
-import type { Component } from '@toa.io/core'
-import type { Remotes } from '../../Remotes.js'
-import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Input } from './types.js'
-
-export class Octets implements DirectiveFamily<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 'octets:${name}' is not implemented`)
-
-    this.discovery ??= remotes.discover('exposition', 'octets')
-
-    return new Class(value, this.discovery, remotes)
-  }
-
-  /** What the request takes, which only sending a file says anything about. */
-  public explain(directives: Directive[], _: Input, introspection: Introspection): Introspection {
-    for (const directive of directives) directive.describe?.(introspection)
-
-    return introspection
-  }
-
-  public async precall(
-    directives: Directive[],
-    input: Input,
-    parameters: Parameter[]
-  ): 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 ambiguous')
-
-    if (action === null) return null
-
-    // noinspection PointlessBooleanExpressionJS
-    if (context === null) throw new Error('Octets context is not defined')
-
-    const targeted = input.request.url[input.request.url.length - 1] !== '/'
-
-    if (targeted !== action.targeted)
-      throw new NotFound(
-        `Trailing slash is ${action.targeted ? 'redundant' : 'required'}`
-      )
-
-    // noinspection JSObjectNullOrUndefined
-    return await action.apply(context.storage, input, parameters)
-  }
-}
-
-const DIRECTIVES: Record<string, Constructor> = {
-  context: Context,
-  put: Put,
-  get: Get,
-  head: Get,
-  delete: Delete,
-  workflow: WorkflowDirective
-}
-
-type Constructor = new (
-  value: any,
-  discovery: Promise<Component>,
-  remotes: Remotes
-) => Directive

package/source/directives/octets/Put.ts

@@ -1,186 +0,0 @@
-import { PassThrough } from 'node:stream'
-import { match } from 'matchacho'
-import * as http from '../../HTTP/index.js'
-import { cors } from '../cors/index.js'
-import * as schemas from './schemas.js'
-import { Workflow } from './workflows/index.js'
-import { Directive } from './Directive.js'
-import { toBytes } from './bytes.js'
-import type { Readable } from 'stream'
-import type { Parameter } from '../../RTD/index.js'
-import type { Unit, Location } from './workflows/index.js'
-import type { Entry } from '@toa.io/extensions.storages'
-import type { Remotes } from '../../Remotes.js'
-import type { Component } from '@toa.io/core'
-import type { Introspection } from '../../Introspection.js'
-import type { Output } from '../../io.js'
-import type { Input } from './types.js'
-
-export class Put extends Directive {
-  public readonly targeted = false
-
-  private readonly location?: string
-  private readonly accept?: string
-  private readonly limit: number
-  private readonly limitString: string
-  private readonly trust?: Array<string | RegExp>
-  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.put.validate<Options>(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)
-
-    if (options?.trust !== undefined)
-      this.trust = options.trust.map((value: string) =>
-        value.startsWith('/') ? new RegExp(value.slice(1, -1)) : value
-      )
-
-    if (options?.location !== undefined) this.location = options.location
-
-    this.limitString = options?.limit ?? '64MiB'
-    this.limit = toBytes(this.limitString)
-    this.discovery.storage = discovery
-
-    cors.allow('content-attributes')
-    cors.allow('content-location')
-  }
-
-  /** What sending a file here takes: what may be sent, how much of it, and what comes back. */
-  public override describe(introspection: Introspection): void {
-    introspection.octets = {
-      ...(this.accept === undefined ? {} : { accept: this.accept }),
-      limit: this.limitString,
-      ...(this.workflow === undefined ? {} : { stream: true })
-    }
-  }
-
-  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,
-        location: this.location,
-        accept: this.accept,
-        limit: this.limit,
-        trust: this.trust
-      }
-    }
-
-    const entry = await this.storage.invoke<Entry>('put', request)
-
-    return match<Output>(
-      entry,
-      Error,
-      (error: CodedError) => 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)
-
-    const location: Location = {
-      storage,
-      authority: input.authority,
-      identity: input.identity?.id,
-      path: this.location ?? input.request.url
-    }
-
-    this.workflow!.execute(location, entry, parameters).pipe(stream)
-
-    return stream
-  }
-
-  private throw(error: CodedError): never {
-    throw match(
-      error.code,
-      'NOT_ACCEPTABLE',
-      () => new http.UnsupportedMediaType(),
-      'TYPE_MISMATCH',
-      () => new http.BadRequest(),
-      'LIMIT_EXCEEDED',
-      () => new http.RequestEntityTooLarge(`Size limit is ${this.limitString}`),
-      'LOCATION_UNTRUSTED',
-      () => new http.Forbidden(error.message),
-      'LOCATION_LENGTH',
-      () => new http.BadRequest(error.message),
-      'LOCATION_UNAVAILABLE',
-      () => new http.NotFound(error.message),
-      'INVALID_ID',
-      () => new http.BadRequest(error.message),
-      error
-    )
-  }
-}
-
-export interface Options {
-  location?: string
-  accept?: string | string[]
-  limit?: string
-  workflow?: Unit[] | Unit
-  trust?: string[]
-}
-
-interface StoreRequest {
-  input: {
-    storage: string
-    request: Input['request']
-    location?: string
-    accept?: string
-    limit?: number
-    trust?: Array<string | RegExp>
-    attributes?: Record<string, string>
-  }
-}
-
-interface CodedError extends Error {
-  code: string
-}

package/source/directives/octets/Workflow.ts

@@ -1,60 +0,0 @@
-import { NotFound } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { Workflow } from './workflows/index.js'
-import { Directive } from './Directive.js'
-import type { Unit, Location } from './workflows/index.js'
-import type { Input } from './types.js'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Remotes } from '../../Remotes.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Entry } from '@toa.io/extensions.storages'
-import type { Parameter } from '../../RTD/index.js'
-
-export class WorkflowDirective extends Directive {
-  public readonly targeted = true
-
-  private readonly workflow: Workflow
-  private readonly discovery: Promise<Component>
-  private storage: Component | null = null
-
-  public constructor(
-    units: Unit[] | Unit,
-    discovery: Promise<Component>,
-    remotes: Remotes
-  ) {
-    super()
-    schemas.workflow.validate(units)
-
-    this.workflow = new Workflow(units, remotes)
-    this.discovery = discovery
-  }
-
-  public async apply(
-    storage: string,
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    const entry = await this.storage.invoke<Maybe<Entry>>('head', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-
-    if (entry instanceof Error) throw new NotFound()
-
-    const location: Location = {
-      storage,
-      authority: input.authority,
-      path: input.request.url
-    }
-
-    return {
-      status: 202,
-      body: this.workflow.execute(location, entry, parameters)
-    }
-  }
-}

package/source/directives/octets/bytes.test.ts

@@ -1,33 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { toBytes } from './bytes.js'
-
-it('should parse bytes', async () => {
-  assert.strictEqual(toBytes('10'), 10)
-  assert.strictEqual(toBytes('10B'), 10)
-})
-
-it('should parse binary prefix', async () => {
-  assert.strictEqual(toBytes('10KiB'), 10240)
-  assert.strictEqual(toBytes('10MiB'), 10485760)
-  assert.strictEqual(toBytes('10GiB'), 10737418240)
-  assert.strictEqual(toBytes('10TiB'), 10995116277760)
-})
-
-it('should parse decimal prefix', async () => {
-  assert.strictEqual(toBytes('10kB'), 10000)
-  assert.strictEqual(toBytes('10MB'), 10000000)
-  assert.strictEqual(toBytes('10GB'), 10000000000)
-  assert.strictEqual(toBytes('10TB'), 10000000000000)
-})
-
-it('should parse incorrect value as binary', async () => {
-  assert.strictEqual(toBytes('10b'), 10)
-  assert.strictEqual(toBytes('10kb'), 10240)
-  assert.strictEqual(toBytes('10kib'), 10240)
-  assert.strictEqual(toBytes('10mb'), 10485760)
-  assert.strictEqual(toBytes('10gb'), 10737418240)
-  assert.strictEqual(toBytes('10tib'), 10995116277760)
-  assert.strictEqual(toBytes('10Mb'), 10485760)
-})

package/source/directives/octets/bytes.ts

@@ -1,18 +0,0 @@
-import assert from 'node:assert'
-
-export function toBytes(input: string): number {
-  const match = RX.exec(input)
-
-  assert.ok(match !== null, `Invalid bytes format: ${input}`)
-
-  const value = parseFloat(match.groups!.value)
-  const prefix = match.groups!.prefix?.[0].toLowerCase() ?? ''
-  const binary = match.groups!.binary !== undefined || match.groups!.unit === 'b'
-  const base = binary ? 1024 : 1000
-  const power = POWERS.indexOf(prefix)
-
-  return value * Math.pow(base, power)
-}
-
-const POWERS = ['', 'k', 'm', 'g', 't']
-const RX = /^(?<value>(\d+)(\.\d+)?)(?<prefix>[kmgt](?<binary>i)?)?(?<unit>b)?$/i

package/source/directives/octets/index.ts

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

package/source/directives/octets/schemas.test.ts

@@ -1,20 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import * as schemas from './schemas.js'
-
-describe('workflow', () => {
-  const ok = [{ echo: 'hello world' }, [{ echo: 'hello world' }, { ok: 'ok' }]]
-
-  const oh = [{ echo: [] }, { echo: 'hello world', ok: { not: 'ok' } }]
-
-  for (const workflow of ok)
-    it('should be valid', () => {
-      assert.doesNotThrow(() => schemas.workflow.validate(workflow))
-    })
-
-  for (const workflow of oh)
-    it('should not be valid', () => {
-      assert.throws(() => schemas.workflow.validate(workflow))
-    })
-})

package/source/directives/octets/schemas.ts

@@ -1,15 +0,0 @@
-import { resolve } from 'node:path'
-import * as schemas from '@toa.io/schemas'
-import type { Options as GetOptions } from './Get.js'
-import type { Options as PutOptions } from './Put.js'
-import type { Options as DeleteOptions } from './Delete.js'
-import type { Schema } from '@toa.io/schemas'
-import type { Unit } from './workflows/index.js'
-
-const path = resolve(import.meta.dirname, '../../../schemas/octets')
-const namespace = schemas.namespace(path)
-
-export const put: Schema<PutOptions | null> = namespace.schema('put')
-export const get: Schema<GetOptions | null> = namespace.schema('get')
-export const remove: Schema<DeleteOptions | null> = namespace.schema('delete')
-export const workflow: Schema<Unit[] | Unit> = namespace.schema('workflow')

package/source/directives/octets/types.ts

@@ -1,9 +0,0 @@
-import type * as io from '../../io.js'
-import type { Identity } from '../auth/types.js' // meh
-
-export interface Extension {
-  identity?: Identity
-  octets?: string
-}
-
-export type Input = io.Input & Extension