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

package/src/server.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const express = require('express')
+const cors = require('cors')
+
+const { Connector } = require('@toa.io/core')
+const { console } = require('@toa.io/console')
+
+const { PORT } = require('./constants')
+
+// noinspection JSClosureCompilerSyntax
+/**
+ * @implements {toa.extensions.exposition.Server}
+ */
+class Server extends Connector {
+  /** @type {import('express').Application} */
+  #app
+  /** @type {import('http').Server} */
+  #server
+
+  constructor () {
+    super()
+
+    // TODO: remove express
+    this.#app = express()
+    this.#app.disable('x-powered-by')
+    this.#app.enable('case sensitive routing')
+    this.#app.enable('strict routing')
+    this.#app.disable('etag')
+    this.#app.use(express.json())
+    this.#app.use(cors({ allowedHeaders: ['content-type'] }))
+
+    this.#app.use((req, res, next) => {
+      req.safe = req.method in SAFE
+
+      if (req.method in METHODS) next()
+      else res.status(501).end()
+    })
+  }
+
+  route (route, callback) {
+    this.#app.use(route, callback)
+  }
+
+  async connection () {
+    console.info(`Starting HTTP server at :${PORT} ...`)
+
+    return new Promise((resolve, reject) => {
+      const error = () => reject(new Error(`Error starting HTTP server at :${PORT}`))
+      // noinspection JSCheckFunctionSignatures
+      this.#server = this.#app.listen(PORT, () => {
+        console.info(`HTTP server at :${PORT} started`)
+
+        this.#server.off('error', error)
+        resolve()
+      })
+
+      this.#server.on('error', error)
+    })
+  }
+
+  async disconnection () {
+    console.info(`Stopping HTTP server at :${PORT} ...`)
+
+    return new Promise((resolve, reject) => {
+      const error = () => reject(new Error(`Error stopping HTTP server at :${PORT}`))
+
+      this.#server.close(() => {
+        console.info(`HTTP server at :${PORT} stopped`)
+
+        this.#server.off('error', error)
+        resolve()
+      })
+
+      this.#server.on('error', error)
+    })
+  }
+}
+
+const METHODS = { HEAD: 1, GET: 1, POST: 1, PUT: 1, PATCH: 1 }
+const SAFE = { HEAD: 1, GET: 1 }
+
+exports.Server = Server

package/src/tenant.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+class Tenant extends Connector {
+  #binding
+  #declaration
+
+  constructor (binding, { namespace, name }, resources) {
+    super()
+
+    this.#binding = binding
+    this.#declaration = { namespace, name, resources }
+
+    this.depends(binding)
+  }
+
+  async connection () {
+    await this.#binding.receive('ping', () => this.#expose())
+    await this.#expose()
+  }
+
+  async #expose () {
+    await this.#binding.send('expose', this.#declaration)
+  }
+}
+
+exports.Tenant = Tenant

package/src/translate/etag.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const get = (header) => {
+  const match = header.match(rx)
+  return match === null ? null : match[1]
+}
+
+const set = (value) => '"' + value + '"'
+
+const rx = /^"([^"]+)"$/
+
+exports.get = get
+exports.set = set
+exports.rx = rx

package/src/translate/index.js

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

package/src/translate/request.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const { exceptions: { RequestSyntaxException, RequestConflictException } } = require('@toa.io/core')
+const { empty } = require('@toa.io/generic')
+
+const etag = require('./etag')
+
+/**
+ * @hot
+ *
+ * @param {import('express').Request} req
+ * @param {{[key: string]: string}} params
+ * @returns {toa.core.Request}
+ */
+const request = (req, params) => {
+  const request = {}
+
+  if (!empty(req.body)) request.input = req.body
+
+  if (!empty(req.query)) {
+    request.query = req.query
+
+    if (request.query.projection !== undefined) request.query.projection = request.query.projection.split(',')
+    if (request.query.sort !== undefined) request.query.sort = request.query.sort.split(',')
+  }
+
+  if (!empty(params)) {
+    if (req.method === 'POST') {
+      if (request.input === undefined) request.input = {}
+
+      for (const [key, value] of Object.entries(params)) {
+        if (request.input[key] === undefined) request.input[key] = value
+        else throw new RequestConflictException(`Input property '${key}' conflicts with path parameter`)
+      }
+    } else {
+      const criteria = []
+
+      if (request.query === undefined) request.query = {}
+
+      for (const [key, value] of Object.entries(params)) {
+        if (key === 'id') request.query.id = value
+        else criteria.push(key + '==' + value)
+      }
+
+      if (criteria.length > 0) {
+        const value = criteria.join(';')
+
+        if (request.query.criteria === undefined) request.query.criteria = value
+        else request.query.criteria = value + ';' + request.query.criteria
+      }
+    }
+  }
+
+  const condition = req.get('if-match')
+
+  if (condition !== undefined && condition !== '*') {
+    const value = etag.get(condition)
+
+    if (value === null) throw new RequestSyntaxException('ETag value must match ' + etag.rx)
+    if (request.query === undefined) request.query = {}
+
+    request.query.version = +value
+  }
+
+  return request
+}
+
+exports.request = request

