@toa.io/extensions.exposition 0.22.1 → 1.0.0-alpha.0

package/source/HTTP/messages.ts

@@ -1,23 +1,28 @@
-import { type IncomingHttpHeaders, type OutgoingHttpHeaders } from 'node:http'
+import { type IncomingHttpHeaders } from 'node:http'
 import { Readable } from 'node:stream'
 import { type Request, type Response } from 'express'
-import Negotiator from 'negotiator'
-import { buffer } from '@toa.io/generic'
-import { map } from '@toa.io/streams'
-import { formats, types } from './formats'
+import { buffer } from '@toa.io/streams'
+import { formats } from './formats'
 import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
-
-export function write (request: Request, response: Response, body: any): void {
-  if (body instanceof Readable) void pipe(body, request, response)
-  else send(body, request, response)
+import type { ParsedQs } from 'qs'
+import type { Format } from './formats'
+
+export function write
+(request: IncomingMessage, response: Response, message: OutgoingMessage): void {
+  if (message.body instanceof Readable)
+    stream(message, request, response)
+  else
+    send(message, request, response)
 }
 
 export async function read (request: Request): Promise<any> {
   const type = request.headers['content-type']
 
-  if (type === undefined) return undefined
+  if (type === undefined)
+    return undefined
 
-  if (!(type in formats)) throw new UnsupportedMediaType()
+  if (!(type in formats))
+    throw new UnsupportedMediaType()
 
   const format = formats[type]
 
@@ -30,57 +35,77 @@ export async function read (request: Request): Promise<any> {
   }
 }
 
-function send (body: any, request: Request, response: Response): void {
-  if (body === undefined || body?.length === 0) {
+function send (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
+  if (message.body === undefined) {
     response.end()
 
     return
   }
 
-  const type = negotiate(request)
-  const format = formats[type]
-  const buf = format.encode(body)
+  if (request.encoder === null)
+    throw new NotAcceptable()
+
+  const buf = request.encoder.encode(message.body)
 
-  // content-length and etag are set by Express
-  response.set('content-type', type)
-  response.send(buf)
+  response.set('content-type', request.encoder.type)
+  response.end(buf)
 }
 
-async function pipe (stream: Readable, request: Request, response: Response): Promise<void> {
-  const type = negotiate(request)
-  const format = formats[type]
+function stream
+(message: OutgoingMessage, request: IncomingMessage, response: Response): void {
+  const encoded = message.headers !== undefined && message.headers.has('content-type')
+
+  if (encoded)
+    pipe(message, response)
+  else
+    multipart(message, request, response)
 
-  response.set('content-type', type)
-  map(stream, format.encode).pipe(response)
+  message.body.on('error', (e: Error) => {
+    console.error(e)
+    response.end()
+  })
 }
 
-function negotiate (request: Request): string {
-  const negotiator = new Negotiator(request)
-  const mediaType = negotiator.mediaType(types)
+function pipe (message: OutgoingMessage, response: Response): void {
+  message.headers?.forEach((value, key) => response.set(key, value))
+  message.body.pipe(response)
+}
 
-  if (mediaType === undefined) throw new NotAcceptable()
+function multipart (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
+  if (request.encoder === null)
+    throw new NotAcceptable()
 
-  return mediaType
-}
+  const encoder = request.encoder
 
-interface Message {
-  body: any
+  response.set('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
+
+  message.body
+    .map((part: unknown) => Buffer.concat([CUT, encoder.encode(part)]))
+    .on('end', () => response.end(FINALCUT))
+    .pipe(response)
 }
 
-export interface IncomingMessage extends Message {
+const BOUNDARY = 'cut'
+const CUT = Buffer.from(`--${BOUNDARY}\r\n`)
+const FINALCUT = Buffer.from(`--${BOUNDARY}--`)
+
+export interface IncomingMessage extends Request {
   method: string
   path: string
+  url: string
   headers: IncomingHttpHeaders
   query: Query
+  parse: <T> () => Promise<T>
+  encoder: Format | null
 }
 
 export interface OutgoingMessage {
   status?: number
-  headers?: OutgoingHttpHeaders
+  headers?: Headers
   body?: any
 }
 
-export interface Query {
+export interface Query extends ParsedQs {
   id?: string
   criteria?: string
   sort?: string

package/source/RTD/Route.ts

@@ -25,7 +25,7 @@ export class Route {
       if (segment.fragment !== null && segment.fragment !== fragments[i])
         return null
 
-      if (segment.fragment === null)
+      if (segment.fragment === null && segment.placeholder !== null)
         parameters.push({ name: segment.placeholder, value: fragments[i] })
     }
 

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/RTD/syntax/parse.ts

@@ -5,7 +5,8 @@ import {
   type Route,
   type Method,
   type Mapping,
-  type Directive, type Range
+  type Directive,
+  type Range
 } from './types'
 
 export function parse (input: object, shortcuts?: Shortcuts): Node {

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

@@ -30,6 +30,11 @@ export class Tenant extends Connector {
       `'${this.branch.namespace}.${this.branch.component}' has started.`)
   }
 
+  public override async dispose (): Promise<void> {
+    console.info('Exposition Tenant for ' +
+      `'${this.branch.namespace}.${this.branch.component}' has been stopped.`)
+  }
+
   private async expose (): Promise<void> {
     await this.broadcast.transmit('expose', this.branch)
   }

package/source/directives/auth/Family.ts

@@ -1,31 +1,34 @@
-import { type Component } from '@toa.io/core'
-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
@@ -40,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
@@ -86,9 +90,9 @@ class Authorization implements Family<Directive, Extension> {
     const authorization = `Token ${token}`
 
     if (response.headers === undefined)
-      response.headers = {}
+      response.headers = new Headers()
 
-    response.headers.authorization = authorization
+    response.headers.set('authorization', authorization)
   }
 
   private async resolve (authorization: string | undefined): Promise<Identity | null> {

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/cache/Control.ts

@@ -0,0 +1,59 @@
+import { match } from 'matchacho'
+import type { AuthenticatedRequest, Directive } from './types'
+
+export class Control implements Directive {
+  protected readonly value: string
+  private cache: string | null = null
+
+  public constructor (value: string) {
+    this.value = value
+  }
+
+  public set (request: AuthenticatedRequest, headers: Headers): void {
+    if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method))
+      return
+
+    this.cache ??= this.resolve(request)
+
+    headers.set('cache-control', this.cache)
+  }
+
+  protected resolve (request: AuthenticatedRequest): string {
+    if (request.identity === null)
+      return this.value
+
+    const directives = this.mask()
+
+    if ((directives & (PUBLIC | NO_CACHE)) === PUBLIC)
+      return 'no-cache, ' + this.value
+
+    if ((directives & (PUBLIC | PRIVATE)) === 0)
+      return 'private, ' + this.value
+
+    return this.value
+  }
+
+  private mask (): number {
+    const directives = this.value.match(DIRECTIVES_RX)
+
+    if (directives === null)
+      return 0
+
+    let mask = 0
+
+    for (const directive of directives)
+      mask |= match<number>(directive,
+        'private', PRIVATE,
+        'public', PUBLIC,
+        'no-cache', NO_CACHE,
+        0)
+
+    return mask
+  }
+}
+
+const DIRECTIVES_RX = /\b(private|public|no-cache)\b/ig
+
+const PUBLIC = 1
+const PRIVATE = 2
+const NO_CACHE = 4

package/source/directives/cache/Exact.ts

@@ -0,0 +1,7 @@
+import { Control } from './Control'
+
+export class Exact extends Control {
+  protected override resolve (): string {
+    return this.value
+  }
+}

package/source/directives/cache/Family.ts

@@ -0,0 +1,36 @@
+import { type Input, type Output, type Family } from '../../Directive'
+import { Control } from './Control'
+import { type Directive } from './types'
+import { Exact } from './Exact'
+import type * as http from '../../HTTP'
+
+class Cache implements Family<Directive> {
+  public readonly name: string = 'cache'
+  public readonly mandatory: boolean = false
+
+  public create (name: string, value: any): Directive {
+    const Class = constructors[name]
+
+    if (Class === undefined)
+      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+
+    return new Class(value)
+  }
+
+  public preflight (): Output {
+    return null
+  }
+
+  public async settle
+  (directives: Directive[], request: Input, response: http.OutgoingMessage): Promise<void> {
+    response.headers ??= new Headers()
+    directives[0]?.set(request, response.headers)
+  }
+}
+
+const constructors: Record<string, new (value: any) => Directive> = {
+  control: Control,
+  exact: Exact
+}
+
+export = new Cache()

package/source/directives/cache/index.ts

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

package/source/directives/cache/types.ts

@@ -0,0 +1,9 @@
+import { type Input } from '../../Directive'
+
+export interface Directive {
+  set: (input: Input, headers: Headers) => void
+}
+
+export interface AuthenticatedRequest extends Input {
+  identity?: unknown | null
+}

package/source/directives/index.ts

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

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 = new Headers({
+      'content-type': result.type,
+      'content-length': result.size.toString(),
+      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 }
+  }
+}