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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@toa.io/extensions.exposition",
+  "version": "0.2.1-dev.3",
+  "description": "Toa Resources Exposition",
+  "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"
+  },
+  "scripts": {
+    "test": "echo \"Error: run tests from root\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/express": "4.17.13"
+  },
+  "dependencies": {
+    "@toa.io/bindings.amqp": "*",
+    "@toa.io/console": "*",
+    "@toa.io/core": "*",
+    "@toa.io/generic": "*",
+    "@toa.io/schema": "*",
+    "@toa.io/yaml": "*",
+    "cors": "2.8.5",
+    "express": "4.18.1",
+    "path-to-regexp": "6.2.0"
+  },
+  "gitHead": "2be07592325b2e4dc823e81d882a4e50bf50de24"
+}

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,58 @@
+'use strict'
+
+/**
+ * @returns {toa.extensions.exposition.declarations.Node}
+ */
+const normalize = (node, manifest) => {
+  if (node instanceof Array) node = { operations: node }
+
+  node.operations = operations(node.operations, manifest)
+  node.query = query(node.query)
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key.substring(0, 1) === '/') node[key] = normalize(value, manifest)
+  }
+
+  return node
+}
+
+/**
+ * @returns {toa.extensions.exposition.declarations.Operation[] | undefined}
+ */
+const operations = (operations, manifest) => {
+  if (operations === undefined) return
+
+  return operations.map((operation) => {
+    if (typeof operation === 'object') operation = operation.operation
+
+    if (manifest.operations[operation] === undefined) {
+      throw new Error(`Resource references undefined operation '${operation}'`)
+    }
+
+    const { type, scope, query } = manifest.operations[operation]
+    const normal = { operation, type, scope }
+
+    if (query !== undefined) normal.query = query
+
+    return normal
+  })
+}
+
+/**
+ * @returns {toa.extensions.exposition.declarations.Query | undefined}
+ */
+const query = (query) => {
+  if (query === undefined) return
+
+  if (query.omit !== undefined && typeof query.omit !== 'object') {
+    query.omit = { value: query.omit, range: [] }
+  }
+
+  if (query.limit !== undefined && typeof query.limit !== 'object') {
+    query.limit = { value: query.limit, range: [] }
+  }
+
+  return query
+}
+
+exports.normalize = normalize

package/src/.manifest/schema.yaml