package/src/translate/response.js

@@ -0,0 +1,62 @@
+'use strict'
+
+const { exceptions: { codes } } = require('@toa.io/core')
+
+const etag = require('./etag')
+
+/**
+ * @param {toa.core.Reply} reply
+ * @param res
+ * @param req
+ * @hot
+ */
+const ok = (reply, res, req) => {
+  if (reply.output?._version !== undefined) {
+    const { _version, ...output } = reply.output
+    const condition = req.get('if-none-match')
+
+    if (condition !== undefined && req.safe) {
+      const value = etag.get(condition)
+
+      if (value === _version) {
+        res.status(304).end()
+        return
+      }
+    }
+
+    res.set('etag', etag.set(_version))
+    reply.output = output
+  }
+
+  let status
+
+  if (req.method === 'POST') status = 201
+  else if (reply.output !== undefined || reply.error !== undefined) status = 200
+  else status = 204
+
+  res.status(status)
+  if (status !== 204) res.send(reply)
+}
+
+const missed = (response) => response.status(404)
+
+const exception = (exception, response) => {
+  const status = STATUSES[exception.code] || 500
+
+  response.status(status)
+  response.send(exception)
+}
+
+const STATUSES = {
+  [codes.RequestContract]: 400,
+  [codes.RequestSyntax]: 400,
+  [codes.QuerySyntax]: 400,
+  [codes.RequestConflict]: 403,
+  [codes.StateNotFound]: 404,
+  [codes.NotImplemented]: 405,
+  [codes.StatePrecondition]: 412
+}
+
+exports.ok = ok
+exports.missed = missed
+exports.exception = exception

package/src/tree.js

@@ -0,0 +1,107 @@
+'use strict'
+
+const path = require('path')
+const { match } = require('path-to-regexp')
+
+const { console } = require('@toa.io/console')
+
+/**
+ * @implements {toa.extensions.exposition.Tree}
+ */
+class Tree {
+  /** @type {toa.extensions.exposition.tree.Node[]} */
+  #nodes
+
+  /** @type {toa.extensions.exposition.query.Factory} */
+  #query
+
+  /**
+   * @param {toa.extensions.exposition.query.Factory} query
+   */
+  constructor (query) {
+    this.#query = query
+  }
+
+  /** @hot */
+  match (path) {
+    // dev only check
+    if (process.env.TOA_ENV === 'local') {
+      const nodes = this.#nodes.filter((node) => node.match(path) !== false)
+
+      if (nodes.length > 1) {
+        const routes = nodes.map((node) => node.route)
+
+        throw new Error('Ambiguous routes ' + routes.join(', '))
+      }
+    }
+
+    let match
+
+    const node = this.#nodes.find((node) => {
+      match = node.match(path)
+      return match !== false
+    })
+
+    return node === undefined ? undefined : { node, params: match.params }
+  }
+
+  update (tree) {
+    this.#nodes = []
+    this.#traverse(tree)
+  }
+
+  /**
+   * @param {toa.extensions.exposition.declarations.Node | any} node
+   * @param {string} route
+   * @param {toa.extensions.exposition.declarations.Node} parent
+   */
+  #traverse (node, route = undefined, parent = undefined) {
+    const current = {}
+
+    if (route === undefined) route = '/'
+    else route = trail(route)
+
+    if (parent !== undefined) node.parent = parent
+
+    if (node.operations) {
+      current.route = route
+      current.match = match(route)
+      current.query = this.#query(node)
+      current.operations = {}
+
+      for (const operation of node.operations) current.operations[method(operation)] = operation
+
+      this.#nodes.push(current)
+    }
+
+    let branches = 0
+
+    for (const [key, value] of Object.entries(node)) {
+      if (key[0] === '/') {
+        branches++
+
+        const branch = path.posix.resolve(route, '.' + key)
+
+        this.#traverse(value, branch, node)
+      }
+    }
+
+    if (branches === 0 && node.operations === undefined) {
+      console.warn(`Resource tree leaf '${route}' has no operations`)
+    }
+  }
+}
+
+const trail = (path) => path[path.length - 1] === '/' ? path : path + '/'
+
+const method = (operation) => {
+  if (operation.type === 'transition') {
+    if (operation.query === false) return 'POST'
+    else return 'PUT'
+  }
+
+  if (operation.type === 'observation') return 'GET'
+  if (operation.type === 'assignment') return 'PATCH'
+}
+
+exports.Tree = Tree

