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

package/source/Client.ts

@@ -1,251 +0,0 @@
-import { console } from 'openspan'
-import { Connector, Locator } from '@toa.io/core'
-import { EVENT, SOURCE } from './const.js'
-import type { Remote } from '@toa.io/core'
-import type { Message } from '@toa.io/core/types'
-import type { Host } from './Factory.js'
-
-/**
- * One per process: one remote to the values service and one subscription to its events,
- * shared by every Aspect. What the Aspects ask for is collected and sent as one call;
- * what the service creates afterwards is handed to whoever subscribed.
- */
-export class Client extends Connector {
-  /** Disconnected once, a connector keeps what it depended on, so a gone client is not reused. */
-  public disposed = false
-
-  private readonly host: Host
-  private readonly options: Options
-  private readonly pending = new Map<string, Pending>()
-  private readonly listeners = new Map<string, Set<Listener>>()
-  private remote: Remote | null = null
-  private timer: NodeJS.Timeout | null = null
-  private flushing = false
-  private fresh = false
-  private round = 0
-
-  public constructor(host: Host, options: Partial<Options> = {}) {
-    super()
-
-    this.host = host
-    this.options = { ...DEFAULTS, ...options }
-  }
-
-  /** The configuration of a component for an epoch, once the service has one. */
-  public async fetch(component: string, epoch: string): Promise<Value> {
-    const key = id(component, epoch)
-
-    let entry = this.pending.get(key)
-
-    if (entry === undefined) {
-      entry = { component, epoch, waiters: [] }
-      this.pending.set(key, entry)
-    }
-
-    const promise = new Promise<Value>((resolve) => {
-      entry!.waiters.push(resolve)
-    })
-
-    if (this.flushing) this.fresh = true
-    else this.schedule(0)
-
-    return await promise
-  }
-
-  public subscribe(component: string, epoch: string, listener: Listener): void {
-    const key = id(component, epoch)
-
-    if (!this.listeners.has(key)) this.listeners.set(key, new Set())
-
-    this.listeners.get(key)!.add(listener)
-  }
-
-  public unsubscribe(component: string, epoch: string, listener: Listener): void {
-    this.listeners.get(id(component, epoch))?.delete(listener)
-  }
-
-  protected override async open(): Promise<void> {
-    this.remote = await this.host.remote(LOCATOR, SOURCE)
-
-    this.depends(this.remote)
-    await this.remote.connect()
-
-    const subscription = new Subscription(this.deliver.bind(this))
-    const consumer = await this.host.receive(EVENT, subscription)
-
-    this.depends(consumer)
-    await consumer.connect()
-  }
-
-  protected override async close(): Promise<void> {
-    if (this.timer !== null) {
-      clearTimeout(this.timer)
-      this.timer = null
-    }
-  }
-
-  protected override async dispose(): Promise<void> {
-    this.disposed = true
-  }
-
-  private schedule(delay: number): void {
-    if (this.flushing) return
-
-    if (this.timer !== null) {
-      // a request that has just arrived does not wait for the round already planned
-      if (delay > 0) return
-
-      clearTimeout(this.timer)
-    }
-
-    this.timer = setTimeout(() => {
-      void this.flush()
-    }, delay)
-  }
-
-  private async flush(): Promise<void> {
-    this.timer = null
-    this.flushing = true
-    this.fresh = false
-
-    const batch = [...this.pending.values()]
-    const input = batch.map(({ component, epoch }) => ({ component, epoch }))
-
-    try {
-      const output = await this.remote!.invoke<Fetched[] | Error>('fetch', { input })
-
-      if (output instanceof Error) throw output
-
-      this.settle(output)
-    } catch (error) {
-      console.warn('Configuration fetch failed', { error })
-    } finally {
-      this.flushing = false
-    }
-
-    this.report(batch)
-
-    if (this.pending.size === 0) return
-
-    if (this.fresh) this.schedule(0)
-    else this.schedule(this.backoff())
-  }
-
-  /** Those the service has served are told; the rest stay for the next round. */
-  private settle(output: Fetched[]): void {
-    for (const { component, epoch, configuration, created } of output) {
-      if (configuration === null) continue
-
-      const key = id(component, epoch)
-      const entry = this.pending.get(key)
-
-      if (entry === undefined) continue
-
-      this.pending.delete(key)
-
-      for (const resolve of entry.waiters) resolve({ configuration, created })
-    }
-  }
-
-  private report(batch: Pending[]): void {
-    const waiting = batch
-      .filter(({ component, epoch }) => this.pending.has(id(component, epoch)))
-      .map(({ component }) => component)
-
-    if (waiting.length === 0) {
-      this.round = 0
-
-      return
-    }
-
-    this.round++
-
-    if (this.round % this.options.warn === 1)
-      console.warn('Waiting for configuration', {
-        components: waiting,
-        round: this.round
-      })
-  }
-
-  private backoff(): number {
-    return Math.min(this.options.base * Math.pow(FACTOR, this.round), this.options.max)
-  }
-
-  /** A created object goes to the subscribers of its component and epoch, as it is. */
-  private deliver(created: Created): void {
-    const listeners = this.listeners.get(id(created.component, created.epoch))
-
-    if (listeners === undefined) return
-
-    const value: Value = {
-      configuration: created.configuration,
-      created: created.CREATED
-    }
-
-    for (const listener of listeners) listener(value)
-  }
-}
-
-/** What the event consumer hands deliveries to. */
-class Subscription extends Connector {
-  private readonly handler: (created: Created) => void
-
-  public constructor(handler: (created: Created) => void) {
-    super()
-
-    this.handler = handler
-  }
-
-  public async receive(message: Message<Created>): Promise<void> {
-    this.handler(message.payload)
-  }
-}
-
-function id(component: string, epoch: string): string {
-  return component + '\0' + epoch
-}
-
-const LOCATOR = new Locator('values', 'configuration')
-const FACTOR = 1.5
-
-const DEFAULTS: Options = {
-  base: 1000,
-  max: 10000,
-  warn: 5
-}
-
-export interface Options {
-  base: number
-  max: number
-  /** Every n-th round of waiting is reported. */
-  warn: number
-}
-
-/** A configuration and when it was created; `0` for the deployed defaults. */
-export interface Value {
-  configuration: object
-  created: number
-}
-
-export interface Fetched {
-  component: string
-  epoch: string
-  configuration: object | null
-  created: number
-}
-
-/** The `configuration.values.created` payload: the object as stored. */
-export interface Created {
-  component: string
-  epoch: string
-  configuration: object
-  CREATED: number
-}
-
-export type Listener = (value: Value) => void
-
-interface Pending {
-  component: string
-  epoch: string
-  waiters: Array<(value: Value) => void>
-}

