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

package/schemas/query.cos.yaml

@@ -1,17 +1,11 @@
-_: true
 id?: string
 criteria?: string
 sort?: string
-omit:
+omit?:
   $ref: range
-  default:
-    value: 0
-    range: [0, 1000]
-limit:
+limit?:
   $ref: range
-  default:
-    value: 10
-    range: [1, 1000]
-  required: [value]
 selectors?: [string]
 projection?: [string]
+parameters?: [string]
+_: true

package/schemas/querystring.cos.yaml

@@ -3,3 +3,4 @@ criteria: string
 sort: string
 omit: number
 limit: number
+version: number

package/source/Annotation.ts

@@ -1,7 +1,8 @@
 export interface Annotation {
-  host?: string
+  authorities: Record<string, string>
   class?: string
   annotations?: Record<string, string>
-  debug: boolean
+  debug?: boolean
+  trace?: boolean
   '/'?: object // parsed and validated by RTD.syntax.parse
 }

package/source/Branch.ts

@@ -5,4 +5,5 @@ export interface Branch {
   component: string
   isolated: boolean
   node: RTD.Node
+  version: string
 }

package/source/Composition.ts

@@ -18,12 +18,6 @@ export class Composition extends Connector {
     await composition.connect()
 
     this.depends(composition)
-
-    console.info('Composition complete.')
-  }
-
-  protected override dispose (): void {
-    console.info('Composition shutdown complete.')
   }
 }
 

package/source/Context.ts

@@ -1,6 +1,9 @@
-import { type Endpoint } from './Endpoint'
-import { type Directives } from './Directive'
-import { type Branch } from './Branch'
 import type * as RTD from './RTD'
 
-export type Context = RTD.Context<Endpoint, Directives, Branch>
+export type Context = RTD.Context<Extension>
+
+interface Extension {
+  namespace: string
+  component: string
+  version: string
+}

package/source/Directive.test.ts

@@ -1,10 +1,11 @@
+import assert from 'node:assert'
 import { generate } from 'randomstring'
-import { DirectivesFactory, type Family } from './Directive'
-import { type syntax } from './RTD'
-import { type IncomingMessage } from './HTTP'
-import { type Remotes } from './Remotes'
+import { DirectivesFactory } from './Directive'
+import type { syntax, DirectiveFamily } from './RTD'
+import type { Remotes } from './Remotes'
+import type { Context } from './HTTP'
 
