@toa.io/definitions 1.0.0-alpha.292 → 1.0.0-alpha.294

package/source/extensions.exposition/deployment.ts

@@ -1,95 +0,0 @@
-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 './components.js'
-import { parse } from './syntax/index.js'
-import { DELAY, PORT, PROBE } from './const.js'
-import { version } from '../version.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,
-    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/extensions.exposition/index.ts

@@ -1,16 +0,0 @@
-export { manifest } from './manifest.js'
-export { components } from './components.js'
-export { deployment, image } from './deployment.js'
-export { shortcuts } from './shortcuts.js'
-export * from './const.js'
-export * as schemas from './schemas.js'
-export * as syntax from './syntax/index.js'
-
-export type {
-  Annotation,
-  Bouncer,
-  MCP as MCPAnnotation,
-  OAuth,
-  Protocol,
-  RPC as RPCAnnotation
-} from './Annotation.js'

package/source/extensions.exposition/manifest.ts

@@ -1,56 +0,0 @@
-import assert from 'node:assert'
-import { parse, type Node, type Method, type Query } from './syntax/index.js'
-import { shortcuts } from './shortcuts.js'
-import * as schemas from './schemas.js'
-import type { Manifest } from '@toa.io/norm'
-
-export function manifest(declaration: object, manifest: Manifest): Node {
-  assert.ok(
-    typeof declaration === 'object' && declaration !== null,
-    'Exposition declaration must be an object'
-  )
-
-  declaration = wrap(declaration, manifest.namespace, manifest.name)
-
-  const node = parse(declaration, shortcuts)
-
-  specify(node, manifest)
-  schemas.node.validate(node)
-
-  return node
-}
-
-function wrap(declaration: object, namespace: string, name: string): object {
-  const path =
-    (namespace === undefined || namespace === 'default' ? '' : '/' + namespace) +
-    '/' +
-    name
-
-  return { [path]: declaration }
-}
-
-function specify(node: Node, manifest: Manifest): void {
-  for (const route of node.routes) {
-    for (const method of route.node.methods) specifyMethod(method, manifest)
-
-    specify(route.node, manifest)
-  }
-}
-
-function specifyMethod(method: Method, manifest: Manifest): void {
-  if (method.mapping?.endpoint === undefined) return
-
-  const operation = manifest.operations[method.mapping.endpoint]
-
-  assert.ok(operation !== undefined, `Operation '${method.mapping.endpoint}' not found`)
-
-  if (method.mapping.query === undefined)
-    method.mapping.query = operation.query === false ? null : ({} as unknown as Query)
-
-  // a page is taken of a collection, and of nothing else: an operation that answers one object
-  // takes no `omit` and no `limit`, and refuses a request that carries them
-  method.mapping.paged = operation.type === 'observation' && operation.scope === 'objects'
-
-  method.mapping.namespace = manifest.namespace
-  method.mapping.component = manifest.name
-}

package/source/extensions.exposition/schemas.ts

@@ -1,16 +0,0 @@
-import { resolve } from 'node:path'
-import * as schemas from '@toa.io/schemas'
-import type { Schema } from '@toa.io/schemas'
-import type { Node } from './syntax/types.js'
-import type { Annotation } from './Annotation.js'
-
-const path = resolve(import.meta.dirname, '../../schemas/extensions.exposition')
-const namespace = schemas.namespace(path)
-
-// what the gateway validates a request by, kept beside what a manifest is validated by
-export const querystring: Schema<Record<string, unknown>> =
-  namespace.schema('querystring')
-export const call: Schema<Record<string, unknown>> = namespace.schema('call')
-
-export const annotation: Schema<Annotation> = namespace.schema('annotation')
-export const node: Schema<Node> = namespace.schema('node')

package/source/extensions.exposition/shortcuts.ts

@@ -1,14 +0,0 @@
-import type { Shortcuts } from './syntax/index.js'
-
-/** What a directive may be written as, where the family is implied. */
-export const shortcuts: Shortcuts = new Map([
-  ['anonymous', 'auth:anonymous'],
-  ['anyone', 'auth:anyone'],
-  ['id', 'auth:id'],
-  ['role', 'auth:role'],
-  ['rule', 'auth:rule'],
-  ['incept', 'auth:incept'],
-  ['input', 'io:input'],
-  ['output', 'io:output'],
-  ['languages', 'map:languages']
-])

package/source/extensions.exposition/syntax/index.ts

@@ -1,2 +0,0 @@
-export * from './parse.js'
-export * from './types.js'

package/source/extensions.exposition/syntax/parse.ts