package/source/Composition.ts

@@ -1,57 +0,0 @@
-import { readdirSync, type Dirent } from 'node:fs'
-import { resolve } from 'node:path'
-import { Connector } from '@toa.io/core'
-import { uiPort } from './const.js'
-import { UI } from './UI.js'
-import type { Host } from './Factory.js'
-
-/** Hosts the values component in the service process. */
-export class Composition extends Connector {
-  private readonly host: Host
-
-  public constructor(host: Host) {
-    super()
-    this.host = host
-  }
-
-  protected override async open(): Promise<void> {
-    const composition = await this.host.composition(components().paths)
-
-    await composition.connect()
-
-    this.depends(composition)
-
-    // connected here rather than declared as a dependency: dependencies are connected
-    // before `open` runs, so one added from inside it would never be
-    const ui = new UI(uiPort())
-
-    await ui.connect()
-
-    this.depends(ui)
-  }
-}
-
-export function components(): Components {
-  const labels: string[] = []
-  const paths: string[] = []
-
-  for (const entry of entries()) {
-    labels.push(entry.name.replace('.', '-'))
-    paths.push(resolve(ROOT, entry.name))
-  }
-
-  return { labels, paths }
-}
-
-function entries(): Dirent[] {
-  const entries = readdirSync(ROOT, { withFileTypes: true })
-
-  return entries.filter((entry) => entry.isDirectory())
-}
-
-interface Components {
-  labels: string[]
-  paths: string[]
-}
-
-const ROOT = resolve(import.meta.dirname, '../components/')

package/source/Factory.ts

@@ -1,34 +0,0 @@
-import { type Connector, type Locator } from '@toa.io/core'
-import type { extensions } from '@toa.io/core/types'
-import { Aspect } from './Aspect.js'
-import { Client } from './Client.js'
-import { Composition } from './Composition.js'
-import { overridden } from './configuration.js'
-import type { Manifest } from './manifest.js'
-
-export class Factory implements extensions.Factory {
-  private readonly host: Host
-  private client: Client | null = null
-
-  public constructor(host: Host) {
-    this.host = host
-  }
-
-  public aspect(locator: Locator, manifest: Manifest): extensions.Aspect {
-    const client = overridden(locator) ? null : this.shared()
-
-    return new Aspect(locator, manifest, client)
-  }
-
-  public service(): Connector {
-    return new Composition(this.host)
-  }
-
-  private shared(): Client {
-    if (this.client === null || this.client.disposed) this.client = new Client(this.host)
-
-    return this.client
-  }
-}
-
-export type Host = extensions.Host

