@toa.io/extensions.configuration 0.20.0-dev.4 → 0.20.0-dev.40

package/source/manifest.ts

@@ -0,0 +1,15 @@
+import * as schemas from './schemas'
+import { type Configuration } from './configuration'
+
+export function manifest (manifest: Manifest): Manifest {
+  if (manifest.schema === undefined) manifest = { schema: manifest }
+
+  schemas.manifest.validate(manifest)
+
+  return manifest
+}
+
+export interface Manifest {
+  schema: object
+  defaults?: Configuration
+}

package/source/schemas.ts

@@ -0,0 +1,8 @@
+import { resolve } from 'node:path'
+import * as schemas from '@toa.io/schemas'
+
+const path = resolve(__dirname, '../schemas')
+const namespace = schemas.namespace(path)
+
+export const manifest = namespace.schema('manifest')
+export const annotation = namespace.schema('annotation')

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./transpiled"
+  },
+  "include": [
+    "source"
+  ]
+}

package/docs/discussion.md

@@ -1,109 +0,0 @@
-# Discussion
-
-## Change Requests
-
-- [x] feat(configuration): add configuration extension
-    - manifest (schema) validation
-    - context extension
-- [x] feat(formation): add well-known extension 'configuration'
-    - component
-    - context
-- [x] feat(node): add well-known context extension 'configuration'
-- [x] feat(configuration): add concise declarations
-- [x] feat(configuration): add runtime configuration resolution
-- [x] feat(cli): add `toa configure <key> <value> --reset`
-    - validate type
-- [x] feat(operations): add configuration deployment
-    - annotations (values) validation
-- [ ] feat(configuration): add secrets resolution
-- [ ] feat(operations): add secrets deployment
-- [ ] feat(cli): add `toa conceal`
-    - validate type
-- [ ] feat(cli): add `toa configure`
-    - prompt required values
-    - use JSON Schema title
-
-## Statements
-
-### Common
-
-- Secrets are being deployed separately by `toa conceal` command
-
-### 1: Environment variables
-
-- Configuration values and secrets are mapped as environment variables to composition deployments
-- Extensions may expose *deployment mutators*, which are able to modify deployment declaration
-- Configuration context extension reads environment variables to resolve configuration and secrets
-
-### 2: Dedicated Components
-
-- Hot updates
-- [Configuration consistency](consistency.md)
-
-## Questions
-
-### Where are values comes from?
-
-Environment variables.
-
-### Is there a configuration service or configuration component?
-
-No. It will be implemented later as a part of [consistent configuration](consistency.md).
-
-### How are configuration values being stored?
-
-As a kubernetes secrets mapped as environment variables.
-
-### Where are secrets being stored and how do they resolve to value?
-
-As a kubernetes secrets mapped as environment variables.
-
-### Is configuration a single environment variable or a set (one per component)?
-
-#### Context Configuration
-
-In later versions, context extension will resolve configuration values by component locator. Given
-that it is yet
-unknown when this will happen, a certain context might have appeared which configuration is big
-enough to not fit the
-environment variable limitations.
-
-That is, Context Configuration must be mapped as a set of environment variables (one per component).
-Values are
-serialized Configuration Objects.
-
-> This will also allow to configure local environment per component.
-
-#### Secrets
-
-Secrets are mapped per secret as they are not bound to components.
-
-### Is configuration a single kubernetes secret or a set (one per component)?
-
-#### Configuration
-
-Single secret with a set of values per component.
-
-#### Secrets
-
-Once kubernetes secret per configuration secret.
-
-### Is there an option to configure local environment?
-
-<dl>
-<dt><code>toa configure &lt;component&gt;</code></dt>
-<dd>Create local environment configuration values</dd>
-</dl>
-
-### Whose responsibility is to call annotations?
-
-- norm
-- deployment
-
-`toa export context` should throw errors if context has invalid annotations, and it's not a part of
-the deployment.
-
-## References
-
-- [#125](https://github.com/toa-io/toa/issues/125)
-- [#132](https://github.com/toa-io/toa/issues/132)

package/source/.deployment/index.js

@@ -1,7 +0,0 @@
-'use strict'
-
-const { variables } = require('./variables')
-const { secrets } = require('./secrets')
-
-exports.variables = variables
-exports.secrets = secrets

package/source/.deployment/secrets.js

@@ -1,33 +0,0 @@
-'use strict'
-
-const find = require('../secrets')
-
-/**
- * @param {toa.norm.context.dependencies.Instance[]} components
- * @param {object} annotations
- * @return {toa.deployment.dependency.Variables}
- */
-function secrets (components, annotations) {
-  /** @type {toa.deployment.dependency.Variables} */
-  const variables = {}
-
-  for (const [id, annotation] of Object.entries(annotations)) {
-    const component = components.find((component) => component.locator.id === id)
-    const label = component.locator.label
-
-    find.secrets(annotation, (variable, key) => {
-      if (variables[label] === undefined) variables[label] = []
-
-      variables[label].push({
-        name: variable,
-        secret: { name: SECRET_NAME, key }
-      })
-    })
-  }
-
-  return variables
-}
-
-const SECRET_NAME = 'toa-configuration'
-
-exports.secrets = secrets

package/source/.deployment/variables.js

@@ -1,26 +0,0 @@
-'use strict'
-
-const { encode } = require('@toa.io/generic')
-
-/**
- * @param {toa.norm.context.dependencies.Instance[]} components
- * @param {object} annotations
- * @return {toa.deployment.dependency.Variables}
- */
-function variables (components, annotations) {
-  /** @type {toa.deployment.dependency.Variables} */
-  const variables = {}
-
-  for (const [id, annotation] of Object.entries(annotations)) {
-    const component = components.find((component) => component.locator.id === id)
-
-    variables[component.locator.label] = [{
-      name: 'TOA_CONFIGURATION_' + component.locator.uppercase,
-      value: encode(annotation)
-    }]
-  }
-
-  return variables
-}
-
-exports.variables = variables

package/source/.manifest/.normalize/verbose.js

@@ -1,51 +0,0 @@
-'use strict'
-
-const { remap } = require('@toa.io/generic')
-
-const verbose = (node) => {
-  const isObject = node.properties !== undefined
-  const isValue = node.type !== undefined && node.type !== 'object'
-  const isProperties = node[SYM] === 1
-
-  if (!isObject && !isValue && !isProperties) return convert(node)
-
-  return node
-}
-
-const convert = (node) => {
-  const properties = remap(node, property)
-
-  properties[SYM] = 1
-
-  return { type: 'object', properties, additionalProperties: false }
-}
-
-function property (node) {
-  if (node === null) return { type: 'null', default: null }
-
-  const type = Array.isArray(node) ? 'array' : typeof node
-
-  if (type === 'object') return node
-  if (type === 'array') return array(node)
-
-  return { type, default: node }
-}
-
-const array = (array) => {
-  if (array.length === 0) throw new Error('Configuration: cannot resolve concise array items type because it\'s empty')
-
-  const type = typeof array[0]
-
-  const schema = {
-    type: 'array',
-    default: array
-  }
-
-  if (array.length === 1) schema.items = array[0]
-
-  return schema
-}
-
-const SYM = Symbol()
-
-exports.verbose = verbose

package/source/.manifest/index.js

@@ -1,7 +0,0 @@
-'use strict'
-
-const { normalize } = require('./normalize')
-const { validate } = require('./validate')
-
-exports.normalize = normalize
-exports.validate = validate

package/source/.manifest/normalize.js

@@ -1,16 +0,0 @@
-'use strict'
-
-const { traverse } = require('@toa.io/generic')
-const { verbose } = require('./.normalize/verbose')
-
-const normalize = (manifest) => {
-  if (manifest.properties === undefined) manifest = expand(manifest)
-
-  return manifest
-}
-
-const expand = (concise) => {
-  return traverse(concise, verbose)
-}
-
-exports.normalize = normalize

package/source/.manifest/schema.yaml

@@ -1,9 +0,0 @@
-$schema: https://json-schema.org/draft/2019-09/schema
-$id: https://schemas.toa.io/0.0.0/extensions/configuration/manifest
-
-$ref: 'https://schemas.toa.io/0.0.0/definitions#/definitions/schema'
-type: object
-properties:
-  type:
-    const: object
-    default: object

package/source/.manifest/validate.js

@@ -1,13 +0,0 @@
-'use strict'
-
-const path = require('path')
-
-const { Schema } = require('@toa.io/schema')
-const { load } = require('@toa.io/yaml')
-
-const schema = load.sync(path.resolve(__dirname, 'schema.yaml'))
-const validator = new Schema(schema)
-
-const validate = (declaration) => validator.validate(declaration)
-
-exports.validate = validate

package/source/.provider/env.js

@@ -1,19 +0,0 @@
-'use strict'
-
-const { map } = require('@toa.io/generic')
-
-function env (object) {
-  return map(object,
-    /**
-     * @type {toa.generic.map.transform<string>}
-     */
-    (value) => {
-      if (typeof value !== 'string') return
-
-      return value.replaceAll(RX, (match, variable) => process.env[variable] ?? match)
-    })
-}
-
-const RX = /\${(?<variable>[A-Z0-9_]{1,32})}/g
-
-exports.env = env

package/source/.provider/form.js

@@ -1,20 +0,0 @@
-'use strict'
-
-const { traverse } = require('@toa.io/generic')
-
-/**
- * @param {toa.schema.JSON | Object} schema
- * @return {Object}
- */
-const form = (schema) => {
-  const defaults = (node) => {
-    if (node.type === 'object' && node.properties !== undefined) return { ...node.properties }
-    if (node.default !== undefined) return node.default
-
-    return null
-  }
-
-  return traverse(schema, defaults)
-}
-
-exports.form = form

package/source/.provider/index.js

@@ -1,7 +0,0 @@
-'use strict'
-
-const { form } = require('./form')
-const { env } = require('./env')
-
-exports.form = form
-exports.env = env

package/source/annotation.fixtures.js

@@ -1,39 +0,0 @@
-'use strict'
-
-const { generate } = require('randomstring')
-const { Locator } = require('@toa.io/core')
-const { random } = require('@toa.io/generic')
-
-const instance = () => {
-  const name = generate()
-  const namespace = generate()
-  const locator = new Locator(name, namespace)
-
-  const manifest = {
-    type: 'object',
-    properties: {
-      foo: {
-        type: 'number',
-        default: 1
-      }
-    }
-  }
-
-  return { locator, manifest }
-}
-
-/** @type {toa.norm.context.dependencies.Instance[]} */
-const instances = []
-
-for (let i = 0; i < random(5) + 5; i++) instances.push(instance())
-
-/** @type {Object} */
-const annotation = {}
-
-for (let i = 0; i < random(instances.length - 1) + 1; i++) {
-  const instance = instances[i]
-  annotation[instance.locator.id] = { foo: random() }
-}
-
-exports.instances = instances
-exports.annotation = annotation

package/source/annotation.js

@@ -1,36 +0,0 @@
-'use strict'
-
-const { Schema } = require('@toa.io/schema')
-
-/**
- * @param {Object} annotation
- * @param {toa.norm.context.dependencies.Instance[]} instances
- */
-const annotation = (annotation, instances) => {
-  const keys = Object.keys(annotation)
-
-  check(keys, instances)
-
-  for (const instance of instances) {
-    const object = annotation[instance.locator.id] ?? {}
-    const schema = new Schema(instance.manifest)
-
-    schema.validate(object)
-  }
-
-  return annotation
-}
-
-/**
- * @param {string[]} keys
- * @param {toa.norm.context.dependencies.Instance[]} instances
- */
-const check = (keys, instances) => {
-  const ids = instances.map((instance) => instance.locator.id)
-
-  for (const key of keys) {
-    if (!ids.includes(key)) throw new Error(`Configuration Schema '${key}' is not defined`)
-  }
-}
-
-exports.annotation = annotation

package/source/annotation.test.js

@@ -1,43 +0,0 @@
-'use strict'
-
-const clone = require('clone-deep')
-const { generate } = require('randomstring')
-const { sample } = require('@toa.io/generic')
-
-const fixtures = require('./annotation.fixtures')
-const { annotation } = require('../')
-
-let input
-/** @type {toa.norm.context.dependencies.Instance[]} */ let instances
-
-const call = () => annotation(input, instances)
-
-beforeEach(() => {
-  input = clone(fixtures.annotation)
-  instances = clone(fixtures.instances)
-})
-
-it('sample must be valid', () => {
-  expect(call).not.toThrow()
-})
-
-it('should must be a function', () => {
-  expect(annotation).toBeDefined()
-  expect(annotation).toBeInstanceOf(Function)
-})
-
-it('should throw on non-existent component', () => {
-  input[generate()] = {}
-
-  expect(call).toThrow(/Configuration Schema/)
-})
-
-it('should throw if object doesn\'t match schema', () => {
-  const keys = Object.keys(input)
-  const key = sample(keys)
-  const object = input[key]
-
-  object.foo = generate()
-
-  expect(call).toThrow(/foo must be number/)
-})

package/source/aspect.fixtures.js

@@ -1,32 +0,0 @@
-'use strict'
-
-const { generate } = require('randomstring')
-
-const schema = {
-  type: 'object',
-  properties: {
-    foo: {
-      type: 'string',
-      default: generate()
-    },
-    bar: {
-      type: 'object',
-      properties: {
-        baz: {
-          type: 'number',
-          default: 1
-        }
-      }
-    }
-  }
-}
-
-const concise = {
-  foo: schema.properties.foo.default,
-  bar: {
-    baz: schema.properties.bar.properties.baz.default
-  }
-}
-
-exports.schema = schema
-exports.concise = concise

package/source/aspect.js

@@ -1,36 +0,0 @@
-'use strict'
-
-const { Connector } = require('@toa.io/core')
-
-/**
- * @implements {toa.extensions.configuration.Aspect}
- */
-class Aspect extends Connector {
-  /** @readonly */
-  name = 'configuration'
-
-  /** @type {toa.core.Reflection} */
-  #refection
-
-  /**
-   * @param {toa.core.Reflection} reflection
-   */
-  constructor (reflection) {
-    super()
-
-    this.#refection = reflection
-
-    this.depends(reflection)
-  }
-
-  invoke (path) {
-    /** @type {any} */
-    let cursor = this.#refection.value
-
-    if (path !== undefined) for (const segment of path) cursor = cursor[segment]
-
-    return cursor
-  }
-}
-
-exports.Aspect = Aspect

package/source/aspect.test.js

@@ -1,76 +0,0 @@
-'use strict'
-
-const { Locator } = require('@toa.io/core')
-const { encode } = require('@toa.io/generic')
-
-const fixtures = require('./aspect.fixtures')
-const { Factory } = require('../')
-const { generate } = require('randomstring')
-
-const factory = new Factory()
-
-/** @type {toa.extensions.configuration.Aspect} */
-let aspect
-
-/** @type {toa.core.Locator} */
-let locator
-
-describe('defaults', () => {
-  beforeEach(async () => {
-    const namespace = generate()
-    const name = generate()
-
-    locator = new Locator(name, namespace)
-
-    aspect = factory.aspect(locator, fixtures.schema)
-
-    await aspect.connect()
-  })
-
-  it('should return schema defaults', () => {
-    const foo = aspect.invoke(['foo'])
-
-    expect(foo).toStrictEqual(fixtures.schema.properties.foo.default)
-  })
-
-  it('should return nested values', () => {
-    const baz = aspect.invoke(['bar', 'baz'])
-
-    expect(baz).toStrictEqual(fixtures.schema.properties.bar.properties.baz.default)
-  })
-
-  it('should expose configuration tree', () => {
-    const configuration = aspect.invoke()
-
-    expect(configuration).toStrictEqual({
-      foo: fixtures.schema.properties.foo.default,
-      bar: {
-        baz: fixtures.schema.properties.bar.properties.baz.default
-      }
-    })
-  })
-})
-
-describe('resolution', () => {
-  let object
-  let varname
-
-  beforeEach(() => {
-    object = { foo: generate() }
-
-    varname = 'TOA_CONFIGURATION_' + locator.uppercase
-  })
-
-  it('should resolve configuration object from environment variable', async () => {
-    process.env[varname] = encode(object)
-
-    aspect = factory.aspect(locator, fixtures.schema)
-
-    await aspect.connect()
-
-    const configuration = aspect.invoke()
-
-    expect(configuration.foo).toStrictEqual(object.foo)
-    expect(configuration.bar.baz).toStrictEqual(fixtures.schema.properties.bar.properties.baz.default)
-  })
-})

package/source/configuration.js

@@ -1,19 +0,0 @@
-'use strict'
-
-const { Reflection } = require('@toa.io/core')
-
-/**
- * @implements {toa.core.Reflection}
- */
-class Configuration extends Reflection {
-  /**
-   * @param {toa.extensions.configuration.Provider} provider
-   */
-  constructor (provider) {
-    super(provider.source)
-
-    this.depends(provider)
-  }
-}
-
-exports.Configuration = Configuration