@@ -0,0 +1,69 @@
+$schema: https://json-schema.org/draft/2019-09/schema
+$id: https://schemas.toa.io/0.0.0/rtd
+
+definitions:
+  resource:
+    patternProperties:
+      ^(\/([^\/#\?]+)?)+\/?$:
+        $ref: "#/definitions/resource"
+    properties:
+      query:
+        type: object
+        properties:
+          criteria:
+            nullable: true
+            type: string
+            minLength: 1
+          sort:
+            type: array
+            uniqueItems: true
+            minItems: 1
+            items:
+              type: string
+          projection:
+            type: array
+            uniqueItems: true
+            minItems: 1
+            items:
+              type: string
+          omit:
+            $ref: "#/definitions/range"
+          limit:
+            $ref: "#/definitions/range"
+        additionalProperties: false
+      operations:
+        type: array
+        uniqueItems: true
+        minItems: 1
+        items:
+          type: object
+          properties:
+            operation:
+              $ref: definitions#/definitions/token
+            type:
+              enum: [transition, observation, assignment]
+            scope:
+              type: string
+              enum: [object, objects, changeset, none]
+            query:
+              type: boolean
+          additionalProperties: false
+    additionalProperties: false
+  range:
+    type: object
+    properties:
+      value:
+        type: integer
+        minimum: 0
+      range:
+        type: array
+        uniqueItems: true
+        minItems: 0
+        items:
+          $ref: "#/definitions/range/properties/value"
+      additionalProperties: false
+    required: [range]
+
+$ref: "#/definitions/resource"
+not:
+  required: [operations] # root doesn't have path

package/src/.manifest/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 Error(error.message)
+}
+
+exports.validate = validate

package/src/constants.js

@@ -0,0 +1,3 @@
+'use strict'
+
+exports.PORT = 8000

package/src/deployment.js

@@ -0,0 +1,23 @@
+'use strict'
+
+const { PORT } = require('./constants')
+
+/**
+ * @param {toa.norm.context.dependencies.Instance[]} components
+ * @param {toa.extensions.exposition.Annotations} annotations
+ * @type {toa.deployment.dependency.Constructor}
+ */
+const deployment = (components, annotations) => {
+  const group = 'exposition'
+  const name = 'resources'
+  const version = require('../package.json').version
+  const port = PORT
+  const ingress = annotations
+
+  /** @type {toa.deployment.dependency.Service} */
+  const exposition = { group, name, version, port, ingress }
+
+  return { services: [exposition] }
+}
+
+exports.deployment = deployment

package/src/exposition.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+const { console } = require('@toa.io/console')
+
+class Exposition extends Connector {
+  /** @type {toa.core.bindings.Broadcaster} */
+  #broadcast
+
+  /** @type {toa.extensions.exposition.remotes.Factory} */
+  #remote
+
+  /** @type {toa.extensions.exposition.exposition.Remotes} */
+  #remotes = {}
+
+  /**
+   * @param {toa.core.bindings.Broadcaster} broadcast
+   * @param {toa.extensions.exposition.remotes.Factory} connect
+   */
+  constructor (broadcast, connect) {
+    super()
+
+    this.#broadcast = broadcast
+    this.#remote = connect
+
+    this.depends(broadcast)
+  }
+
+  /** @override */
+  async connection () {
+    await this.#broadcast.receive('expose', this.#expose.bind(this))
+    this.#broadcast.send('ping', {}).then()
+
+    console.info(this.constructor.name + ' started')
+  }
+
+  /**
+   * @param {toa.extensions.exposition.declarations.Exposition} declaration
+   * @returns {Promise<void>}
+   */
+  async #expose (declaration) {
+    const { namespace, name, resources } = declaration
+    const key = namespace + '/' + name
+
+    if (this.#remotes[key] === undefined) this.#remotes[key] = this.#connect(namespace, name)
+
+    const remote = await this.#remotes[key]
+
+    remote.update(resources)
+  }
+
+  /**
+   * @param {string} namespace
+   * @param {string} name
+   * @returns {Promise<Remote>}
+   */
+  async #connect (namespace, name) {
+    const remote = await this.#remote(namespace, name)
+
+    await remote.connect()
+
+    this.depends(remote)
+
+    return remote
+  }
+}
+
+exports.Exposition = Exposition

package/src/factory.js

@@ -0,0 +1,76 @@
+'use strict'
+
+const { Locator } = require('@toa.io/core')
+const { remap } = require('@toa.io/generic')
+
+const { Tenant } = require('./tenant')
+const { Exposition } = require('./exposition')
+const { Server } = require('./server')
+const { Remote } = require('./remote')
+const { Tree } = require('./tree')
+const { Query, constraints } = require('./query')
+
+/**
+ * @implements {toa.core.extensions.Factory}
+ */
+class Factory {
+  #boot
+
+  /** @type {toa.extensions.exposition.Server} */
+  #server
+
+  constructor (boot) {
+    this.#boot = boot
+    this.#server = new Server()
+  }
+
+  tenant (locator, declaration) {
+    const broadcast = this.#boot.bindings.broadcast(BINDING, GROUP, locator.id)
+
+    return new Tenant(broadcast, locator, declaration)
+  }
+
+  service (name) {
+    if (name === undefined || name === 'default' || name === 'resources') return this.#expose()
+  }
+
+  #expose () {
+    const broadcast = this.#boot.bindings.broadcast(BINDING, GROUP)
+    const connect = this.#connect.bind(this)
+    const exposition = new Exposition(broadcast, connect)
+
+    exposition.depends(this.#server)
+
+    return exposition
+  }
+
+  /**
+   * @param {string} namespace
+   * @param {string} name
+   * @returns {Promise<toa.extensions.exposition.Remote>}
+   */
+  async #connect (namespace, name) {
+    const locator = new Locator(name, namespace)
+    const remote = await this.#boot.remote(locator)
+    const query = this.#query.bind(this)
+    const tree = new Tree(query)
+
+    return new Remote(this.#server, remote, tree)
+  }
+
+  /**
+   * @param {toa.extensions.exposition.declarations.Node | any} node
+   * @returns {toa.extensions.exposition.Query}
+   */
+  #query (node) {
+    const query = Query.merge(node)
+    const properties = remap(query, (value, key) => new constraints[key](value))
+
+    return new Query(properties)
+  }
+}
+
+const BINDING = '@toa.io/bindings.amqp'
+const GROUP = 'exposition'
+
+exports.Factory = Factory