package/test/manifest.normalize.fixtures.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const manifest = {
+  operations: {
+    one: {
+      type: 'transition',
+      scope: 'object',
+      query: false
+    },
+    two: {
+      type: 'observation',
+      scope: 'objects'
+    },
+    three: {
+      type: 'observation',
+      scope: 'objects'
+    }
+  }
+}
+
+const resources = {
+  '/': ['one', 'two'],
+  '/top': {
+    operations: ['one'],
+    '/nested': {
+      operations: ['two'],
+      '/deeper': {
+        operations: [{
+          operation: 'three'
+        }]
+      }
+    }
+  }
+}
+
+exports.manifest = manifest
+exports.resources = resources

package/test/manifest.normalize.test.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const clone = require('clone-deep')
+
+const { normalize } = require('../src/.manifest')
+const fixtures = require('./manifest.normalize.fixtures')
+
+describe('normalize', () => {
+  let manifest, resources
+
+  const map = (operation) => ({
+    ...fixtures.manifest.operations[operation],
+    operation
+  })
+
+  beforeEach(() => {
+    manifest = clone(fixtures.manifest)
+    resources = clone(fixtures.resources)
+  })
+
+  it('should expand array', () => {
+    normalize(resources, manifest)
+
+    expect(resources['/'].operations)
+      .toStrictEqual(fixtures.resources['/'].map(map))
+  })
+
+  it('should expand operations', () => {
+    normalize(resources, manifest)
+
+    expect(resources['/top'].operations)
+      .toStrictEqual(fixtures.resources['/top'].operations.map(map))
+
+    expect(resources['/top']['/nested'].operations)
+      .toStrictEqual(fixtures.resources['/top']['/nested'].operations.map(map))
+  })
+})

package/test/manifest.validate.test.js

@@ -0,0 +1,25 @@
+'use strict'
+
+const { validate } = require('../src/.manifest')
+
+it('should validate', () => {
+  const resources = {
+    '/path/to': {
+      operations: [
+        {
+          operation: 'foo',
+          type: 'observation'
+        }
+      ],
+      '/deeper/': {
+        operations: [{
+          operation: 'bar',
+          type: 'transition',
+          query: false
+        }]
+      }
+    }
+  }
+
+  expect(() => validate(resources)).not.toThrow()
+})

package/test/query.range.test.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const { Range } = require('../src/query/range')
+
+let range
+
+const operation = { type: 'observation', scope: 'objects' }
+
+describe('exact', () => {
+  beforeAll(() => {
+    range = new Range({ value: 10, range: [] })
+  })
+
+  it('should throw on value mismatch', () => {
+    expect(() => range.parse(10, operation)).not.toThrow()
+    expect(() => range.parse(11, operation)).toThrow(/out of range/)
+  })
+})

package/test/tree.fixtures.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const declaration = {
+  '/': {
+    operations: ['find'],
+    '/:id': {
+      operations: ['observe'],
+      '/segment': {
+        operations: ['delete']
+      }
+    },
+    '/segment/:param': {
+      operations: ['transit']
+    }
+  },
+  '/sibling': {
+    operations: ['update']
+  }
+}
+
+exports.declaration = declaration

