@toa.io/norm 1.0.0-alpha.27 → 1.0.0-alpha.272

package/src/.component/schema.yaml

@@ -8,7 +8,7 @@ definitions:
   binding:
     type: string
     not:
-      const: '@toa.io/bindings.loop' # loop is for system use only
+      const: "@toa.io/bindings.loop" # loop is for system use only
 
 type: object
 properties:
@@ -17,19 +17,19 @@ properties:
     nullable: true
     properties:
       prototype:
-        $ref: '#/properties/prototype'
+        $ref: "#/properties/prototype"
       path:
         type: string
       operations:
         type: object
         propertyNames:
-          $ref: '#/definitions/name'
+          $ref: "#/definitions/name"
         patternProperties:
-          '.*':
+          ".*":
             type: object
             properties:
               bridge:
-                $ref: '#/properties/bridge'
+                $ref: "#/properties/bridge"
 
   path:
     type: string
@@ -38,19 +38,23 @@ properties:
     type: object
     properties:
       id:
-        $ref: 'definitions#/definitions/locator'
+        type: string
+        pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(\.([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))$
       label:
-        $ref: 'definitions#/definitions/label'
+        type: string
+        pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(-([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))*$
 
   name:
-    $ref: 'definitions#/definitions/token'
+    type: string
+    pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
 
   namespace:
-    $ref: 'definitions#/definitions/token'
-    default: 'default'
+    type: string
+    pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
+    default: "default"
     not:
       oneOf:
-        - const: 'system'
+        - const: "system"
 
   version:
     type: string
@@ -60,15 +64,17 @@ properties:
     properties:
       image:
         type: string
+      run:
+        type: string
 
   entity:
     type: object
     properties:
       storage:
         type: string
-        default: '@toa.io/storages.mongodb'
+        default: "@toa.io/storages.mongodb"
       schema:
-        $ref: 'definitions#/definitions/schema'
+        $ref: https://json-schema.org/draft/2019-09/schema
         type: object
         properties:
           type:
@@ -78,24 +84,24 @@ properties:
             type: object
             propertyNames:
               oneOf:
-                - $ref: '#/definitions/name'
+                - $ref: "#/definitions/name"
                 - enum: [_version, _created, _updated, _deleted]
       unique:
         type: object
         patternProperties:
-          '.*':
+          ".*":
             type: array
             items:
               type: string
       index:
         type: object
         patternProperties:
-          '.*':
+          ".*":
             type: object
             patternProperties:
-              '.*':
+              ".*":
                 type: string
-                enum: [asc, desc, hash]
+                enum: [asc, desc, hash, text]
       associated:
         type: boolean
         default: false
@@ -109,7 +115,7 @@ properties:
     type: array
     uniqueItems: true
     items:
-      $ref: '#/definitions/binding'
+      $ref: "#/definitions/binding"
 
   bridge:
     type: string
@@ -117,27 +123,40 @@ properties:
   operations:
     type: object
     propertyNames:
-      $ref: '#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           type:
-            enum: [transition, observation, assignment, computation, effect]
+            enum:
+              [
+                transition,
+                observation,
+                assignment,
+                computation,
+                effect,
+                unmanaged,
+              ]
           scope:
-            enum: [object, objects, changeset, none]
+            enum: [object, objects, changeset, stream, none]
           concurrency:
             enum: [none, retry]
           forward:
-            $ref: '#/definitions/name'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           bindings:
-            $ref: '#/properties/bindings'
+            $ref: "#/properties/bindings"
           input:
-            $ref: 'definitions#/definitions/schema'
+            $ref: https://json-schema.org/draft/2019-09/schema
           output:
-            $ref: 'definitions#/definitions/schema'
+            $ref: https://json-schema.org/draft/2019-09/schema
+            default: {}
+          errors:
+            type: array
+            items:
+              type: string
           query:
             type: boolean
         required: [type, scope, bindings]
@@ -149,8 +168,8 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object]
-              if: # transition query: false
+                  enum: [object, objects]
+              if: # not query: false
                 not:
                   properties:
                     query:
@@ -158,6 +177,17 @@ properties:
                   required: [query]
               then:
                 required: [concurrency]
+          - if: # transition and scope=objects
+              properties:
+                type:
+                  const: transition
+                scope:
+                  const: objects
+            then:
+              properties:
+                query:
+                  not:
+                    const: false
           - if: # not transition
               not:
                 properties:
@@ -174,7 +204,7 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object, objects, none]
+                  enum: [object, objects, stream, none]
                 query:
                   not:
                     const: false