package/source/Secret.test.ts

@@ -1,32 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { inspect } from 'node:util'
-import { REDACTED, Secret } from './Secret.js'
-
-const secret = new Secret('s3cret')
-
-it('should unwrap', () => {
-  assert.deepStrictEqual(secret.unwrap(), 's3cret')
-})
-
-it('should not show as a string', () => {
-  assert.deepStrictEqual(String(secret), REDACTED)
-  assert.deepStrictEqual(`${secret}`, REDACTED)
-  assert.deepStrictEqual('' + secret, REDACTED)
-})
-
-it('should not show in JSON', () => {
-  assert.deepStrictEqual(JSON.stringify({ key: secret }), '{"key":"<REDACTED>"}')
-})
-
-it('should not show when inspected', () => {
-  assert.deepStrictEqual(inspect(secret), REDACTED)
-  assert.ok(inspect({ key: secret }).includes(REDACTED))
-  assert.ok(!inspect({ key: secret }).includes('s3cret'))
-})
-
-it('should not expose the value as a property', () => {
-  assert.deepStrictEqual(Object.keys(secret), [])
-  assert.deepStrictEqual({ ...secret }, {})
-})

package/source/Secret.ts

@@ -1,32 +0,0 @@
-import { inspect } from 'node:util'
-
-/**
- * A configuration value that must not leak: a string only to whoever asks for it.
- *
- * This is what a value declared `format: secret` is on a component's context.
- */
-export class Secret {
-  readonly #value: string
-
-  public constructor(value: string) {
-    this.#value = value
-  }
-
-  public unwrap(): string {
-    return this.#value
-  }
-
-  public toString(): string {
-    return REDACTED
-  }
-
-  public toJSON(): string {
-    return REDACTED
-  }
-
-  public [inspect.custom](): string {
-    return REDACTED
-  }
-}
-
-export const REDACTED = '<REDACTED>'

package/source/UI.ts

