@toa.io/extensions.configuration 0.7.3 → 0.20.0-alpha.0

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/src/.manifest/.normalize/verbose.js

@@ -1,48 +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) throw new Error('Configuration: cannot resolve type of null, use JSONSchema declaration.')
-
-  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]
-
-  return {
-    type: 'array',
-    items: { type },
-    default: array
-  }
-}
-
-const SYM = Symbol()
-
-exports.verbose = verbose

package/src/.manifest/index.js

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

package/src/.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/src/.manifest/schema.yaml

@@ -1,8 +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'
-properties:
-  type:
-    const: object
-    default: object

package/src/.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/src/.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.properties !== undefined) return { ...node.properties }
-    if (node.default !== undefined) return node.default
-
-    return null
-  }
-
-  return traverse(schema, defaults)
-}
-
-exports.form = form

package/src/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/src/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/src/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

package/src/deployment.js

@@ -1,23 +0,0 @@
-'use strict'
-
-const { encode } = require('@toa.io/generic')
-
-/**
- * @type {toa.deployment.dependency.Constructor}
- */
-const deployment = (components, annotations) => {
-  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.deployment = deployment

package/src/factory.js

@@ -1,39 +0,0 @@
-'use strict'
-
-const { Schema } = require('@toa.io/schema')
-const { Aspect } = require('./aspect')
-const { Configuration } = require('./configuration')
-const { Provider } = require('./provider')
-
-/**
- * @implements {toa.extensions.configuration.Factory}
- */
-class Factory {
-  /**
-   * @param {toa.core.Locator} locator
-   * @param {toa.schema.JSON | Object} declaration
-   * @return {toa.extensions.configuration.Aspect}
-   */
-  aspect (locator, declaration) {
-    const schema = new Schema(declaration)
-    const provider = new Provider(locator, schema)
-    const configuration = new Configuration(provider)
-
-    return new Aspect(configuration)
-  }
-
-  provider (component) {
-    const locator = component.locator
-    const declaration = component.extensions?.[ID]
-
-    if (declaration === undefined) throw new Error(`Configuration extension not found in '${locator.id}'`)
-
-    const schema = new Schema(declaration)
-
-    return new Provider(locator, schema)
-  }
-}
-
-const ID = require('../package.json').name
-
-exports.Factory = Factory

package/src/index.js

@@ -1,13 +0,0 @@
-'use strict'
-
-const { manifest } = require('./manifest')
-const { annotation } = require('./annotation')
-const { deployment } = require('./deployment')
-
-const { Factory } = require('./factory')
-
-exports.manifest = manifest
-exports.annotation = annotation
-exports.deployment = deployment
-
-exports.Factory = Factory

package/src/manifest.js

@@ -1,13 +0,0 @@
-'use strict'
-
-const { normalize, validate } = require('./.manifest')
-
-const manifest = (manifest) => {
-  const declaration = normalize(manifest)
-
-  validate(declaration)
-
-  return declaration
-}
-
-exports.manifest = manifest

package/src/provider.js

@@ -1,114 +0,0 @@
-'use strict'
-
-const clone = require('clone-deep')
-const { decode, encode, empty, overwrite } = require('@toa.io/generic')
-
-const { Connector } = require('@toa.io/core')
-const { form } = require('./.provider/form')
-
-/**
- * @implements {toa.extensions.configuration.Provider}
- */
-class Provider extends Connector {
-  /** @type {toa.schema.Schema} */
-  #schema
-
-  /** @type {Object} */
-  #form
-  /** @type {Object} */
-  #value
-
-  source
-  object
-  key
-
-  /**
-   * @param {toa.core.Locator} locator
-   * @param {toa.schema.Schema} schema
-   */
-  constructor (locator, schema) {
-    super()
-
-    this.source = this.#source.bind(this)
-
-    this.key = PREFIX + locator.uppercase
-    this.#schema = schema
-
-    // form is required to enable nested defaults
-    this.#form = form(schema.schema)
-  }
-
-  async open () {
-    await this.#retrieve()
-  }
-
-  async #source () {
-    return this.#value
-  }
-
-  set (key, value) {
-    const object = this.object === undefined ? {} : clone(this.object)
-    const properties = key.split('.')
-    const property = properties.pop()
-
-    let cursor = object
-
-    for (const name of properties) {
-      if (cursor[name] === undefined) cursor[name] = {}
-
-      cursor = cursor[name]
-    }
-
-    if (value === undefined) delete cursor[property]
-    else cursor[property] = value
-
-    this.#set(object)
-  }
-
-  unset (key) {
-    this.set(key, undefined)
-  }
-
-  reset () {
-    this.object = undefined
-  }
-
-  export () {
-    return this.object === undefined ? undefined : encode(this.object)
-  }
-
-  async #retrieve () {
-    const string = process.env[this.key]
-    const object = string === undefined ? {} : decode(string)
-
-    this.#set(object)
-  }
-
-  #set (object) {
-    this.#validate(object)
-    this.#merge(object)
-
-    this.object = empty(object) ? undefined : object
-  }
-
-  #validate (object) {
-    const error = this.#schema.match(object)
-
-    if (error !== null) throw new TypeError(error.message)
-  }
-
-  #merge (object) {
-    object = clone(object)
-
-    const form = clone(this.#form)
-    const value = overwrite(form, object)
-
-    this.#schema.validate(value)
-
-    this.#value = value
-  }
-}
-
-const PREFIX = 'TOA_CONFIGURATION_'
-
-exports.Provider = Provider

package/test/annotations.fixtures.js

@@ -1,38 +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 = {
-    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/test/annotations.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('./annotations.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/test/aspect.fixtures.js

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