From 15afbbfbe683aab747a5c71a0e9617a112d13a31 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 16:44:37 +0200 Subject: [PATCH 01/19] Move secrets to top level --- schema/yaml/component.yml | 9 ------ schema/yaml/graph.yml | 61 ----------------------------------- schema/yaml/network.yml | 19 ----------- schema/yaml/runtime.yml | 7 ---- schema/yaml/shared.yml | 7 ++-- schema/yaml/trace.yml | 12 +++---- spec/protocol.js.md | 2 ++ src/WebSocket.coffee | 5 +-- test/schema/test_trace.coffee | 16 ++++----- 9 files changed, 20 insertions(+), 118 deletions(-) diff --git a/schema/yaml/component.yml b/schema/yaml/component.yml index c23fa06..075464d 100644 --- a/schema/yaml/component.yml +++ b/schema/yaml/component.yml @@ -124,10 +124,6 @@ input: enum: ['list'] payload: required: [] - properties: - secret: - type: string - description: access token to authorize user getsource: id: 'input/getsource' @@ -149,9 +145,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' @@ -189,5 +182,3 @@ input: tests: type: string description: 'Unit tests for the component' - secret: - type: string diff --git a/schema/yaml/graph.yml b/schema/yaml/graph.yml index e605ed3..e5fc7fb 100644 --- a/schema/yaml/graph.yml +++ b/schema/yaml/graph.yml @@ -158,9 +158,6 @@ input: type: string description: >- Description to use for the graph when used as a component - secret: - type: string - description: access token to authorize user addnode: id: 'input/addnode' @@ -188,9 +185,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user removenode: id: 'input/removenode' @@ -212,9 +206,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user renamenode: id: 'input/renamenode' @@ -239,9 +230,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user changenode: id: 'input/changenode' @@ -266,9 +254,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user addedge: id: 'input/addedge' @@ -296,9 +281,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user removeedge: id: 'input/removeedge' @@ -323,9 +305,6 @@ input: tgt: description: 'target node for the edge' $ref: '/shared/port' - secret: - type: string - description: access token to authorize user changeedge: id: 'input/changeedge' @@ -353,9 +332,6 @@ input: tgt: description: 'target node for the edge' $ref: '/shared/port' - secret: - type: string - description: access token to authorize user addinitial: id: 'input/addinitial' @@ -384,9 +360,6 @@ input: tgt: description: 'target node/port for the edge' $ref: '/shared/port' - secret: - type: string - description: access token to authorize user removeinitial: id: 'input/removeinitial' @@ -411,9 +384,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user addinport: id: 'input/addinport' @@ -444,9 +414,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user removeinport: id: 'input/removeinport' @@ -468,9 +435,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user renameinport: id: 'input/renameinport' @@ -495,9 +459,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user addoutport: id: 'input/addoutport' @@ -528,9 +489,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user removeoutport: id: 'input/removeoutport' @@ -552,9 +510,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user renameoutport: id: 'input/renameoutport' @@ -579,9 +534,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user addgroup: id: 'input/addgroup' @@ -609,9 +561,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user removegroup: id: 'input/removegroup' @@ -633,9 +582,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user renamegroup: id: 'input/renamegroup' @@ -659,9 +605,6 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user changegroup: id: 'input/changegroup' @@ -686,7 +629,3 @@ input: graph: type: string description: 'graph the action targets' - secret: - type: string - description: access token to authorize user - diff --git a/schema/yaml/network.yml b/schema/yaml/network.yml index 25c93a1..7a16705 100644 --- a/schema/yaml/network.yml +++ b/schema/yaml/network.yml @@ -349,9 +349,6 @@ input: graph: type: "string" description: 'graph the action targets' - secret: - type: string - description: access token to authorize user getstatus: id: 'input/getstatus' @@ -372,9 +369,6 @@ input: graph: type: "string" description: 'graph the action targets' - secret: - type: string - description: access token to authorize user stop: id: 'input/stop' @@ -393,9 +387,6 @@ input: graph: type: "string" description: 'graph the action targets' - secret: - type: string - description: access token to authorize user persist: id: 'input/persist' @@ -414,9 +405,6 @@ input: required: [] additionalProperties: false properties: - secret: - type: string - description: access token to authorize user debug: id: 'input/debug' @@ -438,9 +426,6 @@ input: graph: description: graph the action targets type: string - secret: - description: access token to authorize the user - type: string edges: id: 'input/edges' @@ -475,7 +460,3 @@ input: tgt: description: 'target node for the edge' $ref: '/shared/port' - secret: - type: string - description: access token to authorize user - diff --git a/schema/yaml/runtime.yml b/schema/yaml/runtime.yml index 2dcb501..f7ebfce 100644 --- a/schema/yaml/runtime.yml +++ b/schema/yaml/runtime.yml @@ -21,10 +21,6 @@ input: enum: ['getruntime'] payload: required: [] - properties: - secret: - type: string - description: access token to authorize user packet: id: 'input/packet' @@ -74,9 +70,6 @@ input: description: >- payload for the packet. Used only with begingroup (for group names) and data packets - secret: - type: string - description: access token to authorize user output: error: diff --git a/schema/yaml/shared.yml b/schema/yaml/shared.yml index aecf101..3d463f1 100644 --- a/schema/yaml/shared.yml +++ b/schema/yaml/shared.yml @@ -2,10 +2,6 @@ $schema: 'http://json-schema.org/draft-04/schema#' title: 'Shared' description: 'Shared schema fragments' -secret: - id: secret - description: access token to authorize the client - type: string graph_id: id: graph_id description: Graph identifier the message targets @@ -28,6 +24,9 @@ message: payload: type: object description: 'content of message' + secret: + type: string + description: access token to authorize the client metadata_node: id: 'metadata_node' diff --git a/schema/yaml/trace.yml b/schema/yaml/trace.yml index f6611e4..2cf6261 100644 --- a/schema/yaml/trace.yml +++ b/schema/yaml/trace.yml @@ -70,10 +70,9 @@ input: command: enum: ['start'] payload: - required: ['secret', 'graph'] + required: ['graph'] additionalProperties: false properties: - secret: { $ref: '/shared/secret' } graph: { $ref: '/shared/graph_id' } buffersize: description: 'Size of tracing buffer to keep. In bytes' @@ -90,10 +89,9 @@ input: command: enum: ['stop'] payload: - required: ['secret', 'graph'] + required: ['graph'] additionalProperties: false properties: - secret: { $ref: '/shared/secret' } graph: { $ref: '/shared/graph_id' } dump: @@ -107,10 +105,9 @@ input: command: enum: ['dump'] payload: - required: ['secret', 'graph', 'type'] + required: ['graph', 'type'] additionalProperties: false properties: - secret: { $ref: '/shared/secret' } graph: { $ref: '/shared/graph_id' } type: description: Type/format of trace to output @@ -128,8 +125,7 @@ input: command: enum: ['clear'] payload: - required: ['secret', 'graph'] + required: ['graph'] additionalProperties: false properties: - secret: { $ref: '/shared/secret' } graph: { $ref: '/shared/graph_id' } diff --git a/spec/protocol.js.md b/spec/protocol.js.md index d9f58e8..0577adc 100644 --- a/spec/protocol.js.md +++ b/spec/protocol.js.md @@ -33,6 +33,8 @@ The [fbp-protocol](https://github.com/flowbased/fbp-protocol) tool provides a se ## Changes +* 2018-08-18: **Version 0.8** + - Moved `secret` from payload to message top-level * 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 diff --git a/src/WebSocket.coffee b/src/WebSocket.coffee index b57fdd8..1152ced 100644 --- a/src/WebSocket.coffee +++ b/src/WebSocket.coffee @@ -59,11 +59,11 @@ exports.testRuntime = (runtimeType, startServer, stopServer, host='localhost', p send = (protocol, command, payload) -> payload = {} unless payload - payload.secret = process.env.FBP_PROTOCOL_SECRET if process.env.FBP_PROTOCOL_SECRET connection.sendUTF JSON.stringify protocol: protocol command: command payload: payload + secret: process.env.FBP_PROTOCOL_SECRET messageMatches = (msg, expected) -> return false unless msg.protocol is expected.protocol @@ -82,6 +82,7 @@ exports.testRuntime = (runtimeType, startServer, stopServer, host='localhost', p # Validate all received packets against schema validateSchema data, getPacketSchema data # Don't ever expect payloads to return a secret + chai.expect(data.secret, 'Message should not contain secret').to.be.a 'undefined' chai.expect(data.payload.secret, 'Payload should not contain secret').to.be.a 'undefined' if allowExtraPackets and not messageMatches data, expects[0] # Ignore messages we don't care about in context of the test @@ -110,7 +111,7 @@ exports.testRuntime = (runtimeType, startServer, stopServer, host='localhost', p delete expected.payload.stack # Don't ever expect payloads to return a secret - delete expected.payload.secret + delete expected.secret chai.expect(data.payload).to.eql expected.payload # Received all expected packets diff --git a/test/schema/test_trace.coffee b/test/schema/test_trace.coffee index cbf6ced..6e4b2a5 100644 --- a/test/schema/test_trace.coffee +++ b/test/schema/test_trace.coffee @@ -8,26 +8,26 @@ validExamples = command: 'start' payload: graph: 'mygraph' - secret: 'verygood' + secret: 'verygood' 'dump flowtrace.json': protocol: 'trace' command: 'dump' payload: graph: 'mygraph' - secret: 'verygood' type: 'flowtrace.json' + secret: 'verygood' 'clear buffer': protocol: 'trace' command: 'clear' payload: graph: 'mygraph' - secret: 'verygood' + secret: 'verygood' 'stop recording': protocol: 'trace' command: 'stop' payload: graph: 'mygraph' - secret: 'verygood' + secret: 'verygood' invalidExamples = 'start with invalid graph id': @@ -35,26 +35,26 @@ invalidExamples = command: 'start' payload: graph: 112.0 - secret: 'nnice' + secret: 'nnice' 'dump with invalid type': protocol: 'trace' command: 'dump' payload: graph: 'mygraph' - secret: 'verygood' type: 'not-a-valid-trace-type' + secret: 'verygood' 'stop with missing secret': protocol: 'trace' command: 'start' payload: graph: 112.0 - secret: undefined + secret: undefined 'clear without graph': protocol: 'trace' command: 'start' payload: graph: undefined - secret: 'verygood' + secret: 'verygood' testValid = (name) -> describe name, -> From 336bae7300857fb3412ff8d809a5a0f1c2c9dc79 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 17:41:16 +0200 Subject: [PATCH 02/19] Differentiate between input and output message formats --- schema/yaml/component.yml | 39 +- schema/yaml/graph.yml | 999 +++++++++++++++++++++----------------- schema/yaml/network.yml | 36 +- schema/yaml/runtime.yml | 12 +- schema/yaml/shared.yml | 20 +- schema/yaml/trace.yml | 101 ++-- 6 files changed, 661 insertions(+), 546 deletions(-) diff --git a/schema/yaml/component.yml b/schema/yaml/component.yml index 075464d..77eb370 100644 --- a/schema/yaml/component.yml +++ b/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'] @@ -57,19 +57,20 @@ output: 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 + - $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 +79,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,7 +117,7 @@ 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'] @@ -131,7 +132,7 @@ input: 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'] @@ -153,7 +154,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'] diff --git a/schema/yaml/graph.yml b/schema/yaml/graph.yml index e5fc7fb..bd5d521 100644 --- a/schema/yaml/graph.yml +++ b/schema/yaml/graph.yml @@ -4,123 +4,574 @@ description: >- This protocol is utilized for communicating about graph changes in both directions. +messages: + error: + properties: + protocol: + enum: ['graph'] + command: + enum: ['error'] + payload: + required: ['message'] + properties: + message: + type: 'string' + description: 'Error message describing what went wrong' + clear: + properties: + protocol: + enum: ['graph'] + command: + enum: ['clear'] + payload: + required: ['id'] + additionalProperties: false + properties: + id: + type: string + description: 'identifier for the graph being created. Used for all subsequent messages related to the graph instance' + name: + type: string + description: 'Human-readable label for the graph' + library: + type: string + description: 'Component library identifier' + main: + type: boolean + + description: "Identifies the graph as a main graph of a project that should not be registered as a component\nGraphs registered in this way should also be available for use as subgraphs in other graphs. Therefore a graph registration and later changes to it may cause component messages of the Component protocol to be sent back to the client informing of possible changes in the ports of the subgraph component." + icon: + type: string + description: >- + Icon to use for the graph when used as a component + description: + type: string + description: >- + Description to use for the graph when used as a component + addnode: + properties: + protocol: + enum: ['graph'] + command: + enum: ['addnode'] + payload: + required: ['id', 'component', 'graph'] + additionalProperties: false + properties: + id: + type: string + description: 'identifier for the node' + component: + type: string + description: 'component name used for the node' + metadata: + description: 'structure of key-value pairs for node metadata' + $ref: '/shared/metadata_node' + graph: + type: string + description: 'graph the action targets' + removenode: + properties: + protocol: + enum: ['graph'] + command: + enum: ['removenode'] + payload: + required: ['id', 'graph'] + additionalProperties: false + properties: + id: + type: string + description: 'identifier for the node' + graph: + type: string + description: 'graph the action targets' + renamenode: + properties: + protocol: + enum: ['graph'] + command: + enum: ['renamenode'] + payload: + required: ['from', 'to', 'graph'] + additionalProperties: false + properties: + from: + type: string + description: 'original identifier for the node' + to: + type: string + description: 'new identifier for the node' + graph: + type: string + description: 'graph the action targets' + changenode: + properties: + protocol: + enum: ['graph'] + command: + enum: ['changenode'] + payload: + required: ['id', 'metadata', 'graph'] + additionalProperties: false + properties: + id: + type: string + description: 'identifier for the node' + metadata: + description: 'structure of key-value pairs for node metadata' + $ref: '/shared/metadata_node' + graph: + type: string + description: 'graph the action targets' + addedge: + properties: + protocol: + enum: ['graph'] + command: + enum: ['addedge'] + payload: + required: ['src', 'tgt', 'graph'] + additionalProperties: false + properties: + src: + $ref: '/shared/port' + description: 'source node for the edge' + tgt: + $ref: '/shared/port' + description: 'target node for the edge' + metadata: + description: 'Structure of key-value pairs for edge metadata' + $ref: '/shared/metadata_edge' + graph: + type: string + description: 'graph the action targets' + removeedge: + properties: + protocol: + enum: ['graph'] + command: + enum: ['removeedge'] + payload: + additionalProperties: false + required: ['graph', 'src', 'tgt'] + properties: + graph: + type: string + description: 'graph the action targets' + src: + description: 'source node for the edge' + $ref: '/shared/port' + tgt: + description: 'target node for the edge' + $ref: '/shared/port' + changeedge: + properties: + protocol: + enum: ['graph'] + command: + enum: ['changeedge'] + payload: + additionalProperties: false + required: ['graph', 'src', 'tgt'] + properties: + graph: + type: string + description: 'graph the action targets' + metadata: + description: 'struct of key-value pairs for edge metadata' + $ref: '/shared/metadata_edge' + src: + description: 'source node for the edge' + $ref: '/shared/port' + tgt: + description: 'target node for the edge' + $ref: '/shared/port' + addinitial: + properties: + protocol: + enum: ['graph'] + command: + enum: ['addinitial'] + payload: + additionalProperties: false + required: ['graph', 'src', 'tgt'] + properties: + graph: + type: string + description: 'graph the action targets' + metadata: + type: object + description: 'structure of key-value pairs for IIP metadata' + $ref: '/shared/metadata_edge' + src: + description: 'source data for the edge' + $ref: '/shared/iip' + tgt: + description: 'target node/port for the edge' + $ref: '/shared/port' + removeinitial: + properties: + protocol: + enum: ['graph'] + command: + enum: ['removeinitial'] + payload: + required: ['tgt', 'graph'] + additionalProperties: false + properties: + src: + description: 'IIP data' + $ref: '/shared/iip' + tgt: + $ref: '/shared/port' + description: 'target node/port for the edge' + graph: + type: string + description: 'graph the action targets' + addinport: + properties: + protocol: + enum: ['graph'] + command: + enum: ['addinport'] + payload: + additionalProperties: false + required: ['public', 'port', 'node', 'graph'] + properties: + public: + type: string + description: 'the exported name of the port' + node: + type: string + description: 'node identifier' + port: + type: string + description: 'internal port name' + metadata: + description: 'structure of key-value pairs for node metadata' + $ref: '/shared/metadata_node' + graph: + type: string + description: 'graph the action targets' + removeinport: + properties: + protocol: + enum: ['graph'] + command: + enum: ['removeinport'] + payload: + required: ['public', 'graph'] + additionalProperties: false + properties: + public: + type: string + description: 'the exported name of the port to remove' + graph: + type: string + description: 'graph the action targets' + renameinport: + properties: + protocol: + enum: ['graph'] + command: + enum: ['renameinport'] + payload: + required: ['from', 'to', 'graph'] + additionalProperties: false + properties: + from: + type: string + description: 'original exported port name' + to: + type: string + description: 'new exported port name' + graph: + type: string + description: 'graph the action targets' + addoutport: + properties: + protocol: + enum: ['graph'] + command: + enum: ['addoutport'] + payload: + required: ['public', 'node', 'port', 'graph'] + additionalProperties: false + properties: + public: + type: string + description: 'the exported name of the port' + node: + type: string + description: 'node identifier' + port: + type: string + description: 'internal port name' + metadata: + description: 'structure of key-value pairs for port metadata' + $ref: '/shared/metadata_node' + graph: + type: string + description: 'graph the action targets' + removeoutport: + properties: + protocol: + enum: ['graph'] + command: + enum: ['removeoutport'] + payload: + required: ['public'] + additionalProperties: false + properties: + public: + type: string + description: 'the exported name of the port to remove' + graph: + type: string + description: 'graph the action targets' + renameoutport: + properties: + protocol: + enum: ['graph'] + command: + enum: ['renameoutport'] + payload: + required: ['from', 'to', 'graph'] + additionalProperties: false + properties: + from: + type: string + description: 'original exported port name' + to: + type: string + description: 'new exported port name' + graph: + type: string + description: 'graph the action targets' + addgroup: + properties: + protocol: + enum: ['graph'] + command: + enum: ['addgroup'] + payload: + required: ['name', 'nodes', 'graph'] + additionalProperties: false + properties: + name: + type: string + description: 'the group name' + nodes: + type: array + description: 'an array of node ids part of the group' + metadata: + description: 'structure of key-value pairs for group metadata' + $ref: '/shared/metadata_group' + graph: + type: string + description: 'graph the action targets' + removegroup: + properties: + protocol: + enum: ['graph'] + command: + enum: ['removegroup'] + payload: + required: ['name', 'graph'] + additionalProperties: false + properties: + name: + type: string + description: 'the group name' + graph: + type: string + description: 'graph the action targets' + renamegroup: + properties: + protocol: + enum: ['graph'] + command: + enum: ['renamegroup'] + payload: + required: ['from', 'to', 'graph'] + properties: + from: + type: string + description: 'original group name' + to: + type: string + description: 'new group name' + graph: + type: string + description: 'graph the action targets' + changegroup: + properties: + protocol: + enum: ['graph'] + command: + enum: ['changegroup'] + payload: + required: ['name', 'metadata', 'graph'] + additionalProperties: false + properties: + name: + type: string + description: 'the group name' + metadata: + description: 'structure of key-value pairs for group metadata' + $ref: '/shared/metadata_group' + graph: + type: string + description: 'graph the action targets' + output: error: id: 'output/error' description: 'Error response to a command on graph protocol' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['error'] - payload: - required: ['message'] - properties: - message: - type: 'string' - description: 'Error message describing what went wrong' + - $ref: '/shared/output_message' + - $ref: '../messages/error' clear: id: 'output/clear' description: 'An empty graph was initialized' - $ref: '../input/clear' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/clear' addnode: id: 'output/addnode' - description: 'Add node to a graph.' - $ref: '../input/addnode' + description: 'A node was added to a graph.' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/addnode' removenode: id: 'output/removenode' - description: 'Remove a node from a graph.' - $ref: '../input/removenode' + description: 'A node was removed from a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/removenode' renamenode: id: 'output/renamenode' - description: 'Change the ID of a node in the graph' - $ref: '../input/renamenode' + description: 'A node was renamed in a graph.' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/renamenode' changenode: id: 'output/changenode' - description: 'Change the metadata associated to a node in the graph' - $ref: '../input/changenode' + description: 'Metadata of a node was changed in a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/changenode' addedge: id: 'output/addedge' - description: 'Add an edge to the graph' - $ref: '../input/addedge' + description: 'An edge was added to a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/addedge' removeedge: id: 'output/removeedge' - description: 'Remove an edge from the graph' - $ref: '../input/removeedge' + description: 'An edge was removed from a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/removeedge' changeedge: id: 'output/changeedge' - description: 'Change an edge''s metadata' - $ref: '../input/changeedge' + description: 'Metadata of an edge was changed in a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/changeedge' addinitial: id: 'output/addinitial' - description: 'Add an IIP to the graph' - $ref: '../input/addinitial' + description: 'An IIP was added to a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/addinitial' removeinitial: id: 'output/removeinitial' - description: 'Remove an IIP from the graph' - $ref: '../input/removeinitial' + description: 'An IIP was removed from a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/removeinitial' addinport: id: 'output/addinport' - description: 'Add an exported inport to the graph.' - $ref: '../input/addinport' + description: 'An exported inport was added to a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/addinport' removeinport: id: 'output/removeinport' - description: 'Remove an exported port from the graph' - $ref: '../input/removeinport' + description: 'An exported inport was removed from a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/removeinport' renameinport: id: 'output/renameinport' - description: 'Rename an exported port in the graph' - $ref: '../input/renameinport' + description: 'An exported inport was renamed in a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/renameinport' addoutport: id: 'output/addoutport' - description: 'Add an exported outport to the graph.' - $ref: '../input/addoutport' + description: 'An exported outport was added to a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/addoutport' removeoutport: id: 'output/removeoutport' - description: 'Remove an exported port from the graph' - $ref: '../input/removeoutport' + description: 'An exported outport was removed from a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/removeoutport' renameoutport: id: 'output/renameoutport' - description: 'Rename an exported port in the graph' - $ref: '../input/renameoutport' + description: 'An exported outport was renamed in a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/renameoutport' addgroup: id: 'output/addgroup' - description: 'Add a group to the graph' - $ref: '../input/addgroup' + description: 'A group was added to a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/addgroup' removegroup: id: 'output/removegroup' - description: 'Remove a group from the graph' - $ref: '../input/removegroup' + description: 'A group was removed from a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/removegroup' renamegroup: id: 'output/renamegroup' - description: 'Rename a group in the graph.' - $ref: '../input/renamegroup' + description: 'A group was renamed in a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/renamegroup' changegroup: id: 'output/changegroup' - description: 'Change a group''s metadata' - $ref: '../input/changegroup' + description: 'Metadata of a group was changed in a graph' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/changegroup' input: @@ -128,504 +579,138 @@ input: id: 'input/clear' description: 'Initialize an empty graph.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['clear'] - payload: - required: ['id'] - additionalProperties: false - properties: - id: - type: string - description: 'identifier for the graph being created. Used for all subsequent messages related to the graph instance' - name: - type: string - description: 'Human-readable label for the graph' - library: - type: string - description: 'Component library identifier' - main: - type: boolean - description: "Identifies the graph as a main graph of a project that should not be registered as a component\nGraphs registered in this way should also be available for use as subgraphs in other graphs. Therefore a graph registration and later changes to it may cause component messages of the Component protocol to be sent back to the client informing of possible changes in the ports of the subgraph component." - icon: - type: string - description: >- - Icon to use for the graph when used as a component - description: - type: string - description: >- - Description to use for the graph when used as a component + - $ref: '/shared/input_message' + - $ref: '../messages/clear' addnode: id: 'input/addnode' description: 'Add node to a graph.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['addnode'] - payload: - required: ['id', 'component', 'graph'] - additionalProperties: false - properties: - id: - type: string - description: 'identifier for the node' - component: - type: string - description: 'component name used for the node' - metadata: - description: 'structure of key-value pairs for node metadata' - $ref: '/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/addnode' removenode: id: 'input/removenode' description: 'Remove a node from a graph.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['removenode'] - payload: - required: ['id', 'graph'] - additionalProperties: false - properties: - id: - type: string - description: 'identifier for the node' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/removenode' renamenode: id: 'input/renamenode' description: 'Change the ID of a node in the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['renamenode'] - payload: - required: ['from', 'to', 'graph'] - additionalProperties: false - properties: - from: - type: string - description: 'original identifier for the node' - to: - type: string - description: 'new identifier for the node' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/renamenode' changenode: id: 'input/changenode' description: 'Change the metadata associated to a node in the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['changenode'] - payload: - required: ['id', 'metadata', 'graph'] - additionalProperties: false - properties: - id: - type: string - description: 'identifier for the node' - metadata: - description: 'structure of key-value pairs for node metadata' - $ref: '/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/changenode' addedge: id: 'input/addedge' description: 'Add an edge to the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['addedge'] - payload: - required: ['src', 'tgt', 'graph'] - additionalProperties: false - properties: - src: - $ref: '/shared/port' - description: 'source node for the edge' - tgt: - $ref: '/shared/port' - description: 'target node for the edge' - metadata: - description: 'Structure of key-value pairs for edge metadata' - $ref: '/shared/metadata_edge' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/addedge' removeedge: id: 'input/removeedge' description: 'Remove an edge from the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['removeedge'] - payload: - additionalProperties: false - required: ['graph', 'src', 'tgt'] - properties: - graph: - type: string - description: 'graph the action targets' - src: - description: 'source node for the edge' - $ref: '/shared/port' - tgt: - description: 'target node for the edge' - $ref: '/shared/port' + - $ref: '/shared/input_message' + - $ref: '../messages/removeedge' changeedge: id: 'input/changeedge' description: 'Change an edge''s metadata' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['changeedge'] - payload: - additionalProperties: false - required: ['graph', 'src', 'tgt'] - properties: - graph: - type: string - description: 'graph the action targets' - metadata: - description: 'struct of key-value pairs for edge metadata' - $ref: '/shared/metadata_edge' - src: - description: 'source node for the edge' - $ref: '/shared/port' - tgt: - description: 'target node for the edge' - $ref: '/shared/port' + - $ref: '/shared/input_message' + - $ref: '../messages/changeedge' addinitial: id: 'input/addinitial' description: 'Add an IIP to the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['addinitial'] - payload: - additionalProperties: false - required: ['graph', 'src', 'tgt'] - properties: - graph: - type: string - description: 'graph the action targets' - metadata: - type: object - description: 'structure of key-value pairs for IIP metadata' - $ref: '/shared/metadata_edge' - src: - description: 'source data for the edge' - $ref: '/shared/iip' - tgt: - description: 'target node/port for the edge' - $ref: '/shared/port' + - $ref: '/shared/input_message' + - $ref: '../messages/addinitial' removeinitial: id: 'input/removeinitial' description: 'Remove an IIP from the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['removeinitial'] - payload: - required: ['tgt', 'graph'] - additionalProperties: false - properties: - src: - description: 'IIP data' - $ref: '/shared/iip' - tgt: - $ref: '/shared/port' - description: 'target node/port for the edge' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/removeinitial' addinport: id: 'input/addinport' description: 'Add an exported inport to the graph.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['addinport'] - payload: - additionalProperties: false - required: ['public', 'port', 'node', 'graph'] - properties: - public: - type: string - description: 'the exported name of the port' - node: - type: string - description: 'node identifier' - port: - type: string - description: 'internal port name' - metadata: - description: 'structure of key-value pairs for node metadata' - $ref: '/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/addinport' removeinport: id: 'input/removeinport' description: 'Remove an exported port from the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['removeinport'] - payload: - required: ['public', 'graph'] - additionalProperties: false - properties: - public: - type: string - description: 'the exported name of the port to remove' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/removeinport' renameinport: id: 'input/renameinport' description: 'Rename an exported port in the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['renameinport'] - payload: - required: ['from', 'to', 'graph'] - additionalProperties: false - properties: - from: - type: string - description: 'original exported port name' - to: - type: string - description: 'new exported port name' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/renameinport' addoutport: id: 'input/addoutport' description: 'Add an exported outport to the graph.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['addoutport'] - payload: - required: ['public', 'node', 'port', 'graph'] - additionalProperties: false - properties: - public: - type: string - description: 'the exported name of the port' - node: - type: string - description: 'node identifier' - port: - type: string - description: 'internal port name' - metadata: - description: 'structure of key-value pairs for port metadata' - $ref: '/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/addoutport' removeoutport: id: 'input/removeoutport' description: 'Remove an exported port from the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['removeoutport'] - payload: - required: ['public'] - additionalProperties: false - properties: - public: - type: string - description: 'the exported name of the port to remove' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/removeoutport' renameoutport: id: 'input/renameoutport' description: 'Rename an exported port in the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['renameoutport'] - payload: - required: ['from', 'to', 'graph'] - additionalProperties: false - properties: - from: - type: string - description: 'original exported port name' - to: - type: string - description: 'new exported port name' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/renameoutport' addgroup: id: 'input/addgroup' description: 'Add a group to the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['addgroup'] - payload: - required: ['name', 'nodes', 'graph'] - additionalProperties: false - properties: - name: - type: string - description: 'the group name' - nodes: - type: array - description: 'an array of node ids part of the group' - metadata: - description: 'structure of key-value pairs for group metadata' - $ref: '/shared/metadata_group' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/addgroup' removegroup: id: 'input/removegroup' description: 'Remove a group from the graph' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['removegroup'] - payload: - required: ['name', 'graph'] - additionalProperties: false - properties: - name: - type: string - description: 'the group name' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/removegroup' renamegroup: id: 'input/renamegroup' description: 'Rename a group in the graph.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['renamegroup'] - payload: - required: ['from', 'to', 'graph'] - properties: - from: - type: string - description: 'original group name' - to: - type: string - description: 'new group name' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/renamegroup' changegroup: id: 'input/changegroup' description: 'Change a group''s metadata' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['graph'] - command: - enum: ['changegroup'] - payload: - required: ['name', 'metadata', 'graph'] - additionalProperties: false - properties: - name: - type: string - description: 'the group name' - metadata: - description: 'structure of key-value pairs for group metadata' - $ref: '/shared/metadata_group' - graph: - type: string - description: 'graph the action targets' + - $ref: '/shared/input_message' + - $ref: '../messages/changegroup' diff --git a/schema/yaml/network.yml b/schema/yaml/network.yml index 7a16705..49ac029 100644 --- a/schema/yaml/network.yml +++ b/schema/yaml/network.yml @@ -9,7 +9,7 @@ output: id: 'output/stopped' description: 'Inform that a given network has stopped.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -43,7 +43,7 @@ output: id: 'output/started' description: 'Inform that a given network has been started.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -74,7 +74,7 @@ output: id: 'output/status' description: 'Response to a getstatus message.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -107,7 +107,7 @@ output: of a Unix process, or a line of console.log in JavaScript. Output can also be used for passing images from the runtime to the UI.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -135,7 +135,7 @@ output: An error from a running network, roughly similar to STDERR output of a Unix process, or a line of console.error in JavaScript.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -160,7 +160,7 @@ output: description: >- When in debug mode, a network can signal an error happening inside a process. allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -184,7 +184,7 @@ output: id: 'output/icon' description: 'Icon of a component instance has changed.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -208,7 +208,7 @@ output: id: 'output/connect' description: 'Beginning of transmission on an edge.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -222,7 +222,7 @@ output: id: 'output/begingroup' description: 'Beginning of a group (bracket IP) on an edge.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -249,7 +249,7 @@ output: id: 'output/data' description: 'Data transmission on an edge.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -286,7 +286,7 @@ output: id: 'output/endgroup' description: 'Ending of a group (bracket IP) on an edge.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -313,7 +313,7 @@ output: id: 'output/disconnect' description: 'End of transmission on an edge.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['network'] @@ -336,7 +336,7 @@ input: id: 'input/start' description: 'Start execution of a FBP network based on a given graph.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['network'] @@ -356,7 +356,7 @@ input: Get the current status of the runtime. The runtime should respond with a status message. allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['network'] @@ -374,7 +374,7 @@ input: id: 'input/stop' description: 'Stop execution of a FBP network based on a given graph.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['network'] @@ -395,7 +395,7 @@ input: so that they are available between restarts. Requires the network:persist capability. allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['network'] @@ -410,7 +410,7 @@ input: id: 'input/debug' description: Set a network into debug mode allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['network'] @@ -433,7 +433,7 @@ input: List of edges user has selected for inspection in a user interface or debugger, sent from UI to a runtime. allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['network'] diff --git a/schema/yaml/runtime.yml b/schema/yaml/runtime.yml index f7ebfce..75c8f68 100644 --- a/schema/yaml/runtime.yml +++ b/schema/yaml/runtime.yml @@ -13,7 +13,7 @@ input: able to speak the full Runtime protocol, it should follow up with a ports message. allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['runtime'] @@ -32,7 +32,7 @@ input: These packets can be send from the client to the runtimes input ports, or from runtimes output ports to the client. allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['runtime'] @@ -76,7 +76,7 @@ output: id: 'output/error' description: 'Error response to a command on runtime protocol' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -96,7 +96,7 @@ output: is responsible for sending the up-to-date list of available ports back to client whenever it changes. allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -122,7 +122,7 @@ output: id: 'output/runtime' description: 'Response from the runtime to the getruntime request.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -186,7 +186,7 @@ output: id: 'output/packetsent' description: Confirmation that a packet has been sent allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['runtime'] diff --git a/schema/yaml/shared.yml b/schema/yaml/shared.yml index 3d463f1..a067e6d 100644 --- a/schema/yaml/shared.yml +++ b/schema/yaml/shared.yml @@ -7,7 +7,7 @@ graph_id: description: Graph identifier the message targets type: string -message: +input_message: id: 'message' description: 'protocol message' additionalProperties: false @@ -28,6 +28,24 @@ message: type: string description: access token to authorize the client +output_message: + id: 'message' + description: 'protocol message' + additionalProperties: false + required: ['protocol', 'command', 'payload'] + properties: + protocol: + type: string + description: 'type of protocol' + example: 'graph' + command: + type: string + description: 'command to be executed' + example: 'addnode' + payload: + type: object + description: 'content of message' + metadata_node: id: 'metadata_node' description: 'structure of key-value pairs for graph node metadata' diff --git a/schema/yaml/trace.yml b/schema/yaml/trace.yml index 2cf6261..060f69d 100644 --- a/schema/yaml/trace.yml +++ b/schema/yaml/trace.yml @@ -4,25 +4,67 @@ description: >- This protocol is utilized for triggering and transmitting [Flowtrace](https://github.com/flowbased/flowtrace)s -output: +messages: + start: + properties: + protocol: + enum: ['trace'] + command: + enum: ['start'] + payload: + required: ['graph'] + additionalProperties: false + properties: + graph: { $ref: '/shared/graph_id' } + buffersize: + description: 'Size of tracing buffer to keep. In bytes' + type: integer + stop: + properties: + protocol: + enum: ['trace'] + command: + enum: ['stop'] + payload: + required: ['graph'] + additionalProperties: false + properties: + graph: { $ref: '/shared/graph_id' } + clear: + properties: + protocol: + enum: ['trace'] + command: + enum: ['clear'] + payload: + required: ['graph'] + additionalProperties: false + properties: + graph: { $ref: '/shared/graph_id' } +output: start: id: 'output/start' description: 'Tracing was started' - $ref: '../input/start' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/start' stop: id: 'output/stop' description: 'Tracing was stopped' - $ref: '../input/stop' + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/stop' clear: id: 'output/clear' description: 'Tracing buffer was cleared' - $ref: '../input/clear' - + allOf: + - $ref: '/shared/output_message' + - $ref: '../messages/clear' dump: id: 'output/dump' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['trace'] @@ -40,12 +82,11 @@ output: flowtrace: description: A Flowtrace file of `type` type: string - error: id: 'output/error' description: 'Error response to a command on trace protocol' allOf: - - $ref: '/shared/message' + - $ref: '/shared/output_message' - properties: protocol: enum: ['trace'] @@ -63,42 +104,21 @@ input: id: 'input/start' description: 'Enable/start tracing of a network.' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['trace'] - command: - enum: ['start'] - payload: - required: ['graph'] - additionalProperties: false - properties: - graph: { $ref: '/shared/graph_id' } - buffersize: - description: 'Size of tracing buffer to keep. In bytes' - type: integer + - $ref: '/shared/input_message' + - $ref: '../messages/start' stop: description: 'Stop/disable tracing of a network.' id: 'input/stop' allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['trace'] - command: - enum: ['stop'] - payload: - required: ['graph'] - additionalProperties: false - properties: - graph: { $ref: '/shared/graph_id' } + - $ref: '/shared/input_message' + - $ref: '../messages/stop' dump: id: 'input/dump' description: 'Trigger dumping of the current tracing buffer, to return it back to server.' allOf: - - $ref: '/shared/message' + - $ref: '/shared/input_message' - properties: protocol: enum: ['trace'] @@ -118,14 +138,5 @@ input: id: 'input/clear' description: Clear current tracing buffer. allOf: - - $ref: '/shared/message' - - properties: - protocol: - enum: ['trace'] - command: - enum: ['clear'] - payload: - required: ['graph'] - additionalProperties: false - properties: - graph: { $ref: '/shared/graph_id' } + - $ref: '/shared/input_message' + - $ref: '../messages/clear' From 2a292b157855ebe5c11b515e9482bf75ed92e076 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 17:41:54 +0200 Subject: [PATCH 03/19] Introduce requestId and responseTo --- schema/yaml/shared.yml | 8 +++++++- spec/protocol.js.md | 1 + 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/schema/yaml/shared.yml b/schema/yaml/shared.yml index a067e6d..98483a8 100644 --- a/schema/yaml/shared.yml +++ b/schema/yaml/shared.yml @@ -11,7 +11,7 @@ input_message: id: 'message' description: 'protocol message' additionalProperties: false - required: ['protocol', 'command', 'payload'] + required: ['protocol', 'command', 'payload', 'requestId'] properties: protocol: type: string @@ -27,6 +27,9 @@ input_message: secret: type: string description: access token to authorize the client + requestId: + type: string + description: unique request identifier output_message: id: 'message' @@ -45,6 +48,9 @@ output_message: payload: type: object description: 'content of message' + responseTo: + type: string + description: unique identifier of the request message is response to metadata_node: id: 'metadata_node' diff --git a/spec/protocol.js.md b/spec/protocol.js.md index 0577adc..7115c0a 100644 --- a/spec/protocol.js.md +++ b/spec/protocol.js.md @@ -35,6 +35,7 @@ The [fbp-protocol](https://github.com/flowbased/fbp-protocol) tool provides a se * 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 From a29bcfd5307c415a88d8260ffc8e0bd72555b98b Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 17:44:53 +0200 Subject: [PATCH 04/19] Linting fixes --- schema/yaml/component.yml | 1 + schema/yaml/graph.yml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/schema/yaml/component.yml b/schema/yaml/component.yml index 77eb370..ba1741e 100644 --- a/schema/yaml/component.yml +++ b/schema/yaml/component.yml @@ -57,6 +57,7 @@ output: componentsready: id: 'output/componentsready' description: Indication that a component listing has finished + allOf: - $ref: '/shared/output_message' - properties: protocol: diff --git a/schema/yaml/graph.yml b/schema/yaml/graph.yml index bd5d521..e7f9ccd 100644 --- a/schema/yaml/graph.yml +++ b/schema/yaml/graph.yml @@ -329,7 +329,7 @@ messages: description: 'the exported name of the port to remove' graph: type: string - description: 'graph the action targets' + description: 'graph the action targets' renameoutport: properties: protocol: From 3d36b5b415d21a933875c836151ca2cb391e603e Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 20:36:49 +0200 Subject: [PATCH 05/19] Add serve command for serving docs --- package.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/package.json b/package.json index 37ee948..4d95473 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ "fbp-test": "./bin/fbp-test" }, "scripts": { + "serve": "http-server dist", "test": "grunt test" }, "dependencies": { @@ -37,6 +38,7 @@ "grunt-jekyll": "^0.4.4", "grunt-mocha-test": "^0.13.2", "grunt-yaml": "^0.4.2", + "http-server": "^0.11.1", "noflo-core": "^0.5.0", "noflo-nodejs": "^0.10.0" }, From 57ae9a2156cac659b310147f7e764b623f24e707 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 20:37:57 +0200 Subject: [PATCH 06/19] Make refs deferenceable --- schema/yaml/component.yml | 42 ++++---- schema/yaml/graph.yml | 204 +++++++++++++++++++------------------- schema/yaml/network.yml | 52 +++++----- schema/yaml/runtime.yml | 22 ++-- schema/yaml/shared.yml | 8 +- schema/yaml/trace.yml | 40 ++++---- 6 files changed, 185 insertions(+), 183 deletions(-) diff --git a/schema/yaml/component.yml b/schema/yaml/component.yml index ba1741e..2efba53 100644 --- a/schema/yaml/component.yml +++ b/schema/yaml/component.yml @@ -6,7 +6,7 @@ output: id: 'output/error' description: 'Error response to a command on component protocol' allOf: - - $ref: '/shared/output_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/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['component'] @@ -50,28 +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 allOf: - - $ref: '/shared/output_message' + - $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 + 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' @@ -80,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/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['component'] @@ -118,7 +118,7 @@ input: Request a list of currently available components. Will be responded with a set of `component` messages. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['component'] @@ -133,7 +133,7 @@ input: Request for the source code of a given component. Will be responded with a `source` message. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['component'] @@ -155,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/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['component'] diff --git a/schema/yaml/graph.yml b/schema/yaml/graph.yml index e7f9ccd..62045e6 100644 --- a/schema/yaml/graph.yml +++ b/schema/yaml/graph.yml @@ -6,6 +6,7 @@ description: >- messages: error: + id: 'messages/error' properties: protocol: enum: ['graph'] @@ -18,6 +19,7 @@ messages: type: 'string' description: 'Error message describing what went wrong' clear: + id: 'messages/clear' properties: protocol: enum: ['graph'] @@ -66,7 +68,7 @@ messages: description: 'component name used for the node' metadata: description: 'structure of key-value pairs for node metadata' - $ref: '/shared/metadata_node' + $ref: '#/shared/metadata_node' graph: type: string description: 'graph the action targets' @@ -120,7 +122,7 @@ messages: description: 'identifier for the node' metadata: description: 'structure of key-value pairs for node metadata' - $ref: '/shared/metadata_node' + $ref: '#/shared/metadata_node' graph: type: string description: 'graph the action targets' @@ -135,14 +137,14 @@ messages: additionalProperties: false properties: src: - $ref: '/shared/port' + $ref: '#/shared/port' description: 'source node for the edge' tgt: - $ref: '/shared/port' + $ref: '#/shared/port' description: 'target node for the edge' metadata: description: 'Structure of key-value pairs for edge metadata' - $ref: '/shared/metadata_edge' + $ref: '#/shared/metadata_edge' graph: type: string description: 'graph the action targets' @@ -161,10 +163,10 @@ messages: description: 'graph the action targets' src: description: 'source node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' tgt: description: 'target node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' changeedge: properties: protocol: @@ -180,13 +182,13 @@ messages: description: 'graph the action targets' metadata: description: 'struct of key-value pairs for edge metadata' - $ref: '/shared/metadata_edge' + $ref: '#/shared/metadata_edge' src: description: 'source node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' tgt: description: 'target node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' addinitial: properties: protocol: @@ -203,13 +205,13 @@ messages: metadata: type: object description: 'structure of key-value pairs for IIP metadata' - $ref: '/shared/metadata_edge' + $ref: '#/shared/metadata_edge' src: description: 'source data for the edge' - $ref: '/shared/iip' + $ref: '#/shared/iip' tgt: description: 'target node/port for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' removeinitial: properties: protocol: @@ -222,9 +224,9 @@ messages: properties: src: description: 'IIP data' - $ref: '/shared/iip' + $ref: '#/shared/iip' tgt: - $ref: '/shared/port' + $ref: '#/shared/port' description: 'target node/port for the edge' graph: type: string @@ -250,7 +252,7 @@ messages: description: 'internal port name' metadata: description: 'structure of key-value pairs for node metadata' - $ref: '/shared/metadata_node' + $ref: '#/shared/metadata_node' graph: type: string description: 'graph the action targets' @@ -310,7 +312,7 @@ messages: description: 'internal port name' metadata: description: 'structure of key-value pairs for port metadata' - $ref: '/shared/metadata_node' + $ref: '#/shared/metadata_node' graph: type: string description: 'graph the action targets' @@ -367,7 +369,7 @@ messages: description: 'an array of node ids part of the group' metadata: description: 'structure of key-value pairs for group metadata' - $ref: '/shared/metadata_group' + $ref: '#/shared/metadata_group' graph: type: string description: 'graph the action targets' @@ -420,7 +422,7 @@ messages: description: 'the group name' metadata: description: 'structure of key-value pairs for group metadata' - $ref: '/shared/metadata_group' + $ref: '#/shared/metadata_group' graph: type: string description: 'graph the action targets' @@ -430,148 +432,148 @@ output: id: 'output/error' description: 'Error response to a command on graph protocol' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/error' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/error' clear: id: 'output/clear' description: 'An empty graph was initialized' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/clear' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/clear' addnode: id: 'output/addnode' description: 'A node was added to a graph.' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/addnode' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/addnode' removenode: id: 'output/removenode' description: 'A node was removed from a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/removenode' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/removenode' renamenode: id: 'output/renamenode' description: 'A node was renamed in a graph.' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/renamenode' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/renamenode' changenode: id: 'output/changenode' description: 'Metadata of a node was changed in a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/changenode' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/changenode' addedge: id: 'output/addedge' description: 'An edge was added to a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/addedge' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/addedge' removeedge: id: 'output/removeedge' description: 'An edge was removed from a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/removeedge' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/removeedge' changeedge: id: 'output/changeedge' description: 'Metadata of an edge was changed in a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/changeedge' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/changeedge' addinitial: id: 'output/addinitial' description: 'An IIP was added to a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/addinitial' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/addinitial' removeinitial: id: 'output/removeinitial' description: 'An IIP was removed from a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/removeinitial' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/removeinitial' addinport: id: 'output/addinport' description: 'An exported inport was added to a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/addinport' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/addinport' removeinport: id: 'output/removeinport' description: 'An exported inport was removed from a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/removeinport' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/removeinport' renameinport: id: 'output/renameinport' description: 'An exported inport was renamed in a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/renameinport' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/renameinport' addoutport: id: 'output/addoutport' description: 'An exported outport was added to a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/addoutport' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/addoutport' removeoutport: id: 'output/removeoutport' description: 'An exported outport was removed from a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/removeoutport' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/removeoutport' renameoutport: id: 'output/renameoutport' description: 'An exported outport was renamed in a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/renameoutport' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/renameoutport' addgroup: id: 'output/addgroup' description: 'A group was added to a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/addgroup' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/addgroup' removegroup: id: 'output/removegroup' description: 'A group was removed from a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/removegroup' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/removegroup' renamegroup: id: 'output/renamegroup' description: 'A group was renamed in a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/renamegroup' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/renamegroup' changegroup: id: 'output/changegroup' description: 'Metadata of a group was changed in a graph' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/changegroup' + - $ref: '#/shared/output_message' + - $ref: '#/graph/messages/changegroup' input: @@ -579,138 +581,138 @@ input: id: 'input/clear' description: 'Initialize an empty graph.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/clear' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/clear' addnode: id: 'input/addnode' description: 'Add node to a graph.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/addnode' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/addnode' removenode: id: 'input/removenode' description: 'Remove a node from a graph.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/removenode' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/removenode' renamenode: id: 'input/renamenode' description: 'Change the ID of a node in the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/renamenode' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/renamenode' changenode: id: 'input/changenode' description: 'Change the metadata associated to a node in the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/changenode' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/changenode' addedge: id: 'input/addedge' description: 'Add an edge to the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/addedge' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/addedge' removeedge: id: 'input/removeedge' description: 'Remove an edge from the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/removeedge' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/removeedge' changeedge: id: 'input/changeedge' description: 'Change an edge''s metadata' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/changeedge' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/changeedge' addinitial: id: 'input/addinitial' description: 'Add an IIP to the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/addinitial' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/addinitial' removeinitial: id: 'input/removeinitial' description: 'Remove an IIP from the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/removeinitial' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/removeinitial' addinport: id: 'input/addinport' description: 'Add an exported inport to the graph.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/addinport' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/addinport' removeinport: id: 'input/removeinport' description: 'Remove an exported port from the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/removeinport' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/removeinport' renameinport: id: 'input/renameinport' description: 'Rename an exported port in the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/renameinport' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/renameinport' addoutport: id: 'input/addoutport' description: 'Add an exported outport to the graph.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/addoutport' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/addoutport' removeoutport: id: 'input/removeoutport' description: 'Remove an exported port from the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/removeoutport' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/removeoutport' renameoutport: id: 'input/renameoutport' description: 'Rename an exported port in the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/renameoutport' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/renameoutport' addgroup: id: 'input/addgroup' description: 'Add a group to the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/addgroup' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/addgroup' removegroup: id: 'input/removegroup' description: 'Remove a group from the graph' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/removegroup' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/removegroup' renamegroup: id: 'input/renamegroup' description: 'Rename a group in the graph.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/renamegroup' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/renamegroup' changegroup: id: 'input/changegroup' description: 'Change a group''s metadata' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/changegroup' + - $ref: '#/shared/input_message' + - $ref: '#/graph/messages/changegroup' diff --git a/schema/yaml/network.yml b/schema/yaml/network.yml index 49ac029..e58b884 100644 --- a/schema/yaml/network.yml +++ b/schema/yaml/network.yml @@ -9,7 +9,7 @@ output: id: 'output/stopped' description: 'Inform that a given network has stopped.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -43,7 +43,7 @@ output: id: 'output/started' description: 'Inform that a given network has been started.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -74,7 +74,7 @@ output: id: 'output/status' description: 'Response to a getstatus message.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -107,7 +107,7 @@ output: of a Unix process, or a line of console.log in JavaScript. Output can also be used for passing images from the runtime to the UI.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -135,7 +135,7 @@ output: An error from a running network, roughly similar to STDERR output of a Unix process, or a line of console.error in JavaScript.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -160,7 +160,7 @@ output: description: >- When in debug mode, a network can signal an error happening inside a process. allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -184,7 +184,7 @@ output: id: 'output/icon' description: 'Icon of a component instance has changed.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -208,21 +208,21 @@ output: id: 'output/connect' description: 'Beginning of transmission on an edge.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] command: enum: ['connect'] payload: - $ref: '/shared/network_event' + $ref: '#/shared/network_event' additionalProperties: false begingroup: id: 'output/begingroup' description: 'Beginning of a group (bracket IP) on an edge.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -230,7 +230,7 @@ output: enum: ['begingroup'] payload: allOf: - - $ref: '/shared/network_event' + - $ref: '#/shared/network_event' - required: ['group'] properties: group: @@ -249,7 +249,7 @@ output: id: 'output/data' description: 'Data transmission on an edge.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -257,7 +257,7 @@ output: enum: ['data'] payload: allOf: - - $ref: '/shared/network_event' + - $ref: '#/shared/network_event' - required: ['data'] properties: data: @@ -286,7 +286,7 @@ output: id: 'output/endgroup' description: 'Ending of a group (bracket IP) on an edge.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] @@ -294,7 +294,7 @@ output: enum: ['endgroup'] payload: allOf: - - $ref: '/shared/network_event' + - $ref: '#/shared/network_event' - required: ['group'] properties: group: @@ -313,14 +313,14 @@ output: id: 'output/disconnect' description: 'End of transmission on an edge.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['network'] command: enum: ['disconnect'] payload: - $ref: '/shared/network_event' + $ref: '#/shared/network_event' additionalProperties: false edges: @@ -328,7 +328,7 @@ output: description: >- List of edges user has selected for inspection in a user interface or debugger, sent from runtime to UI. - $ref: '../input/edges' + $ref: '#/network/input/edges' input: @@ -336,7 +336,7 @@ input: id: 'input/start' description: 'Start execution of a FBP network based on a given graph.' allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['network'] @@ -356,7 +356,7 @@ input: Get the current status of the runtime. The runtime should respond with a status message. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['network'] @@ -374,7 +374,7 @@ input: id: 'input/stop' description: 'Stop execution of a FBP network based on a given graph.' allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['network'] @@ -395,7 +395,7 @@ input: so that they are available between restarts. Requires the network:persist capability. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['network'] @@ -410,7 +410,7 @@ input: id: 'input/debug' description: Set a network into debug mode allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['network'] @@ -433,7 +433,7 @@ input: List of edges user has selected for inspection in a user interface or debugger, sent from UI to a runtime. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['network'] @@ -456,7 +456,7 @@ input: properties: src: description: 'source node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' tgt: description: 'target node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' diff --git a/schema/yaml/runtime.yml b/schema/yaml/runtime.yml index 75c8f68..3bff705 100644 --- a/schema/yaml/runtime.yml +++ b/schema/yaml/runtime.yml @@ -13,7 +13,7 @@ input: able to speak the full Runtime protocol, it should follow up with a ports message. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['runtime'] @@ -32,7 +32,7 @@ input: These packets can be send from the client to the runtimes input ports, or from runtimes output ports to the client. allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['runtime'] @@ -76,7 +76,7 @@ output: id: 'output/error' description: 'Error response to a command on runtime protocol' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -96,7 +96,7 @@ output: is responsible for sending the up-to-date list of available ports back to client whenever it changes. allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -113,16 +113,16 @@ output: runtime inPorts: description: 'list of input ports of the runtime' - $ref: '/shared/port_definition' + $ref: '#/shared/port_definition' outPorts: description: 'list of output ports of the runtime' - $ref: '/shared/port_definition' + $ref: '#/shared/port_definition' runtime: id: 'output/runtime' description: 'Response from the runtime to the getruntime request.' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -148,11 +148,11 @@ output: description: >- capability strings for things the runtime is able to do. May include things not permitted for this client. - $ref: '/shared/capabilities' + $ref: '#/shared/capabilities' capabilities: description: >- capability strings for things the runtime is able to do for this client. - $ref: '/shared/capabilities' + $ref: '#/shared/capabilities' graph: description: >- ID of the currently configured main graph running @@ -186,7 +186,7 @@ output: id: 'output/packetsent' description: Confirmation that a packet has been sent allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['runtime'] @@ -234,4 +234,4 @@ output: These packets can be send from the client to the runtimes input ports, or from runtimes output ports to the client. - $ref: '../input/packet' + $ref: '#/runtime/input/packet' diff --git a/schema/yaml/shared.yml b/schema/yaml/shared.yml index 98483a8..39c7674 100644 --- a/schema/yaml/shared.yml +++ b/schema/yaml/shared.yml @@ -9,7 +9,7 @@ graph_id: input_message: id: 'message' - description: 'protocol message' + description: 'protocol message sent by a client' additionalProperties: false required: ['protocol', 'command', 'payload', 'requestId'] properties: @@ -33,7 +33,7 @@ input_message: output_message: id: 'message' - description: 'protocol message' + description: 'protocol message sent by a runtime' additionalProperties: false required: ['protocol', 'command', 'payload'] properties: @@ -171,10 +171,10 @@ network_event: a FBP language line src: description: 'source node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' tgt: description: 'target node for the edge' - $ref: '/shared/port' + $ref: '#/shared/port' graph: type: 'string' description: 'graph the action targets' diff --git a/schema/yaml/trace.yml b/schema/yaml/trace.yml index 060f69d..cc1548c 100644 --- a/schema/yaml/trace.yml +++ b/schema/yaml/trace.yml @@ -15,7 +15,7 @@ messages: required: ['graph'] additionalProperties: false properties: - graph: { $ref: '/shared/graph_id' } + graph: { $ref: '#/shared/graph_id' } buffersize: description: 'Size of tracing buffer to keep. In bytes' type: integer @@ -29,7 +29,7 @@ messages: required: ['graph'] additionalProperties: false properties: - graph: { $ref: '/shared/graph_id' } + graph: { $ref: '#/shared/graph_id' } clear: properties: protocol: @@ -40,31 +40,31 @@ messages: required: ['graph'] additionalProperties: false properties: - graph: { $ref: '/shared/graph_id' } + graph: { $ref: '#/shared/graph_id' } output: start: id: 'output/start' description: 'Tracing was started' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/start' + - $ref: '#/shared/output_message' + - $ref: '#/trace/messages/start' stop: id: 'output/stop' description: 'Tracing was stopped' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/stop' + - $ref: '#/shared/output_message' + - $ref: '#/trace/messages/stop' clear: id: 'output/clear' description: 'Tracing buffer was cleared' allOf: - - $ref: '/shared/output_message' - - $ref: '../messages/clear' + - $ref: '#/shared/output_message' + - $ref: '#/trace/messages/clear' dump: id: 'output/dump' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['trace'] @@ -74,7 +74,7 @@ output: required: ['graph', 'type', 'flowtrace'] additionalProperties: false properties: - graph: { $ref: '/shared/graph_id' } + graph: { $ref: '#/shared/graph_id' } type: description: String describing type of trace. type: string @@ -86,7 +86,7 @@ output: id: 'output/error' description: 'Error response to a command on trace protocol' allOf: - - $ref: '/shared/output_message' + - $ref: '#/shared/output_message' - properties: protocol: enum: ['trace'] @@ -104,21 +104,21 @@ input: id: 'input/start' description: 'Enable/start tracing of a network.' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/start' + - $ref: '#/shared/input_message' + - $ref: '#/trace/messages/start' stop: description: 'Stop/disable tracing of a network.' id: 'input/stop' allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/stop' + - $ref: '#/shared/input_message' + - $ref: '#/trace/messages/stop' dump: id: 'input/dump' description: 'Trigger dumping of the current tracing buffer, to return it back to server.' allOf: - - $ref: '/shared/input_message' + - $ref: '#/shared/input_message' - properties: protocol: enum: ['trace'] @@ -128,7 +128,7 @@ input: required: ['graph', 'type'] additionalProperties: false properties: - graph: { $ref: '/shared/graph_id' } + graph: { $ref: '#/shared/graph_id' } type: description: Type/format of trace to output type: string @@ -138,5 +138,5 @@ input: id: 'input/clear' description: Clear current tracing buffer. allOf: - - $ref: '/shared/input_message' - - $ref: '../messages/clear' + - $ref: '#/shared/input_message' + - $ref: '#/trace/messages/clear' From 5016591253ff55b923d6321e9c7e068d890f2730 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 20:38:29 +0200 Subject: [PATCH 07/19] Dereference with a proper library --- Gruntfile.coffee | 25 +++++++++------ package.json | 1 + src/Documentation.coffee | 67 ++++++++++++---------------------------- 3 files changed, 36 insertions(+), 57 deletions(-) diff --git a/Gruntfile.coffee b/Gruntfile.coffee index 7f4fc01..fed30bb 100644 --- a/Gruntfile.coffee +++ b/Gruntfile.coffee @@ -143,15 +143,22 @@ 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) -> + + 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() diff --git a/package.json b/package.json index 4d95473..1003504 100644 --- a/package.json +++ b/package.json @@ -39,6 +39,7 @@ "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" }, diff --git a/src/Documentation.coffee b/src/Documentation.coffee index 2a902a4..c544aee 100644 --- a/src/Documentation.coffee +++ b/src/Documentation.coffee @@ -1,8 +1,9 @@ fs = require 'fs' path = require 'path' +refParser = require 'json-schema-ref-parser' schemas = null -getSchemas = -> +getSchemas = (callback) -> unless schemas schemas = {} dir = './schema/json/' @@ -12,34 +13,10 @@ getSchemas = -> filename = path.join dir, jsonFile schema = JSON.parse fs.readFileSync filename schemas[name] = schema - - return schemas - -fillRefs = (obj, baseUrl) -> - tv4 = require '../schema/index.js' - - if typeof obj isnt 'object' - return obj - - else if (typeof obj) is 'object' and obj.length? - return obj.map (item) -> fillRefs item, baseUrl - - newObj = {} - for own key, value of obj - if key is '$ref' - schemaPath = value - if schemaPath.indexOf('../') isnt -1 - schemaPath = path.resolve path.dirname("#{baseUrl}#{obj.id}"), value - refObj = fillRefs tv4.getSchema(schemaPath), baseUrl - for own refKey, refValue of refObj - newObj[refKey] = refValue - - else - newObj[key] = fillRefs value, baseUrl - - return newObj + refParser.dereference schemas, callback mergeAllOf = (obj) -> + return obj unless obj unless typeof obj is "object" and not obj.length? return obj @@ -50,11 +27,7 @@ mergeAllOf = (obj) -> for propName, prop of mergeObj newObj[propName] ?= prop - else if typeof value is "object" and not value.length? - newObj[key] = mergeAllOf value - - else - newObj[key] = value + newObj[key] = mergeAllOf value return newObj @@ -78,7 +51,6 @@ getDescriptions = (schemas) -> for category in categories for event, schema of schemas[protocol][category] - schema = fillRefs schema, "/#{protocol}/" message = id: schema.id description: schema.description @@ -95,10 +67,8 @@ getDescriptions = (schemas) -> return desc isAllowedTypeless = (name, parent) -> - return true if parent.id is '/shared/port_definition' and name is 'default' - return true if parent.id is '/runtime/input/packet' and name is 'payload' + return true if parent.id is 'port_definition' and name is 'default' return true if parent.id is 'input/packet' and name is 'payload' - return true if parent.id is '/runtime/output/packet' and name is 'payload' return true if parent.id is 'output/packet' and name is 'payload' return true if parent.id is 'output/packetsent' and name is 'payload' false @@ -203,22 +173,23 @@ renderCapabilities = () -> return lines.join('\n') -renderMessages = () -> - schemas = getSchemas() - descriptions = getDescriptions schemas +renderMessages = (callback) -> + getSchemas (err, schemas) -> + return callback err if err + descriptions = getDescriptions schemas - lines = [] - p = (line) -> lines.push line + lines = [] + p = (line) -> lines.push line - for protocol, protocolProps of descriptions - p "

