@toa.io/extensions.configuration 0.2.1-dev.3

package/docs/consistency.md

@@ -0,0 +1,69 @@
+# Configuration Consistency
+
+![Not Implemented](https://img.shields.io/badge/Not_Implemented-red)
+
+## Problem Definition
+
+At arbitrary moments when the configuration has changed, some distributed operations have started
+but haven't yet
+finished. This leads to operations that start with certain configuration values but will finish with
+another, which may
+result in logical problems.
+
+Given that distributed operations may have arbitrary participants and last for an arbitrary period,
+there is no such
+single moment when configuration can be safely changed. Thus, it must be a process.
+
+## ~~Not a~~ Solution
+
+1. Configuration is a single versioned object.
+2. Configuration version value is included in the Uniform Communication Interface.
+3. The first distributed operation participant (which is the one who has received a UCI without the
+   configuration
+   version value) must include in the outgoing UCI the configuration version value that it considers
+   as current.
+4. Non-first distributed operations participants (which is those who has received a UCI with the
+   configuration version
+   value) must use the configuration version specified in the UCI.
+5. Non-first distributed operation participants must include in the outgoing UCI the same
+   configuration version value as
+   they received in the incoming.
+
+## Restrictions
+
+1. Configuration updates are always backward compatible.
+2. Configuration updates are always being delivered before algorithm updates.
+    1. Including federated deployment, that is: first deliver configuration to all facilities (data
+       centers, zones,
+       whatever), then deliver algorithm updates.
+3. Configuration storage and access solution must provide the transactional updates, that is if any
+   arbitrary
+   participant observed a certain configuration version, then any other participant is guaranteed to
+   be able to
+   subsequently observe that version.
+    1. Including federated deployment[^1].
+
+## Solution
+
+The configuration compatibility problem described above is a particular case of a common
+compatibility problem for
+distributed operation participants. It is not the only configuration that may change while a
+distributed operation is
+running, but participant algorithms themselves. This leads to the conclusion that this particular
+solution must be
+propagated to algorithm versions, that is: which system (as a set of algorithms and configuration)
+version was used to
+start the operation, and that system version must be used to finish the operation.
+
+This kind of solution results in the need to run all versions of the system with appropriate message
+routing. The
+implementation complexity of this solution and its operations costs are considered unreasonable.
+However, an attempt
+will be made to implement this solution with a certain
+constraints [#147](https://github.com/toa-io/toa/issues/147).
+
+[^1]: Since it looks like there is no reasonable way to provide this kind of guarantee without
+significant performance
+and/or availability impact, it may be implemented as a mechanism with read retries and with a
+timeout considered as
+“enough for the most of fail-over scenarios”.

package/docs/discussion.md

@@ -0,0 +1,109 @@
+# 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/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@toa.io/extensions.configuration",
+  "version": "0.2.1-dev.3",
+  "description": "Toa Configuration",
+  "author": "temich <tema.gurtovoy@gmail.com>",
+  "homepage": "https://github.com/toa-io/toa#readme",
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@toa.io/core": "*",
+    "@toa.io/generic": "*",
+    "@toa.io/schema": "*",
+    "@toa.io/yaml": "*",
+    "clone-deep": "4.0.1"
+  }
+}

package/readme.md

