@toa.io/extensions.exposition 1.0.0-alpha.28 → 1.0.0-alpha.283

package/source/RTD/syntax/types.ts

@@ -1,6 +1,7 @@
 export interface Node {
   protected?: boolean
   isolated?: boolean
+  forward?: string
   routes: Route[]
   methods: Method[]
   directives: Directive[]
@@ -27,17 +28,21 @@ export interface Mapping {
   namespace?: string
   component?: string
   endpoint: string
-  query?: Query
+  query?: Query | null
 }
 
 export interface Query {
   id?: string
   criteria?: string
+  search?: boolean
+  sample?: number
   sort?: string
-  omit: Range
-  limit: Range
+  omit?: Range
+  limit?: Range
   selectors?: string[]
   projection?: string[]
+  parameters?: string[]
+  deleted?: boolean
 }
 
 export interface Range {
@@ -45,4 +50,4 @@ export interface Range {
   range: [number, number]
 }
 
-export const verbs = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'])
+export const verbs = new Set<string>(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK'])

package/source/Remotes.test.ts

@@ -1,19 +1,18 @@
+import { it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
+
 import { generate } from 'randomstring'
 import { Connector } from '@toa.io/core'
-import { Remotes } from './Remotes'
-import type { Bootloader } from './Factory'
-import type { Locator } from '@toa.io/core'
-
-jest.mock('@toa.io/boot', () => ({
-  remote: async (locator: Locator) => await boot.remote(locator)
-}))
-
-const boot = {
-  remote: jest.fn(async (..._) => ({
-    connect: jest.fn(() => undefined),
-    link: jest.fn(() => undefined)
+import { Remotes } from './Remotes.js'
+import type { Host } from './Factory.js'
+
+const host = {
+  remote: mock.fn(async () => ({
+    connect: mock.fn(() => undefined),
+    link: mock.fn(() => undefined)
   }))
-} as unknown as jest.MockedObjectDeep<Bootloader>
+} as unknown as Host
 
 const namespace = generate()
 const name = generate()
@@ -21,22 +20,39 @@ const name = generate()
 let remotes: Remotes
 
 beforeEach(() => {
-  remotes = new Remotes(boot)
+  remotes = new Remotes(host)
 })
 
 it('should create remote', async () => {
   const remote = await remotes.discover(namespace, name)
 
-  expect(boot.remote).toHaveBeenCalledWith(expect.objectContaining({ namespace, name }))
-  expect(remote).toStrictEqual(await boot.remote.mock.results[0].value)
+  assert.ok(host.remote.mock.calls.some((call: any) => call.arguments.length === 2 && isPartial(call.arguments[0], { namespace, name }) && call.arguments[1] !== null && call.arguments[1] !== undefined))
+
+  assert.deepStrictEqual(remote, await host.remote.mock.calls[0].result)
 })
 
 it('should be instance of Connector', async () => {
-  expect(remotes).toBeInstanceOf(Connector)
+  assert.ok(remotes instanceof Connector)
 })
 
 it('should depend on created remotes', async () => {
   const remote = await remotes.discover(namespace, name)
 
-  expect(remote.link).toHaveBeenCalledWith(remotes)
+  assert.ok(remote.link.mock.calls.some((call: any) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], remotes)))
+})
+
+it('should attribute calls to the gateway', async () => {
+  await remotes.discover(namespace, name)
+
+  assert.ok(host.remote.mock.calls.some((call: any) => call.arguments.length === 2 && call.arguments[0] !== null && call.arguments[0] !== undefined && isDeepStrictEqual(call.arguments[1], { service: 'exposition' })))
 })
+
+function isPartial (actual, expected) {
+  try {
+    assert.partialDeepStrictEqual(actual, expected)
+
+    return true
+  } catch {
+    return false
+  }
+}

package/source/Remotes.ts

@@ -1,25 +1,27 @@
-import { Locator, Connector, type Component } from '@toa.io/core'
-import { type Bootloader } from './Factory'
+import { Locator, Connector, type Remote, type Source } from '@toa.io/core'
+import { type Host } from './Factory.js'
 
 export class Remotes extends Connector {
-  private readonly boot: Bootloader
-  private readonly remotes: Record<string, Promise<Component>> = {}
+  private readonly host: Host
+  private readonly cache: Record<string, Promise<Remote>> = {}
 
-  public constructor (boot: Bootloader) {
+  public constructor (host: Host) {
     super()
-    this.boot = boot
+    this.host = host
   }
 
-  public async discover (namespace: string, name: string): Promise<Component> {
+  public async discover (namespace: string, name: string, version: string = 'local'): Promise<Remote> {
     const locator = new Locator(name, namespace)
+    const key = locator.id + ':' + version
 
-    this.remotes[locator.id] ??= this.create(locator)
+    this.cache[key] ??= this.locate(locator)
 
-    return await this.remotes[locator.id]
+    return this.cache[key]
   }
 
-  private async create (locator: Locator): Promise<Component> {
-    const remote = await this.boot.remote(locator)
+  private async locate (locator: Locator): Promise<Remote> {
+    // the gateway is the origin of every call it forwards
+    const remote = await this.host.remote(locator, SOURCE)
 
     this.depends(remote)
 
@@ -28,3 +30,5 @@ export class Remotes extends Connector {
     return remote
   }
 }
+
+const SOURCE: Source = { service: 'exposition' }

package/source/Tenant.ts

@@ -1,35 +1,73 @@
-import { Connector, type Locator, type bindings } from '@toa.io/core'
-import { type Label } from './discovery'
-import { type Branch } from './Branch'
-import type * as RTD from './RTD/syntax'
+import { setTimeout } from 'node:timers/promises'
+import { Connector } from '@toa.io/core'
+import { BRANCH_TTL } from './const.js'
+import type { bindings } from '@toa.io/core'
+import type { Label } from './discovery.js'
+import type { Branch } from './Branch.js'
 
 export class Tenant extends Connector {
   private readonly broadcast: Broadcast
-  private readonly branch: Branch
+  private readonly branch: Omit<Branch, 'timestamp'>
+  private started = 0
+  private stopped = false
 
-  public constructor (broadcast: Broadcast, locator: Locator, node: RTD.Node) {
+  public constructor (broadcast: Broadcast, branch: Omit<Branch, 'timestamp'>) {
     super()
 
     this.broadcast = broadcast
-
-    this.branch = {
-      namespace: locator.namespace,
-      component: locator.name,
-      isolated: locator.namespace === 'identity',
-      node
-    }
+    this.branch = branch
 
     this.depends(broadcast)
   }
 
   public override async open (): Promise<void> {
+    this.started = Date.now()
+
     await this.expose()
     await this.broadcast.receive('ping', this.expose.bind(this))
+
+    void this.announce()
+  }
+
+  /**
+   * Announcing is stopped where the teardown begins, not in `dispose`, which a connector
+   * runs after every one of its dependencies has gone. A component on its way out that
+   * announces itself once more has its routes held open by whoever is listening, and the
+   * requests that follow reach nothing.
+   */
+  protected override async close (): Promise<void> {
+    this.stopped = true
+  }
+
+  private async announce (): Promise<void> {
+    while (!this.stopped) {
+      const delay = exposeInterval(Date.now() - this.started)
+
+      await setTimeout(delay, undefined, { ref: false })
+
+      if (this.stopped)
+        break
+
+      await this.expose()
+    }
   }
 
   private async expose (): Promise<void> {
-    await this.broadcast.transmit('expose', this.branch)
+    // the ping subscription outlives the announcing loop, and answering one on the way out
+    // is the same announcement by another route
+    if (this.stopped)
+      return
+
+    await this.broadcast.transmit('expose', { ...this.branch, timestamp: this.started })
   }
 }
 
+function exposeInterval (uptime: number): number {
+  return Math.round(EXPOSE_MAX - (EXPOSE_MAX - EXPOSE_MIN) * Math.exp(-uptime / EXPOSE_TAU))
+}
+
+const EXPOSE_MIN = 5_000
+const EXPOSE_MAX = Math.round(BRANCH_TTL / 2.1)
+const EXPOSE_TAU = 900_000
+
 type Broadcast = bindings.Broadcast<Label>

package/source/const.ts

@@ -0,0 +1,4 @@
+export const BRANCH_TTL = 1_800_000
+
+/** The replicas of the gateway decide together, whatever context they serve. */
+export const ATOM_GROUP = 'exposition'

package/source/deployment.ts

@@ -1,12 +1,12 @@
+import { readFileSync } from 'node:fs'
 import assert from 'node:assert'
 import { type Dependency, type Service } from '@toa.io/operations'
-import { encode } from '@toa.io/generic'
-import { type Annotation } from './Annotation'
-import * as schemas from './schemas'
-import { shortcuts } from './Directive'
-import { components } from './Composition'
-import { parse } from './RTD/syntax'
-import { DELAY, PORT } from './HTTP/Server'
+import { type Annotation } from './Annotation.js'
+import * as schemas from './schemas.js'
+import { shortcuts } from './Directive.js'
+import { components } from './Composition.js'
+import { parse } from './RTD/syntax/index.js'
+import { DELAY, PORT, PROBE } from './HTTP/index.js'
 
 export function deployment (_: unknown, annotation?: Annotation): Dependency {
   assert.ok(annotation !== undefined, 'Exposition context annotation is required')
@@ -18,14 +18,14 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
     group: 'exposition',
     name: 'gateway',
     port: PORT,
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    version: require('../package.json').version,
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
     variables: [],
     components: labels,
-    ingress: { hosts: [] },
+    resources: annotation.resources,
+    ingress: { path: '/', hosts: [] },
     probe: {
       path: '/.ready',
-      port: PORT,
+      port: PROBE,
       delay: DELAY
     }
   }
@@ -33,32 +33,57 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   if (annotation?.['/'] !== undefined) {
     const tree = parse(annotation['/'], shortcuts)
 
-    service.variables.push({
+    service.variables!.push({
       name: 'TOA_EXPOSITION',
-      value: encode(tree)
+      value: JSON.stringify(tree)
     })
   }
 
-  const { debug, trace, authorities } = annotation
+  const { debug, authorities } = annotation
 
-  service.ingress.hosts = Object.values(authorities)
-  service.ingress.class = annotation.class
-  service.ingress.annotations = annotation.annotations
+  service.ingress!.hosts = Object.values(authorities)
+
+  // leaving these undefined lets the context's own ingress section supply them
+  if (annotation.class !== undefined)
+    service.ingress!.class = annotation.class
+
+  if (annotation.annotations !== undefined)
+    service.ingress!.annotations = annotation.annotations
+
+  if (annotation.service?.annotations !== undefined)
+    service.annotations = annotation.service.annotations
 
   const properties: Properties = { authorities }
 
   if (debug === true)
     properties.debug = true
 
-  if (trace === true)
-    properties.trace = true
+  if (annotation.protocol !== undefined)
+    properties.protocol = annotation.protocol
+
+  if (annotation.ip !== undefined)
+    properties.ip = annotation.ip
 
-  service.variables.push({
+  if (annotation.bouncer !== undefined)
+    properties.bouncer = annotation.bouncer
+
+  if (annotation.oauth !== undefined)
+    properties.oauth = annotation.oauth
+
+  service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
-    value: encode(properties)
+    value: JSON.stringify(properties)
+  })
+
+  // The identity composition nested in this process connects before route discovery settles,
+  // so telemetry's probe — which tracks that composition — would report ready too early.
+  // The gateway answers for itself, on the same port telemetry would have used.
+  service.variables!.push({
+    name: 'TOA_TELEMETRY_READY',
+    value: JSON.stringify(false)
   })
 
   return { services: [service] }
 }
 
-type Properties = Pick<Annotation, 'authorities' | 'debug' | 'trace'>
+type Properties = Pick<Annotation, 'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip' | 'oauth'>

package/source/directives/auth/Anonymous.ts

@@ -1,4 +1,4 @@
-import { type Directive, type Input } from './types'
+import { type Directive, type Context } from './types.js'
 
 export class Anonymous implements Directive {
   private readonly allow: boolean
@@ -7,8 +7,8 @@ export class Anonymous implements Directive {
     this.allow = allow
   }
 
-  public authorize (_: any, input: Input): boolean {
-    return 'authorization' in input.request.headers
+  public authorize (_: any, context: Context): boolean {
+    return 'authorization' in context.request.headers
       ? false
       : this.allow
   }

package/source/directives/auth/Anyone.ts

@@ -0,0 +1,13 @@
+import { type Directive, type Context } from './types.js'
+
+export class Anyone implements Directive {
+  private readonly allow: boolean
+
+  public constructor (allow: boolean) {
+    this.allow = allow
+  }
+
+  public authorize (_: any, context: Context): boolean {
+    return context.identity !== null && this.allow
+  }
+}

package/source/directives/auth/Assert.ts

@@ -0,0 +1,38 @@
+import assert from 'node:assert'
+import { newid } from '@toa.io/generic'
+import * as http from '../../HTTP/index.js'
+import { Incept } from './Incept.js'
+import type { Context, Directive, Identity } from './types.js'
+
+export class Assert implements Directive {
+  private readonly disabled: boolean
+
+  public constructor (enabled: boolean) {
+    assert.ok(typeof enabled === 'boolean', '`auth:assert` directive value must be a boolean')
+
+    this.disabled = !enabled
+  }
+
+  public async authorize (identity: Identity | null, context: Context): Promise<boolean> {
+    if (!this.disabled)
+      await this.incept(context, identity)
+
+    return false
+  }
+
+  private async incept (context: Context, identity: Identity | null): Promise<void> {
+    if (context.request.headers.authorization === undefined)
+      throw new http.Unauthorized()
+
+    if (identity === null) {
+      if (!Incept.acceptable(context))
+        throw new http.Unauthorized()
+
+      context.identity = await Incept.incept(context, newid())
+
+      context.pipelines.response.push((response) => {
+        response.status = 201
+      })
+    }
+  }
+}

package/source/directives/auth/Authorization.test.ts

@@ -0,0 +1,24 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { permits } from './Authorization.js'
+
+const permissions = { '/users/me/**': ['GET'], '/notes/': ['*'] }
+
+it('should permit a matching method and path', () => {
+  assert.equal(permits(permissions, 'GET', '/users/me/posts/'), true)
+  assert.equal(permits(permissions, 'DELETE', '/notes/'), true)
+})
+
+it('should refuse another method or path', () => {
+  assert.equal(permits(permissions, 'POST', '/users/me/posts/'), false)
+  assert.equal(permits(permissions, 'GET', '/admin/'), false)
+})
+
+it('should be matched on the routed path, not on the request URL', () => {
+  const raw = '/users/me/%2e%2e/admin/'
+  const routed = new URL(raw, 'https://example.com').pathname
+
+  assert.equal(routed, '/users/admin/')
+  assert.equal(permits(permissions, 'GET', routed), false)
+})