@@ -1,171 +0,0 @@
-import * as schemas from '../schemas.js'
-import {
-  verbs,
-  type Node,
-  type Route,
-  type Method,
-  type Mapping,
-  type Directive,
-  type Range
-} from './types.js'
-
-export function parse(input: object, shortcuts?: Shortcuts): Node {
-  const node = parseNode(input, shortcuts)
-
-  schemas.node.validate(node)
-
-  return node
-}
-
-function parseNode(input: object | string, shortcuts?: Shortcuts): Node {
-  const node = createNode()
-
-  if (typeof input === 'string') {
-    node.forward = input
-
-    return node
-  }
-
-  for (const [key, value] of Object.entries(input) as Array<[keyof Node, unknown]>)
-    switch (key) {
-      case 'protected':
-      case 'isolated':
-        node[key] = value as boolean
-        break
-      case 'forward':
-        node[key] = value as string
-        break
-
-      default:
-        // eslint-disable-next-line max-depth
-        if (key[0] === '/') {
-          const route = parseRoute(key, value as Node, shortcuts)
-
-          node.routes.push(route)
-
-          continue
-        }
-
-        // eslint-disable-next-line max-depth
-        if (verbs.has(key)) {
-          const method = parseMethod(key, value as Mapping, shortcuts)
-
-          node.methods.push(method)
-
-          continue
-        }
-
-        // eslint-disable-next-line no-case-declarations
-        const directive = parseDirective(key, value, shortcuts)
-
-        // eslint-disable-next-line max-depth
-        if (directive !== null) {
-          node.directives.push(directive)
-
-          continue
-        }
-
-        throw new Error(`RTD parse error: unknown key '${key}'`)
-    }
-
-  return node
-}
-
-export function createNode(): Node {
-  return {
-    routes: [],
-    methods: [],
-    directives: []
-  }
-}
-
-function parseRoute(path: string, value: Node, shortcuts?: Shortcuts): Route {
-  const node = parse(value, shortcuts)
-
-  return createRoute(path, node)
-}
-
-function createRoute(path: string, node: Node): Route {
-  return { path, node }
-}
-
-function parseMethod(
-  verb: string,
-  value: Mapping | string,
-  shortcuts?: Shortcuts
-): Method {
-  const mapping = typeof value === 'string' ? { endpoint: value } : value
-
-  parseEndpoint(mapping)
-  parseQuery(mapping)
-
-  const directives = parseDirectives(mapping, shortcuts)
-
-  return { verb, mapping, directives }
-}
-
-function parseEndpoint(mapping: Mapping): void {
-  if (mapping.endpoint === undefined) return
-
-  const [endpoiont, component, namespace] = mapping.endpoint.split('.').reverse()
-
-  if (component !== undefined) {
-    mapping.component = component
-    mapping.namespace = namespace ?? mapping.namespace ?? 'default'
-    mapping.endpoint = endpoiont
-  }
-}
-
-function parseQuery(mapping: any): void {
-  const query = mapping.query
-
-  if (query === undefined || query === null) return
-
-  if (typeof query.limit === 'number') query.limit = expandRange(query.limit as number)
-
-  if (typeof query.omit === 'number') query.omit = expandRange(query.omit as number)
-}
-
-function parseDirectives(
-  mapping: Record<string, any>,
-  shortcuts?: Shortcuts
-): Directive[] {
-  const directives: Directive[] = []
-
-  for (const [key, value] of Object.entries(mapping)) {
-    const directive = parseDirective(key, value, shortcuts)
-
-    if (directive === null) continue
-
-    directives.push(directive)
-
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    delete mapping[key]
-  }
-
-  return directives
-}
-
-function parseDirective(
-  key: string,
-  value: any,
-  shortcuts?: Shortcuts
-): Directive | null {
-  if (shortcuts?.has(key) === true) key = shortcuts.get(key)! // eslint-disable-line @typescript-eslint/no-non-null-assertion
-
-  const match = key.match(DIRECTIVE_RX)
-
-  if (match === null) return null
-
-  const { family, name } = match.groups as { family: string; name: string }
-
-  return { family, name, value }
-}
-
-function expandRange(range: number): Range {
-  return { value: range, range: [range, range] }
-}
-
-const DIRECTIVE_RX = /^(?<family>\w{1,32}):(?<name>\w{1,32})$/
-
-export type Shortcuts = Map<string, string>

package/source/extensions.exposition/syntax/types.ts

