Request-response identifiers

.gitignore

@@ -1,5 +1,6 @@
 fbp-config.json
 fbp.json
+flowhub.json
 *.tgz
 node_modules
 npm-debug.log

CHANGES.md

@@ -0,0 +1,73 @@
+## Changes
+
+* 2018-08-18: **Version 0.8**
+  - Moved `secret` from payload to message top-level
+  - Introduced `requestId` and `responseTo` top-level keys for identifying requests and the response packets to them
+* 2018-03-27:
+  - Added schema for `network:edges` output message
+  - Modified `subgraph` key of `network:data` and other network packet events to be an array as specified in the text
+* 2018-03-26:
+  - Fixed documentation for `component:setsource` to use `component:source` input, and `component:component` output
+  - Added schema for `trace:error` message
+  - Added `:error` output to all capabilities where user can perform actions that may fail
+* 2018-03-23:
+  - Added optional `graph` key to `network:error` payloads
+* 2018-03-22: **Version 0.7**
+  - Added `network:debug` and `network:getstatus` to the `network:control` permission
+* 2018-03-21:
+  - Fixed signature of `runtime:packet.payload`, `runtime:packetsent.payload`, and port definition `default` to accept any payload type
+  - Added `values` and `default` keys for port definitions
+  - Added schema for `component:componentsready` output message
+  - Added schema for `graph:clear` output message
+  - Added `packetsent` response for `runtime:packet` input message
+* 2017-09-17:
+  - Added `schema` support for ports and packets
+  - Documented known metadata keys for various graph entities
+* 2017-04-09: **Version 0.6**
+  - Version 0.6. No breaking changes over 0.5.
+  - Added additional capabilities `graph:readonly`, `network:control`, `network:data`, `network:status`. Especially useful for read-only access.
+  - Deprecated the `protocol:network` capability in favor of the new fine-gained `network:*` capabilities.
+  - Each capability now defines the set of messages contained in it. Available as `inputs` and `outputs` in the schema `/shared/capabilities`.
+* 2017-05-04:
+  - Fixed protocol errors (`graph:error`, `component:error` and `runtime:error`) to have mandatory `message` string payload.
+  - Fixed missing `required` markers in some JSON schemas for `graph` protocol. Affected messages:
+`graph:renamegroup`, `graph:renameinport`, `graph:removeinport`, `graph:addinitial`, `graph:changeedge`
+  - More readable HTML output, including property value types and examples
+* 2017-05-03:
+  - Added more optional metadata to `runtime:runtime` message: `repository`, `repositoryVersion` and `namespace`
+* 2017-02-20:
+  - Fixed payload definition of `network:edges` missing mandatory `graph` key
+* 2016-07-01:
+  - `network:error` payload may now contain an optional `stacktrace`
+* 2016-06-23:
+  - Trace subprotocol also available in machine-readable format
+* 2016-06-17:
+  - Protocol definition available as machine-readable JSON [schemas](https://github.com/flowbased/fbp-protocol/tree/master/schema/yaml).
+  - The human-readable HTML documentation is generated from this defintion.
+  - The npm package `fbp-protocol` contains the schemas as YAML, JSON and .js modules.
+* 2015-11-20:
+  - Initial `trace` subprotocol, for [Flowtrace](https://github.com/flowbased/flowtrace) support
+* 2015-03-27:
+  - Documented `network` `persist` and `component` `componentsready` messages
+* 2015-03-26: **Version 0.5**
+  - All messages sent to runtime should include the `secret` in payload
+  - Runtime description message includes an `allCapabilities` array describing capabilities of the runtime, including ones not available to current user
+* 2014-10-23
+  - added clarifications to network running state in `status`, `started`, and `stopped` messages
+* 2014-09-26
+  - Add `secret` as payload to `getruntime` to support [access levels](https://github.com/noflo/noflo-ui/issues/278)
+* 2014-08-05:
+  - Add get, list, graph, graphsdone commands to the graph protocol
+  - Add list, network commands to the network protocol
+* 2014-07-15:
+  - Add changenode, changeedge, addgroup, removegroup, renamegroup,
+    changegroup commands to the graph protocol
+* 2014-03-13: **Version 0.4**
+  - Capability discovery support
+  - Network exported port messaging for remote subgraphs
+* 2014-02-18: **Version 0.3**
+  - Support for exported graph ports
+* 2014-01-09: **Version 0.2**
+  - Multi-graph support via the `graph` key in payload
+  - Harmonization with [JSON format](http://noflojs.org/documentation/json/) by renaming `from`/`to` in edges to `src`/`tgt`
+  - Network `edges` message

Gruntfile.coffee

@@ -143,15 +143,24 @@ module.exports = ->
   @registerTask 'default', ['test']
 
   @registerTask 'json-to-js', ->
-    schemaJs = "module.exports = #{JSON.stringify documentation.getSchemas()}"
-    fs.writeFileSync './schema/schemas.js', schemaJs, 'utf8'
+    done = @async()
+    documentation.getSchemas (err, schemas) ->
+      return done err if err
+      schemaJs = "module.exports = #{JSON.stringify schemas}"
+      fs.writeFileSync './schema/schemas.js', schemaJs, 'utf8'
+      done()
 
   @registerTask 'build-markdown', ->
-    messages = documentation.renderMessages() 
-    capabilities = documentation.renderCapabilities()
-
-    file = fs.readFileSync 'spec/protocol.js.md', 'utf8'
-    file = file.replace '<%= messages %>\n', messages
-    file = file.replace '<%= capabilities %>', capabilities
-    fs.writeFileSync 'spec/protocol.md', file, 'utf8'
+    done = @async()
+    documentation.renderMessages (err, messages) ->
+      return done err if err
+      capabilities = documentation.renderCapabilities (err, capabilities) ->
+        return done err if err
+        changelog = fs.readFileSync 'CHANGES.md', 'utf8'
+        file = fs.readFileSync 'spec/protocol.js.md', 'utf8'
+        file = file.replace '<%= messages %>\n', messages
+        file = file.replace '<%= capabilities %>', capabilities
+        file = file.replace '<%= changelog %>', changelog
+        fs.writeFileSync 'spec/protocol.md', file, 'utf8'
+        done()
 

package.json

@@ -16,6 +16,7 @@
     "fbp-test": "./bin/fbp-test"
   },
   "scripts": {
+    "serve": "http-server dist",
     "test": "grunt test"
   },
   "dependencies": {
@@ -37,8 +38,11 @@
     "grunt-jekyll": "^0.4.4",
     "grunt-mocha-test": "^0.13.2",
     "grunt-yaml": "^0.4.2",
+    "http-server": "^0.11.1",
+    "json-schema-ref-parser": "^5.1.2",
     "noflo-core": "^0.5.0",
-    "noflo-nodejs": "^0.10.0"
+    "noflo-nodejs": "^0.10.0",
+    "uuid": "^3.3.2"
   },
   "main": "./schema/index.js"
 }

schema/yaml/component.yml

@@ -6,7 +6,7 @@ output:
     id: 'output/error'
     description: 'Error response to a command on component protocol'
     allOf:
-      - $ref: '/shared/message'
+      - $ref: '#/shared/output_message'
       - properties:
           protocol:
             enum: ['component']
@@ -23,7 +23,7 @@ output:
     id: 'output/component'
     description: Transmit the metadata about a component instance.
     allOf:
-      - $ref: '/shared/message'
+      - $ref: '#/shared/output_message'
       - properties:
           protocol:
             enum: ['component']
@@ -50,26 +50,28 @@ output:
                 description: 'boolean telling whether the component is a subgraph'
               inPorts:
                 description: 'list of input ports of the component'
-                $ref: '/shared/port_definition'
+                $ref: '#/shared/port_definition'
               outPorts:
                 description: 'list of output ports of the component'
-                $ref: '/shared/port_definition'
+                $ref: '#/shared/port_definition'
   componentsready:
     id: 'output/componentsready'
     description: Indication that a component listing has finished
-    properties:
-      protocol:
-        enum: ['component']
-        type: string
-        description: 'type of protocol'
-      command:
-        enum: ['componentsready']
-        description: 'command to be executed'
-        example: 'addnode'
-      payload:
-        type: 'integer'
-        description: 'number of components transmitted in this batch'
-        example: 42
+    allOf:
+      - $ref: '#/shared/output_message'
+      - properties:
+          protocol:
+            enum: ['component']
+            type: string
+            description: 'type of protocol'
+          command:
+            enum: ['componentsready']
+            description: 'command to be executed'
+            example: 'addnode'
+          payload:
+            type: 'integer'
+            description: 'number of components transmitted in this batch'
+            example: 42
 
   source:
     id: 'output/source'
@@ -78,7 +80,7 @@ output:
       message, it should do whatever operations are needed for making that
       component available for graphs, including possible compilation.
     allOf:
-      - $ref: '/shared/message'
+      - $ref: '#/shared/output_message'
       - properties:
           protocol:
             enum: ['component']
@@ -116,26 +118,22 @@ input:
       Request a list of currently available components. Will be responded with
       a set of `component` messages.
     allOf:
-      - $ref: '/shared/message'
+      - $ref: '#/shared/input_message'
       - properties:
           protocol:
             enum: ['component']
           command:
             enum: ['list']
           payload:
             required: []
-            properties:
-              secret:
-                type: string
-                description: access token to authorize user
 
   getsource:
     id: 'input/getsource'
     description: >-
       Request for the source code of a given component. Will be responded with
       a `source` message.
     allOf:
-      - $ref: '/shared/message'
+      - $ref: '#/shared/input_message'
       - properties:
           protocol:
             enum: ['component']
@@ -149,9 +147,6 @@ input:
                 type: string
                 description: 'Name of the component to for which to get source code. Should contain the library prefix'
                 example: 'my-project/SomeComponent'
-              secret:
-                type: string
-                description: access token to authorize user
 
   source:
     id: 'input/source'
@@ -160,7 +155,7 @@ input:
       message, it should do whatever operations are needed for making that
       component available for graphs, including possible compilation.
     allOf:
-      - $ref: '/shared/message'
+      - $ref: '#/shared/input_message'
       - properties:
           protocol:
             enum: ['component']
@@ -189,5 +184,3 @@ input:
               tests:
                 type: string
                 description: 'Unit tests for the component'
-              secret:
-                type: string