@@ -189,7 +219,7 @@ properties:
           - if: # computation
               properties:
                 type:
-                  const: computation
+                  enum: [computation, unmanaged]
             then:
               properties:
                 scope:
@@ -205,20 +235,17 @@ properties:
             then:
               properties:
                 scope:
-                  const: none
                   default: none
-                query:
-                  const: false
-                  default: false
+                  enum: [object, objects, stream, none]
         additionalProperties: false
     additionalProperties: false
 
   events:
     type: object
     propertyNames:
-      $ref: 'definitions#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           bridge:
@@ -226,7 +253,7 @@ properties:
           path:
             type: string
           binding:
-            $ref: '#/definitions/binding'
+            $ref: "#/definitions/binding"
           conditioned:
             type: boolean
             default: false
@@ -239,17 +266,17 @@ properties:
   receivers:
     type: object
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           operation:
-            $ref: 'definitions#/definitions/name'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           binding:
             type: string
           source:
-            $ref: 'definitions#/definitions/name'
+            $ref: "#/definitions/name"
             not:
               const: context
           path:
@@ -260,9 +287,22 @@ properties:
           adaptive:
             type: boolean
             default: false
+          arguments:
+            type: array
         required: [operation]
         additionalProperties: false
 
+  guards:
+    type: object
+    patternProperties:
+      ".*":
+        type: object
+        properties:
+          bridge: { type: string }
+          path: { type: string }
+        required: [bridge, path]
+        additionalProperties: false
+
   extensions:
     type: object
 

package/src/.component/validate.js

@@ -3,15 +3,15 @@
 const path = require('node:path')
 
 const { load } = require('@toa.io/yaml')
-const { Schema } = require('@toa.io/schema')
+const schemas = require('@toa.io/schemas')
 
 const object = load.sync(path.resolve(__dirname, 'schema.yaml'))
-const schema = new Schema(object)
+const schema = schemas.schema(object)
 
 const validate = (manifest) => {
   const error = schema.fit(manifest)
 
-  if (error) throw new Error(error.message)
+  if (error) throw error
 
   if (manifest.events !== undefined) events(manifest)
   if (manifest.receivers !== undefined) receivers(manifest)
@@ -32,11 +32,11 @@ const receivers = (manifest) => {
     }
 
     if (!TYPES.has(manifest.operations[receiver.operation].type)) {
-      throw new Error(`Receiver '${locator}' must refer to an operation of one of the allowed types: ${Array.from(TYPES).join(', ')}`)
+      throw new Error(`Receiver '${locator}' must refer to an operation of the allowed types: ${Array.from(TYPES).join(', ')}`)
     }
   }
 }
 
-const TYPES = new Set(['transition', 'effect'])
+const TYPES = new Set(['transition', 'assignment', 'effect', 'unmanaged'])
 
 exports.validate = validate

package/src/.context/.dependencies/extensions.js