@@ -1,69 +0,0 @@
-export interface Node {
-  protected?: boolean
-  isolated?: boolean
-  forward?: string
-  routes: Route[]
-  methods: Method[]
-  directives: Directive[]
-}
-
-export interface Route {
-  path: string
-  node: Node
-}
-
-export interface Method {
-  verb: string
-  mapping?: Mapping
-  directives: Directive[]
-}
-
-export interface Directive {
-  family: string
-  name: string
-  value: any
-}
-
-export interface Mapping {
-  namespace?: string
-  component?: string
-  endpoint: string
-  query?: Query | null
-
-  /**
-   * Whether the operation this maps to answers a page of a collection, and so takes the
-   * `omit` and `limit` a page is taken by. Written where the component's manifest is read,
-   * beside `namespace` and `component`, and not declared.
-   */
-  paged?: boolean
-}
-
-export interface Query {
-  id?: string
-  criteria?: string
-  search?: boolean
-  sample?: number
-  sort?: string
-  omit?: Range
-  limit?: Range
-  selectors?: string[]
-  projection?: string[]
-  parameters?: string[]
-  deleted?: boolean
-}
-
-export interface Range {
-  value?: number
-  range: [number, number]
-}
-
-export const verbs = new Set<string>([
-  'GET',
-  'HEAD',
-  'POST',
-  'PUT',
-  'PATCH',
-  'DELETE',
-  'LOCK',
-  'UNLOCK'
-])

package/source/extensions.fetch/context.ts

@@ -1,10 +0,0 @@
-import type { Contribution } from '@toa.io/core/types'
-
-/** What this extension puts on the context of every component, being declared for all. */
-export function context(): Contribution {
-  return {
-    name: 'fetch',
-    type: '(input: string | URL | Request, init?: FetchInit) => Promise<Response>',
-    imports: { '@toa.io/extensions.fetch': ['FetchInit'] }
-  }
-}

package/source/extensions.fetch/index.ts

@@ -1 +0,0 @@
-export { context } from './context.js'

package/source/extensions.introspection/annotation.ts

@@ -1,87 +0,0 @@
-import { DEFAULT_INTERVAL, DEFAULT_THRESHOLD, DENIED, ENV } from './const.js'
-import { environment as variables } from '@toa.io/generic'
-import type { Resources } from '@toa.io/operations'
-
-/** `context.toa.yaml` */
-export type Annotation =
-  | false
-  | {
-      /** Capture real payloads. Off by default: this is production data. */
-      samples?: boolean
-      /** Flush period, seconds. */
-      interval?: number
-      /** Flush as soon as this many distinct edges are buffered. */
-      threshold?: number
-      /** Publish the UI. On by default. */
-      ui?: boolean
-      resources?: Resources
-    }
-
-/** `manifest.toa.yaml` */
-export type Declaration =
-  | false
-  | {
-      samples?: boolean
-    }
-
-/** What `deployment()` encodes into the environment. */
-export interface Options {
-  samples: boolean
-  interval: number
-  threshold: number
-  ui: boolean
-}
-
-/** The effective per-component decision. */
-export interface Settings {
-  enabled: boolean
-  samples: boolean
-}
-
-export const DISABLED: Settings = { enabled: false, samples: false }
-
-export function options(annotation?: Annotation): Options {
-  const declaration = annotation === undefined || annotation === false ? {} : annotation
-
-  return {
-    samples: declaration.samples === true,
-    interval: declaration.interval ?? DEFAULT_INTERVAL,
-    threshold: declaration.threshold ?? DEFAULT_THRESHOLD,
-    ui: declaration.ui !== false
-  }
-}
-
-/** Reads what `deployment()` has put into the environment. */
-export function environment(): Options | null {
-  const value = variables.get(ENV)
-
-  if (value === undefined) return null
-
-  return JSON.parse(value) as Options
-}
-
-export function component(declaration: Declaration | null | undefined): Declaration {
-  if (declaration === false) return false
-
-  // predefined extensions arrive as null for components that say nothing
-  if (declaration === null || declaration === undefined) return {}
-
-  return declaration.samples === undefined ? {} : { samples: declaration.samples }
-}
-
-/**
- * Both levels must agree, and either can veto: the context is the environment
- * ceiling, the manifest is the component's own call. A component handling
- * personal data opts out for good, and no context flag overrides that.
- */
-export function settings(
-  namespace: string,
-  declaration: Declaration,
-  opts: Options | null
-): Settings {
-  if (opts === null || declaration === false) return DISABLED
-
-  const samples = opts.samples && declaration.samples !== false && !DENIED.has(namespace)
-
-  return { enabled: true, samples }
-}

package/source/extensions.introspection/components.ts