#{protocolProps.title}

" - p "

#{protocolProps.description}

" + for protocol, protocolProps of descriptions + p "

#{protocolProps.title}

" + p "

#{protocolProps.description}

" - for messageType, message of protocolProps.messages - m = renderMessage messageType, message, protocol - lines = lines.concat m + for messageType, message of protocolProps.messages + m = renderMessage messageType, message, protocol + lines = lines.concat m - return lines.join('\n') + callback null, lines.join('\n') module.exports = renderMessages: renderMessages From 4ab9a88e22897362f3cc96c207107cf6a0822404 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 20:49:08 +0200 Subject: [PATCH 08/19] Include request IDs --- package.json | 3 ++- test/schema/test_component.coffee | 5 ++++- test/schema/test_graph.coffee | 32 +++++++++++++++++++++++++++++++ test/schema/test_network.coffee | 8 ++++++++ test/schema/test_runtime.coffee | 4 ++++ test/schema/test_trace.coffee | 15 +++++++++++++++ 6 files changed, 65 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 1003504..8220dba 100644 --- a/package.json +++ b/package.json @@ -41,7 +41,8 @@ "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" } diff --git a/test/schema/test_component.coffee b/test/schema/test_component.coffee index 72c238d..0650210 100644 --- a/test/schema/test_component.coffee +++ b/test/schema/test_component.coffee @@ -1,6 +1,7 @@ chai = require 'chai' schemas = require '../../schema/schemas.js' tv4 = require 'tv4' +uuid = require 'uuid/v4' describe 'Test component protocol schema on event', -> before -> @@ -78,6 +79,7 @@ describe 'Test component protocol schema on event', -> protocol: 'component' command: 'list' payload: {} + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.true @@ -94,6 +96,7 @@ describe 'Test component protocol schema on event', -> command: 'getsource' payload: name: 'component1' + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.true @@ -112,7 +115,7 @@ describe 'Test component protocol schema on event', -> name: 'component1' language: 'coffeescript' code: '-> console.log Array.prototype.slice.call arguments' + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.true - diff --git a/test/schema/test_graph.coffee b/test/schema/test_graph.coffee index 5d4d903..00eacc7 100644 --- a/test/schema/test_graph.coffee +++ b/test/schema/test_graph.coffee @@ -1,6 +1,7 @@ chai = require 'chai' schemas = require '../../schema/schemas.js' tv4 = require 'tv4' +uuid = require 'uuid/v4' describe 'Test graph protocol schema on event', -> before -> @@ -27,6 +28,7 @@ describe 'Test graph protocol schema on event', -> id: 'node1' component: 'core/Kick' graph: 'mygraph' + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.true @@ -40,6 +42,7 @@ describe 'Test graph protocol schema on event', -> component: 'core/Kick' graph: 'mygraph' whatisthis: 'notallowed' + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.false @@ -51,6 +54,7 @@ describe 'Test graph protocol schema on event', -> id: 'node1' component: 'core/Kick' graph: 'mygraph' + requestId: uuid() res = tv4.validate event, schema @@ -63,6 +67,7 @@ describe 'Test graph protocol schema on event', -> id: 'node1' component: 'core/Kick' graph: 'mygraph' + requestId: uuid() describe 'removenode', -> schema = '/graph/input/removenode' @@ -81,6 +86,7 @@ describe 'Test graph protocol schema on event', -> payload: id: 'node1' graph: 'mygraph' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -102,6 +108,7 @@ describe 'Test graph protocol schema on event', -> from: 'node1' to: 'node2' graph: 'mygraph' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -125,6 +132,7 @@ describe 'Test graph protocol schema on event', -> metadata: x: 5 y: -1000 + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -135,6 +143,7 @@ describe 'Test graph protocol schema on event', -> payload: id: 'node1' graph: 'mygraph' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -160,6 +169,7 @@ describe 'Test graph protocol schema on event', -> tgt: node: 'node2' port: 'IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -173,6 +183,7 @@ describe 'Test graph protocol schema on event', -> port: 'OUT' tgt: port: 'IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -198,6 +209,7 @@ describe 'Test graph protocol schema on event', -> tgt: node: 'node2' port: 'IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -225,6 +237,7 @@ describe 'Test graph protocol schema on event', -> port: 'IN' metadata: route: 1 + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -249,6 +262,7 @@ describe 'Test graph protocol schema on event', -> tgt: node: 'node2' port: 'IN' + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.missing).to.eql [] @@ -265,6 +279,7 @@ describe 'Test graph protocol schema on event', -> tgt: port: 'IN' node: 'node2' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -287,6 +302,7 @@ describe 'Test graph protocol schema on event', -> tgt: node: 'node2' port: 'IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -301,6 +317,7 @@ describe 'Test graph protocol schema on event', -> tgt: node: 'node2' port: 'IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -323,6 +340,7 @@ describe 'Test graph protocol schema on event', -> public: 'IN' node: 'core/Kick' port: 'DATA' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -336,6 +354,7 @@ describe 'Test graph protocol schema on event', -> node: 'core/Kick' port: 'DATA' extra: 'doesntwork' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -356,6 +375,7 @@ describe 'Test graph protocol schema on event', -> payload: graph: 'mygraph' public: 'IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -368,6 +388,7 @@ describe 'Test graph protocol schema on event', -> public: 'IN' node: 'core/Kick' port: 'DATA' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -389,6 +410,7 @@ describe 'Test graph protocol schema on event', -> graph: 'mygraph' from: 'IN' to: 'MORE_IN' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -411,6 +433,7 @@ describe 'Test graph protocol schema on event', -> public: 'OUT' node: 'core/Repeat' port: 'OUT' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -424,6 +447,7 @@ describe 'Test graph protocol schema on event', -> node: 'core/Repeat' port: 'OUT' extra: 'doesntwork' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -444,6 +468,7 @@ describe 'Test graph protocol schema on event', -> payload: graph: 'mygraph' public: 'OUT' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -456,6 +481,7 @@ describe 'Test graph protocol schema on event', -> public: 'OUT' node: 'core/Kick' port: 'DATA' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -477,6 +503,7 @@ describe 'Test graph protocol schema on event', -> graph: 'mygraph' from: 'OUT' to: 'MORE_OUT' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -498,6 +525,7 @@ describe 'Test graph protocol schema on event', -> graph: 'mygraph' name: 'mygroup' nodes: ['Kick', 'Drop'] + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -510,6 +538,7 @@ describe 'Test graph protocol schema on event', -> name: 'mygroup' nodes: ['Kick', 'Drop'] extra: 'nope' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.false @@ -530,6 +559,7 @@ describe 'Test graph protocol schema on event', -> payload: graph: 'mygraph' name: 'mygroup' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -551,6 +581,7 @@ describe 'Test graph protocol schema on event', -> graph: 'mygraph' from: 'mygroup' to: 'yourgroup' + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true @@ -572,5 +603,6 @@ describe 'Test graph protocol schema on event', -> graph: 'mygraph' name: 'mygroup' metadata: {} + requestId: uuid() chai.expect(tv4.validate event, schema).to.be.true diff --git a/test/schema/test_network.coffee b/test/schema/test_network.coffee index 49e0344..773e243 100644 --- a/test/schema/test_network.coffee +++ b/test/schema/test_network.coffee @@ -1,6 +1,7 @@ chai = require 'chai' schemas = require '../../schema/schemas.js' tv4 = require 'tv4' +uuid = require 'uuid/v4' format = require '../../schema/format' describe 'Test network protocol schema on events', -> @@ -373,6 +374,7 @@ describe 'Test network protocol schema on events', -> command: 'start' payload: graph: 'start' + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] @@ -391,6 +393,7 @@ describe 'Test network protocol schema on events', -> command: 'getstatus' payload: graph: 'mygraph' + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] @@ -409,6 +412,7 @@ describe 'Test network protocol schema on events', -> command: 'getstatus' payload: graph: 'mygraph' + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] @@ -427,6 +431,7 @@ describe 'Test network protocol schema on events', -> command: 'stop' payload: graph: 'mygraph' + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] @@ -444,6 +449,7 @@ describe 'Test network protocol schema on events', -> protocol: 'network' command: 'persist' payload: {} + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] @@ -463,6 +469,7 @@ describe 'Test network protocol schema on events', -> payload: enable: true graph: 'mygraph' + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] @@ -490,6 +497,7 @@ describe 'Test network protocol schema on events', -> port: 'IN' index: 0 ] + requestId: uuid() res = tv4.validateMultiple event, schema chai.expect(res.errors).to.eql [] diff --git a/test/schema/test_runtime.coffee b/test/schema/test_runtime.coffee index 5f796c9..c7a592c 100644 --- a/test/schema/test_runtime.coffee +++ b/test/schema/test_runtime.coffee @@ -1,6 +1,7 @@ chai = require 'chai' schemas = require '../../schema/schemas.js' tv4 = require 'tv4' +uuid = require 'uuid/v4' describe 'Test runtime protocol schema on event', -> before -> @@ -22,6 +23,7 @@ describe 'Test runtime protocol schema on event', -> protocol: 'runtime' command: 'getruntime' payload: {} + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.true @@ -40,6 +42,7 @@ describe 'Test runtime protocol schema on event', -> port: 'IN' graph: 'mygraph' event: 'connect' + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.true @@ -52,6 +55,7 @@ describe 'Test runtime protocol schema on event', -> port: 'IN' graph: 'mygraph' event: 'bad event' + requestId: uuid() res = tv4.validate event, schema chai.expect(res).to.be.false diff --git a/test/schema/test_trace.coffee b/test/schema/test_trace.coffee index 6e4b2a5..35831ba 100644 --- a/test/schema/test_trace.coffee +++ b/test/schema/test_trace.coffee @@ -1,6 +1,7 @@ chai = require 'chai' schemas = require '../../schema/schemas.js' tv4 = require 'tv4' +uuid = require 'uuid/v4' validExamples = 'start recording': @@ -9,6 +10,7 @@ validExamples = payload: graph: 'mygraph' secret: 'verygood' + requestId: uuid() 'dump flowtrace.json': protocol: 'trace' command: 'dump' @@ -16,18 +18,21 @@ validExamples = graph: 'mygraph' type: 'flowtrace.json' secret: 'verygood' + requestId: uuid() 'clear buffer': protocol: 'trace' command: 'clear' payload: graph: 'mygraph' secret: 'verygood' + requestId: uuid() 'stop recording': protocol: 'trace' command: 'stop' payload: graph: 'mygraph' secret: 'verygood' + requestId: uuid() invalidExamples = 'start with invalid graph id': @@ -36,6 +41,7 @@ invalidExamples = payload: graph: 112.0 secret: 'nnice' + requestId: uuid() 'dump with invalid type': protocol: 'trace' command: 'dump' @@ -43,18 +49,27 @@ invalidExamples = graph: 'mygraph' type: 'not-a-valid-trace-type' secret: 'verygood' + requestId: uuid() 'stop with missing secret': protocol: 'trace' command: 'start' payload: graph: 112.0 secret: undefined + requestId: uuid() 'clear without graph': protocol: 'trace' command: 'start' payload: graph: undefined secret: 'verygood' + requestId: uuid() + 'start without requestId': + protocol: 'trace' + command: 'start' + payload: + graph: 'mygraph' + secret: 'verygood' testValid = (name) -> describe name, -> From d8271877297fe0ec30dbc4090cfa6dfe6b467286 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:00:13 +0200 Subject: [PATCH 09/19] Improve message structure docs --- spec/protocol.js.md | 84 ++++++++++++++++++++++++++++++--------------- 1 file changed, 57 insertions(+), 27 deletions(-) diff --git a/spec/protocol.js.md b/spec/protocol.js.md index 7115c0a..1f87836 100644 --- a/spec/protocol.js.md +++ b/spec/protocol.js.md @@ -117,6 +117,63 @@ There are currently three transports utilized commonly: Different transports can be utilized as needed. It could be interesting to implement the FBP protocol using [MQTT](http://en.wikipedia.org/wiki/MQ_Telemetry_Transport), for instance. +### Message structure + +There are three types of messages in FBP Protocol: + +1. Requests sent by client to runtime +2. Responses sent by runtime to client +3. Events sent by runtime to client unrelated to any request + +This document describes all messages as the data structures that are passed. The way these are encoded depends on the transport being used. For example, with WebSockets all messages are encoded as stringified JSON. + +All messages consist of three parts: + +* Sub-protocol identifier (`graph`, `component`, or `network`) +* Topic (for example, `addnode`) +* Message payload (typically a data structure specific to the sub-protocol and topic) + +Additionally requests made by clients include a unique `requestId` and optionally a `secret`. Responses sent by runtime include a `responseTo` referring to a request ID. Runtimes may also send messages on events that happen on the runtime without referring to a request ID. + +The keys listed in specific messages are for the message `payload`. + +An example message sent by a client: + +```json +{ + "protocol": "graph", + "command": "addnode", + "payload": { + "component": "canvas/Draw", + "graph": "hello-canvas-example", + "id": "draw", + "metadata": { + "label": "Draw onto canvas element" + } + }, + "secret": "fbp rocks", + "requestId: "10259710-bc70-4d2c-b0b3-e78075d9b960" +} +``` + +Response to this could look like: + +```json +{ + "protocol": "graph", + "command": "addnode", + "payload": { + "component": "canvas/Draw", + "graph": "hello-canvas-example", + "id": "draw", + "metadata": { + "label": "Draw onto canvas element" + } + }, + "responseTo: "10259710-bc70-4d2c-b0b3-e78075d9b960" +} +``` + ### Sub-protocols The FBP protocol is divided into sub-protocols for each of the major resources that can be manipulated: @@ -137,31 +194,4 @@ A few commands do not require any capabilities: the runtime info request/respons <%= capabilities %> -### Message structure - -This document describes all messages as the data structures that are passed. The way these are encoded depends on the transport being used. For example, with WebSockets all messages are encoded as stringified JSON. - -All messages consist of three parts: - -* Sub-protocol identifier (`graph`, `component`, or `network`) -* Topic (for example, `addnode`) -* Message payload (typically a data structure specific to the sub-protocol and topic) - -The keys listed in specific messages are for the message `payload`. - -An example message -``` -"protocol": "graph", -"command": "addnode", -"payload": { - "component": "canvas/Draw", - "graph": "hello-canvas-example", - "id": "draw", - "metadata": { - "label": "Draw onto canvas element" - } -} -``` - <%= messages %> - From a655b7b1d3ac5a19f61846d2f9473d0564d871e6 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:01:51 +0200 Subject: [PATCH 10/19] Move changelog to the end --- spec/protocol.js.md | 149 ++++++++++++++++++++++---------------------- 1 file changed, 75 insertions(+), 74 deletions(-) diff --git a/spec/protocol.js.md b/spec/protocol.js.md index 1f87836..ae4d9e5 100644 --- a/spec/protocol.js.md +++ b/spec/protocol.js.md @@ -31,80 +31,6 @@ Some [examples](https://github.com/flowbased/protocol-examples) have also been c The [fbp-protocol](https://github.com/flowbased/fbp-protocol) tool provides a set of tests for FBP protocol implementations. -## 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 - ## Basics The FBP protocol is a message-based protocol that can be handled using various different transport mechanisms. The messages are designed to be independent, and not to form a request-response cycle in order to allow highly asynchronous operations and situations where multiple protocol clients talk with the same runtime. @@ -195,3 +121,78 @@ A few commands do not require any capabilities: the runtime info request/respons <%= capabilities %> <%= messages %> + +## 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 + From c3166dd71211071488c3636eaa029040b3f8baae Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:04:56 +0200 Subject: [PATCH 11/19] Ignore flowhub.json --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 6548830..bff86b3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ fbp-config.json fbp.json +flowhub.json *.tgz node_modules npm-debug.log From d391403c90776a3b0b639a91a3d67afd22532449 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:05:12 +0200 Subject: [PATCH 12/19] Move ChangeLog to toplevel --- CHANGES.md | 73 +++++++++++++++++++++++++++++++++++++++++++ Gruntfile.coffee | 2 ++ spec/protocol.js.md | 75 +-------------------------------------------- 3 files changed, 76 insertions(+), 74 deletions(-) create mode 100644 CHANGES.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..a2954cf --- /dev/null +++ b/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 diff --git a/Gruntfile.coffee b/Gruntfile.coffee index fed30bb..b29cd7f 100644 --- a/Gruntfile.coffee +++ b/Gruntfile.coffee @@ -156,9 +156,11 @@ module.exports = -> return done err if err capabilities = documentation.renderCapabilities (err, capabilities) -> + 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() diff --git a/spec/protocol.js.md b/spec/protocol.js.md index ae4d9e5..724b2fc 100644 --- a/spec/protocol.js.md +++ b/spec/protocol.js.md @@ -122,77 +122,4 @@ A few commands do not require any capabilities: the runtime info request/respons <%= messages %> -## 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 - +<%= changelog %> From 19659aa90dd2723be5acca909ab551f71bd64e1b Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:11:44 +0200 Subject: [PATCH 13/19] Make protocol links work again --- src/Documentation.coffee | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Documentation.coffee b/src/Documentation.coffee index c544aee..f083c3c 100644 --- a/src/Documentation.coffee +++ b/src/Documentation.coffee @@ -182,7 +182,7 @@ renderMessages = (callback) -> p = (line) -> lines.push line for protocol, protocolProps of descriptions - p "

#{protocolProps.title}

" + p "

#{protocolProps.title}

" p "

#{protocolProps.description}

" for messageType, message of protocolProps.messages From 0b03eaef42a1b63700b8950f62013a0f1261db12 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:27:26 +0200 Subject: [PATCH 14/19] Use shared definition of graph ID --- schema/yaml/graph.yml | 80 +++++++++++------------------------------ schema/yaml/network.yml | 44 ++++++----------------- schema/yaml/runtime.yml | 15 +++----- 3 files changed, 36 insertions(+), 103 deletions(-) diff --git a/schema/yaml/graph.yml b/schema/yaml/graph.yml index 62045e6..5e6ad93 100644 --- a/schema/yaml/graph.yml +++ b/schema/yaml/graph.yml @@ -30,8 +30,8 @@ messages: additionalProperties: false properties: id: - type: string description: 'identifier for the graph being created. Used for all subsequent messages related to the graph instance' + $ref: '#/shared/graph_id' name: type: string description: 'Human-readable label for the graph' @@ -69,9 +69,7 @@ messages: metadata: description: 'structure of key-value pairs for node metadata' $ref: '#/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } removenode: properties: protocol: @@ -85,9 +83,7 @@ messages: id: type: string description: 'identifier for the node' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } renamenode: properties: protocol: @@ -104,9 +100,7 @@ messages: to: type: string description: 'new identifier for the node' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } changenode: properties: protocol: @@ -123,9 +117,7 @@ messages: metadata: description: 'structure of key-value pairs for node metadata' $ref: '#/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } addedge: properties: protocol: @@ -145,9 +137,7 @@ messages: metadata: description: 'Structure of key-value pairs for edge metadata' $ref: '#/shared/metadata_edge' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } removeedge: properties: protocol: @@ -158,15 +148,13 @@ messages: additionalProperties: false required: ['graph', 'src', 'tgt'] properties: - graph: - type: string - description: 'graph the action targets' src: description: 'source node for the edge' $ref: '#/shared/port' tgt: description: 'target node for the edge' $ref: '#/shared/port' + graph: { $ref: '#/shared/graph_id' } changeedge: properties: protocol: @@ -177,9 +165,6 @@ messages: additionalProperties: false required: ['graph', 'src', 'tgt'] properties: - graph: - type: string - description: 'graph the action targets' metadata: description: 'struct of key-value pairs for edge metadata' $ref: '#/shared/metadata_edge' @@ -189,6 +174,7 @@ messages: tgt: description: 'target node for the edge' $ref: '#/shared/port' + graph: { $ref: '#/shared/graph_id' } addinitial: properties: protocol: @@ -199,9 +185,6 @@ messages: additionalProperties: false required: ['graph', 'src', 'tgt'] properties: - graph: - type: string - description: 'graph the action targets' metadata: type: object description: 'structure of key-value pairs for IIP metadata' @@ -212,6 +195,7 @@ messages: tgt: description: 'target node/port for the edge' $ref: '#/shared/port' + graph: { $ref: '#/shared/graph_id' } removeinitial: properties: protocol: @@ -228,9 +212,7 @@ messages: tgt: $ref: '#/shared/port' description: 'target node/port for the edge' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } addinport: properties: protocol: @@ -253,9 +235,7 @@ messages: metadata: description: 'structure of key-value pairs for node metadata' $ref: '#/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } removeinport: properties: protocol: @@ -269,9 +249,7 @@ messages: public: type: string description: 'the exported name of the port to remove' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } renameinport: properties: protocol: @@ -288,9 +266,7 @@ messages: to: type: string description: 'new exported port name' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } addoutport: properties: protocol: @@ -313,9 +289,7 @@ messages: metadata: description: 'structure of key-value pairs for port metadata' $ref: '#/shared/metadata_node' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } removeoutport: properties: protocol: @@ -323,15 +297,13 @@ messages: command: enum: ['removeoutport'] payload: - required: ['public'] + required: ['public', 'graph'] additionalProperties: false properties: public: type: string description: 'the exported name of the port to remove' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } renameoutport: properties: protocol: @@ -348,9 +320,7 @@ messages: to: type: string description: 'new exported port name' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } addgroup: properties: protocol: @@ -370,9 +340,7 @@ messages: metadata: description: 'structure of key-value pairs for group metadata' $ref: '#/shared/metadata_group' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } removegroup: properties: protocol: @@ -386,9 +354,7 @@ messages: name: type: string description: 'the group name' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } renamegroup: properties: protocol: @@ -404,9 +370,7 @@ messages: to: type: string description: 'new group name' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } changegroup: properties: protocol: @@ -423,9 +387,7 @@ messages: metadata: description: 'structure of key-value pairs for group metadata' $ref: '#/shared/metadata_group' - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } output: error: diff --git a/schema/yaml/network.yml b/schema/yaml/network.yml index e58b884..01586cd 100644 --- a/schema/yaml/network.yml +++ b/schema/yaml/network.yml @@ -26,9 +26,7 @@ output: uptime: type: number description: 'time the network was running, in seconds' - graph: - type: "string" - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } running: type: boolean description: 'whether or not network is currently running' @@ -57,9 +55,7 @@ output: type: "string" format: "date-time" description: 'time when the network was started' - graph: - type: "string" - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } started: type: "boolean" description: 'whether or not network has started running' @@ -84,9 +80,7 @@ output: required: ['running', 'graph'] additionalProperties: false properties: - graph: - type: string - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } uptime: type: number description: 'time the network has been running, in seconds' @@ -151,9 +145,7 @@ output: stack: description: 'stack trace' type: 'string' - graph: - type: string - description: graph the action targets + graph: { $ref: '#/shared/graph_id' } processerror: id: 'output/processerror' @@ -176,9 +168,7 @@ output: error: type: string description: error from the component - graph: - type: string - description: graph the action targets + graph: { $ref: '#/shared/graph_id' } icon: id: 'output/icon' @@ -200,9 +190,7 @@ output: icon: type: "string" description: 'new icon for the component instance' - graph: - type: "string" - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } connect: id: 'output/connect' @@ -346,9 +334,7 @@ input: required: ['graph'] additionalProperties: false properties: - graph: - type: "string" - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } getstatus: id: 'input/getstatus' @@ -366,9 +352,7 @@ input: required: ['graph'] additionalProperties: false properties: - graph: - type: "string" - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } stop: id: 'input/stop' @@ -384,9 +368,7 @@ input: required: ['graph'] additionalProperties: false properties: - graph: - type: "string" - description: 'graph the action targets' + graph: { $ref: '#/shared/graph_id' } persist: id: 'input/persist' @@ -423,9 +405,7 @@ input: enable: description: tells whether to put the network in debug mode type: boolean - graph: - description: graph the action targets - type: string + graph: { $ref: '#/shared/graph_id' } edges: id: 'input/edges' @@ -443,9 +423,6 @@ input: required: ['graph', 'edges'] additionalProperties: false properties: - graph: - description: graph the action targets - type: string edges: type: array description: 'list of selected edges' @@ -460,3 +437,4 @@ input: tgt: description: 'target node for the edge' $ref: '#/shared/port' + graph: { $ref: '#/shared/graph_id' } diff --git a/schema/yaml/runtime.yml b/schema/yaml/runtime.yml index 3bff705..e504cf6 100644 --- a/schema/yaml/runtime.yml +++ b/schema/yaml/runtime.yml @@ -63,13 +63,11 @@ input: format: uri description: 'Link to JSON schema describing the format of the data' example: 'https://example.net/schemas/person.json' - graph: - type: string - description: 'graph the action targets' payload: description: >- payload for the packet. Used only with begingroup (for group names) and data packets + graph: { $ref: '#/shared/graph_id' } output: error: @@ -106,17 +104,13 @@ output: required: ['graph', 'inPorts', 'outPorts'] additionalProperties: false properties: - graph: - type: string - description: >- - ID of the currently configured main graph running on the - runtime inPorts: description: 'list of input ports of the runtime' $ref: '#/shared/port_definition' outPorts: description: 'list of output ports of the runtime' $ref: '#/shared/port_definition' + graph: { $ref: '#/shared/graph_id' } runtime: id: 'output/runtime' @@ -159,6 +153,7 @@ output: on the runtime, if any type: string example: 'service-main' + $ref: '#/shared/graph_id' type: description: 'type of the runtime' type: string @@ -217,13 +212,11 @@ output: format: uri description: 'Link to JSON schema describing the format of the data' example: 'https://example.net/schemas/person.json' - graph: - type: string - description: 'graph the action targeted' payload: description: >- payload for the packet. Used only with begingroup (for group names) and data packets + graph: { $ref: '#/shared/graph_id' } packet: id: 'output/packet' From bb6ffa65753c21694e8c0c3c799dbfd6af09ceea Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:42:59 +0200 Subject: [PATCH 15/19] Shared definitions for port and node IDs --- schema/yaml/graph.yml | 32 ++++++++++++++++++-------------- schema/yaml/network.yml | 6 ++---- schema/yaml/runtime.yml | 5 ++--- schema/yaml/shared.yml | 26 +++++++++++++++++--------- 4 files changed, 39 insertions(+), 30 deletions(-) diff --git a/schema/yaml/graph.yml b/schema/yaml/graph.yml index 5e6ad93..c16aea3 100644 --- a/schema/yaml/graph.yml +++ b/schema/yaml/graph.yml @@ -224,14 +224,13 @@ messages: required: ['public', 'port', 'node', 'graph'] properties: public: - type: string description: 'the exported name of the port' + $ref: '#/shared/port_id' node: - type: string - description: 'node identifier' + $ref: '#/shared/node_id' port: - type: string - description: 'internal port name' + description: 'internal port name in the graph' + $ref: '#/shared/port_id' metadata: description: 'structure of key-value pairs for node metadata' $ref: '#/shared/metadata_node' @@ -247,8 +246,8 @@ messages: additionalProperties: false properties: public: - type: string description: 'the exported name of the port to remove' + $ref: '#/shared/port_id' graph: { $ref: '#/shared/graph_id' } renameinport: properties: @@ -261,11 +260,11 @@ messages: additionalProperties: false properties: from: - type: string description: 'original exported port name' + $ref: '#/shared/port_id' to: - type: string description: 'new exported port name' + $ref: '#/shared/port_id' graph: { $ref: '#/shared/graph_id' } addoutport: properties: @@ -278,14 +277,16 @@ messages: additionalProperties: false properties: public: - type: string description: 'the exported name of the port' + $ref: '#/shared/port_id' + example: out node: - type: string description: 'node identifier' + $ref: '#/shared/node_id' port: - type: string description: 'internal port name' + $ref: '#/shared/port_id' + example: 'out[2]' metadata: description: 'structure of key-value pairs for port metadata' $ref: '#/shared/metadata_node' @@ -301,8 +302,9 @@ messages: additionalProperties: false properties: public: - type: string description: 'the exported name of the port to remove' + $ref: '#/shared/port_id' + example: out graph: { $ref: '#/shared/graph_id' } renameoutport: properties: @@ -315,11 +317,11 @@ messages: additionalProperties: false properties: from: - type: string description: 'original exported port name' + $ref: '#/shared/port_id' to: - type: string description: 'new exported port name' + $ref: '#/shared/port_id' graph: { $ref: '#/shared/graph_id' } addgroup: properties: @@ -337,6 +339,8 @@ messages: nodes: type: array description: 'an array of node ids part of the group' + items: + $ref: '#/shared/node_id' metadata: description: 'structure of key-value pairs for group metadata' $ref: '#/shared/metadata_group' diff --git a/schema/yaml/network.yml b/schema/yaml/network.yml index 01586cd..354fb66 100644 --- a/schema/yaml/network.yml +++ b/schema/yaml/network.yml @@ -163,8 +163,7 @@ output: additionalProperties: false properties: id: - type: string - description: identifier of the node + $ref: '#/shared/node_id' error: type: string description: error from the component @@ -185,8 +184,7 @@ output: additionalProperties: false properties: id: - type: "string" - description: 'identifier of the node' + $ref: '#/shared/node_id' icon: type: "string" description: 'new icon for the component instance' diff --git a/schema/yaml/runtime.yml b/schema/yaml/runtime.yml index e504cf6..1ef4403 100644 --- a/schema/yaml/runtime.yml +++ b/schema/yaml/runtime.yml @@ -43,8 +43,7 @@ input: additionalProperties: false properties: port: - type: string - description: 'port name for the input or output port' + $ref: '#/shared/port_id' event: type: string enum: @@ -192,8 +191,8 @@ output: additionalProperties: false properties: port: - type: string description: 'port name for the input port' + $ref: '#/shared/port_id' event: type: string enum: diff --git a/schema/yaml/shared.yml b/schema/yaml/shared.yml index 39c7674..c4b6c5f 100644 --- a/schema/yaml/shared.yml +++ b/schema/yaml/shared.yml @@ -7,6 +7,18 @@ graph_id: description: Graph identifier the message targets type: string +node_id: + id: node_id + description: Node identifier in a graph + type: string + example: Repeat + +port_id: + id: port_id + description: Port identifier in a component or process + type: string + example: in + input_message: id: 'message' description: 'protocol message sent by a client' @@ -102,11 +114,9 @@ port: additionalProperties: false properties: node: - type: string - description: 'node identifier' + $ref: '#/shared/node_id' port: - type: string - description: 'port name' + $ref: '#/shared/port_id' index: type: ["string", "number"] description: 'connection index, for addressable ports' @@ -120,8 +130,7 @@ port_definition: additionalProperties: false properties: id: - type: string - description: 'port name' + $ref: '#/shared/port_id' type: description: 'port datatype' type: string @@ -176,15 +185,14 @@ network_event: description: 'target node for the edge' $ref: '#/shared/port' graph: - type: 'string' - description: 'graph the action targets' + $ref: '#/shared/graph_id' subgraph: type: 'array' description: >- Subgraph identifier for the event. An array of node IDs. items: - type: string + $ref: '#/shared/node_id' capabilities: id: 'capabilities' From 8317562b18f9c25b75b7f76abe78fc061aec229a Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sat, 18 Aug 2018 21:49:41 +0200 Subject: [PATCH 16/19] Render enums --- src/Documentation.coffee | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/Documentation.coffee b/src/Documentation.coffee index f083c3c..5d83a3e 100644 --- a/src/Documentation.coffee +++ b/src/Documentation.coffee @@ -91,6 +91,10 @@ renderProperty = (name, def, parent) -> classes += " optional" if isOptional name = "" type = "" + + if def.enum?.length + def.description += " (one of: #{def.enum.join(', ')})" + description = "" example = "" example = "#{JSON.stringify(def.example)}" if def.example? From b00c116b20cce270ce8ee1c564cedf4fa6844c22 Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sun, 19 Aug 2018 18:14:09 +0200 Subject: [PATCH 17/19] Allow secret in getruntime so clients can support both old and new runtimes --- schema/yaml/runtime.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/schema/yaml/runtime.yml b/schema/yaml/runtime.yml index 1ef4403..908e679 100644 --- a/schema/yaml/runtime.yml +++ b/schema/yaml/runtime.yml @@ -21,6 +21,10 @@ input: enum: ['getruntime'] payload: required: [] + properties: + secret: + type: string + description: access token to authorize the client. Provided also in payload for compatibility with older runtimes packet: id: 'input/packet' From 218046e79190fece47d18e689d9dadb76fd7d68f Mon Sep 17 00:00:00 2001 From: Henri Bergius Date: Sun, 19 Aug 2018 20:10:49 +0200 Subject: [PATCH 18/19] Allow tests pass with 0.7 runtimes --- schema/yaml/shared.yml | 4 ++++ src/WebSocket.coffee | 8 ++++++++ 2 files changed, 12 insertions(+) diff --git a/schema/yaml/shared.yml b/schema/yaml/shared.yml index c4b6c5f..d812a08 100644 --- a/schema/yaml/shared.yml +++ b/schema/yaml/shared.yml @@ -36,6 +36,10 @@ input_message: payload: type: object description: 'content of message' + properties: + secret: + type: string + description: access token to authorize the client. Legacy location, use toplevel secret instead secret: type: string description: access token to authorize the client diff --git a/src/WebSocket.coffee b/src/WebSocket.coffee index 1152ced..b0bfe29 100644 --- a/src/WebSocket.coffee +++ b/src/WebSocket.coffee @@ -59,6 +59,8 @@ exports.testRuntime = (runtimeType, startServer, stopServer, host='localhost', p send = (protocol, command, payload) -> payload = {} unless payload + # FIXME: Remove from payload once runtimes are on 0.8 + payload.secret = process.env.FBP_PROTOCOL_SECRET connection.sendUTF JSON.stringify protocol: protocol command: command @@ -79,6 +81,10 @@ exports.testRuntime = (runtimeType, startServer, stopServer, host='localhost', p data = JSON.parse message.utf8Data chai.expect(data.protocol).to.be.a 'string' chai.expect(data.command).to.be.a 'string' + + # FIXME: Remove once runtimes are on 0.8 + delete data.payload.secret + # Validate all received packets against schema validateSchema data, getPacketSchema data # Don't ever expect payloads to return a secret @@ -110,6 +116,8 @@ exports.testRuntime = (runtimeType, startServer, stopServer, host='localhost', p delete data.payload.stack delete expected.payload.stack + # FIXME: Remove once runtimes are on 0.8 + delete expected.payload.secret # Don't ever expect payloads to return a secret delete expected.secret From 438d1b04291338060ea16ed52b4bbec36ed9fd8b Mon Sep 17 00:00:00 2001 From: Jon Nordby Date: Mon, 27 Aug 2018 23:07:04 +0200 Subject: [PATCH 19/19] Grunt: Check for error in renderCapabilities() --- Gruntfile.coffee | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Gruntfile.coffee b/Gruntfile.coffee index b29cd7f..b7c6188 100644 --- a/Gruntfile.coffee +++ b/Gruntfile.coffee @@ -155,12 +155,12 @@ module.exports = -> documentation.renderMessages (err, messages) -> return done err if err capabilities = documentation.renderCapabilities (err, capabilities) -> - - 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() + 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()