@@ -3,7 +3,7 @@
 const extensions = async (context) => {
   const extensions = {}
   const components = context.components?.slice() ?? []
-  const extracted = await extractExtensionComponents(components, extensions)
+  const extracted = await extractExtensionComponents(components, extensions, context.annotations)
 
   components.push(...extracted)
 
@@ -20,8 +20,9 @@ const extensions = async (context) => {
   return { extensions, components: extracted }
 }
 
-async function extractExtensionComponents (components, extensions) {
+async function extractExtensionComponents (components, extensions, annotations) {
   const { component: load } = require('../../component')
+  const { load: loadDependency } = require('./load')
 
   const extracted = []
 
@@ -33,11 +34,14 @@ async function extractExtensionComponents (components, extensions) {
 
       extensions[reference] = []
 
-      const mod = require(reference)
+      const { metadata, module: mod } = loadDependency(reference)
 
       if (mod.components === undefined) continue
 
-      for (const path of mod.components().paths) {
+      // the annotation decides whether an extension contributes components at all
+      const annotation = annotations?.[metadata?.name ?? reference]
+
+      for (const path of mod.components(annotation).paths) {
         const component = await load(path)
 
         extracted.push(component)
@@ -48,7 +52,7 @@ async function extractExtensionComponents (components, extensions) {
   if (extracted.length === 0)
     return extracted
 
-  const deeper = await extractExtensionComponents(extracted, extensions)
+  const deeper = await extractExtensionComponents(extracted, extensions, annotations)
 
   return extracted.concat(deeper)
 }

package/src/.context/.dependencies/resolve.js

@@ -24,7 +24,28 @@ const resolve = (references, annotations) => {
     }
   }
 
+  for (const dependency of Object.keys(annotations)) {
+    if (dependency in dependencies) continue
+
+    // an annotation may be keyed by a dependency id rather than by a module reference
+    const module = optional(dependency)
+
+    if (module?.standalone === true) dependencies[dependency] = []
+  }
+
   return dependencies
 }
 
+/**
+ * @param {string} reference
+ * @returns {object | null}
+ */
+function optional (reference) {
+  try {
+    return load(reference).module
+  } catch {
+    return null
+  }
+}
+
 exports.resolve = resolve

package/src/.context/schema.yaml

@@ -6,12 +6,10 @@ properties:
   version:
     type: string
   name:
-    $ref: 'definitions#/definitions/label'
-  description:
     type: string
-  packages:
+    pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(-([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))*$
+  description:
     type: string
-    default: components/*
   build:
     type: object
     properties:
@@ -46,7 +44,7 @@ properties:
           - linux/amd64
           - linux/arm/v7
           - linux/arm64
-    required: [base, platforms]
+    # required: [base]
   compositions:
     type: array
     minItems: 1
@@ -54,16 +52,126 @@ properties:
       type: object
       properties:
         name:
-          $ref: 'definitions#/definitions/token'
+          type: string
+          pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
         image:
           type: string
         components:
           type: array
           minItems: 1
           items:
-            $ref: 'definitions#/definitions/locator'
+            type: string
+            pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(\.([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))$
+        resources:
+          $ref: '#/definitions/resources'
       required: [name, components]
+  atomicity:
+    description: >
+      Where the replicas of a component decide together: who owns what, what they have spent
+      between them, and which of them holds a name while it works. Absent or unreachable,
+      nothing is owned and whoever asked stands down; metering and locking are refused.
+    type: object
+    additionalProperties: false
+    properties:
+      redis:
+        description: >
+          One address, or an odd number of them — independent servers, not the nodes of a
+          cluster. A lock is taken on a quorum of them; the registry and the meter use the
+          first, because each of them counts on a single key.
+        oneOf:
+          - type: string
+          - type: array
+            minItems: 1
+            items:
+              type: string
+      interval:
+        description: >
+          How often a replica registers, in milliseconds. It has to comfortably exceed a round
+          trip to Redis and the jitter around it, and nothing is owned until two consecutive
+          intervals have agreed — so this is also how long a replica owns nothing after it
+          joins, restarts or stalls.
+        type: integer
+        minimum: 100
+    required: [redis]
+  outbox:
+    type: object
+    additionalProperties: false
+    properties:
+      interval:
+        description: >
+          The pump's cycle, in milliseconds. One cycle reads what is unpublished, publishes it
+          and marks it. In steady state it reads nothing, so this is budgeted for how fast a rare
+          failure heals rather than for how fast events flow.
+        type: integer
+        minimum: 100
+      batch:
+        description: >
+          How many rows one read brings back. A page that comes back full is read on from,
+          so this bounds a read rather than a cycle.
+        type: integer
+        minimum: 1
+      retention:
+        description: >
+          Seconds a published row is kept as a change log before it expires. A row that never
+          made it out has no expiry and is never reaped.
+        type: integer
+        minimum: 0
+  events:
+    description: >
+      Events of this context that are consumed outside it. An event is otherwise published only
+      where something in the context receives it.
+    type: array
+    items:
+      type: string
+      pattern: ^[a-zA-Z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9]*$
+  mono:
+    type: object
+    additionalProperties: false
+    properties:
+      replicas:
+        type: integer
+        minimum: 1
+      resources:
+        $ref: '#/definitions/resources'
+  ingress:
+    type: object
+    additionalProperties: false
+    properties:
+      hosts:
+        type: array
+        minItems: 1
+        items:
+          type: string
+      class:
+        type: string
+      annotations:
+        type: object
+      default:
+        type: boolean
   annotations:
     type: object
+  resources:
+    $ref: '#/definitions/resources'
 required: [runtime, name, registry]
 additionalProperties: false
+
+definitions:
+  # What a deployment may take. `null` deploys it without any, which is a decision
+  # rather than an omission — every deployment has to make one.
+  resources:
+    type: object
+    nullable: true
+    additionalProperties: false
+    properties:
+      cpu:
+        type: array
+        items:
+          type: string
+        minItems: 2
+        maxItems: 2
+      memory:
+        type: array
+        items:
+          type: string
+        minItems: 2
+        maxItems: 2

package/src/.context/validate.js

@@ -3,15 +3,12 @@
 const { resolve } = require('node:path')
 
 const { load } = require('@toa.io/yaml')
-const { Schema } = require('@toa.io/schema')
+const schemas = require('@toa.io/schemas')
 
 const path = resolve(__dirname, 'schema.yaml')
 const object = load.sync(path)
-const schema = new Schema(object)
+const schema = schemas.schema(object)
 
-/**
- * @param {toa.norm.context.Declaration} context
- */
 const validate = (context) => {
   schema.validate(context)
 }

package/src/component.js

@@ -20,7 +20,7 @@ const {
 const component = async (path) => {
   const manifest = await load(path)
 
-  normalize(manifest)
+  normalize(manifest, path)
   validate(manifest)
   extensions(manifest)
 
@@ -29,21 +29,21 @@ const component = async (path) => {
   return manifest
 }
 
-const load = async (path, base) => {
+const load = async (path, base, proto = false) => {
   if (base !== undefined) path = find(path, base, MANIFEST)
 
   const file = join(path, MANIFEST)
-  const manifest = /** @type {toa.norm.Component} */ await yaml(file) ?? {}
+  const manifest = await yaml(file) ?? {}
 
   manifest.path = path
 
-  defaults(manifest)
+  defaults(manifest, proto)
   await expand(manifest)
 
   await merge(path, manifest)
 
   if (manifest.prototype !== null) {
-    const prototype = await load(manifest.prototype, path)
+    const prototype = await load(manifest.prototype, path, true)
 
     collapse(manifest, prototype)
   }

package/src/context.js

@@ -19,7 +19,6 @@ const {
 const context = async (root, environment = process.env.TOA_ENV) => {
   const path = resolve(root, CONTEXT)
   const context = /** @type {toa.norm.Context} */ await load(path)
-  const pattern = resolve(root, context.packages)
 
   context.environment = environment
 
@@ -29,7 +28,7 @@ const context = async (root, environment = process.env.TOA_ENV) => {
 
   validate(context)
 
-  const paths = await glob(pattern)
+  const paths = await glob(resolve(root, COMPONENTS))
 
   context.components = await Promise.all(paths.map(component))
   context.dependencies = await dependencies(context)
@@ -41,5 +40,6 @@ const context = async (root, environment = process.env.TOA_ENV) => {
 }
 
 const CONTEXT = 'context.toa.yaml'
+const COMPONENTS = 'components/*'
 
 exports.context = context

package/src/shortcuts.js

@@ -48,9 +48,10 @@ const SHORTCUTS = {
   exposition: '@toa.io/extensions.exposition',
   realtime: '@toa.io/extensions.realtime',
   configuration: '@toa.io/extensions.configuration',
-  origins: '@toa.io/extensions.origins',
   stash: '@toa.io/extensions.stash',
-  storages: '@toa.io/extensions.storages'
+  storages: '@toa.io/extensions.storages',
+  telemetry: '@toa.io/extensions.telemetry',
+  introspection: '@toa.io/extensions.introspection'
 }
 
 exports.recognize = recognize

package/test/component/expand.fixtures.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const source = {
-  path: '',
+  path: __dirname, // `version` hashes the component directory
   entity: {
     schema: {
       properties: {

package/test/component/expand.test.js

@@ -11,17 +11,31 @@ beforeEach(() => {
   source = clone(fixtures.source)
 })
 
-it('should expand', () => {
-  expand(source)
+it('should expand', async () => {
+  await expand(source)
   expect(source).toMatchObject(fixtures.target)
 })
 
+it('should derive version from the component contents', async () => {
+  await expand(source)
+
+  expect(source.version).toMatch(/^[0-9a-f]{8}$/)
+})
+
+it('should keep declared version', async () => {
+  source.version = '1.0.0'
+
+  await expand(source)
+
+  expect(source.version).toStrictEqual('1.0.0')
+})
+
 it('should recognize storages.queues', async () => {
   const queues = { foo: 'bar' }
 
   source.queues = clone(queues)
 
-  expand(source)
+  await expand(source)
 
   expect(source.queues).toBeUndefined()
   expect(source.properties['@toa.io/storages.queues']).toMatchObject(queues)