@@ -1,13 +0,0 @@
-import { components as digest, type Components } from '../digest/read.js'
-import type { Annotation } from './annotation.js'
-
-/**
- * The extension is predefined, so an application that turns introspection off
- * must not end up with the explorer components — nor with the exposition
- * dependency they bring in.
- */
-export function components(annotation?: Annotation): Components {
-  if (annotation === false) return { labels: [], manifests: [] }
-
-  return digest('extensions.introspection')
-}

package/source/extensions.introspection/const.ts

@@ -1,46 +0,0 @@
-import { environment } from '@toa.io/generic'
-
-export const ID = 'introspection'
-export const NAMESPACE = 'introspection'
-
-export const ENV = 'TOA_INTROSPECTION'
-
-export const NODES = 'nodes'
-export const EDGES = 'edges'
-
-/** Where the UI is mounted; `/introspection/*` belongs to the components' own API. */
-export const UI_PATH = '/.introspection'
-export const UI_PORT = 8002
-
-/**
- * The port the UI is served on. `UI_PORT` is what a deployment publishes and what the chart
- * renders; the variable is for a machine that runs more than one Toa process — a Toa checkout
- * beside an application, or two applications — where one of them has to give it up.
- */
-export const UI_PORT_ENV = 'TOA_INTROSPECTION_UI_PORT'
-export function uiPort(): number {
-  const value = environment.get(UI_PORT_ENV)
-
-  return value === undefined ? UI_PORT : Number(value)
-}
-
-export const DEFAULT_INTERVAL = 300
-export const DEFAULT_THRESHOLD = 1024
-
-/** How often a component re-announces its description, so that removed components fade out. */
-export const ANNOUNCE_INTERVAL = 1_800_000
-
-/**
- * `source` arrives over the wire, so the number of distinct edges a process
- * can hold must be bounded regardless of what peers send.
- */
-export const MAX_EDGES = 4096
-
-/** Never capture samples for these namespaces, whatever the annotation says. */
-export const DENIED = new Set(['identity', 'introspection'])
-
-/** Keys never stored in a sample, even when sampling is on. */
-export const REDACTED = /^(password|secret|token|credentials?|key|authorization|cookie)$/i
-
-/** Serialized size cap of a single sample. */
-export const SAMPLE_LIMIT = 4096

package/source/extensions.introspection/deployment.ts

@@ -1,48 +0,0 @@
-import { options } from './annotation.js'
-import { components } from './components.js'
-import { version } from '../version.js'
-import { ENV, UI_PATH, UI_PORT } from './const.js'
-import * as schemas from './schemas.js'
-import type { Annotation } from './annotation.js'
-import type { Dependency, Instances, Service } from '@toa.io/operations'
-
-/** 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-introspection-explorer'
-
-export const standalone = true
-
-/**
- * The explorer hosts the introspection components, exactly as the exposition
- * gateway hosts the identity ones. Collection is on unless the context says
- * `introspection: false`, and the environment variable is emitted together
- * with the service — never on its own, or tasks would pile up in a queue
- * nothing consumes.
- */
-export function deployment(_: Instances<unknown>, annotation?: Annotation): Dependency {
-  if (annotation === false) return {}
-
-  if (annotation !== undefined) schemas.annotation.validate(annotation)
-
-  const opts = options(annotation)
-
-  const service: Service = {
-    group: 'introspection',
-    name: 'explorer',
-    image,
-    version,
-    components: components().labels,
-    resources: annotation?.resources,
-    variables: []
-  }
-
-  if (opts.ui) {
-    service.port = UI_PORT
-    service.ingress = { path: UI_PATH }
-  }
-
-  return {
-    services: [service],
-    variables: { global: [{ name: ENV, value: JSON.stringify(opts) }] }
-  }
-}

package/source/extensions.introspection/index.ts

@@ -1,6 +0,0 @@
-export { manifest } from './manifest.js'
-export { components } from './components.js'
-export { deployment, image, standalone } from './deployment.js'
-export * from './annotation.js'
-export * from './const.js'
-export * as schemas from './schemas.js'

package/source/extensions.introspection/manifest.ts

@@ -1,18 +0,0 @@
-import { component } from './annotation.js'
-import * as schemas from './schemas.js'
-import type { Declaration } from './annotation.js'
-
-/**
- * The component level of the annotation.
- *
- * The extension is predefined, so most components say nothing and the
- * declaration arrives as `null` — which still has to produce a value,
- * or norm rejects the extension.
- */
-export function manifest(declaration: Declaration | null | undefined): Declaration {
-  const normalized = component(declaration)
-
-  if (normalized !== false) schemas.declaration.validate(normalized)
-
-  return normalized
-}