@@ -0,0 +1,231 @@
+# Toa Configuration Extension
+
+## TL;DR
+
+### Define
+
+```yaml
+# component.toa.yaml
+name: dummy
+namespace: dummies
+
+configuration:
+  foo: bar
+  baz: 1
+```
+
+### Use
+
+```javascript
+function transition (input, entity, context) {
+  const { foo, baz } = context.configuration
+
+  // ...
+}
+```
+
+### Override
+
+```yaml
+# context.toa.yaml
+configuration:
+  dummies.dummy:
+    foo: qux
+    foo@staging: quux # use deployment environment discriminator
+    baz: $BAZ_VALUE   # use secrets
+```
+
+### Deploy secrets
+
+```shell
+$ toa conceal
+```
+
+---
+
+## Problem Definition
+
+- Components must be reusable in different contexts and deployment environments,
+  that is in different configurations.
+- Some algorithm parameters must be deployed secretly.
+
+## Definitions
+
+### Configuration (Distributed System Configuration)
+
+Set of static[^1] parameters for all algorithms within a given system.
+
+### Configuration Schema
+
+Schema defining component's algorithms parameters (optionally with default
+values).
+
+### Configuration Object
+
+Value valid against Configuration Schema.
+
+### Configuration Value
+
+Merge result of Configuration Schema's defaults and Configuration Object.
+
+### Context Configuration
+
+Map of Configuration Objects for components added to a given context.
+
+## Responsibility Segregation
+
+Configuration Schema is a *form* of configuration defined by component. Specific *values* for
+specific contexts and deployment environments are defined by Context Configuration according to the
+Schema.
+
+See [Reusable Components](#).
+
+## Configuration Schema
+
+Configuration Schema is declared as a component extension
+using [JSON Schema](https://json-schema.org) `object` type.
+
+> ![Warning](https://img.shields.io/badge/Warning-yellow)<br/>
+> By introducing non-backward compatible changes to a Configuration Schema the compatibility
+> with existent contexts and deployment environments will be broken. That is, Configuration
+> Schema changes are subjects of component versioning.
+
+> ![Recommendation](https://img.shields.io/badge/Recommendation-green)<br/>
+> Having default values for all required parameters will allow components to be runnable
+> without configuration (i.e. on local environment).
+
+### Example
+
+```yaml
+# component.toa.yaml
+name: dummy
+namespace: dummies
+
+extensions:
+  @toa.io/extensions.configuration:
+     properties:
+       foo:
+         type: string
+         default: 'baz'
+       bar:
+         type: number
+     required: [foo]
+```
+
+### Concise Declaration
+
+As it is known that Configuration Schema is declared with a JSON Schema `object` type, any
+configuration declaration without defined `properties` considered as concise. Properties of concise
+declaration are treated as required Configuration Schema properties with the same type as its value
+type and no additional properties allowed.
+
+Also note that a well-known shortcut `configuration` is available.
+
+Next two declarations are equivalent.
+
+```yaml
+# component.toa.yaml
+configuration:
+  foo: baz
+  bar: 1
+```
+
+```yaml
+# component.toa.yaml
+extensions:
+  @toa.io/extensions.configuration:
+     properties:
+       foo:
+         type: string
+         default: baz
+       bar:
+         type: number
+         default: 1
+     additionalProperties: false
+     required: [foo, bar]
+```
+
+## Context Configuration
+
+Context Configuration is declared as a context annotaion. Its keys must be
+component identifiers and its values must be Configuration Objects for those
+components.
+
+Context Configuration keys and Configuration Object keys may be defined
+with [deployment environment discriminators](#).
+
+### Example
+
+```yaml
+# context.toa.yaml
+configuration:
+  dummies.dummy:
+    foo: quu
+    bar: 1
+    bar@staging: 2
+```
+
+### Local environment
+
+Configuration Objects for local environment may be created
+by [`toa configure`](../../runtime/cli/readme.md#configure) command.
+
+## Configuration Secrets
+
+Context Configuration values which are uppercase strings prefixed with `$`
+considered as Secrets.
+
+### Example
+
+```yaml
+# context.toa.yaml
+configuration:
+  payments.gateway:
+    api-key: $STRIPE_API_KEY
+```
+
+### Secrets Deployment
+
+Secrets are not being deployed with context
+deployment ([`toa deploy`](../../runtime/cli/readme.md#deploy)),
+thus must be deployed separately at least once for each deployment environment
+manually ([`toa conceal`](../../runtime/cli/readme.md#conceal)).
+
+## Operation Context
+
+Configuration Value is available as a well-known operation context extension `configuration`.
+
+### Usage: node
+
+```javascript
+function transition (input, entity, context) {
+  const foo = context.configiuration.foo
+
+  // ...
+}
+```
+
+> ![Warning](https://img.shields.io/badge/Warning-yellow)<br/>
+> It is strongly **not** recommended to store a copy of value type configuration
+> values outside of operation scope, thus it prevents operation to benefit
+> from [hot updates](#).
+>
+> ```javascript
+> // THIS IS WEIRD, BAD AND NOT RECOMMENDED
+> let foo
+> 
+> function transition (input, entity, context) {
+>   if (foo === undefined) foo = context.configuration.foo
+> 
+>   // ...
+> }
+> ```
+> See [Genuine operations](#).
+
+## Appendix
+
+- [Discussion](./docs/discussion.md)
+- [Configuration consistency](./docs/consistency.md)
+
+[^1]: Cannot be changed without a deployment. New values are considered to be a subject of
+testing. [#146](https://github.com/toa-io/toa/issues/146)

package/src/.manifest/.normalize/verbose.js

@@ -0,0 +1,48 @@
+'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

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

package/src/.manifest/normalize.js

@@ -0,0 +1,16 @@
+'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

@@ -0,0 +1,8 @@
+$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

@@ -0,0 +1,13 @@
+'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

@@ -0,0 +1,20 @@
+'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

@@ -0,0 +1,36 @@
+'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

@@ -0,0 +1,36 @@
+'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

@@ -0,0 +1,19 @@
+'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

@@ -0,0 +1,23 @@
+'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

@@ -0,0 +1,39 @@
+'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

@@ -0,0 +1,13 @@
+'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

@@ -0,0 +1,13 @@
+'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

@@ -0,0 +1,114 @@
+'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 connection () {
+    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

@@ -0,0 +1,38 @@
+'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

@@ -0,0 +1,43 @@
+'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

@@ -0,0 +1,33 @@
+'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

package/test/aspect.test.js

@@ -0,0 +1,77 @@
+'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
+      },
+      quu: 0
+    })
+  })
+})
+
+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/test/deployment.fixtures.js

@@ -0,0 +1,38 @@
+'use strict'
+
+const { generate } = require('randomstring')
+
+const { Locator } = require('@toa.io/core')
+const { random } = require('@toa.io/generic')
+
+const component = () => {
+  const namespace = generate()
+  const name = generate()
+
+  return { locator: new Locator(name, namespace) }
+}
+
+/** @type {toa.norm.context.dependencies.Instance[]} */
+const components = []
+const annotations = {}
+
+const annotate = (component) => {
+  const key = component.locator.id
+
+  annotations[key] = { [generate()]: generate() }
+}
+
+for (let i = 0; i < random(10) + 5; i++) components.push(component())
+for (let i = 0; i < components.length; i++) if (i % 2 === 0) annotate(components[i])
+
+/**
+ * @param {string} id
+ * @returns {toa.norm.context.dependencies.Instance}
+ */
+const find = (id) => {
+  return components.find((component) => component.locator.id === id)
+}
+
+exports.components = components
+exports.annotations = annotations
+exports.find = find

package/test/deployment.test.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const { encode } = require('@toa.io/generic')
+
+const fixtures = require('./deployment.fixtures')
+const { deployment } = require('../')
+
+/** @type {toa.deployment.dependency.Declaration} */
+let declaration
+
+beforeAll(() => {
+  declaration = deployment(fixtures.components, fixtures.annotations)
+})
+
+it('should exist', () => {
+  expect(deployment).toBeDefined()
+})
+
+it('should declare variables', () => {
+  expect(declaration.variables).toBeDefined()
+})
+
+it('should map configurations', () => {
+  const keys = Object.keys(fixtures.annotations)
+
+  expect(keys.length).toBeGreaterThan(0)
+
+  for (const [id, annotations] of Object.entries(fixtures.annotations)) {
+    const component = fixtures.find(id)
+    const variables = declaration.variables[component.locator.label]
+    const encoded = encode(annotations)
+
+    expect(component).toBeDefined()
+    expect(variables).toBeDefined()
+    expect(variables).toBeInstanceOf(Array)
+    expect(variables.length).toStrictEqual(1)
+
+    const env = variables[0]
+
+    expect(env.name).toBeDefined()
+    expect(env.name).toStrictEqual('TOA_CONFIGURATION_' + component.locator.uppercase)
+    expect(env.value).toBeDefined()
+    expect(env.value).toStrictEqual(encoded)
+  }
+})

package/test/factory.test.js

@@ -0,0 +1,22 @@
+'use strict'
+
+const { Factory } = require('../')
+
+it('should export', () => {
+  expect(Factory).toBeInstanceOf(Function)
+})
+
+/** @type {toa.extensions.configuration.Factory} */
+let factory
+
+beforeAll(async () => {
+  factory = new Factory()
+})
+
+it('should expose context', () => {
+  expect(factory.aspect).toBeInstanceOf(Function)
+})
+
+it('should expose provider', () => {
+  expect(factory.provider).toBeInstanceOf(Function)
+})

package/test/manifest.test.js

@@ -0,0 +1,132 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { random } = require('@toa.io/generic')
+
+const { manifest } = require('../')
+
+it('should export', () => {
+  expect(manifest).toBeInstanceOf(Function)
+})
+
+describe('validation', () => {
+  it('should throw if not an object', () => {
+    const call = () => manifest(generate())
+    expect(call).toThrow(/must be object/)
+  })
+
+  it('should throw if not a valid schema', () => {
+    const object = { type: generate() }
+    const call = () => manifest(object)
+
+    expect(call).toThrow(/one of the allowed values/)
+  })
+
+  it('should throw if schema is not an object type', () => {
+    const schema = { type: 'number' }
+    const call = () => manifest(schema)
+
+    expect(call).toThrow(/equal to constant 'object'/)
+  })
+})
+
+describe('normalization', () => {
+  it('should expand concise', () => {
+    const concise = {
+      foo: generate(),
+      bar: {
+        baz: random()
+      }
+    }
+
+    const declaration = manifest(concise)
+
+    expect(declaration).toMatchObject({
+      type: 'object',
+      properties: {
+        foo: {
+          type: 'string',
+          default: concise.foo
+        },
+        bar: {
+          type: 'object',
+          properties: {
+            baz: {
+              type: 'number',
+              default: concise.bar.baz
+            }
+          }
+        }
+      }
+    })
+  })
+
+  it('should expand partially concise', () => {
+    const concise = {
+      foo: generate(),
+      bar: {
+        baz: random()
+      },
+      qux: {
+        type: 'string',
+        default: null
+      }
+    }
+
+    const declaration = manifest(concise)
+
+    expect(declaration).toMatchObject({
+      type: 'object',
+      properties: {
+        foo: {
+          type: 'string',
+          default: concise.foo
+        },
+        bar: {
+          type: 'object',
+          properties: {
+            baz: {
+              type: 'number',
+              default: concise.bar.baz
+            }
+          }
+        },
+        qux: {
+          type: 'string',
+          default: null
+        }
+      }
+    })
+  })
+
+  it('should expand arrays', () => {
+    const concise = { foo: [1, 2, 3] }
+
+    const declaration = manifest(concise)
+
+    expect(declaration).toMatchObject({
+      type: 'object',
+      properties: {
+        foo: {
+          type: 'array',
+          items: {
+            type: 'number'
+          },
+          default: [1, 2, 3]
+        }
+      }
+    })
+  })
+
+  it('should throw on empty array', () => {
+    const concise = { foo: [] }
+
+    expect(() => manifest(concise)).toThrow(/array items type because it's empty/)
+  })
+
+  it('should throw on null', () => {
+    const concise = { foo: null }
+
+    expect(() => manifest(concise)).toThrow(/type of null/)
+  })
+})

package/types/aspect.ts

@@ -0,0 +1,11 @@
+// noinspection ES6UnusedImports
+
+import * as core from '@toa.io/core/types/extensions'
+
+declare namespace toa.extensions.configuration {
+
+  interface Aspect extends core.Aspect {
+    invoke(path?: string[]): any
+  }
+
+}

package/types/factory.d.ts

@@ -0,0 +1,12 @@
+import { Component } from '@toa.io/norm/types'
+
+import * as _extensions from '@toa.io/core/types/extensions'
+import * as _provider from './provider'
+
+declare namespace toa.extensions.configuration {
+
+  interface Factory extends _extensions.Factory {
+    provider(component: Component): _provider.Provider
+  }
+
+}

package/types/provider.d.ts

@@ -0,0 +1,22 @@
+import { Source } from '@toa.io/core/types/reflection'
+import { Connector } from '@toa.io/core/types'
+
+declare namespace toa.extensions.configuration {
+
+    interface Provider extends Connector {
+        source: Source
+        object: Object
+        key: string
+
+        set(key: string, value: any): void
+
+        unset(key: string): void
+
+        reset(): void
+
+        export(): string
+    }
+
+}
+
+export type Provider = toa.extensions.configuration.Provider