package/src/index.js

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

package/src/manifest.js

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

package/src/query/criteria.js

@@ -0,0 +1,55 @@
+'use strict'
+
+const { exceptions: { RequestConflictException } } = require('@toa.io/core')
+
+class Criteria {
+  #value
+  #open
+  #logic
+  #right
+
+  constructor (value) {
+    if (value === null) return
+
+    const last = value.slice(-1)
+
+    if (last === ',' || last === ';') {
+      this.#open = true
+      this.#right = true
+      this.#logic = last
+
+      value = value.substring(0, value.length - 1)
+    } else {
+      const first = value.substring(0, 1)
+
+      this.#open = first === ',' || first === ';'
+
+      if (this.#open === true) {
+        this.#right = false
+        this.#logic = first
+
+        value = value.substring(1)
+      }
+    }
+
+    this.#value = value
+  }
+
+  /** @hot */
+  parse (value, operation) {
+    if (operation.query === false) return value
+
+    if (value !== undefined) {
+      if (this.#open === true) {
+        if (this.#right) value = this.#value + this.#logic + value
+        else value = value + this.#logic + this.#value
+      } else {
+        throw new RequestConflictException('Query criteria is defined as closed')
+      }
+    } else value = this.#value
+
+    return value
+  }
+}
+
+exports.Criteria = Criteria

package/src/query/enum.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const { exceptions: { RequestConflictException } } = require('@toa.io/core')
+
+class Enum {
+  #value
+  #keys
+
+  constructor (value) {
+    this.#value = value
+
+    this.#keys = value.reduce((acc, key) => {
+      acc[key] = true
+      return acc
+    }, {})
+  }
+
+  /** @hot */
+  parse (value, operation) {
+    if (operation.type !== 'observation') return value
+
+    if (value === undefined) return this.#value
+    else if (value instanceof Array) {
+      const key = value.find((key) => !(key in this.#keys))
+
+      if (key !== undefined) {
+        throw new RequestConflictException(`Query projection must not contain '${key}'`)
+      }
+    }
+
+    return value
+  }
+}
+
+exports.Enum = Enum

package/src/query/index.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const { Query } = require('./query')
+const { Range } = require('./range')
+const { Criteria } = require('./criteria')
+const { Enum } = require('./enum')
+const { Sort } = require('./sort')
+
+exports.Query = Query
+
+exports.constraints = {
+  criteria: Criteria,
+  sort: Sort,
+  omit: Range,
+  limit: Range,
+  projection: Enum
+}

package/src/query/query.js

@@ -0,0 +1,60 @@
+'use strict'
+
+const { merge } = require('@toa.io/generic')
+
+/**
+ * @implements {toa.extensions.exposition.Query}
+ */
+class Query {
+  #constraints
+
+  constructor (constraints) {
+    this.#constraints = Object.entries(constraints)
+  }
+
+  /** @hot */
+  parse (query, operation) {
+    for (const [key, constraint] of this.#constraints) {
+      const value = constraint.parse(query?.[key], operation)
+
+      if (value !== undefined) {
+        if (query === undefined) query = {}
+
+        query[key] = value
+      }
+    }
+
+    return query
+  }
+
+  /**
+   * @param {toa.extensions.exposition.declarations.Node} node
+   * @returns {toa.extensions.exposition.declarations.Query}
+   */
+  static merge (node) {
+    const query = {}
+    let current = node
+
+    do {
+      if (current.query !== undefined) merge(query, current.query, { ignore: true })
+
+      current = current.parent
+    } while (current !== undefined)
+
+    merge(query, DEFAULTS, { ignore: true })
+
+    return query
+  }
+}
+
+const DEFAULTS = {
+  omit: {
+    range: [0, 1000]
+  },
+  limit: {
+    value: 100,
+    range: [1, 100]
+  }
+}
+
+exports.Query = Query

package/src/query/range.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const { exceptions: { RequestConflictException } } = require('@toa.io/core')
+
+class Range {
+  #value
+  #min
+  #max
+
+  constructor (constraint) {
+    this.#value = constraint.value
+
+    this.#min = constraint.range[0] === undefined ? this.#value : constraint.range[0]
+    this.#max = constraint.range[1] === undefined ? this.#value : constraint.range[1]
+  }
+
+  /** @hot */
+  parse (value, operation) {
+    if (operation.type !== 'observation' || operation.scope !== 'objects') return value
+    if (value === undefined) return this.#value
+
+    if (value > this.#max || value < this.#min) {
+      throw new RequestConflictException(`Query omit/limit value is out of range [${this.#min}, ${this.#max}]`)
+    }
+  }
+}
+
+exports.Range = Range

package/src/query/sort.js

@@ -0,0 +1,19 @@
+'use strict'
+
+class Sort {
+  #value
+
+  constructor (value) {
+    this.#value = value
+  }
+
+  /** @hot */
+  parse (value, operation) {
+    if (operation.query === false) return value
+
+    if (value === undefined) return this.#value
+    else return this.#value.concat(value)
+  }
+}
+
+exports.Sort = Sort

package/src/remote.js

@@ -0,0 +1,88 @@
+'use strict'
+
+const { Connector, exceptions: { NotImplementedException } } = require('@toa.io/core')
+const { console } = require('@toa.io/console')
+
+const translate = require('./translate')
+
+/**
+ * @implements {toa.extensions.exposition.Remote}
+ */
+class Remote extends Connector {
+  /** @type {toa.core.Runtime} */
+  #remote
+
+  /** @type {toa.extensions.exposition.Tree} */
+  #tree
+
+  /**
+   * @param {toa.extensions.exposition.Server} server
+   * @param {toa.core.Runtime} remote
+   * @param {toa.extensions.exposition.Tree} tree
+   */
+  constructor (server, remote, tree) {
+    super()
+
+    const { namespace, name } = remote.locator
+    const route = '/' + (namespace === name ? namespace : namespace + '/' + name) + '*'
+
+    server.route(route, (req, res) => this.#reply(req, res))
+
+    this.#remote = remote
+    this.#tree = tree
+
+    this.depends(server)
+    this.depends(remote)
+  }
+
+  update (declaration) {
+    console.info(`Updating tree '${this.#remote.locator.id}'`)
+
+    this.#tree.update(declaration)
+  }
+
+  /**
+   * @hot
+   * @param {toa.extensions.exposition.http.Request} req
+   * @param {toa.extensions.exposition.http.Response} res
+   * @return {Promise<void>}
+   */
+  async #reply (req, res) {
+    const match = this.#tree.match(req.params[0])
+
+    if (match !== undefined) {
+      try {
+        const reply = await this.#call(req, match)
+
+        translate.response.ok(reply, res, req)
+      } catch (e) {
+        translate.response.exception(e, res)
+      }
+    } else {
+      translate.response.missed(res)
+    }
+
+    res.end()
+  }
+
+  /**
+   * @param {toa.extensions.exposition.http.Request} req
+   * @param {toa.extensions.exposition.tree.Match} match
+   * @return {Promise<toa.core.Reply>}
+   */
+  async #call (req, match) {
+    const method = req.method === 'HEAD' ? 'GET' : req.method
+    const operation = match.node.operations[method]
+
+    if (operation === undefined) throw new NotImplementedException()
+
+    const request = translate.request(req, match.params)
+    const query = match.node.query.parse(request.query, operation)
+
+    if (query !== undefined) request.query = query
+
+    return this.#remote.invoke(operation.operation, request)
+  }
+}
+
+exports.Remote = Remote