package/test/tree.test.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const { Tree } = require('../src/tree')
+const fixtures = require('./tree.fixtures')
+
+let tree
+
+beforeEach(() => {
+  tree = new Tree(() => null)
+  tree.update(fixtures.declaration)
+})
+
+it('should find node', () => {
+  expect(tree.match('/12/')).toBeDefined()
+  expect(tree.match('/12/segment/')).toBeDefined()
+})
+
+it('should return undefined on mismatch', () => {
+  expect(tree.match('/12')).not.toBeDefined()
+  expect(tree.match('/non/existent/')).not.toBeDefined()
+})
+
+it('should throw on resource conflicts on local dev env', () => {
+  const declaration = {
+    '/:id': {
+      operations: ['observe']
+    },
+    '/ok': {
+      operations: ['transit']
+    }
+  }
+
+  const env = process.env.TOA_ENV
+
+  process.env.TOA_ENV = 'local'
+
+  tree = new Tree(() => null)
+
+  tree.update(declaration)
+
+  expect(() => tree.match('/ok/')).toThrow(/Ambiguous routes/)
+
+  process.env.TOA_ENV = env
+})

package/types/annotations.d.ts

@@ -0,0 +1,10 @@
+declare namespace toa.extensions.exposition {
+
+    interface Annotations {
+        host: string
+        class: string
+        annotations: Record<string, string>
+    }
+
+
+}

package/types/declarations.d.ts

@@ -0,0 +1,31 @@
+declare namespace toa.extensions.exposition.declarations {
+
+  interface Operation {
+    operation: string
+    type: 'transition' | 'observation' | 'assignment'
+    scope: 'object' | 'objects' | 'changeset'
+    query?: boolean
+  }
+
+  interface Query {
+    criteria?: string
+    sort?: string[]
+    projection?: string[]
+  }
+
+  type Node = {
+    query?: Query
+    operations?: Operation[]
+  } & {
+    [key: string]: Node
+  }
+
+  interface Exposition {
+    namespace: string
+    name: string
+    resources: Node
+  }
+}
+
+export type Node = toa.extensions.exposition.declarations.Node
+export type Operation = toa.extensions.exposition.declarations.Operation

package/types/exposition.d.ts

@@ -0,0 +1,13 @@
+// noinspection ES6UnusedImports
+
+import type { Remote } from './remote'
+
+declare namespace toa.extensions.exposition {
+
+    namespace exposition {
+
+        type Remotes = Record<string, Promise<Remote>>
+
+    }
+
+}

package/types/http.d.ts

@@ -0,0 +1,13 @@
+import type * as express from 'express'
+
+declare namespace toa.extensions.exposition.http {
+    type Method = 'GET' | 'POST' | 'PUT' | 'PATCH'
+
+    interface Request extends express.Request {
+    }
+
+    interface Response extends express.Response {
+    }
+}
+
+export type Method = toa.extensions.exposition.http.Method

package/types/query.d.ts

@@ -0,0 +1,16 @@
+import type { Query as RequestQuery } from '@toa.io/core/types/request'
+import type { Node, Operation } from './declarations'
+
+declare namespace toa.extensions.exposition {
+
+    namespace query {
+        type Factory = (node: Node) => Query
+    }
+
+    interface Query {
+        parse(query: RequestQuery, operation: Operation): RequestQuery
+    }
+
+}
+
+export type Query = toa.extensions.exposition.Query

package/types/remote.d.ts

@@ -0,0 +1,19 @@
+// noinspection ES6UnusedImports
+
+import type * as declarations from './declarations'
+
+declare namespace toa.extensions.exposition {
+
+    namespace remotes {
+
+        type Factory = (namespace: string, name: string) => Promise<Remote>
+
+    }
+
+    interface Remote {
+        update(declaration: declarations.Node): void
+    }
+
+}
+
+export type Remote = toa.extensions.exposition.Remote

package/types/server.d.ts

@@ -0,0 +1,13 @@
+import type { Request, Response } from 'express'
+
+declare namespace toa.extensions.exposition {
+
+    namespace server {
+        type Callback = (req: Request, res: Response) => void
+    }
+
+    interface Server {
+        route(route: string, callback: server.Callback)
+    }
+
+}