@toa.io/pointer 0.2.1-dev.3

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@toa.io/pointer",
+  "version": "0.2.1-dev.3",
+  "description": "Toa Pointer",
+  "homepage": "https://toa.io",
+  "author": {
+    "name": "Artem Gurtovoi",
+    "url": "https://github.com/temich"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "engines": {
+    "node": ">= 12.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "source/index.js",
+  "dependencies": {
+    "@toa.io/console": "*",
+    "@toa.io/generic": "*",
+    "@toa.io/schema": "*",
+    "@toa.io/yaml": "*"
+  }
+}

package/readme.md

@@ -0,0 +1,126 @@
+# Pointer
+
+Library to declare, deploy and resolve URL to connect to at the runtime. Used by connectors.
+
+## Pointer class
+
+Pointer builds URL for a given locator, protocol and a package prefix. Prefix must be unique value
+for a given package conforming [label format](#) (ex.: `bindings-ampq`).
+
+### Constructor signature
+
+<dl>
+<dt><code>prefix</code></dt>
+<dd><code>string</code> unique for each package</dd>
+<dt><code>locator</code></dt>
+<dd><code>toa.core.Locator</code> component for which Pointer is intended</dd>
+<dt><code>options</code></dt>
+<dd><code><a href="./types/pointer.d.ts">toa.pointer.Options</a></code> Pointer options</dd>
+</dl>
+
+### Local Environment
+
+If `TOA_ENV` is `local` then these values are used:
+
+| Property | Value       |
+|----------|-------------|
+| hostname | `localhost` |
+| username | `developer` |
+| password | `secret`    |
+
+> In the local environment there is no way to provide values for `protocol` or `port`.
+
+See [types](types/pointer.d.ts) and [tests](test/pointer.test.js) for details.
+
+## Annotation
+
+Declaration of a set of hosts, matching exact components, namespaces with a default value for
+non-matched ones.
+
+```yaml
+something:
+  default: protocol://host1
+  namespace1: protocol://host2
+  namespace1.component1: protocol://host3
+  namespace2.component2: protocol://host4
+```
+
+See the [schema](source/uris/.construct/schema.yaml).
+
+### Concise Declaration
+
+Next two declarations are equivalent.
+
+```yaml
+something: host1
+```
+
+```yaml
+something:
+  default: host1
+```
+
+### Usage
+
+```javascript
+const { uris } = require('@toa.io/pointer')
+
+const annotation = uris.construct(declaration)
+const url = uris.resolve(annotation, locator)
+```
+
+See [types](types/uris.d.ts) and [tests](test/uris.test.js) for details.
+
+### Custom Extensions
+
+Packages using Pointer Annotation may use or require additional properties.
+See [Deployment Extensions](#extensions) below.
+
+## Deployment
+
+Deployment function builds global[^1] variables: containing Annotation and a set of variables for
+pointer credentials.
+
+See [types](types/deployment.d.ts) and [tests](test/deployment.test.js) for details.
+
+### Credentials
+
+Each entry of the Annotation requires values for `username` and `password`. These values are being
+deployed as global[^1] secret variables. Secret names are following the
+convention: `toa-package-prefix-entry-label` and `key` names match corresponding URL
+properties (`username` and `password`).
+
+> Note that declaration is made of `Locator.id` while secret names contain `Locator.label`.
+> See [Locator](#).
+
+#### Example
+
+```yaml
+# context.toa.yaml
+amqp:
+  default: amqp://host0
+  dummies.dummy: amqps://host1:5671
+```
+
+```shell
+$ toa conceal bindings-amqp-default username admin
+$ toa conceal bindings-amqp-default password ibreakthings
+$ toa conceal bindings-amqp-dummies-dummy username developer
+$ toa conceal bindings-amqp-dummies-dummy password iluvtests
+```
+
+See [`toa conceal`](../../runtime/cli/readme.md#conceal).
+
+### Extensions
+
+For each custom extension additional proxy is being deployed.
+
+#### Example
+
+AMQP binding is a systematic binding used by the runtime. That is a system proxy must be deployed
+and compositions require variables to establish connection through that proxy.
+
+Therefore, AMQP binding declares a `system` extension and deployment function declares additional
+proxy `bindings-amqp-system`.
+
+[^1]: [#174](https://github.com/toa-io/toa/issues/174)

package/source/.deployment/.variables/credentials.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const { concat, letters: { up, down } } = require('@toa.io/generic')
+
+/**
+ * @param {string} prefix
+ * @param {toa.pointer.URIs} uris
+ * @returns {toa.deployment.dependency.Variable[]}
+ */
+const credentials = (prefix, uris) => {
+  const variables = []
+
+  for (const key of Object.keys(uris)) {
+    const [namespace, name] = key.split('.')
+    const entry = namespace + concat('-', name)
+
+    const env = `TOA_${up(prefix)}_${up(entry)}_`
+    const sec = `toa-${down(prefix)}-${down(entry)}`
+
+    for (const property of ['username', 'password']) {
+      const name = env + up(property)
+
+      const secret = {
+        name: sec,
+        key: property
+      }
+
+      variables.push({ name, secret })
+    }
+  }
+
+  return variables
+}
+
+exports.credentials = credentials

package/source/.deployment/.variables/index.js

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

package/source/.deployment/.variables/pointer.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const { encode, letters: { up } } = require('@toa.io/generic')
+
+/**
+ * @param {string} prefix
+ * @param {toa.pointer.URIs} uris
+ * @returns {toa.deployment.dependency.Variable}
+ */
+const pointer = (prefix, uris) => {
+  const name = `TOA_${up(prefix)}_POINTER`
+  const json = JSON.stringify(uris)
+  const value = encode(json)
+
+  return { name, value }
+}
+
+exports.pointer = pointer

package/source/.deployment/index.js

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

package/source/.deployment/validate.js

@@ -0,0 +1,19 @@
+'use strict'
+
+/**
+ * @param {toa.pointer.URIs} uris
+ */
+const validate = (uris) => {
+  Object.values(uris).forEach(check)
+}
+
+/**
+ * @param {string} uri
+ */
+const check = (uri) => {
+  const url = new URL(uri)
+
+  if (url.hostname === '') throw new Error(`URI ${url.href} must contain a hostname`)
+}
+
+exports.validate = validate

package/source/.deployment/variables.js

@@ -0,0 +1,22 @@
+'use strict'
+
+const declare = require('./.variables')
+
+/**
+ * @param {toa.pointer.URIs} uris
+ * @param {string} prefix
+ * @returns {toa.deployment.dependency.Variable[]}
+ */
+const variables = (uris, prefix) => {
+  /** @type {toa.deployment.dependency.Variable[]} */
+  const variables = []
+  const pointer = declare.pointer(prefix, uris)
+  const credentials = declare.credentials(prefix, uris)
+
+  variables.push(pointer)
+  variables.push(...credentials)
+
+  return variables
+}
+
+exports.variables = variables

package/source/.pointer/env.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const { concat, decode, letters: { up, capitalize } } = require('@toa.io/generic')
+const { console } = require('@toa.io/console')
+
+const { resolve } = require('../uris')
+
+/**
+ * @param {string} prefix
+ * @param {toa.core.Locator} locator
+ */
+const env = (prefix, locator) => {
+  const key = `TOA_${up(prefix)}_POINTER`
+  const value = process.env[key]
+
+  if (value === undefined) throw new Error(`Environment variable ${key} is not set`)
+
+  const uris = decode(value)
+  const { url, entry } = resolve(locator, uris)
+
+  const suffix = convert(entry)
+  const env = `TOA_${up(prefix)}_${suffix}`
+
+  for (const property of ['username', 'password']) {
+    const value = process.env[env + '_' + up(property)]
+
+    if (value !== undefined) url[property] = value
+    else console.warn(`${capitalize(property)} for ${env} is not set`)
+  }
+
+  return url
+}
+
+/**
+ * @param {string} entry
+ * @returns {string}
+ */
+const convert = (entry) => {
+  const [namespace, name] = entry.toUpperCase().split('.')
+
+  return namespace + concat('_', name)
+}
+
+exports.env = env

package/source/.pointer/index.js

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

package/source/.pointer/local.js

@@ -0,0 +1,17 @@
+'use strict'
+
+/**
+ * @param {string} protocol
+ * @returns {URL}
+ */
+const local = (protocol) => {
+  const url = new URL(protocol + '//')
+
+  url.hostname = 'localhost'
+  url.username = 'developer'
+  url.password = 'secret'
+
+  return url
+}
+
+exports.local = local

package/source/deployment.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const get = require('./.deployment')
+
+/** @type {toa.pointer.Deployment} */
+const deployment = (instances, uris, options) => {
+  if (typeof uris === 'string') uris = { default: uris }
+
+  get.validate(uris)
+
+  const global = get.variables(uris, options.prefix)
+  const variables = { global }
+
+  return { variables }
+}
+
+exports.deployment = deployment

package/source/index.js

@@ -0,0 +1,11 @@
+'use strict'
+
+const { Pointer } = require('./pointer')
+const { deployment } = require('./deployment')
+const { variable } = require('./variable')
+
+exports.uris = require('./uris')
+
+exports.Pointer = Pointer
+exports.deployment = deployment
+exports.variable = variable

package/source/pointer.js

@@ -0,0 +1,50 @@
+'use strict'
+
+const get = require('./.pointer')
+
+// noinspection JSClosureCompilerSyntax
+/**
+ * @implements {toa.pointer.Pointer}
+ */
+class Pointer {
+  protocol
+  host
+  port
+  hostname
+  path
+  reference
+  label
+
+  /**
+   * @param {string} prefix
+   * @param {toa.core.Locator} locator
+   * @param {toa.pointer.Options} options
+   */
+  constructor (prefix, locator, options) {
+    const local = process.env.TOA_ENV === 'local'
+    const url = local ? get.local(options.protocol) : get.env(prefix, locator)
+
+    this.protocol = url.protocol
+    this.hostname = url.hostname
+    this.port = Number(url.port)
+    this.path = url.pathname
+    this.username = url.username
+    this.password = url.password
+    this.reference = url.href
+    this.label = label(url)
+  }
+}
+
+/**
+ * @param {URL} url
+ * @returns {string}
+ */
+const label = (url) => {
+  const safe = new URL(url.href)
+
+  safe.password = ''
+
+  return safe.href
+}
+
+exports.Pointer = Pointer

package/source/uris/.construct/index.js

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

package/source/uris/.construct/normalize.js

@@ -0,0 +1,17 @@
+'use strict'
+
+/**
+ * @param {toa.pointer.URIs | string} declaration
+ * @returns {toa.pointer.URIs}
+ */
+const normalize = (declaration) => {
+  /** @type {toa.pointer.URIs} */
+  let annotation
+
+  if (typeof declaration === 'string') annotation = { default: declaration }
+  else annotation = declaration
+
+  return annotation
+}
+
+exports.normalize = normalize

package/source/uris/.construct/schema.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2019-09/schema
+$id: https://schemas.toa.io/0.0.0/storages/mongodb/annotations
+
+definitions:
+  node:
+    oneOf:
+      - $ref: '#/definitions/locator'
+      - type: object
+        patternProperties:
+          '.*':
+            $ref: '#/definitions/node'
+  locator:
+    type: string
+    format: uri
+
+type: object
+patternProperties:
+  '.*':
+    $ref: '#/definitions/node'

package/source/uris/.construct/validate.js

@@ -0,0 +1,17 @@
+'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) => {
+  const error = validator.fit(declaration)
+
+  if (error) throw new TypeError(error.message)
+}
+
+exports.validate = validate

package/source/uris/construct.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { normalize, validate } = require('./.construct')
+
+/** @type {toa.pointer.uris.Constructor} */
+const construct = (declaration) => {
+  const normalized = normalize(declaration)
+
+  validate(normalized)
+
+  return normalized
+}
+
+exports.construct = construct

package/source/uris/index.js

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

package/source/uris/resolve.js

@@ -0,0 +1,30 @@
+'use strict'
+
+/** @type {toa.pointer.uris.Resolver} */
+const resolve = (locator, uris) => {
+  let entry
+
+  /** @type {string} */
+  let uri
+
+  const entries = [locator.id, locator.namespace, 'default']
+
+  for (const key of entries) {
+    if (typeof uris[key] === 'string') {
+      uri = uris[key]
+      entry = key
+
+      break
+    }
+  }
+
+  if (uri === undefined) throw new Error(`URI annotation for '${locator.id}' is not found`)
+
+  const url = new URL(uri)
+
+  if (url.hostname === '') throw new Error(`URI annotation for '${locator.id}' must contain hostname`)
+
+  return { url, entry }
+}
+
+exports.resolve = resolve

package/source/variable.js

@@ -0,0 +1,12 @@
+'use strict'
+
+const { letters: { up } } = require('@toa.io/generic')
+
+/** @type {toa.pointer.Variable} */
+const variable = (scope, locator, label, value) => {
+  const name = `TOA_${up(scope)}_${locator.uppercase}_${up(label)}`
+
+  return { name, value }
+}
+
+exports.variable = variable

package/test/deployment.test.js

@@ -0,0 +1,92 @@
+'use strict'
+
+const { encode, letters: { up, down } } = require('@toa.io/generic')
+const mock = require('@toa.io/mock')
+
+const { deployment } = require('../')
+
+const prefix = 'foo-bar'
+
+/** @type {toa.norm.context.dependencies.Instance[]} */
+let instances
+
+/** @type {toa.pointer.deployment.Options} */
+let options
+
+beforeEach(() => {
+  instances = mock.dependencies.instances()
+  options = { prefix }
+})
+
+it('should be', () => {
+  expect(deployment).toBeInstanceOf(Function)
+})
+
+it('should throw if protocol is omitted', () => {
+  const annotation = { default: 'no-protocol' }
+
+  expect(() => deployment(instances, annotation, options)).toThrow('Invalid URL')
+})
+
+it('should throw if hostname is omitted', () => {
+  const annotation = { default: 'amqps:///' }
+
+  expect(() => deployment(instances, annotation, options)).toThrow('must contain a hostname')
+})
+
+it('should consider string annotation as default', () => {
+  const annotation = 'pg://host0'
+
+  const output = deployment(instances, annotation, options)
+
+  const name = `TOA_${up(prefix)}_POINTER`
+  const value = encode({ default: annotation })
+
+  expect(output.variables.global).toStrictEqual(expect.arrayContaining([{ name, value }]))
+})
+
+describe('variables', () => {
+  it('should export POINTER variable', () => {
+    const annotation = { default: 'amqps://host0' }
+    const json = JSON.stringify(annotation)
+    const value = encode(json)
+    const output = deployment(instances, annotation, options)
+
+    expect(output.variables.global).toStrictEqual(expect.arrayContaining([{
+      name: `TOA_${up(prefix)}_POINTER`,
+      value
+    }]))
+  })
+
+  it('should export USERNAME and PASSWORD for each entry of URI Set', () => {
+    const annotation = {
+      default: 'amqps://host0',
+      system: 'amqps://host2',
+      dummies: 'amqps://host3',
+      'dummies.one': 'amqps://host4'
+    }
+
+    const expected = []
+
+    const env = `TOA_${up(prefix)}_`
+    const sec = `toa-${down(prefix)}-`
+
+    for (const key of Object.keys(annotation)) {
+      const label = key.replaceAll('.', '-').toLowerCase()
+
+      for (const property of ['username', 'password']) {
+        expected.push({
+          name: `${env}${up(label)}_${up(property)}`,
+          secret: {
+            name: `${sec}${down(label)}`,
+            key: property
+          }
+        })
+      }
+    }
+
+    const output = deployment(instances, annotation, options)
+
+    expect(output.variables.global).toStrictEqual(expect.arrayContaining(expected))
+  })
+})

package/test/pointer.test.js

@@ -0,0 +1,213 @@
+'use strict'
+
+const mock = { console: { info: jest.fn(), warn: jest.fn() } }
+
+jest.mock('@toa.io/console', () => mock)
+
+const { generate } = require('randomstring')
+const { Locator } = require('@toa.io/core')
+const { encode, letters: { up } } = require('@toa.io/generic')
+
+const { Pointer } = require('../')
+
+it('should be', () => {
+  expect(Pointer).toBeDefined()
+  expect(Pointer).toBeInstanceOf(Function)
+})
+
+const prefix = 'bindings-amqp'
+
+/** @type {toa.core.Locator} */
+let locator
+
+/** @type {toa.pointer.Options} */
+const options = { protocol: 'protocol:' }
+
+/** @type {toa.pointer.Pointer} */
+let pointer
+
+/** @type {URL} */
+let url
+
+const uris = (uris) => (process.env[`TOA_${up(prefix)}_POINTER`] = encode(uris))
+
+beforeEach(() => {
+  jest.clearAllMocks()
+
+  const name = generate()
+  const namespace = generate()
+
+  locator = new Locator(name, namespace)
+
+  url = new URL('amqp://whatever:3000')
+
+  uris({ default: url.href })
+})
+
+it('should throw if env not set', () => {
+  const name = `TOA_${up(prefix)}_POINTER`
+  delete process.env[name]
+
+  expect(() => new Pointer(prefix, locator, options)).toThrow(`Environment variable ${name} is not set`)
+})
+
+it('should use declared protocol', () => {
+  pointer = new Pointer(prefix, locator, options)
+
+  expect(pointer.protocol).toStrictEqual(url.protocol)
+})
+
+it('should point to host', () => {
+  pointer = new Pointer(prefix, locator, options)
+
+  expect(pointer.hostname).toStrictEqual(url.hostname)
+})
+
+it('should resolve credentials', () => {
+  const check = (entry) => {
+    const env = `TOA_${up(prefix)}_${up(entry)}_`
+    const username = generate()
+    const password = generate()
+
+    process.env[env + 'USERNAME'] = username
+    process.env[env + 'PASSWORD'] = password
+
+    pointer = new Pointer(prefix, locator, options)
+
+    delete process.env[env + 'USERNAME']
+    delete process.env[env + 'PASSWORD']
+
+    expect(pointer.username).toStrictEqual(username)
+    expect(pointer.password).toStrictEqual(password)
+  }
+
+  // default resolution
+  check('default')
+
+  // namespace resolution
+  uris({ [locator.namespace]: 'pg://host0/db' })
+  check(locator.namespace)
+
+  // id resolution
+  uris({ [locator.id]: 'pg://host0/db' })
+  check(locator.label)
+})
+
+it('should expose port as number', () => {
+  pointer = new Pointer(prefix, locator, options)
+
+  expect(pointer.port).toStrictEqual(Number(url.port))
+})
+
+it('should expose reference', () => {
+  pointer = new Pointer(prefix, locator, options)
+
+  expect(pointer.reference).toStrictEqual(url.href)
+})
+
+it('should use localhost and given protocol on local environment', () => {
+  process.env.TOA_ENV = 'local'
+
+  pointer = new Pointer(prefix, locator, options)
+
+  delete process.env.TOA_ENV
+
+  expect(pointer.hostname).toStrictEqual('localhost')
+  expect(pointer.protocol).toStrictEqual(options.protocol)
+})
+
+it('should use default protocol and credentials on local environment', () => {
+  process.env.TOA_ENV = 'local'
+
+  pointer = new Pointer(prefix, locator, options)
+
+  delete process.env.TOA_ENV
+
+  expect(pointer.reference).toStrictEqual(`${options.protocol}//developer:secret@localhost`)
+  expect(pointer.label).toStrictEqual(`${options.protocol}//developer@localhost`)
+})
+
+describe('environment variables', () => {
+  const username = generate()
+  const password = generate()
+
+  const env = `TOA_${up(prefix)}_DEFAULT`
+
+  let set
+  let unset
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+
+    set = (name, value, prefix = env) => {
+      const key = prefix + '_' + up(name)
+
+      process.env[key] = value
+      url[name] = value
+    }
+
+    unset = (name, prefix = env) => {
+      const key = prefix + '_' + up(name)
+
+      delete process.env[key]
+      url[name] = ''
+    }
+
+    set('username', username)
+    set('password', password)
+  })
+
+  afterEach(() => {
+    unset('username')
+    unset('password')
+  })
+
+  it('should use env variables for credentials', () => {
+    pointer = new Pointer(prefix, locator, options)
+
+    expect(pointer.reference).toStrictEqual(url.href)
+
+    url.password = ''
+
+    expect(pointer.label).toStrictEqual(url.href)
+  })
+
+  it('should warn if username is not set', () => {
+    url.hostname = locator.hostname(prefix)
+
+    unset('username')
+    url.password = ''
+
+    const pointer = new Pointer(prefix, locator, options)
+
+    expect(pointer).toBeDefined()
+    expect(mock.console.warn).toHaveBeenCalledWith(`Username for ${env} is not set`)
+  })
+
+  it('should warn if password is not set', () => {
+    url.hostname = locator.hostname(prefix)
+
+    unset('password')
+
+    const pointer = new Pointer(prefix, locator, options)
+
+    expect(pointer).toBeDefined()
+    expect(mock.console.warn).toHaveBeenCalledWith(`Password for ${env} is not set`)
+  })
+
+  it('should not warn it credentials are set', () => {
+    uris({ [locator.id]: 'amqp://host0' })
+
+    const username = generate()
+    const password = generate()
+    const env = `TOA_${up(prefix)}_${locator.uppercase}`
+
+    set('username', username, env)
+    set('password', password, env)
+
+    const pointer = new Pointer(prefix, locator, options)
+
+    expect(pointer).toBeDefined()
+    expect(mock.console.warn).not.toHaveBeenCalled()
+  })
+})

package/test/uris.fixtures.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const annotations = {
+  default: 'http://host.docker.internal/',
+  credits: {
+    balance: 'amqp://host.docker.internal'
+  }
+}
+
+exports.annotations = annotations

package/test/uris.test.js

@@ -0,0 +1,140 @@
+'use strict'
+
+const clone = require('clone-deep')
+const { generate } = require('randomstring')
+const { random } = require('@toa.io/generic')
+const { Locator } = require('@toa.io/core')
+
+const fixtures = require('./uris.fixtures')
+const { uris } = require('../')
+
+const gen = () => 'schema://host-' + generate().toLowerCase() + ':' + (random(1000) + 1000)
+
+describe('construct', () => {
+  const construct = uris.construct
+
+  let annotations
+
+  beforeEach(() => {
+    annotations = clone(fixtures.annotations)
+  })
+
+  it('should be', () => {
+    expect(construct).toBeDefined()
+    expect(construct).toBeInstanceOf(Function)
+  })
+
+  describe('normalize', () => {
+    it('should treat string value as default', () => {
+      const declaration = gen()
+      const result = construct(declaration)
+
+      expect(result).toStrictEqual({ default: declaration })
+    })
+
+    it('should allow dot notation', () => {
+      const url = gen()
+
+      annotations['foo.bar'] = url
+
+      construct(annotations)
+
+      expect(annotations['foo.bar']).toStrictEqual(url)
+    })
+
+    it('should allow dot notation with namespace value', () => {
+      annotations.foo = gen()
+      annotations['foo.bar'] = gen()
+
+      expect(() => construct(annotations)).not.toThrow()
+    })
+  })
+
+  describe('validate', () => {
+    it('should throw if declaration is not a string or an object', () => {
+      // noinspection JSCheckFunctionSignatures
+      expect(() => construct(1)).toThrow(TypeError)
+      expect(() => construct(null)).toThrow(TypeError)
+    })
+
+    it('should throw if property is not url', () => {
+      annotations.foo = 'not url'
+
+      expect(() => construct(annotations)).toThrow(TypeError)
+    })
+  })
+})
+
+describe('resolve', () => {
+  const resolve = uris.resolve
+
+  let name
+  let namespace
+  let uri
+
+  /** @type {toa.pointer.URIs} */
+  let annotation
+
+  /** @type {toa.core.Locator} */
+  let locator
+
+  beforeEach(() => {
+    name = generate()
+    namespace = generate()
+    uri = gen()
+
+    annotation = {
+      [namespace + '.' + name]: uri
+    }
+
+    locator = new Locator(name, namespace)
+  })
+
+  it('should be', () => {
+    expect(uris.resolve).toBeDefined()
+    expect(uris.resolve).toBeInstanceOf(Function)
+  })
+
+  it('should resolve by id', () => {
+    const { url } = resolve(locator, annotation)
+
+    expect(url).toBeInstanceOf(URL)
+    expect(url.href).toStrictEqual(uri)
+  })
+
+  it('should throw if not found', () => {
+    const name = generate()
+    const namespace = generate()
+    const locator = new Locator(name, namespace)
+
+    expect(() => resolve(locator, annotation)).toThrow(`URI annotation for '${locator.id}' is not found`)
+  })
+
+  it('should resolve by namespace', () => {
+    annotation[namespace] = uri
+
+    const { url } = resolve(locator, annotation)
+
+    expect(url.href).toStrictEqual(uri)
+  })
+
+  it('should resolve default', () => {
+    annotation = { default: gen() }
+
+    const { url } = resolve(locator, annotation)
+
+    expect(url.href).toStrictEqual(annotation.default)
+  })
+
+  it('should resolve global locators', () => {
+    const name = generate()
+    const locator = new Locator(name)
+    const uri = gen()
+
+    annotation = { [name]: uri }
+
+    const { url } = resolve(locator, annotation)
+
+    expect(url.href).toStrictEqual(uri)
+  })
+})

package/test/variable.test.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { Locator } = require('@toa.io/core')
+const { random, letters: { up } } = require('@toa.io/generic')
+
+const { variable } = require('../')
+
+it('should be', () => {
+  expect(variable).toBeInstanceOf(Function)
+})
+
+it('should create variable', () => {
+  const prefix = 'foo-bar'
+  const namespace = generate()
+  const component = generate()
+  const locator = new Locator(component, namespace)
+  const name = generate()
+
+  let value = generate()
+
+  const string = variable(prefix, locator, name, value)
+
+  const expected = {
+    name: `TOA_${up(prefix)}_${locator.uppercase}_${up(name)}`,
+    value
+  }
+
+  expect(string).toStrictEqual(expected)
+
+  value = random()
+  expected.value = value
+
+  const number = variable(prefix, locator, name, value)
+
+  expect(number).toStrictEqual(expected)
+})

package/types/deployment.d.ts

@@ -0,0 +1,22 @@
+// noinspection ES6UnusedImports
+
+import { dependency } from '@toa.io/operations/types/deployment'
+import { dependencies } from '@toa.io/norm/types'
+import { URIs } from './uris'
+
+declare namespace toa.pointer {
+
+  namespace deployment {
+
+    type Options = {
+      prefix: string
+    }
+
+  }
+
+  type Deployment = (instances: dependencies.Instance[], uris: URIs, options: deployment.Options)
+    => dependency.Declaration
+
+}
+
+export const deployment: toa.pointer.Deployment

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export type { Pointer } from './pointer'
+
+export { deployment } from './deployment'
+export { variable } from './variable'
+
+export * as uris from './uris'

package/types/pointer.d.ts

@@ -0,0 +1,21 @@
+declare namespace toa.pointer {
+
+  type Options = {
+    protocol: string    // for local environment
+  }
+
+  class Pointer {
+    protocol: string
+    host: string
+    port: number
+    hostname: string
+    path: string
+    username: string
+    password: string
+    reference: string
+    label: string     // safe for logging
+  }
+
+}
+
+export type Pointer = toa.pointer.Pointer

package/types/uris.d.ts

@@ -0,0 +1,32 @@
+import { Locator } from '@toa.io/core/types'
+
+declare namespace toa.pointer {
+
+  namespace uris {
+
+    type Node = {
+      [key: string]: string | Node
+    }
+
+    type Constructor = (declaration: URIs | string) => URIs
+
+    type Resolution = {
+      url: URL
+      entry: string
+    }
+
+    type Resolver = (locator: Locator, uris: URIs) => Resolution
+
+  }
+
+  type URIs = {
+    default?: string
+    [key: string]: string | uris.Node
+  } | string
+
+}
+
+export type URIs = toa.pointer.URIs
+
+export const construct: toa.pointer.uris.Constructor
+export const resolve: toa.pointer.uris.Resolver

package/types/variable.d.ts

@@ -0,0 +1,8 @@
+import { Locator } from '@toa.io/core/types'
+import { dependency } from '@toa.io/operations/types/deployment'
+
+declare namespace toa.pointer {
+  type Variable = (scope: string, locator: Locator, label: string, value: string | number) => dependency.Variable
+}
+
+export const variable: toa.pointer.Variable