@@ -1,213 +0,0 @@
-import * as fs from 'node:fs'
-import * as http from 'node:http'
-import * as path from 'node:path'
-import { Connector } from '@toa.io/core'
-import { console } from 'openspan'
-import { UI_PATH } from './const.js'
-
-/**
- * Serves the configuration UI: the directory `ui` builds, and nothing else.
- *
- * The page is a single-page application whose mount path is baked into the bundle,
- * so this server routes relative to `UI_PATH` — which is also what the ingress
- * forwards. `/configuration/*` is left alone: that is the component's own API.
- */
-export class UI extends Connector {
-  private readonly server: http.Server = http.createServer()
-  private readonly port: number
-  private readonly root: string
-
-  public constructor(port: number, root: string = SITE) {
-    super()
-
-    this.port = port
-    this.root = root
-    this.server.on('request', (request, response) => {
-      this.listen(request, response)
-    })
-  }
-
-  protected override async open(): Promise<void> {
-    /*
-     * A taken port is a real error: uniqueness across services is settled at export
-     * time, so nothing here has to negotiate for one.
-     */
-    await new Promise<void>((resolve, reject) => {
-      const failed = (error: Error): void => {
-        this.server.off('listening', listening)
-        reject(error)
-      }
-
-      const listening = (): void => {
-        this.server.off('error', failed)
-        resolve()
-      }
-
-      this.server.once('error', failed)
-      this.server.once('listening', listening)
-      this.server.listen(this.port)
-    })
-
-    if (!isFile(path.join(this.root, 'index.html')))
-      console.warn('Configuration UI is not built', { root: this.root })
-
-    console.info('Configuration UI started', { port: this.port, path: UI_PATH + '/' })
-  }
-
-  protected override async close(): Promise<void> {
-    const closed = new Promise<void>((resolve) =>
-      this.server.once('close', () => {
-        resolve()
-      })
-    )
-
-    this.server.close()
-    this.server.closeAllConnections()
-
-    await closed
-  }
-
-  private listen(request: http.IncomingMessage, response: http.ServerResponse): void {
-    void this.respond(request, response).catch((error: Error) => {
-      console.error('Configuration UI failure', { message: error.message })
-
-      if (!response.writableEnded) response.writeHead(500).end()
-    })
-  }
-
-  private async respond(
-    request: http.IncomingMessage,
-    response: http.ServerResponse
-  ): Promise<void> {
-    if (request.method !== 'GET' && request.method !== 'HEAD') {
-      response.writeHead(405, { allow: 'GET, HEAD' }).end()
-
-      return
-    }
-
-    const pathname = decode(request.url ?? '/')
-
-    if (pathname === null) {
-      response.writeHead(400).end()
-
-      return
-    }
-
-    // the port is the explorer's alone, so the root is the way in
-    if (pathname === '/') {
-      response.writeHead(302, { location: UI_PATH + '/' }).end()
-
-      return
-    }
-
-    const file = this.resolve(pathname)
-
-    if (file === null) response.writeHead(404).end()
-    else await this.send(file, request, response)
-  }
-
-  /**
-   * The file a request lands on, or `null` when nothing does. A path that exists is
-   * served as it is; anything else that could be a route falls back to the page,
-   * because the client router — not this server — knows what routes there are.
-   */
-  private resolve(pathname: string): string | null {
-    if (!pathname.startsWith(UI_PATH)) return null
-
-    const relative = pathname.slice(UI_PATH.length)
-
-    if (relative !== '' && !relative.startsWith('/')) return null
-
-    const file = path.join(this.root, relative)
-
-    if (file !== this.root && !file.startsWith(this.root + path.sep)) return null
-
-    if (isFile(file)) return file
-
-    /*
-     * A missing asset is missing, but a route can look like one: `identity.passkeys` is a
-     * component, not a file with an extension. What this server would have served is what
-     * it knows how to serve, so anything else is a route and falls back to the page — as
-     * does anything ending in a slash, which is no name for a file at all.
-     */
-    const asset = !relative.endsWith('/') && path.extname(relative) in TYPES
-
-    return asset ? null : path.join(this.root, 'index.html')
-  }
-
-  private async send(
-    file: string,
-    request: http.IncomingMessage,
-    response: http.ServerResponse
-  ): Promise<void> {
-    const stats = await fs.promises.stat(file).catch(() => null)
-
-    if (stats === null) {
-      response
-        .writeHead(503, { 'content-type': 'text/plain' })
-        .end('The configuration UI is not built. Run `npm run build:ui`.\n')
-
-      return
-    }
-
-    response.writeHead(200, {
-      'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream',
-      'content-length': stats.size,
-      'cache-control': caching(path.relative(this.root, file))
-    })
-
-    if (request.method === 'HEAD') response.end()
-    else fs.createReadStream(file).pipe(response)
-  }
-}
-
-function decode(url: string): string | null {
-  try {
-    return decodeURIComponent(url.split('?')[0])
-  } catch {
-    return null
-  }
-}
-
-function isFile(file: string): boolean {
-  return fs.existsSync(file) && fs.statSync(file).isFile()
-}
-
-/** Where `npm run build:ui` puts the page, from both `source` and `transpiled`. */
-const SITE = path.resolve(import.meta.dirname, '..', 'ui', 'dist')
-
-/** Assets under this prefix carry their build hash in the name. */
-const IMMUTABLE = path.join('_app', 'immutable')
-const FOREVER = 'public, max-age=31536000, immutable'
-
-/** The icons: named without a hash, so they are re-read, but rarely. */
-const ICONS = new Set(['favicon.ico', 'favicon-96x96.png', 'apple-touch-icon.png'])
-const DAY = 'public, max-age=86400'
-
-/**
- * How long what is served may be held. The page is never cached — it names the assets,
- * and their names carry the build. An icon is named for what it is rather than for its
- * content, so it is asked about again, but not on every page load.
- */
-function caching(relative: string): string {
-  if (relative.startsWith(IMMUTABLE)) return FOREVER
-
-  return ICONS.has(relative) ? DAY : 'no-cache'
-}
-
-const TYPES: Record<string, string> = {
-  '.css': 'text/css; charset=utf-8',
-  '.html': 'text/html; charset=utf-8',
-  '.ico': 'image/x-icon',
-  '.jpg': 'image/jpeg',
-  '.js': 'text/javascript; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.map': 'application/json; charset=utf-8',
-  '.png': 'image/png',
-  '.svg': 'image/svg+xml',
-  '.txt': 'text/plain; charset=utf-8',
-  '.webmanifest': 'application/manifest+json',
-  '.webp': 'image/webp',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2'
-}