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

package/source/RTD/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/RTD/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/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/manifest.test.ts

@@ -1,56 +0,0 @@
-import { it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { type Manifest } from '@toa.io/norm'
-import { generate } from 'randomstring'
-import { manifest } from './manifest.js'
-
-const name = 'cm-' + generate()
-const namespace = 'ns' + generate()
-
-let mf: Manifest
-
-const operations = { observe: {} }
-
-beforeEach(() => {
-  mf = { namespace, name, operations } as unknown as Manifest
-})
-
-const declaration = {
-  '/': { GET: 'observe' }
-}
-
-it('should create branch', async () => {
-  const node = manifest(declaration, mf)
-
-  assert.notStrictEqual(node, undefined)
-  assert.strictEqual(node.routes.length, 1)
-  assert.strictEqual(node.routes[0].path, '/' + namespace + '/' + name)
-})
-
-it('should not create node for default namespace', async () => {
-  mf.namespace = 'default'
-
-  const node = manifest(declaration, mf)
-
-  assert.strictEqual(node.routes.length, 1)
-  assert.strictEqual(node.routes[0].path, '/' + name)
-})
-
-it('should throw on invalid declaration type', async () => {
-  assert.throws(
-    () => manifest('hello' as unknown as object, mf),
-    (error: any) => /Exposition declaration must be an object/.test(error.message)
-  )
-})
-
-it('should set namespace and component', async () => {
-  const node = manifest(declaration, mf)
-
-  const root = node.routes[0].node
-  const intemediate = root.routes[0].node
-  const GET = intemediate.methods[0]
-
-  assert.strictEqual(GET.mapping?.namespace, namespace)
-  assert.strictEqual(GET.mapping?.component, name)
-})

package/source/manifest.ts

@@ -1,56 +0,0 @@
-import assert from 'node:assert'
-import { parse, type Node, type Method, type Query } from './RTD/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/schemas.test.ts

@@ -1,31 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import * as schemas from './schemas.js'
-
-const authorities = { nex: 'nex.toa.io' }
-
-it('should require ip with bouncer', () => {
-  assert.throws(() => schemas.annotation.validate({ authorities, bouncer: {} }))
-  assert.doesNotThrow(() =>
-    schemas.annotation.validate({ authorities, bouncer: {}, ip: 'x-real-ip' })
-  )
-  assert.doesNotThrow(() => schemas.annotation.validate({ authorities, ip: 'x-real-ip' }))
-})
-
-it('should default nothing in bouncer', () => {
-  assert.doesNotThrow(() =>
-    schemas.annotation.validate({
-      authorities,
-      ip: 'x-real-ip',
-      bouncer: { attempts: 5 }
-    })
-  )
-  assert.throws(() =>
-    schemas.annotation.validate({
-      authorities,
-      ip: 'x-real-ip',
-      bouncer: { attempts: 0 }
-    })
-  )
-})

package/source/schemas.ts

@@ -1,15 +0,0 @@
-import { resolve } from 'node:path'
-import * as schemas from '@toa.io/schemas'
-import type { Query } from './HTTP/index.js'
-import type { Node } from './RTD/index.js'
-import type { Call } from './RPC/types.js'
-import type { Schema } from '@toa.io/schemas'
-import type { Annotation } from './Annotation.js'
-
-const path = resolve(import.meta.dirname, '../schemas')
-const namespace = schemas.namespace(path)
-
-export const querystring: Schema<Query> = namespace.schema('querystring')
-export const annotation: Schema<Annotation> = namespace.schema('annotation')
-export const node: Schema<Node> = namespace.schema('node')
-export const call: Schema<Call> = namespace.schema('call')

package/source/shortcuts.ts

@@ -1,14 +0,0 @@
-import type { Shortcuts } from './RTD/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/transpiled/Annotation.d.ts

@@ -1,70 +0,0 @@
-import type { Resources } from '@toa.io/operations';
-import type { Protocol } from './HTTP/index.js';
-export interface Annotation {
-    authorities: Record<string, string>;
-    /**
-     * `h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream.
-     * See `documentation/protocol.md`.
-     */
-    protocol?: Protocol;
-    class?: string;
-    resources?: Resources;
-    annotations?: Record<string, string>;
-    /** The Service, as opposed to the Ingress that `annotations` above describes. */
-    service?: {
-        annotations?: Record<string, string>;
-    };
-    debug?: boolean;
-    /** The header the client address is read from; the connection's without one. See `ip.md`. */
-    ip?: string;
-    /** Failed authentications an address may make; none are metered unless set. See `identity.md`. */
-    bouncer?: Bouncer;
-    /** The authorization server this context exposes; none is exposed without it. */
-    oauth?: OAuth;
-    /** JSON-RPC at `/.rpc`; none is served without it. See `documentation/rpc.md`. */
-    rpc?: RPC;
-    /** MCP at `/.mcp`; none is served without it. See `documentation/mcp.md`. */
-    mcp?: MCP;
-    '/'?: object;
-}
-export interface OAuth {
-    /**
-     * Where a client sends the user to consent. The one endpoint of the flow that needs a
-     * person, and so the one this extension does not serve: an application builds it.
-     */
-    authorize: string;
-    /** Paths a token may be restricted to, each advertised as a protected resource. */
-    resources?: string[];
-    /** What a client may ask for. Each is a role, or a scope within one. */
-    scopes?: string[];
-    /** Origins whose Client ID Metadata Documents may be read. None are without it. */
-    trust?: string[];
-    /** Dynamic Client Registration, off unless opened. */
-    registration?: 'open' | 'closed';
-}
-export interface RPC {
-    /**
-     * Calls one request may carry, 32 by default. One request is one authentication and one
-     * reply however many calls it makes, so what a caller may ask for at once is bounded.
-     */
-    batch?: number;
-}
-export interface MCP {
-    /** What the server calls itself, which a client shows a user. */
-    name: string;
-    /** What a model is told before it calls anything here. */
-    instructions?: string;
-    /**
-     * Browser origins the endpoint answers, which the revision requires against DNS rebinding.
-     * None are admitted without it; a request carrying no `Origin` is not a browser's.
-     */
-    origins?: string[];
-    /** Whether the endpoint answers without a credential. It does not unless it says so. */
-    anonymous?: boolean;
-}
-export interface Bouncer {
-    /** what an address may fail at once, 20 by default */
-    attempts?: number;
-    /** seconds it takes to earn them back, 60 by default */
-    interval?: number;
-}

package/transpiled/Annotation.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=Annotation.js.map

package/transpiled/Annotation.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Annotation.js","sourceRoot":"","sources":["../source/Annotation.ts"],"names":[],"mappings":""}

package/transpiled/RTD/syntax/parse.d.ts

@@ -1,4 +0,0 @@
-import { type Node } from './types.js';
-export declare function parse(input: object, shortcuts?: Shortcuts): Node;
-export declare function createNode(): Node;
-export type Shortcuts = Map<string, string>;