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

package/source/Tenant.ts

@@ -1,73 +0,0 @@
-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/types'
-import type { Label } from './discovery.js'
-import type { Branch } from './Branch.js'
-
-export class Tenant extends Connector {
-  private readonly broadcast: Broadcast
-  private readonly branch: Omit<Branch, 'timestamp'>
-  private started = 0
-  private stopped = false
-
-  public constructor(broadcast: Broadcast, branch: Omit<Branch, 'timestamp'>) {
-    super()
-
-    this.broadcast = broadcast
-    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> {
-    // 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

@@ -1,45 +0,0 @@
-export const BRANCH_TTL = 1_800_000
-
-/** The broadcast the gateway and its tenants share. */
-export const CHANNEL = 'exposition'
-
-/** The replicas of the gateway decide together, whatever context they serve. */
-export const ATOM_GROUP = 'exposition'
-
-/**
- * Where JSON-RPC is served, for every procedure at once. Pinned rather than configured: a
- * path an application could choose is a path it could collide with a route of its own.
- */
-export const RPC = '/.rpc'
-
-/** Calls one request may carry where the annotation does not say. */
-export const BATCH = 32
-
-/**
- * Where the Model Context Protocol is served. Pinned for the reason `/.rpc` is: a path an
- * application could choose is a path it could collide with a route of its own.
- */
-export const MCP = '/.mcp'
-
-/**
- * Where the resource tree and the page that reads it are served. Pinned for the reason
- * `/.rpc` is: a path an application could choose is a path it could collide with a route of
- * its own. Unlike those two it is not annotated — every entry it carries is what `OPTIONS`
- * on that path already answers to the same caller, and what it adds is the enumeration.
- */
-export const DISCOVERY = '/.discovery'
-
-/** Where the gateway serves. */
-export const PORT = 8000
-
-/**
- * Reserved for the readiness probe. `8001` is the Telemetry readiness probe's, and `toa export`
- * refuses a port claimed twice — `toa mono` and a local run put every service in one process.
- */
-export const PROBE = 8004
-
-/**
- * The initial delay of the readiness probe. The server does not sleep for it: whoever
- * probes is the one that waits, and doing it here as well only delayed the process twice.
- */
-export const DELAY = 3 // seconds

package/source/deployment.ts

@@ -1,96 +0,0 @@
-import { readFileSync } from 'node:fs'
-import assert from 'node:assert'
-import { type Dependency, type Service } from '@toa.io/operations'
-import { type Annotation } from './Annotation.js'
-import * as schemas from './schemas.js'
-import { shortcuts } from './shortcuts.js'
-import { components } from './Composition.js'
-import { parse } from './RTD/syntax/index.js'
-import { DELAY, PORT, PROBE } from './const.js'
-
-/** Where Toa's release publishes this service's image. An application takes it
- *  instead of building one when its context says `registry.services: published`. */
-export const image = 'ghcr.io/toa-io/extension-exposition-gateway'
-
-export function deployment(_: unknown, annotation?: Annotation): Dependency {
-  assert.ok(annotation !== undefined, 'Exposition context annotation is required')
-  schemas.annotation.validate(annotation)
-
-  const labels = components().labels
-
-  const service: Service = {
-    group: 'exposition',
-    name: 'gateway',
-    image,
-    port: PORT,
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
-      .version,
-    variables: [],
-    components: labels,
-    resources: annotation.resources,
-    ingress: { path: '/', hosts: [] },
-    probe: {
-      path: '/.ready',
-      port: PROBE,
-      delay: DELAY
-    }
-  }
-
-  if (annotation?.['/'] !== undefined) {
-    const tree = parse(annotation['/'], shortcuts)
-
-    service.variables!.push({
-      name: 'TOA_EXPOSITION',
-      value: JSON.stringify(tree)
-    })
-  }
-
-  const { debug, authorities } = annotation
-
-  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 (annotation.protocol !== undefined) properties.protocol = annotation.protocol
-
-  if (annotation.ip !== undefined) properties.ip = annotation.ip
-
-  if (annotation.bouncer !== undefined) properties.bouncer = annotation.bouncer
-
-  if (annotation.oauth !== undefined) properties.oauth = annotation.oauth
-
-  if (annotation.rpc !== undefined) properties.rpc = annotation.rpc
-
-  if (annotation.mcp !== undefined) properties.mcp = annotation.mcp
-
-  service.variables!.push({
-    name: 'TOA_EXPOSITION_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' | 'protocol' | 'bouncer' | 'ip' | 'oauth' | 'rpc' | 'mcp'
->

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

@@ -1,70 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Anonymous } from './Anonymous.js'
-import type { Context } from './types.js'
-
-const context = (
-  headers: Record<string, string>,
-  flags: { procedural?: boolean; exploratory?: boolean } = {}
-): Context =>
-  ({
-    request: { headers },
-    procedural: false,
-    exploratory: false,
-    ...flags
-  }) as unknown as Context
-
-describe('anonymous', () => {
-  it('should admit a request that presents nothing', () => {
-    assert.equal(new Anonymous(true).authorize(null, context({})), true)
-  })
-
-  it('should refuse a request that presents a credential', () => {
-    // it would make the reply uncacheable, which is the whole of the rule
-    assert.equal(
-      new Anonymous(true).authorize(null, context({ authorization: 'Token x' })),
-      false
-    )
-  })
-
-  it('should admit a procedure whatever the request presented', () => {
-    // what a procedure answers is a value in an envelope, and the envelope is `no-store`
-    const procedural = context({ authorization: 'Token x' }, { procedural: true })
-
-    assert.equal(new Anonymous(true).authorize(null, procedural), true)
-  })
-
-  it('should admit a description whatever the request presented', () => {
-    // a description is not the reply a cache would hold, and varies by who asked in any case
-    const exploratory = context({ authorization: 'Token x' }, { exploratory: true })
-
-    assert.equal(new Anonymous(true).authorize(null, exploratory), true)
-  })
-
-  it('should refuse where it admits nobody', () => {
-    assert.equal(new Anonymous(false).authorize(null, context({})), false)
-    assert.equal(
-      new Anonymous(false).authorize(null, context({}, { procedural: true })),
-      false
-    )
-    assert.equal(
-      new Anonymous(false).authorize(null, context({}, { exploratory: true })),
-      false
-    )
-  })
-
-  it('should describe a method as it authorizes one', () => {
-    const directive = new Anonymous(true)
-
-    assert.equal(directive.admits(null, context({ authorization: 'Token x' })), false)
-    assert.equal(
-      directive.admits(null, context({ authorization: 'Token x' }, { procedural: true })),
-      true
-    )
-    assert.equal(
-      directive.admits(null, context({ authorization: 'Token x' }, { exploratory: true })),
-      true
-    )
-  })
-})

package/source/directives/auth/Anonymous.ts

@@ -1,36 +0,0 @@
-import { type Directive, type Context } from './types.js'
-import type { Introspection } from '../../Introspection.js'
-
-export class Anonymous implements Directive {
-  private readonly allow: boolean
-
-  public constructor(allow: boolean) {
-    this.allow = allow
-  }
-
-  /**
-   * A credential refuses, because it would make the reply uncacheable — which is the whole
-   * of the rule, and none of it applies to a procedure, nor to a description. What a
-   * procedure answers is a value in an envelope, and the envelope is the one thing that is
-   * cached or not; what a description answers is what the resource is, which is not the
-   * reply a cache would hold and varies by who asked in any case.
-   */
-  public authorize(_: any, context: Context): boolean {
-    if (context.procedural || context.exploratory) return this.allow
-
-    return 'authorization' in context.request.headers ? false : this.allow
-  }
-
-  public admits(_: any, context: Context): boolean {
-    return this.authorize(_, context)
-  }
-
-  /**
-   * That nothing guards it is something said rather than something left unsaid: it is also
-   * what refuses a caller presenting a credential, and a client with one has to know which
-   * methods not to present it to.
-   */
-  public describe(introspection: Introspection): Introspection {
-    return this.allow ? { ...introspection, anonymous: true } : introspection
-  }
-}

package/source/directives/auth/Anyone.ts

@@ -1,23 +0,0 @@
-import { type Directive, type Context } from './types.js'
-import type { Introspection } from '../../Introspection.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
-  }
-
-  public admits(_: any, context: Context): boolean {
-    return this.authorize(_, context)
-  }
-
-  /** Whoever asks, as long as they are somebody. */
-  public describe(introspection: Introspection): Introspection {
-    return this.allow ? { ...introspection, authenticated: true } : introspection
-  }
-}

package/source/directives/auth/Assert.ts

@@ -1,43 +0,0 @@
-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
-  }
-
-  /** It admits nobody: it is there to require a credential, not to authorize one. */
-  public admits(): boolean {
-    return false
-  }
-
-  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

@@ -1,24 +0,0 @@
-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)
-})