-const families: Array<jest.MockedObject<Family>> = [
+const families: Array<jest.MockedObjectDeep<DirectiveFamily>> = [
   {
     name: 'foo',
     mandatory: true,
@@ -26,6 +27,9 @@ let factory: DirectivesFactory
 beforeEach(() => {
   jest.clearAllMocks()
 
+  assert.ok(families[0].preflight !== undefined)
+  assert.ok(families[1].preflight !== undefined)
+
   families[0].preflight.mockImplementation(() => null)
   families[1].preflight.mockImplementation(() => null)
   factory = new DirectivesFactory(families, {} as unknown as Remotes)
@@ -61,7 +65,7 @@ it('should throw error if directive family is not found', async () => {
   }
 
   expect(() => factory.create([declaration]))
-    .toThrowError(`Directive family '${declaration.family}' not found.`)
+    .toThrowError(`Directive family '${declaration.family}' is not found`)
 })
 
 it('should apply directive', async () => {
@@ -72,18 +76,20 @@ it('should apply directive', async () => {
   }
 
   const directives = factory.create([declaration])
-  const request = generate() as unknown as IncomingMessage
+  const request = generate() as unknown as Context
   const directive = families[0].create.mock.results[0].value
 
   await directives.preflight(request, [])
 
+  assert.ok(families[0].preflight !== undefined)
+
   expect(families[0].preflight.mock.calls[0][0]).toStrictEqual([directive])
   expect(families[0].preflight.mock.calls[0][1]).toEqual(request)
 })
 
 it('should apply mandatory families', async () => {
   const directives = factory.create([])
-  const request = generate() as unknown as IncomingMessage
+  const request = generate() as unknown as Context
 
   await directives.preflight(request, [])
 

package/source/Directive.ts

@@ -1,45 +1,42 @@
-import { type IncomingMessage, type OutgoingMessage } from './HTTP'
-import { type Remotes } from './Remotes'
+import type { Context, OutgoingMessage } from './HTTP'
+import type { Remotes } from './Remotes'
+import type { Output } from './io'
 import type * as RTD from './RTD'
 
-export class Directives implements RTD.Directives<Directives> {
-  private readonly directives: DirectiveSet[]
+export class Directives implements RTD.Directives {
+  private readonly sets: RTD.DirectiveSet[]
 
-  public constructor (directives: DirectiveSet[]) {
-    this.directives = directives
+  public constructor (sets: RTD.DirectiveSet[]) {
+    this.sets = sets
   }
 
-  public async preflight (request: IncomingMessage, parameters: RTD.Parameter[]): Promise<Output> {
-    for (const directive of this.directives) {
-      const output = await directive.family.preflight(directive.directives, request, parameters)
+  public async preflight (context: Context, parameters: RTD.Parameter[]): Promise<Output> {
+    for (const set of this.sets) {
+      if (set.family.preflight === undefined)
+        continue
 
-      if (output !== null) {
-        await this.settle(request, output)
+      const output = await set.family.preflight(set.directives, context, parameters)
 
+      if (output !== null)
         return output
-      }
     }
 
     return null
   }
 
-  public async settle (request: IncomingMessage, response: OutgoingMessage): Promise<void> {
-    for (const directive of this.directives)
-      if (directive.family.settle !== undefined)
-        await directive.family.settle(directive.directives, request, response)
-  }
-
-  public merge (directives: Directives): void {
-    this.directives.push(...directives.directives)
+  public async settle (context: Context, response: OutgoingMessage): Promise<void> {
+    for (const set of this.sets)
+      if (set.family.settle !== undefined)
+        await set.family.settle(set.directives, context, response)
   }
 }
 
-export class DirectivesFactory implements RTD.DirectivesFactory<Directives> {
-  private readonly remtoes: Remotes
-  private readonly families: Record<string, Family> = {}
+export class DirectivesFactory implements RTD.DirectiveFactory {
+  private readonly remotes: Remotes
+  private readonly families: Record<string, RTD.DirectiveFamily> = {}
   private readonly mandatory: string[] = []
 
-  public constructor (families: Family[], remotes: Remotes) {
+  public constructor (families: RTD.DirectiveFamily[], remotes: Remotes) {
     for (const family of families) {
       this.families[family.name] = family
 
@@ -47,7 +44,7 @@ export class DirectivesFactory implements RTD.DirectivesFactory<Directives> {
         this.mandatory.push(family.name)
     }
 
-    this.remtoes = remotes
+    this.remotes = remotes
   }
 
   public create (declarations: RTD.syntax.Directive[]): Directives {
@@ -61,16 +58,16 @@ export class DirectivesFactory implements RTD.DirectivesFactory<Directives> {
       const family = this.families[declaration.family]
 
       if (family === undefined)
-        throw new Error(`Directive family '${declaration.family}' not found.`)
+        throw new Error(`Directive family '${declaration.family}' is not found`)
 
-      const directive = family.create(declaration.name, declaration.value, this.remtoes)
+      const directive = family.create(declaration.name, declaration.value, this.remotes)
 
       groups[family.name] ??= []
       groups[family.name].push(directive)
       mandatory.delete(family.name)
     }
 
-    const sets: DirectiveSet[] = []
+    const sets: RTD.DirectiveSet[] = []
 
     for (const family of mandatory)
       sets.push({
@@ -90,31 +87,12 @@ export class DirectivesFactory implements RTD.DirectivesFactory<Directives> {
 
 export const shortcuts: RTD.syntax.Shortcuts = new Map([
   ['anonymous', 'auth:anonymous'],
+  ['anyone', 'auth:anyone'],
   ['id', 'auth:id'],
   ['role', 'auth:role'],
   ['rule', 'auth:rule'],
-  ['incept', 'auth:incept']
+  ['incept', 'auth:incept'],
+  ['input', 'io:input'],
+  ['output', 'io:output'],
+  ['languages', 'map:languages']
 ])
-
-export interface Family<TDirective = any, TExtension = any> {
-  readonly name: string
-  readonly mandatory: boolean
-
-  create: (name: string, value: any, remotes: Remotes) => TDirective
-
-  preflight: (directives: TDirective[],
-    request: IncomingMessage & TExtension,
-    parameters: RTD.Parameter[]) => Output | Promise<Output>
-
-  settle?: (directives: TDirective[],
-    request: IncomingMessage & TExtension,
-    response: OutgoingMessage) => void | Promise<void>
-}
-
-interface DirectiveSet {
-  family: Family
-  directives: any[]
-}
-
-export type Input = IncomingMessage
-export type Output = OutgoingMessage | null

package/source/Endpoint.ts

@@ -1,28 +1,96 @@
-import { type Component, type Reply } from '@toa.io/core'
-import { type Remotes } from './Remotes'
+import { console } from 'openspan'
 import { Mapping } from './Mapping'
-import { type Context } from './Context'
+import * as http from './HTTP'
+import type { Introspection, Schema } from './Introspection'
+import type { Remote } from '@toa.io/core'
+import type { Remotes } from './Remotes'
+import type { Context } from './Context'
 import type * as RTD from './RTD'
-import type * as http from './HTTP'
 
-export class Endpoint implements RTD.Endpoint<Endpoint> {
+export class Endpoint implements RTD.Endpoint {
   private readonly endpoint: string
   private readonly mapping: Mapping
-  private readonly discovery: Promise<Component>
-  private remote: Component | null = null
+  private readonly discovery: Promise<Remote>
+  private remote: Remote | null = null
 
-  public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Component>) {
+  public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Remote>) {
     this.endpoint = endpoint
     this.mapping = mapping
     this.discovery = discovery
   }
 
-  public async call (body: any, query: http.Query, parameters: RTD.Parameter[]): Promise<Reply> {
+  public async call (context: http.Context, parameters: RTD.Parameter[]): Promise<http.OutgoingMessage> {
+    const body = await context.body()
+    const query = this.query(context)
     const request = this.mapping.fit(body, query, parameters)
 
     this.remote ??= await this.discovery
 
-    return await this.remote.invoke(this.endpoint, request)
+    if (context.debug)
+      console.debug('Calling operation', {
+        endpoint: this.remote.locator.id + '.' + this.endpoint,
+        request
+      })
+
+    const reply = await this.remote.invoke(this.endpoint, request)
+
+    if (reply instanceof Error)
+      throw new http.UnprocessableEntity(reply)
+
+    const message: http.OutgoingMessage = {}
+
+    if (typeof reply === 'object' && reply !== null && '_version' in reply) {
+      const etag = context.request.headers['if-none-match']
+
+      message.headers ??= new Headers()
+
+      if (etag !== undefined && reply._version === this.version(etag)) {
+        message.status = 304
+        message.headers.set('etag', etag)
+
+        return message
+      } else
+        message.headers.set('etag', `"${reply._version.toString()}"`)
+    }
+
+    message.body = reply
+
+    return message
+  }
+
+  public async explain (parameters: RTD.Parameter[]): Promise<Introspection> {
+    this.remote ??= await this.discovery
+
+    // eslint-disable-next-line @typescript-eslint/await-thenable
+    const operation = await this.remote.explain(this.endpoint)
+
+    let route: Record<string, Schema> | null = null
+
+    if (operation.input?.type === 'object')
+      for (const parameter of parameters) {
+        const schema = operation.input.properties[parameter.name]
+
+        // eslint-disable-next-line max-depth
+        if (schema !== undefined) {
+          route ??= {}
+          route[parameter.name] = schema
+
+          delete operation.input.properties[parameter.name]
+        }
+      }
+
+    const query = this.mapping.explain(operation)
+    const introspection: Introspection = {}
+
+    if (route !== null)
+      introspection.route = route
+
+    if (query !== null)
+      introspection.query = query
+
+    Object.assign(introspection, operation)
+
+    return introspection
   }
 
   public async close (): Promise<void> {
@@ -30,9 +98,28 @@ export class Endpoint implements RTD.Endpoint<Endpoint> {
 
     await this.remote.disconnect(INTERRUPT)
   }
+
+  private query (context: http.Context): http.Query {
+    const query: http.Query = Object.fromEntries(context.url.searchParams)
+    const etag = context.request.headers['if-match']
+
+    if (etag !== undefined && this.mapping.queryable)
+      query.version = this.version(etag)
+
+    return query
+  }
+
+  private version (etag: string): number {
+    const match = etag.match(ETAG)
+
+    if (match === null)
+      throw new http.BadRequest('Invalid ETag')
+
+    return Number.parseInt(match.groups!.version)
+  }
 }
 
-export class EndpointsFactory implements RTD.EndpointsFactory<Endpoint> {
+export class EndpointsFactory implements RTD.EndpointsFactory {
   private readonly remotes: Remotes
 
   public constructor (remotes: Remotes) {
@@ -41,19 +128,21 @@ export class EndpointsFactory implements RTD.EndpointsFactory<Endpoint> {
 
   public create (method: RTD.syntax.Method, context: Context): Endpoint {
     if (method.mapping === undefined)
-      throw new Error('Cannot create Endpoint without mapping.')
+      throw new Error('Cannot create Endpoint without mapping')
 
     const mapping = Mapping.create(method.mapping.query)
-    const namespace = method.mapping.namespace ?? context.extension?.namespace
-    const component = method.mapping.component ?? context.extension?.component
+    const namespace = method.mapping.namespace ?? context.extension.namespace
+    const component = method.mapping.component ?? context.extension.component
 
     if (namespace === undefined || component === undefined)
-      throw new Error('Annotation endpoints must be fully qualified.')
+      throw new Error('Annotation endpoints must be fully qualified')
 
-    const discovery = this.remotes.discover(namespace, component)
+    const discovery = this.remotes.discover(namespace, component, context.extension.version)
 
     return new Endpoint(method.mapping.endpoint, mapping, discovery)
   }
 }
 
+const ETAG = /^(W\/)?"(?<version>\d{1,32})"$/
+
 const INTERRUPT = true

package/source/Factory.ts

@@ -1,47 +1,67 @@
+import assert from 'node:assert'
+import { decode } from '@toa.io/generic'
 import { Tenant } from './Tenant'
 import { Gateway } from './Gateway'
 import { Remotes } from './Remotes'
-import { Tree, syntax } from './RTD'
-import { Server } from './HTTP'
-import { type Endpoint, EndpointsFactory } from './Endpoint'
-import * as directives from './directives'
-import { type Directives, DirectivesFactory, type Family } from './Directive'
+import { Tree } from './RTD'
+import { EndpointsFactory } from './Endpoint'
+import { families, interceptors } from './directives'
+import { DirectivesFactory } from './Directive'
 import { Composition } from './Composition'
 import * as root from './root'
+import { Interception } from './Interception'
+import * as http from './HTTP'
+import type { Manifest } from '@toa.io/norm'
+import type { Branch } from './Branch'
+import type { syntax } from './RTD'
+import type { Broadcast } from './Gateway'
 import type { Connector, Locator, extensions } from '@toa.io/core'
 
 export class Factory implements extensions.Factory {
   private readonly boot: Bootloader
-  private readonly families: Family[]
 
   public constructor (boot: Bootloader) {
     this.boot = boot
-    this.families = directives.families
   }
 
-  public tenant (locator: Locator, node: syntax.Node): Connector {
-    const broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
+  public tenant (locator: Locator, node: syntax.Node, manifest: Manifest): Connector {
+    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
 
-    return new Tenant(broadcast, locator, node)
+    const branch: Branch = {
+      namespace: locator.namespace,
+      component: locator.name,
+      isolated: locator.namespace === 'identity',
+      node,
+      version: manifest.version
+    }
+
+    return new Tenant(broadcast, branch)
   }
 
   public service (): Connector | null {
-    const debug = process.env.TOA_EXPOSITION_DEBUG === '1'
-    const broadcast = this.boot.bindings.broadcast(CHANNEL)
-    const server = Server.create({ methods: syntax.verbs, debug })
+    assert.ok(process.env.TOA_EXPOSITION_PROPERTIES,
+      'TOA_EXPOSITION_PROPERTIES is undefined')
+
+    const options = decode<http.Options>(process.env.TOA_EXPOSITION_PROPERTIES)
+    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL)
+    const server = http.Server.create({ ...options })
     const remotes = new Remotes(this.boot)
     const node = root.resolve()
     const methods = new EndpointsFactory(remotes)
-    const directives = new DirectivesFactory(this.families, remotes)
-    const tree = new Tree<Endpoint, Directives>(node, methods, directives)
+    const directives = new DirectivesFactory(families, remotes)
+    const interception = new Interception(interceptors)
+    const tree = new Tree(node, methods, directives)
 
     const composition = new Composition(this.boot)
-    const gateway = new Gateway(broadcast, server, tree)
+    const gateway = new Gateway(broadcast, tree, interception)
 
     gateway.depends(remotes)
     gateway.depends(composition)
 
-    return gateway
+    server.attach(gateway.process.bind(gateway))
+    server.depends(gateway)
+
+    return server
   }
 }