| 1 | <!DOCTYPE html>
|
| 2 | <html>
|
| 3 | <head>
|
| 4 | <meta charset="utf-8">
|
| 5 | <title>FBP Network Protocol</title>
|
| 6 | <meta name="viewport" content="width=device-width, initial-scale=1.0">
|
| 7 | <meta name="theme-color" content="#ffffff">
|
| 8 | <style type="text/css">
|
| 9 | body {
|
| 10 | color: black !important;
|
| 11 | background-color: hsla( 0, 98%, 100%, .8) !important;
|
| 12 | }
|
| 13 | article {
|
| 14 | max-width: 48em;
|
| 15 | margin-left: auto;
|
| 16 | margin-right: auto;
|
| 17 | font-size: 14pt;
|
| 18 | }
|
| 19 | article h1, article h2 {
|
| 20 | font-family: sans-serif;
|
| 21 | margin-bottom: 0px;
|
| 22 | padding-bottom: 0px;
|
| 23 | }
|
| 24 | article aside {
|
| 25 | border-left: 4px #2f4f4f solid;
|
| 26 | margin-top: 1em;
|
| 27 | padding-left: 1em;
|
| 28 | font-size: smaller;
|
| 29 | font-style: italic;
|
| 30 | }
|
| 31 | a {
|
| 32 | color: #2f4f4f;
|
| 33 | }
|
| 34 | a:hover, a:visited {
|
| 35 | color: #708090;
|
| 36 | }
|
| 37 | .properties li {
|
| 38 | padding-bottom: 5px;
|
| 39 | }
|
| 40 | .property.name {
|
| 41 | font-family: monospace;
|
| 42 | font-weight: 700;
|
| 43 | }
|
| 44 | .property.name::after {
|
| 45 | content: ': ';
|
| 46 | font-weight: 500;
|
| 47 | }
|
| 48 | .property.optional.type::after {
|
| 49 | content: ' (optional)';
|
| 50 | font-weight: 500;
|
| 51 | color: hsla(210, 40%, 70%, 1);
|
| 52 | }
|
| 53 | .property.description {
|
| 54 | display: block;
|
| 55 | }
|
| 56 | .property.example {
|
| 57 | font-family: monospace;
|
| 58 | background-color: hsla(210, 70%, 90%, 1);
|
| 59 | }
|
| 60 | .property.example::before {
|
| 61 | content: 'Example: ';
|
| 62 | background-color: white;
|
| 63 | }
|
| 64 | .enum.name {
|
| 65 | font-family: monospace;
|
| 66 | font-weight: 700;
|
| 67 | }
|
| 68 | .message.name a {
|
| 69 | text-decoration: none;
|
| 70 | }
|
| 71 | .capability.messages {
|
| 72 | margin: 0px;
|
| 73 | }
|
| 74 | .capability.messages li {
|
| 75 | display: inline;
|
| 76 | }
|
| 77 | .capability.messages li::after {
|
| 78 | content: ', '
|
| 79 | }
|
| 80 | .capability.messages.header {
|
| 81 | margin: 5px;
|
| 82 | }
|
| 83 | </style>
|
| 84 | </head>
|
| 85 | <body>
|
| 86 | <article>
|
| 87 | <h1>FBP Network Protocol</h1>
|
| 88 | <aside>
|
| 89 | Last updated 2018-03-30 21:25:14 +0000
|
| 90 | </aside>
|
| 91 | <p>The Flow-Based Programming network protocol (<em>FBP protocol</em>) has been designed primarily for flow-based programming interfaces like the <a href="https://flowhub.io">Flowhub</a> to communicate with various FBP runtimes. However, it can also be utilized for communication between different runtimes, for example server-to-server or server-to-microcontroller.</p>
|
| 92 |
|
| 93 | <h2 id="implementations">Implementations</h2>
|
| 94 |
|
| 95 | <p>Clients</p>
|
| 96 |
|
| 97 | <ul>
|
| 98 | <li><a href="https://github.com/noflo/noflo-ui">noflo-ui</a> is an open source visual IDE, which powers <a href="http://flowhub.io">Flowhub</a></li>
|
| 99 | <li><a href="https://github.com/flowbased/fbp-spec">fbp-spec</a> is a data-driven testing tool for FBP components/graphs.</li>
|
| 100 | <li><a href="https://github.com/flowbased/fbp-protocol-client">fbp-protocol-client</a> is a low-level JavaScript client library supporting all the common FBP protocol transports</li>
|
| 101 | <li><a href="https://github.com/flowbased/fbp-client">fbp-client</a> is a higher-level JavaScript client library supporting all the common FBP protocol transports</li>
|
| 102 | </ul>
|
| 103 |
|
| 104 | <p>Runtimes</p>
|
| 105 |
|
| 106 | <ul>
|
| 107 | <li><a href="https://github.com/noflo/noflo-runtime-base">noflo-runtime-base</a> is a transport-independent implementation of the protocol for <a href="http://noflojs.org">NoFlo</a>, client-side and server-side JavaScript programming. WebSocket, WebRTC and iFrame implementations exists.</li>
|
| 108 | <li><a href="https://github.com/jonnor/microflo">microflo</a> is a WebSocket implementation of the protocol in JS/C++, for microcontrollers and embedded systems</li>
|
| 109 | <li><a href="http://www.elixirfbp.org/">Elixir FBP</a> is a WebSocket implementation in Elixir, for programming with systems in Elixir runnin on the Erlang VM.</li>
|
| 110 | <li><a href="https://github.com/jonnor/imgflo">imgflo</a> is a WebSocket implementation in C, for image processing</li>
|
| 111 | <li><a href="https://github.com/jonnor/javafbp-runtime">javafbp-runtime</a> is a Websocket implementation in Java for <a href="https://github.com/jpaulm/javafbp">JavaFBP</a>, for JRE and Android development</li>
|
| 112 | <li><a href="https://github.com/jonnor/sndflo">sndflo</a> is a WebSocket implementation for the SuperCollider audio programming environment</li>
|
| 113 | <li><a href="https://github.com/the-grid/msgflo">MsgFlo</a> is a Websocket implementation in Node.js for heterogenous distributed systems communicating via message queues</li>
|
| 114 | <li><a href="https://github.com/PermaData/rill">rill</a> is a Python FBP runtime implementation, with support for the protocol over WebSocket.</li>
|
| 115 | </ul>
|
| 116 |
|
| 117 | <p>Some <a href="https://github.com/flowbased/protocol-examples">examples</a> have also been created, to help implementors.</p>
|
| 118 |
|
| 119 | <h2 id="test-suite">Test suite</h2>
|
| 120 |
|
| 121 | <p>The <a href="https://github.com/flowbased/fbp-protocol">fbp-protocol</a> tool provides a set of tests for FBP protocol implementations.</p>
|
| 122 |
|
| 123 | <h2 id="changes">Changes</h2>
|
| 124 |
|
| 125 | <ul>
|
| 126 | <li>2018-03-27:
|
| 127 | <ul>
|
| 128 | <li>Added schema for <code class="highlighter-rouge">network:edges</code> output message</li>
|
| 129 | <li>Modified <code class="highlighter-rouge">subgraph</code> key of <code class="highlighter-rouge">network:data</code> and other network packet events to be an array as specified in the text</li>
|
| 130 | </ul>
|
| 131 | </li>
|
| 132 | <li>2018-03-26:
|
| 133 | <ul>
|
| 134 | <li>Fixed documentation for <code class="highlighter-rouge">component:setsource</code> to use <code class="highlighter-rouge">component:source</code> input, and <code class="highlighter-rouge">component:component</code> output</li>
|
| 135 | <li>Added schema for <code class="highlighter-rouge">trace:error</code> message</li>
|
| 136 | <li>Added <code class="highlighter-rouge">:error</code> output to all capabilities where user can perform actions that may fail</li>
|
| 137 | </ul>
|
| 138 | </li>
|
| 139 | <li>2018-03-23:
|
| 140 | <ul>
|
| 141 | <li>Added optional <code class="highlighter-rouge">graph</code> key to <code class="highlighter-rouge">network:error</code> payloads</li>
|
| 142 | </ul>
|
| 143 | </li>
|
| 144 | <li>2018-03-22: <strong>Version 0.7</strong>
|
| 145 | <ul>
|
| 146 | <li>Added <code class="highlighter-rouge">network:debug</code> and <code class="highlighter-rouge">network:getstatus</code> to the <code class="highlighter-rouge">network:control</code> permission</li>
|
| 147 | </ul>
|
| 148 | </li>
|
| 149 | <li>2018-03-21:
|
| 150 | <ul>
|
| 151 | <li>Fixed signature of <code class="highlighter-rouge">runtime:packet.payload</code>, <code class="highlighter-rouge">runtime:packetsent.payload</code>, and port definition <code class="highlighter-rouge">default</code> to accept any payload type</li>
|
| 152 | <li>Added <code class="highlighter-rouge">values</code> and <code class="highlighter-rouge">default</code> keys for port definitions</li>
|
| 153 | <li>Added schema for <code class="highlighter-rouge">component:componentsready</code> output message</li>
|
| 154 | <li>Added schema for <code class="highlighter-rouge">graph:clear</code> output message</li>
|
| 155 | <li>Added <code class="highlighter-rouge">packetsent</code> response for <code class="highlighter-rouge">runtime:packet</code> input message</li>
|
| 156 | </ul>
|
| 157 | </li>
|
| 158 | <li>2017-09-17:
|
| 159 | <ul>
|
| 160 | <li>Added <code class="highlighter-rouge">schema</code> support for ports and packets</li>
|
| 161 | <li>Documented known metadata keys for various graph entities</li>
|
| 162 | </ul>
|
| 163 | </li>
|
| 164 | <li>2017-04-09: <strong>Version 0.6</strong>
|
| 165 | <ul>
|
| 166 | <li>Version 0.6. No breaking changes over 0.5.</li>
|
| 167 | <li>Added additional capabilities <code class="highlighter-rouge">graph:readonly</code>, <code class="highlighter-rouge">network:control</code>, <code class="highlighter-rouge">network:data</code>, <code class="highlighter-rouge">network:status</code>. Especially useful for read-only access.</li>
|
| 168 | <li>Deprecated the <code class="highlighter-rouge">protocol:network</code> capability in favor of the new fine-gained <code class="highlighter-rouge">network:*</code> capabilities.</li>
|
| 169 | <li>Each capability now defines the set of messages contained in it. Available as <code class="highlighter-rouge">inputs</code> and <code class="highlighter-rouge">outputs</code> in the schema <code class="highlighter-rouge">/shared/capabilities</code>.</li>
|
| 170 | </ul>
|
| 171 | </li>
|
| 172 | <li>2017-05-04:
|
| 173 | <ul>
|
| 174 | <li>Fixed protocol errors (<code class="highlighter-rouge">graph:error</code>, <code class="highlighter-rouge">component:error</code> and <code class="highlighter-rouge">runtime:error</code>) to have mandatory <code class="highlighter-rouge">message</code> string payload.</li>
|
| 175 | <li>Fixed missing <code class="highlighter-rouge">required</code> markers in some JSON schemas for <code class="highlighter-rouge">graph</code> protocol. Affected messages:
|
| 176 | <code class="highlighter-rouge">graph:renamegroup</code>, <code class="highlighter-rouge">graph:renameinport</code>, <code class="highlighter-rouge">graph:removeinport</code>, <code class="highlighter-rouge">graph:addinitial</code>, <code class="highlighter-rouge">graph:changeedge</code></li>
|
| 177 | <li>More readable HTML output, including property value types and examples</li>
|
| 178 | </ul>
|
| 179 | </li>
|
| 180 | <li>2017-05-03:
|
| 181 | <ul>
|
| 182 | <li>Added more optional metadata to <code class="highlighter-rouge">runtime:runtime</code> message: <code class="highlighter-rouge">repository</code>, <code class="highlighter-rouge">repositoryVersion</code> and <code class="highlighter-rouge">namespace</code></li>
|
| 183 | </ul>
|
| 184 | </li>
|
| 185 | <li>2017-02-20:
|
| 186 | <ul>
|
| 187 | <li>Fixed payload definition of <code class="highlighter-rouge">network:edges</code> missing mandatory <code class="highlighter-rouge">graph</code> key</li>
|
| 188 | </ul>
|
| 189 | </li>
|
| 190 | <li>2016-07-01:
|
| 191 | <ul>
|
| 192 | <li><code class="highlighter-rouge">network:error</code> payload may now contain an optional <code class="highlighter-rouge">stacktrace</code></li>
|
| 193 | </ul>
|
| 194 | </li>
|
| 195 | <li>2016-06-23:
|
| 196 | <ul>
|
| 197 | <li>Trace subprotocol also available in machine-readable format</li>
|
| 198 | </ul>
|
| 199 | </li>
|
| 200 | <li>2016-06-17:
|
| 201 | <ul>
|
| 202 | <li>Protocol definition available as machine-readable JSON <a href="https://github.com/flowbased/fbp-protocol/tree/master/schema/yaml">schemas</a>.</li>
|
| 203 | <li>The human-readable HTML documentation is generated from this defintion.</li>
|
| 204 | <li>The npm package <code class="highlighter-rouge">fbp-protocol</code> contains the schemas as YAML, JSON and .js modules.</li>
|
| 205 | </ul>
|
| 206 | </li>
|
| 207 | <li>2015-11-20:
|
| 208 | <ul>
|
| 209 | <li>Initial <code class="highlighter-rouge">trace</code> subprotocol, for <a href="https://github.com/flowbased/flowtrace">Flowtrace</a> support</li>
|
| 210 | </ul>
|
| 211 | </li>
|
| 212 | <li>2015-03-27:
|
| 213 | <ul>
|
| 214 | <li>Documented <code class="highlighter-rouge">network</code> <code class="highlighter-rouge">persist</code> and <code class="highlighter-rouge">component</code> <code class="highlighter-rouge">componentsready</code> messages</li>
|
| 215 | </ul>
|
| 216 | </li>
|
| 217 | <li>2015-03-26: <strong>Version 0.5</strong>
|
| 218 | <ul>
|
| 219 | <li>All messages sent to runtime should include the <code class="highlighter-rouge">secret</code> in payload</li>
|
| 220 | <li>Runtime description message includes an <code class="highlighter-rouge">allCapabilities</code> array describing capabilities of the runtime, including ones not available to current user</li>
|
| 221 | </ul>
|
| 222 | </li>
|
| 223 | <li>2014-10-23
|
| 224 | <ul>
|
| 225 | <li>added clarifications to network running state in <code class="highlighter-rouge">status</code>, <code class="highlighter-rouge">started</code>, and <code class="highlighter-rouge">stopped</code> messages</li>
|
| 226 | </ul>
|
| 227 | </li>
|
| 228 | <li>2014-09-26
|
| 229 | <ul>
|
| 230 | <li>Add <code class="highlighter-rouge">secret</code> as payload to <code class="highlighter-rouge">getruntime</code> to support <a href="https://github.com/noflo/noflo-ui/issues/278">access levels</a></li>
|
| 231 | </ul>
|
| 232 | </li>
|
| 233 | <li>2014-08-05:
|
| 234 | <ul>
|
| 235 | <li>Add get, list, graph, graphsdone commands to the graph protocol</li>
|
| 236 | <li>Add list, network commands to the network protocol</li>
|
| 237 | </ul>
|
| 238 | </li>
|
| 239 | <li>2014-07-15:
|
| 240 | <ul>
|
| 241 | <li>Add changenode, changeedge, addgroup, removegroup, renamegroup,
|
| 242 | changegroup commands to the graph protocol</li>
|
| 243 | </ul>
|
| 244 | </li>
|
| 245 | <li>2014-03-13: <strong>Version 0.4</strong>
|
| 246 | <ul>
|
| 247 | <li>Capability discovery support</li>
|
| 248 | <li>Network exported port messaging for remote subgraphs</li>
|
| 249 | </ul>
|
| 250 | </li>
|
| 251 | <li>2014-02-18: <strong>Version 0.3</strong>
|
| 252 | <ul>
|
| 253 | <li>Support for exported graph ports</li>
|
| 254 | </ul>
|
| 255 | </li>
|
| 256 | <li>2014-01-09: <strong>Version 0.2</strong>
|
| 257 | <ul>
|
| 258 | <li>Multi-graph support via the <code class="highlighter-rouge">graph</code> key in payload</li>
|
| 259 | <li>Harmonization with <a href="http://noflojs.org/documentation/json/">JSON format</a> by renaming <code class="highlighter-rouge">from</code>/<code class="highlighter-rouge">to</code> in edges to <code class="highlighter-rouge">src</code>/<code class="highlighter-rouge">tgt</code></li>
|
| 260 | <li>Network <code class="highlighter-rouge">edges</code> message</li>
|
| 261 | </ul>
|
| 262 | </li>
|
| 263 | </ul>
|
| 264 |
|
| 265 | <h2 id="basics">Basics</h2>
|
| 266 |
|
| 267 | <p>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.</p>
|
| 268 |
|
| 269 | <p>There are currently three transports utilized commonly:</p>
|
| 270 |
|
| 271 | <ul>
|
| 272 | <li><a href="http://en.wikipedia.org/wiki/Web_Messaging">Web Messaging</a> (<code class="highlighter-rouge">postMessage</code>) for communication between different web pages or WebWorkers running inside the same browser instance</li>
|
| 273 | <li><a href="http://en.wikipedia.org/wiki/WebSocket">WebSocket</a> for communicating between a browser and a server, or between two server instances</li>
|
| 274 | <li><a href="http://en.wikipedia.org/wiki/WebRTC">WebRTC</a> for peer-to-peer communications between a runtime and a client</li>
|
| 275 | </ul>
|
| 276 |
|
| 277 | <p>Different transports can be utilized as needed. It could be interesting to implement the FBP protocol using <a href="http://en.wikipedia.org/wiki/MQ_Telemetry_Transport">MQTT</a>, for instance.</p>
|
| 278 |
|
| 279 | <h3 id="sub-protocols">Sub-protocols</h3>
|
| 280 |
|
| 281 | <p>The FBP protocol is divided into sub-protocols for each of the major resources that can be manipulated:</p>
|
| 282 |
|
| 283 | <ul>
|
| 284 | <li><a href="#runtime-protocol"><code class="highlighter-rouge">runtime</code></a>: communications about runtime capabilities and its exported ports</li>
|
| 285 | <li><a href="#graph-protocol"><code class="highlighter-rouge">graph</code></a>: communications about graph changes</li>
|
| 286 | <li><a href="#component-protocol"><code class="highlighter-rouge">component</code></a>: communications about available components and changes to them</li>
|
| 287 | <li><a href="#network-protocol"><code class="highlighter-rouge">network</code></a>: communications related to running a FBP graph</li>
|
| 288 | <li><a href="#trace-protocol"><code class="highlighter-rouge">trace</code></a>: communications related to tracing a FBP network</li>
|
| 289 | </ul>
|
| 290 |
|
| 291 | <h3 id="capabilities">Capabilities</h3>
|
| 292 |
|
| 293 | <p>Not all runtimes implementation supports all features of the protocol. Also, a runtime may restrict <em>access</em> to features, either to all clients based on configuration, or based on the <em>secret</em> provided in the messages. To support this a set of <strong>capabilities</strong> are defined, which are reported by the runtime in the <a href="#runtime-runtime">runtime:runtime</a> message.</p>
|
| 294 |
|
| 295 | <p>When receiving a message, the runtime should check for the associated capability. If the capability is not supported, or the client does not have access to the capability, the runtime should respond with an <code class="highlighter-rouge">error</code> reply on the relevant <code class="highlighter-rouge">protocol</code>.</p>
|
| 296 |
|
| 297 | <p>A few commands do not require any capabilities: the runtime info request/response (<a href="#runtime-getruntime">runtime:getruntime</a> and <a href="#runtime-runtime">runtime:runtime</a>), and the error responses (<a href="#runtime-error">runtime:error</a>, <a href="#graph-error">graph:error</a>, <a href="#network-error">network:error</a>, <a href="#component-error">component:error</a>).</p>
|
| 298 |
|
| 299 | <section class="capabilities">
|
| 300 | <h4 class="capability name">protocol:network</h4>
|
| 301 | <p>can control and introspect its running networks using the Network protocol. DEPRECATED. Instead the individual network:... capabilities should be used. Implies capabilities network:status, network:data, network:control. Does not imply capability network:persist.</p>
|
| 302 | <h5 class="capability messages header">input messages</h5>
|
| 303 | <ul class="capability messages">
|
| 304 | <li><a href="#network-start">network:start</a></li>
|
| 305 | <li><a href="#network-getstatus">network:getstatus</a></li>
|
| 306 | <li><a href="#network-stop">network:stop</a></li>
|
| 307 | <li><a href="#network-debug">network:debug</a></li>
|
| 308 | <li><a href="#network-edges">network:edges</a></li>
|
| 309 | </ul>
|
| 310 | <h5 class="capability messages header">output messages</h5>
|
| 311 | <ul class="capability messages">
|
| 312 | <li><a href="#network-stopped">network:stopped</a></li>
|
| 313 | <li><a href="#network-started">network:started</a></li>
|
| 314 | <li><a href="#network-status">network:status</a></li>
|
| 315 | <li><a href="#network-output">network:output</a></li>
|
| 316 | <li><a href="#network-error">network:error</a></li>
|
| 317 | <li><a href="#network-processerror">network:processerror</a></li>
|
| 318 | <li><a href="#network-icon">network:icon</a></li>
|
| 319 | <li><a href="#network-connect">network:connect</a></li>
|
| 320 | <li><a href="#network-begingroup">network:begingroup</a></li>
|
| 321 | <li><a href="#network-data">network:data</a></li>
|
| 322 | <li><a href="#network-endgroup">network:endgroup</a></li>
|
| 323 | <li><a href="#network-disconnect">network:disconnect</a></li>
|
| 324 | <li><a href="#network-edges">network:edges</a></li>
|
| 325 | </ul>
|
| 326 | <h4 class="capability name">network:persist</h4>
|
| 327 | <p>can *flash* a running graph setup to the runtime, making it persistent across restarts</p>
|
| 328 | <h5 class="capability messages header">input messages</h5>
|
| 329 | <ul class="capability messages">
|
| 330 | <li><a href="#network-persist">network:persist</a></li>
|
| 331 | </ul>
|
| 332 | <h5 class="capability messages header">output messages</h5>
|
| 333 | <ul class="capability messages">
|
| 334 | <li><a href="#network-persist">network:persist</a></li>
|
| 335 | <li><a href="#network-error">network:error</a></li>
|
| 336 | </ul>
|
| 337 | <h4 class="capability name">network:status</h4>
|
| 338 | <p>can get and follow changes to network status</p>
|
| 339 | <h5 class="capability messages header">input messages</h5>
|
| 340 | <ul class="capability messages">
|
| 341 | <li><a href="#network-getstatus">network:getstatus</a></li>
|
| 342 | </ul>
|
| 343 | <h5 class="capability messages header">output messages</h5>
|
| 344 | <ul class="capability messages">
|
| 345 | <li><a href="#network-status">network:status</a></li>
|
| 346 | <li><a href="#network-started">network:started</a></li>
|
| 347 | <li><a href="#network-stopped">network:stopped</a></li>
|
| 348 | <li><a href="#network-error">network:error</a></li>
|
| 349 | </ul>
|
| 350 | <h4 class="capability name">network:data</h4>
|
| 351 | <p>can listen to data flowing through the network and processes</p>
|
| 352 | <h5 class="capability messages header">input messages</h5>
|
| 353 | <ul class="capability messages">
|
| 354 | <li><a href="#network-edges">network:edges</a></li>
|
| 355 | </ul>
|
| 356 | <h5 class="capability messages header">output messages</h5>
|
| 357 | <ul class="capability messages">
|
| 358 | <li><a href="#network-edges">network:edges</a></li>
|
| 359 | <li><a href="#network-output">network:output</a></li>
|
| 360 | <li><a href="#network-error">network:error</a></li>
|
| 361 | <li><a href="#network-data">network:data</a></li>
|
| 362 | <li><a href="#network-begingroup">network:begingroup</a></li>
|
| 363 | <li><a href="#network-endgroup">network:endgroup</a></li>
|
| 364 | <li><a href="#network-connect">network:connect</a></li>
|
| 365 | <li><a href="#network-disconnect">network:disconnect</a></li>
|
| 366 | <li><a href="#network-icon">network:icon</a></li>
|
| 367 | <li><a href="#network-processerror">network:processerror</a></li>
|
| 368 | <li><a href="#network-error">network:error</a></li>
|
| 369 | </ul>
|
| 370 | <h4 class="capability name">network:control</h4>
|
| 371 | <p>can start and stop networks</p>
|
| 372 | <h5 class="capability messages header">input messages</h5>
|
| 373 | <ul class="capability messages">
|
| 374 | <li><a href="#network-start">network:start</a></li>
|
| 375 | <li><a href="#network-stop">network:stop</a></li>
|
| 376 | <li><a href="#network-getstatus">network:getstatus</a></li>
|
| 377 | <li><a href="#network-debug">network:debug</a></li>
|
| 378 | </ul>
|
| 379 | <h5 class="capability messages header">output messages</h5>
|
| 380 | <ul class="capability messages">
|
| 381 | <li><a href="#network-started">network:started</a></li>
|
| 382 | <li><a href="#network-stopped">network:stopped</a></li>
|
| 383 | <li><a href="#network-status">network:status</a></li>
|
| 384 | <li><a href="#network-error">network:error</a></li>
|
| 385 | </ul>
|
| 386 | <h4 class="capability name">protocol:component</h4>
|
| 387 | <p>can list components of the runtime using the component:list message.</p>
|
| 388 | <h5 class="capability messages header">input messages</h5>
|
| 389 | <ul class="capability messages">
|
| 390 | <li><a href="#component-list">component:list</a></li>
|
| 391 | </ul>
|
| 392 | <h5 class="capability messages header">output messages</h5>
|
| 393 | <ul class="capability messages">
|
| 394 | <li><a href="#component-component">component:component</a></li>
|
| 395 | <li><a href="#component-componentsready">component:componentsready</a></li>
|
| 396 | <li><a href="#component-error">component:error</a></li>
|
| 397 | </ul>
|
| 398 | <h4 class="capability name">component:getsource</h4>
|
| 399 | <p>read and send component source code back to client</p>
|
| 400 | <h5 class="capability messages header">input messages</h5>
|
| 401 | <ul class="capability messages">
|
| 402 | <li><a href="#component-getsource">component:getsource</a></li>
|
| 403 | </ul>
|
| 404 | <h5 class="capability messages header">output messages</h5>
|
| 405 | <ul class="capability messages">
|
| 406 | <li><a href="#component-source">component:source</a></li>
|
| 407 | <li><a href="#component-error">component:error</a></li>
|
| 408 | </ul>
|
| 409 | <h4 class="capability name">component:setsource</h4>
|
| 410 | <p>runtime is able to compile and run custom components sent as source code strings</p>
|
| 411 | <h5 class="capability messages header">input messages</h5>
|
| 412 | <ul class="capability messages">
|
| 413 | <li><a href="#component-source">component:source</a></li>
|
| 414 | </ul>
|
| 415 | <h5 class="capability messages header">output messages</h5>
|
| 416 | <ul class="capability messages">
|
| 417 | <li><a href="#component-component">component:component</a></li>
|
| 418 | <li><a href="#component-error">component:error</a></li>
|
| 419 | </ul>
|
| 420 | <h4 class="capability name">protocol:runtime</h4>
|
| 421 | <p>can expose ports of main graph and transmit packet information to/from them</p>
|
| 422 | <h5 class="capability messages header">input messages</h5>
|
| 423 | <ul class="capability messages">
|
| 424 | <li><a href="#runtime-packet">runtime:packet</a></li>
|
| 425 | </ul>
|
| 426 | <h5 class="capability messages header">output messages</h5>
|
| 427 | <ul class="capability messages">
|
| 428 | <li><a href="#runtime-ports">runtime:ports</a></li>
|
| 429 | <li><a href="#runtime-packetsent">runtime:packetsent</a></li>
|
| 430 | <li><a href="#runtime-packet">runtime:packet</a></li>
|
| 431 | <li><a href="#runtime-error">runtime:error</a></li>
|
| 432 | </ul>
|
| 433 | <h4 class="capability name">graph:readonly</h4>
|
| 434 | <p>read and follow changes to runtime graphs (but not modify)</p>
|
| 435 | <h5 class="capability messages header">input messages</h5>
|
| 436 | <ul class="capability messages">
|
| 437 | </ul>
|
| 438 | <h5 class="capability messages header">output messages</h5>
|
| 439 | <ul class="capability messages">
|
| 440 | <li><a href="#graph-clear">graph:clear</a></li>
|
| 441 | <li><a href="#graph-addnode">graph:addnode</a></li>
|
| 442 | <li><a href="#graph-removenode">graph:removenode</a></li>
|
| 443 | <li><a href="#graph-renamenode">graph:renamenode</a></li>
|
| 444 | <li><a href="#graph-changenode">graph:changenode</a></li>
|
| 445 | <li><a href="#graph-addedge">graph:addedge</a></li>
|
| 446 | <li><a href="#graph-removeedge">graph:removeedge</a></li>
|
| 447 | <li><a href="#graph-changeedge">graph:changeedge</a></li>
|
| 448 | <li><a href="#graph-addinitial">graph:addinitial</a></li>
|
| 449 | <li><a href="#graph-removeinitial">graph:removeinitial</a></li>
|
| 450 | <li><a href="#graph-addinport">graph:addinport</a></li>
|
| 451 | <li><a href="#graph-removeinport">graph:removeinport</a></li>
|
| 452 | <li><a href="#graph-renameinport">graph:renameinport</a></li>
|
| 453 | <li><a href="#graph-addoutport">graph:addoutport</a></li>
|
| 454 | <li><a href="#graph-removeoutport">graph:removeoutport</a></li>
|
| 455 | <li><a href="#graph-renameoutport">graph:renameoutport</a></li>
|
| 456 | <li><a href="#graph-addgroup">graph:addgroup</a></li>
|
| 457 | <li><a href="#graph-removegroup">graph:removegroup</a></li>
|
| 458 | <li><a href="#graph-renamegroup">graph:renamegroup</a></li>
|
| 459 | <li><a href="#graph-changegroup">graph:changegroup</a></li>
|
| 460 | </ul>
|
| 461 | <h4 class="capability name">protocol:graph</h4>
|
| 462 | <p>read & modify runtime graphs using the Graph protocol.</p>
|
| 463 | <h5 class="capability messages header">input messages</h5>
|
| 464 | <ul class="capability messages">
|
| 465 | <li><a href="#graph-clear">graph:clear</a></li>
|
| 466 | <li><a href="#graph-addnode">graph:addnode</a></li>
|
| 467 | <li><a href="#graph-removenode">graph:removenode</a></li>
|
| 468 | <li><a href="#graph-renamenode">graph:renamenode</a></li>
|
| 469 | <li><a href="#graph-changenode">graph:changenode</a></li>
|
| 470 | <li><a href="#graph-addedge">graph:addedge</a></li>
|
| 471 | <li><a href="#graph-removeedge">graph:removeedge</a></li>
|
| 472 | <li><a href="#graph-changeedge">graph:changeedge</a></li>
|
| 473 | <li><a href="#graph-addinitial">graph:addinitial</a></li>
|
| 474 | <li><a href="#graph-removeinitial">graph:removeinitial</a></li>
|
| 475 | <li><a href="#graph-addinport">graph:addinport</a></li>
|
| 476 | <li><a href="#graph-removeinport">graph:removeinport</a></li>
|
| 477 | <li><a href="#graph-renameinport">graph:renameinport</a></li>
|
| 478 | <li><a href="#graph-addoutport">graph:addoutport</a></li>
|
| 479 | <li><a href="#graph-removeoutport">graph:removeoutport</a></li>
|
| 480 | <li><a href="#graph-renameoutport">graph:renameoutport</a></li>
|
| 481 | <li><a href="#graph-addgroup">graph:addgroup</a></li>
|
| 482 | <li><a href="#graph-removegroup">graph:removegroup</a></li>
|
| 483 | <li><a href="#graph-renamegroup">graph:renamegroup</a></li>
|
| 484 | <li><a href="#graph-changegroup">graph:changegroup</a></li>
|
| 485 | </ul>
|
| 486 | <h5 class="capability messages header">output messages</h5>
|
| 487 | <ul class="capability messages">
|
| 488 | <li><a href="#graph-clear">graph:clear</a></li>
|
| 489 | <li><a href="#graph-addnode">graph:addnode</a></li>
|
| 490 | <li><a href="#graph-removenode">graph:removenode</a></li>
|
| 491 | <li><a href="#graph-renamenode">graph:renamenode</a></li>
|
| 492 | <li><a href="#graph-changenode">graph:changenode</a></li>
|
| 493 | <li><a href="#graph-addedge">graph:addedge</a></li>
|
| 494 | <li><a href="#graph-removeedge">graph:removeedge</a></li>
|
| 495 | <li><a href="#graph-changeedge">graph:changeedge</a></li>
|
| 496 | <li><a href="#graph-addinitial">graph:addinitial</a></li>
|
| 497 | <li><a href="#graph-removeinitial">graph:removeinitial</a></li>
|
| 498 | <li><a href="#graph-addinport">graph:addinport</a></li>
|
| 499 | <li><a href="#graph-removeinport">graph:removeinport</a></li>
|
| 500 | <li><a href="#graph-renameinport">graph:renameinport</a></li>
|
| 501 | <li><a href="#graph-addoutport">graph:addoutport</a></li>
|
| 502 | <li><a href="#graph-removeoutport">graph:removeoutport</a></li>
|
| 503 | <li><a href="#graph-renameoutport">graph:renameoutport</a></li>
|
| 504 | <li><a href="#graph-addgroup">graph:addgroup</a></li>
|
| 505 | <li><a href="#graph-removegroup">graph:removegroup</a></li>
|
| 506 | <li><a href="#graph-renamegroup">graph:renamegroup</a></li>
|
| 507 | <li><a href="#graph-changegroup">graph:changegroup</a></li>
|
| 508 | <li><a href="#graph-error">graph:error</a></li>
|
| 509 | </ul>
|
| 510 | <h4 class="capability name">protocol:trace</h4>
|
| 511 | <p>runtime is able to record and send over flowtraces, used for retroactive debugging.</p>
|
| 512 | <h5 class="capability messages header">input messages</h5>
|
| 513 | <ul class="capability messages">
|
| 514 | <li><a href="#trace-start">trace:start</a></li>
|
| 515 | <li><a href="#trace-stop">trace:stop</a></li>
|
| 516 | <li><a href="#trace-clear">trace:clear</a></li>
|
| 517 | <li><a href="#trace-dump">trace:dump</a></li>
|
| 518 | </ul>
|
| 519 | <h5 class="capability messages header">output messages</h5>
|
| 520 | <ul class="capability messages">
|
| 521 | <li><a href="#trace-start">trace:start</a></li>
|
| 522 | <li><a href="#trace-stop">trace:stop</a></li>
|
| 523 | <li><a href="#trace-clear">trace:clear</a></li>
|
| 524 | <li><a href="#trace-dump">trace:dump</a></li>
|
| 525 | <li><a href="#trace-error">trace:error</a></li>
|
| 526 | </ul>
|
| 527 | </section>
|
| 528 |
|
| 529 | <h3 id="message-structure">Message structure</h3>
|
| 530 |
|
| 531 | <p>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.</p>
|
| 532 |
|
| 533 | <p>All messages consist of three parts:</p>
|
| 534 |
|
| 535 | <ul>
|
| 536 | <li>Sub-protocol identifier (<code class="highlighter-rouge">graph</code>, <code class="highlighter-rouge">component</code>, or <code class="highlighter-rouge">network</code>)</li>
|
| 537 | <li>Topic (for example, <code class="highlighter-rouge">addnode</code>)</li>
|
| 538 | <li>Message payload (typically a data structure specific to the sub-protocol and topic)</li>
|
| 539 | </ul>
|
| 540 |
|
| 541 | <p>The keys listed in specific messages are for the message <code class="highlighter-rouge">payload</code>.</p>
|
| 542 |
|
| 543 | <p>An example message</p>
|
| 544 | <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>"protocol": "graph",
|
| 545 | "command": "addnode",
|
| 546 | "payload": {
|
| 547 | "component": "canvas/Draw",
|
| 548 | "graph": "hello-canvas-example",
|
| 549 | "id": "draw",
|
| 550 | "metadata": {
|
| 551 | "label": "Draw onto canvas element"
|
| 552 | }
|
| 553 | }
|
| 554 | </code></pre></div></div>
|
| 555 |
|
| 556 | <h2 class="protocol name">Runtime protocol</h2>
|
| 557 | <p class="protocol description">When a client connects to a FBP procotol it may choose to discover the capabilities and other information about the runtime.</p>
|
| 558 | <h3 id="runtime-getruntime" class="message name"><a href="#runtime-getruntime">getruntime</a></h3>
|
| 559 | <p>Request the information about the runtime. When receiving this message the runtime should response with a runtime message. If the runtime is currently running a graph and it is able to speak the full Runtime protocol, it should follow up with a ports message.</p>
|
| 560 | <ul class="message properties">
|
| 561 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 562 | </ul>
|
| 563 | <h3 id="runtime-packet" class="message name"><a href="#runtime-packet">packet</a></h3>
|
| 564 | <p>Runtimes that can be used as remote subgraphs (i.e. ones that have reported supporting the protocol:runtime capability) need to be able to receive and transmit information packets at their exposed ports.
|
| 565 | These packets can be send from the client to the runtimes input ports, or from runtimes output ports to the client.</p>
|
| 566 | <ul class="message properties">
|
| 567 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name for the input or output port</label></li>
|
| 568 | <li><label class="property name">event</label><label class="property type">string</label><label class="property description">packet event</label></li>
|
| 569 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">The basic datatype sent</label><code class="property example">"array"</code></li>
|
| 570 | <li><label class="property name">schema</label><label class="property type">string</label><label class="property description">Link to JSON schema describing the format of the data</label><code class="property example">"https://example.net/schemas/person.json"</code></li>
|
| 571 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 572 | <li><label class="property name">payload</label><label class="property type">any</label><label class="property description">payload for the packet. Used only with begingroup (for group names) and data packets</label></li>
|
| 573 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 574 | </ul>
|
| 575 | <h3 id="runtime-error" class="message name"><a href="#runtime-error">error</a></h3>
|
| 576 | <p>Error response to a command on runtime protocol</p>
|
| 577 | <ul class="message properties">
|
| 578 | <li><label class="property name">message</label><label class="property type">string</label><label class="property description">Error message describing what went wrong</label></li>
|
| 579 | </ul>
|
| 580 | <h3 id="runtime-ports" class="message name"><a href="#runtime-ports">ports</a></h3>
|
| 581 | <p>Message sent by the runtime to signal its available ports. The runtime is responsible for sending the up-to-date list of available ports back to client whenever it changes.</p>
|
| 582 | <ul class="message properties">
|
| 583 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">ID of the currently configured main graph running on the runtime</label></li>
|
| 584 | <li><label class="property name">inPorts</label><label class="property type">array</label><label class="property description">list of input ports of the runtime</label></li>Each item contains:
|
| 585 | <ul class="properties">
|
| 586 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 587 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">port datatype</label><code class="property example">"boolean"</code></li>
|
| 588 | <li><label class="property optional name">schema</label><label class="property optional type">string</label><label class="property optional description">Link to JSON schema for data on this port</label><code class="property optional example">"https://example.net/schemas/person.json"</code></li>
|
| 589 | <li><label class="property optional name">required</label><label class="property optional type">boolean</label><label class="property optional description">whether the port needs to be connected for the component to work</label><code class="property optional example">true</code></li>
|
| 590 | <li><label class="property optional name">addressable</label><label class="property optional type">boolean</label><label class="property optional description">whether the port is an ArrayPort</label><code class="property optional example">false</code></li>
|
| 591 | <li><label class="property optional name">description</label><label class="property optional type">string</label><label class="property optional description">textual description of the port</label></li>
|
| 592 | <li><label class="property optional name">values</label><label class="property optional type">array</label><label class="property optional description">list of values accepted for the port</label></li>
|
| 593 | <li><label class="property optional name">default</label><label class="property optional type">any</label><label class="property optional description">default value for the port</label></li>
|
| 594 | </ul>
|
| 595 | <li><label class="property name">outPorts</label><label class="property type">array</label><label class="property description">list of output ports of the runtime</label></li>Each item contains:
|
| 596 | <ul class="properties">
|
| 597 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 598 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">port datatype</label><code class="property example">"boolean"</code></li>
|
| 599 | <li><label class="property optional name">schema</label><label class="property optional type">string</label><label class="property optional description">Link to JSON schema for data on this port</label><code class="property optional example">"https://example.net/schemas/person.json"</code></li>
|
| 600 | <li><label class="property optional name">required</label><label class="property optional type">boolean</label><label class="property optional description">whether the port needs to be connected for the component to work</label><code class="property optional example">true</code></li>
|
| 601 | <li><label class="property optional name">addressable</label><label class="property optional type">boolean</label><label class="property optional description">whether the port is an ArrayPort</label><code class="property optional example">false</code></li>
|
| 602 | <li><label class="property optional name">description</label><label class="property optional type">string</label><label class="property optional description">textual description of the port</label></li>
|
| 603 | <li><label class="property optional name">values</label><label class="property optional type">array</label><label class="property optional description">list of values accepted for the port</label></li>
|
| 604 | <li><label class="property optional name">default</label><label class="property optional type">any</label><label class="property optional description">default value for the port</label></li>
|
| 605 | </ul>
|
| 606 | </ul>
|
| 607 | <h3 id="runtime-runtime" class="message name"><a href="#runtime-runtime">runtime</a></h3>
|
| 608 | <p>Response from the runtime to the getruntime request.</p>
|
| 609 | <ul class="message properties">
|
| 610 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">unique runtime ID. Must be a UUID, version 4</label><code class="property example">"f18a4924-9d4f-414d-a37c-cd24b39bba10"</code></li>
|
| 611 | <li><label class="property name">label</label><label class="property type">string</label><label class="property description">Human-readable description of the runtime</label></li>
|
| 612 | <li><label class="property name">version</label><label class="property type">string</label><label class="property description">version of the runtime protocol that the runtime supports</label><code class="property example">"0.6"</code></li>
|
| 613 | <li><label class="property name">allCapabilities</label><label class="property type">array</label><label class="property description"><a href="#capabilities">capability strings</a> for things the runtime is able to do. May include things not permitted for this client.</label></li>
|
| 614 | <li><label class="property name">capabilities</label><label class="property type">array</label><label class="property description"><a href="#capabilities">capability strings</a> for things the runtime is able to do for this client.</label></li>
|
| 615 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">ID of the currently configured main graph running on the runtime, if any</label><code class="property example">"service-main"</code></li>
|
| 616 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">type of the runtime</label><code class="property example">"microflo"</code></li>
|
| 617 | <li><label class="property name">namespace</label><label class="property type">string</label><label class="property description">Library namespace of the project running on the runtime, if any. Must match that of components belonging to the (top-level) of project.</label><code class="property example">"my-project-foo"</code></li>
|
| 618 | <li><label class="property name">repository</label><label class="property type">string</label><label class="property description">Source-code repository URL of the project running on the runtime, if any</label><code class="property example">"https://github.com/flowbased/fbp-protocol.git"</code></li>
|
| 619 | <li><label class="property name">repositoryVersion</label><label class="property type">string</label><label class="property description">Unique version identifier of the source code of the project, if known. The version should be available in @repository.</label><code class="property example">"0.6.3-8-g90edcfc"</code></li>
|
| 620 | </ul>
|
| 621 | <h3 id="runtime-packetsent" class="message name"><a href="#runtime-packetsent">packetsent</a></h3>
|
| 622 | <p>Confirmation that a packet has been sent</p>
|
| 623 | <ul class="message properties">
|
| 624 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name for the input port</label></li>
|
| 625 | <li><label class="property name">event</label><label class="property type">string</label><label class="property description">packet event</label></li>
|
| 626 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">The basic datatype sent</label><code class="property example">"array"</code></li>
|
| 627 | <li><label class="property name">schema</label><label class="property type">string</label><label class="property description">Link to JSON schema describing the format of the data</label><code class="property example">"https://example.net/schemas/person.json"</code></li>
|
| 628 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targeted</label></li>
|
| 629 | <li><label class="property name">payload</label><label class="property type">any</label><label class="property description">payload for the packet. Used only with begingroup (for group names) and data packets</label></li>
|
| 630 | </ul>
|
| 631 | <h2 class="protocol name">Graph protocol</h2>
|
| 632 | <p class="protocol description">This protocol is utilized for communicating about graph changes in both directions.</p>
|
| 633 | <h3 id="graph-clear" class="message name"><a href="#graph-clear">clear</a></h3>
|
| 634 | <p>Initialize an empty graph.</p>
|
| 635 | <ul class="message properties">
|
| 636 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">identifier for the graph being created. Used for all subsequent messages related to the graph instance</label></li>
|
| 637 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">Human-readable label for the graph</label></li>
|
| 638 | <li><label class="property name">library</label><label class="property type">string</label><label class="property description">Component library identifier</label></li>
|
| 639 | <li><label class="property name">main</label><label class="property type">boolean</label><label class="property description">Identifies the graph as a main graph of a project that should not be registered as a component
|
| 640 | Graphs 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.</label></li>
|
| 641 | <li><label class="property name">icon</label><label class="property type">string</label><label class="property description">Icon to use for the graph when used as a component</label></li>
|
| 642 | <li><label class="property name">description</label><label class="property type">string</label><label class="property description">Description to use for the graph when used as a component</label></li>
|
| 643 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 644 | </ul>
|
| 645 | <h3 id="graph-addnode" class="message name"><a href="#graph-addnode">addnode</a></h3>
|
| 646 | <p>Add node to a graph.</p>
|
| 647 | <ul class="message properties">
|
| 648 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">identifier for the node</label></li>
|
| 649 | <li><label class="property name">component</label><label class="property type">string</label><label class="property description">component name used for the node</label></li>
|
| 650 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph node metadata</label></li>
|
| 651 | <ul class="properties">
|
| 652 | <li><label class="property name">x</label><label class="property type">integer</label><label class="property description">X coordinate of a graph entity</label></li>
|
| 653 | <li><label class="property name">y</label><label class="property type">integer</label><label class="property description">Y coordinate of a graph entity</label></li>
|
| 654 | </ul>
|
| 655 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 656 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 657 | </ul>
|
| 658 | <h3 id="graph-removenode" class="message name"><a href="#graph-removenode">removenode</a></h3>
|
| 659 | <p>Remove a node from a graph.</p>
|
| 660 | <ul class="message properties">
|
| 661 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">identifier for the node</label></li>
|
| 662 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 663 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 664 | </ul>
|
| 665 | <h3 id="graph-renamenode" class="message name"><a href="#graph-renamenode">renamenode</a></h3>
|
| 666 | <p>Change the ID of a node in the graph</p>
|
| 667 | <ul class="message properties">
|
| 668 | <li><label class="property name">from</label><label class="property type">string</label><label class="property description">original identifier for the node</label></li>
|
| 669 | <li><label class="property name">to</label><label class="property type">string</label><label class="property description">new identifier for the node</label></li>
|
| 670 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 671 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 672 | </ul>
|
| 673 | <h3 id="graph-changenode" class="message name"><a href="#graph-changenode">changenode</a></h3>
|
| 674 | <p>Change the metadata associated to a node in the graph</p>
|
| 675 | <ul class="message properties">
|
| 676 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">identifier for the node</label></li>
|
| 677 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph node metadata</label></li>
|
| 678 | <ul class="properties">
|
| 679 | <li><label class="property name">x</label><label class="property type">integer</label><label class="property description">X coordinate of a graph entity</label></li>
|
| 680 | <li><label class="property name">y</label><label class="property type">integer</label><label class="property description">Y coordinate of a graph entity</label></li>
|
| 681 | </ul>
|
| 682 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 683 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 684 | </ul>
|
| 685 | <h3 id="graph-addedge" class="message name"><a href="#graph-addedge">addedge</a></h3>
|
| 686 | <p>Add an edge to the graph</p>
|
| 687 | <ul class="message properties">
|
| 688 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 689 | <ul class="properties">
|
| 690 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 691 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 692 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 693 | </ul>
|
| 694 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 695 | <ul class="properties">
|
| 696 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 697 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 698 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 699 | </ul>
|
| 700 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph edge metadata</label></li>
|
| 701 | <ul class="properties">
|
| 702 | <li><label class="property name">route</label><label class="property type">integer</label><label class="property description">Route identifier of a graph entity</label></li>
|
| 703 | <li><label class="property name">schema</label><label class="property type">string</label><label class="property description">JSON schema associated with a graph entity</label></li>
|
| 704 | <li><label class="property name">secure</label><label class="property type">boolean</label><label class="property description">Whether graph entity data should be treated as secure</label></li>
|
| 705 | </ul>
|
| 706 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 707 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 708 | </ul>
|
| 709 | <h3 id="graph-removeedge" class="message name"><a href="#graph-removeedge">removeedge</a></h3>
|
| 710 | <p>Remove an edge from the graph</p>
|
| 711 | <ul class="message properties">
|
| 712 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 713 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 714 | <ul class="properties">
|
| 715 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 716 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 717 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 718 | </ul>
|
| 719 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 720 | <ul class="properties">
|
| 721 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 722 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 723 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 724 | </ul>
|
| 725 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 726 | </ul>
|
| 727 | <h3 id="graph-changeedge" class="message name"><a href="#graph-changeedge">changeedge</a></h3>
|
| 728 | <p>Change an edge's metadata</p>
|
| 729 | <ul class="message properties">
|
| 730 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 731 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph edge metadata</label></li>
|
| 732 | <ul class="properties">
|
| 733 | <li><label class="property name">route</label><label class="property type">integer</label><label class="property description">Route identifier of a graph entity</label></li>
|
| 734 | <li><label class="property name">schema</label><label class="property type">string</label><label class="property description">JSON schema associated with a graph entity</label></li>
|
| 735 | <li><label class="property name">secure</label><label class="property type">boolean</label><label class="property description">Whether graph entity data should be treated as secure</label></li>
|
| 736 | </ul>
|
| 737 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 738 | <ul class="properties">
|
| 739 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 740 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 741 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 742 | </ul>
|
| 743 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 744 | <ul class="properties">
|
| 745 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 746 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 747 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 748 | </ul>
|
| 749 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 750 | </ul>
|
| 751 | <h3 id="graph-addinitial" class="message name"><a href="#graph-addinitial">addinitial</a></h3>
|
| 752 | <p>Add an IIP to the graph</p>
|
| 753 | <ul class="message properties">
|
| 754 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 755 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph edge metadata</label></li>
|
| 756 | <ul class="properties">
|
| 757 | <li><label class="property name">route</label><label class="property type">integer</label><label class="property description">Route identifier of a graph entity</label></li>
|
| 758 | <li><label class="property name">schema</label><label class="property type">string</label><label class="property description">JSON schema associated with a graph entity</label></li>
|
| 759 | <li><label class="property name">secure</label><label class="property type">boolean</label><label class="property description">Whether graph entity data should be treated as secure</label></li>
|
| 760 | </ul>
|
| 761 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source data for the edge</label></li>
|
| 762 | <ul class="properties">
|
| 763 | <li><label class="property name">data</label><label class="property type">object,array,string,number,integer,boolean,null</label><label class="property description">IIP value in its actual data type</label></li>
|
| 764 | </ul>
|
| 765 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node/port for the edge</label></li>
|
| 766 | <ul class="properties">
|
| 767 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 768 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 769 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 770 | </ul>
|
| 771 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 772 | </ul>
|
| 773 | <h3 id="graph-removeinitial" class="message name"><a href="#graph-removeinitial">removeinitial</a></h3>
|
| 774 | <p>Remove an IIP from the graph</p>
|
| 775 | <ul class="message properties">
|
| 776 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">IIP data</label></li>
|
| 777 | <ul class="properties">
|
| 778 | <li><label class="property name">data</label><label class="property type">object,array,string,number,integer,boolean,null</label><label class="property description">IIP value in its actual data type</label></li>
|
| 779 | </ul>
|
| 780 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node/port for the edge</label></li>
|
| 781 | <ul class="properties">
|
| 782 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 783 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 784 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 785 | </ul>
|
| 786 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 787 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 788 | </ul>
|
| 789 | <h3 id="graph-addinport" class="message name"><a href="#graph-addinport">addinport</a></h3>
|
| 790 | <p>Add an exported inport to the graph.</p>
|
| 791 | <ul class="message properties">
|
| 792 | <li><label class="property name">public</label><label class="property type">string</label><label class="property description">the exported name of the port</label></li>
|
| 793 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 794 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">internal port name</label></li>
|
| 795 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph node metadata</label></li>
|
| 796 | <ul class="properties">
|
| 797 | <li><label class="property name">x</label><label class="property type">integer</label><label class="property description">X coordinate of a graph entity</label></li>
|
| 798 | <li><label class="property name">y</label><label class="property type">integer</label><label class="property description">Y coordinate of a graph entity</label></li>
|
| 799 | </ul>
|
| 800 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 801 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 802 | </ul>
|
| 803 | <h3 id="graph-removeinport" class="message name"><a href="#graph-removeinport">removeinport</a></h3>
|
| 804 | <p>Remove an exported port from the graph</p>
|
| 805 | <ul class="message properties">
|
| 806 | <li><label class="property name">public</label><label class="property type">string</label><label class="property description">the exported name of the port to remove</label></li>
|
| 807 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 808 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 809 | </ul>
|
| 810 | <h3 id="graph-renameinport" class="message name"><a href="#graph-renameinport">renameinport</a></h3>
|
| 811 | <p>Rename an exported port in the graph</p>
|
| 812 | <ul class="message properties">
|
| 813 | <li><label class="property name">from</label><label class="property type">string</label><label class="property description">original exported port name</label></li>
|
| 814 | <li><label class="property name">to</label><label class="property type">string</label><label class="property description">new exported port name</label></li>
|
| 815 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 816 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 817 | </ul>
|
| 818 | <h3 id="graph-addoutport" class="message name"><a href="#graph-addoutport">addoutport</a></h3>
|
| 819 | <p>Add an exported outport to the graph.</p>
|
| 820 | <ul class="message properties">
|
| 821 | <li><label class="property name">public</label><label class="property type">string</label><label class="property description">the exported name of the port</label></li>
|
| 822 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 823 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">internal port name</label></li>
|
| 824 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph node metadata</label></li>
|
| 825 | <ul class="properties">
|
| 826 | <li><label class="property name">x</label><label class="property type">integer</label><label class="property description">X coordinate of a graph entity</label></li>
|
| 827 | <li><label class="property name">y</label><label class="property type">integer</label><label class="property description">Y coordinate of a graph entity</label></li>
|
| 828 | </ul>
|
| 829 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 830 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 831 | </ul>
|
| 832 | <h3 id="graph-removeoutport" class="message name"><a href="#graph-removeoutport">removeoutport</a></h3>
|
| 833 | <p>Remove an exported port from the graph</p>
|
| 834 | <ul class="message properties">
|
| 835 | <li><label class="property name">public</label><label class="property type">string</label><label class="property description">the exported name of the port to remove</label></li>
|
| 836 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 837 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 838 | </ul>
|
| 839 | <h3 id="graph-renameoutport" class="message name"><a href="#graph-renameoutport">renameoutport</a></h3>
|
| 840 | <p>Rename an exported port in the graph</p>
|
| 841 | <ul class="message properties">
|
| 842 | <li><label class="property name">from</label><label class="property type">string</label><label class="property description">original exported port name</label></li>
|
| 843 | <li><label class="property name">to</label><label class="property type">string</label><label class="property description">new exported port name</label></li>
|
| 844 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 845 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 846 | </ul>
|
| 847 | <h3 id="graph-addgroup" class="message name"><a href="#graph-addgroup">addgroup</a></h3>
|
| 848 | <p>Add a group to the graph</p>
|
| 849 | <ul class="message properties">
|
| 850 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">the group name</label></li>
|
| 851 | <li><label class="property name">nodes</label><label class="property type">array</label><label class="property description">an array of node ids part of the group</label></li>
|
| 852 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph group metadata</label></li>
|
| 853 | <ul class="properties">
|
| 854 | <li><label class="property name">description</label><label class="property type">string</label><label class="property description">Longer textual description of the group</label></li>
|
| 855 | </ul>
|
| 856 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 857 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 858 | </ul>
|
| 859 | <h3 id="graph-removegroup" class="message name"><a href="#graph-removegroup">removegroup</a></h3>
|
| 860 | <p>Remove a group from the graph</p>
|
| 861 | <ul class="message properties">
|
| 862 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">the group name</label></li>
|
| 863 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 864 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 865 | </ul>
|
| 866 | <h3 id="graph-renamegroup" class="message name"><a href="#graph-renamegroup">renamegroup</a></h3>
|
| 867 | <p>Rename a group in the graph.</p>
|
| 868 | <ul class="message properties">
|
| 869 | <li><label class="property name">from</label><label class="property type">string</label><label class="property description">original group name</label></li>
|
| 870 | <li><label class="property name">to</label><label class="property type">string</label><label class="property description">new group name</label></li>
|
| 871 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 872 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 873 | </ul>
|
| 874 | <h3 id="graph-changegroup" class="message name"><a href="#graph-changegroup">changegroup</a></h3>
|
| 875 | <p>Change a group's metadata</p>
|
| 876 | <ul class="message properties">
|
| 877 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">the group name</label></li>
|
| 878 | <li><label class="property name">metadata</label><label class="property type">object</label><label class="property description">structure of key-value pairs for graph group metadata</label></li>
|
| 879 | <ul class="properties">
|
| 880 | <li><label class="property name">description</label><label class="property type">string</label><label class="property description">Longer textual description of the group</label></li>
|
| 881 | </ul>
|
| 882 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 883 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 884 | </ul>
|
| 885 | <h2 class="protocol name">Component protocol</h2>
|
| 886 | <p class="protocol description">Protocol for handling the component registry.</p>
|
| 887 | <h3 id="component-list" class="message name"><a href="#component-list">list</a></h3>
|
| 888 | <p>Request a list of currently available components. Will be responded with a set of `component` messages.</p>
|
| 889 | <ul class="message properties">
|
| 890 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 891 | </ul>
|
| 892 | <h3 id="component-getsource" class="message name"><a href="#component-getsource">getsource</a></h3>
|
| 893 | <p>Request for the source code of a given component. Will be responded with a `source` message.</p>
|
| 894 | <ul class="message properties">
|
| 895 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">Name of the component to for which to get source code. Should contain the library prefix</label><code class="property example">"my-project/SomeComponent"</code></li>
|
| 896 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 897 | </ul>
|
| 898 | <h3 id="component-source" class="message name"><a href="#component-source">source</a></h3>
|
| 899 | <p>Source code for a component. In cases where a runtime receives a `source` message, it should do whatever operations are needed for making that component available for graphs, including possible compilation.</p>
|
| 900 | <ul class="message properties">
|
| 901 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">Name of the component. Must not contain library prefix</label><code class="property example">"MyComponent"</code></li>
|
| 902 | <li><label class="property name">language</label><label class="property type">string</label><label class="property description">The programming language used for the component code</label><code class="property example">"c++"</code></li>
|
| 903 | <li><label class="property name">library</label><label class="property type">string</label><label class="property description">Component library identifier</label><code class="property example">"components-common"</code></li>
|
| 904 | <li><label class="property name">code</label><label class="property type">string</label><label class="property description">Component source code</label></li>
|
| 905 | <li><label class="property name">tests</label><label class="property type">string</label><label class="property description">unit tests for the component</label></li>
|
| 906 | </ul>
|
| 907 | <h3 id="component-error" class="message name"><a href="#component-error">error</a></h3>
|
| 908 | <p>Error response to a command on component protocol</p>
|
| 909 | <ul class="message properties">
|
| 910 | <li><label class="property name">message</label><label class="property type">string</label><label class="property description">Error message describing what went wrong</label></li>
|
| 911 | </ul>
|
| 912 | <h3 id="component-component" class="message name"><a href="#component-component">component</a></h3>
|
| 913 | <p>Transmit the metadata about a component instance.</p>
|
| 914 | <ul class="message properties">
|
| 915 | <li><label class="property name">name</label><label class="property type">string</label><label class="property description">component name in format that can be used in graphs. Should contain the component library prefix.</label><code class="property example">"my-project/MyComponent"</code></li>
|
| 916 | <li><label class="property name">description</label><label class="property type">string</label><label class="property description">textual description on what the component does</label></li>
|
| 917 | <li><label class="property name">icon</label><label class="property type">string</label><label class="property description">Visual icon for the component, matching icon names in <a href="http://fortawesome.github.io/Font-Awesome/icons/">Font Awesome</a></label></li>
|
| 918 | <li><label class="property name">subgraph</label><label class="property type">boolean</label><label class="property description">boolean telling whether the component is a subgraph</label></li>
|
| 919 | <li><label class="property name">inPorts</label><label class="property type">array</label><label class="property description">list of input ports of the component</label></li>Each item contains:
|
| 920 | <ul class="properties">
|
| 921 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 922 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">port datatype</label><code class="property example">"boolean"</code></li>
|
| 923 | <li><label class="property optional name">schema</label><label class="property optional type">string</label><label class="property optional description">Link to JSON schema for data on this port</label><code class="property optional example">"https://example.net/schemas/person.json"</code></li>
|
| 924 | <li><label class="property optional name">required</label><label class="property optional type">boolean</label><label class="property optional description">whether the port needs to be connected for the component to work</label><code class="property optional example">true</code></li>
|
| 925 | <li><label class="property optional name">addressable</label><label class="property optional type">boolean</label><label class="property optional description">whether the port is an ArrayPort</label><code class="property optional example">false</code></li>
|
| 926 | <li><label class="property optional name">description</label><label class="property optional type">string</label><label class="property optional description">textual description of the port</label></li>
|
| 927 | <li><label class="property optional name">values</label><label class="property optional type">array</label><label class="property optional description">list of values accepted for the port</label></li>
|
| 928 | <li><label class="property optional name">default</label><label class="property optional type">any</label><label class="property optional description">default value for the port</label></li>
|
| 929 | </ul>
|
| 930 | <li><label class="property name">outPorts</label><label class="property type">array</label><label class="property description">list of output ports of the component</label></li>Each item contains:
|
| 931 | <ul class="properties">
|
| 932 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 933 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">port datatype</label><code class="property example">"boolean"</code></li>
|
| 934 | <li><label class="property optional name">schema</label><label class="property optional type">string</label><label class="property optional description">Link to JSON schema for data on this port</label><code class="property optional example">"https://example.net/schemas/person.json"</code></li>
|
| 935 | <li><label class="property optional name">required</label><label class="property optional type">boolean</label><label class="property optional description">whether the port needs to be connected for the component to work</label><code class="property optional example">true</code></li>
|
| 936 | <li><label class="property optional name">addressable</label><label class="property optional type">boolean</label><label class="property optional description">whether the port is an ArrayPort</label><code class="property optional example">false</code></li>
|
| 937 | <li><label class="property optional name">description</label><label class="property optional type">string</label><label class="property optional description">textual description of the port</label></li>
|
| 938 | <li><label class="property optional name">values</label><label class="property optional type">array</label><label class="property optional description">list of values accepted for the port</label></li>
|
| 939 | <li><label class="property optional name">default</label><label class="property optional type">any</label><label class="property optional description">default value for the port</label></li>
|
| 940 | </ul>
|
| 941 | </ul>
|
| 942 | <h3 id="component-componentsready" class="message name"><a href="#component-componentsready">componentsready</a></h3>
|
| 943 | <p>Indication that a component listing has finished</p>
|
| 944 | <ul class="message properties">
|
| 945 | </ul>
|
| 946 | <h2 class="protocol name">Network protocol</h2>
|
| 947 | <p class="protocol description">Protocol for starting and stopping FBP networks, and finding out about their state.</p>
|
| 948 | <h3 id="network-start" class="message name"><a href="#network-start">start</a></h3>
|
| 949 | <p>Start execution of a FBP network based on a given graph.</p>
|
| 950 | <ul class="message properties">
|
| 951 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 952 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 953 | </ul>
|
| 954 | <h3 id="network-getstatus" class="message name"><a href="#network-getstatus">getstatus</a></h3>
|
| 955 | <p>Get the current status of the runtime. The runtime should respond with a status message.</p>
|
| 956 | <ul class="message properties">
|
| 957 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 958 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 959 | </ul>
|
| 960 | <h3 id="network-stop" class="message name"><a href="#network-stop">stop</a></h3>
|
| 961 | <p>Stop execution of a FBP network based on a given graph.</p>
|
| 962 | <ul class="message properties">
|
| 963 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 964 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 965 | </ul>
|
| 966 | <h3 id="network-persist" class="message name"><a href="#network-persist">persist</a></h3>
|
| 967 | <p>Tells the runtime to persist the current state of graphs and components so that they are available between restarts. Requires the network:persist capability.</p>
|
| 968 | <ul class="message properties">
|
| 969 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 970 | </ul>
|
| 971 | <h3 id="network-debug" class="message name"><a href="#network-debug">debug</a></h3>
|
| 972 | <p>Set a network into debug mode</p>
|
| 973 | <ul class="message properties">
|
| 974 | <li><label class="property name">enable</label><label class="property type">boolean</label><label class="property description">tells whether to put the network in debug mode</label></li>
|
| 975 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 976 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize the user</label></li>
|
| 977 | </ul>
|
| 978 | <h3 id="network-edges" class="message name"><a href="#network-edges">edges</a></h3>
|
| 979 | <p>List of edges user has selected for inspection in a user interface or debugger, sent from UI to a runtime.</p>
|
| 980 | <ul class="message properties">
|
| 981 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 982 | <li><label class="property name">edges</label><label class="property type">array</label><label class="property description">list of selected edges</label></li>Each item contains:
|
| 983 | <ul class="properties">
|
| 984 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 985 | <ul class="properties">
|
| 986 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 987 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 988 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 989 | </ul>
|
| 990 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 991 | <ul class="properties">
|
| 992 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 993 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 994 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 995 | </ul>
|
| 996 | </ul>
|
| 997 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize user</label></li>
|
| 998 | </ul>
|
| 999 | <h3 id="network-stopped" class="message name"><a href="#network-stopped">stopped</a></h3>
|
| 1000 | <p>Inform that a given network has stopped.</p>
|
| 1001 | <ul class="message properties">
|
| 1002 | <li><label class="property name">time</label><label class="property type">string</label><label class="property description">time when the network was stopped</label></li>
|
| 1003 | <li><label class="property name">uptime</label><label class="property type">number</label><label class="property description">time the network was running, in seconds</label></li>
|
| 1004 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1005 | <li><label class="property name">running</label><label class="property type">boolean</label><label class="property description">whether or not network is currently running</label></li>
|
| 1006 | <li><label class="property name">started</label><label class="property type">boolean</label><label class="property description">whether or not network has been started</label></li>
|
| 1007 | <li><label class="property name">debug</label><label class="property type">boolean</label><label class="property description">whether or not network is in debug mode</label></li>
|
| 1008 | </ul>
|
| 1009 | <h3 id="network-started" class="message name"><a href="#network-started">started</a></h3>
|
| 1010 | <p>Inform that a given network has been started.</p>
|
| 1011 | <ul class="message properties">
|
| 1012 | <li><label class="property name">time</label><label class="property type">string</label><label class="property description">time when the network was started</label></li>
|
| 1013 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1014 | <li><label class="property name">started</label><label class="property type">boolean</label><label class="property description">whether or not network has started running</label></li>
|
| 1015 | <li><label class="property name">running</label><label class="property type">boolean</label><label class="property description">whether or not network is currently running</label></li>
|
| 1016 | <li><label class="property name">debug</label><label class="property type">boolean</label><label class="property description">whether or not network is in debug mode</label></li>
|
| 1017 | </ul>
|
| 1018 | <h3 id="network-status" class="message name"><a href="#network-status">status</a></h3>
|
| 1019 | <p>Response to a getstatus message.</p>
|
| 1020 | <ul class="message properties">
|
| 1021 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1022 | <li><label class="property name">uptime</label><label class="property type">number</label><label class="property description">time the network has been running, in seconds</label></li>
|
| 1023 | <li><label class="property name">started</label><label class="property type">boolean</label><label class="property description">whether or not network has started running</label></li>
|
| 1024 | <li><label class="property name">running</label><label class="property type">boolean</label><label class="property description">boolean tells whether the network is running or not</label></li>
|
| 1025 | <li><label class="property name">debug</label><label class="property type">boolean</label><label class="property description">whether or not network is in debug mode</label></li>
|
| 1026 | </ul>
|
| 1027 | <h3 id="network-output" class="message name"><a href="#network-output">output</a></h3>
|
| 1028 | <p>An output message from a running network, roughly similar to STDOUT 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.'</p>
|
| 1029 | <ul class="message properties">
|
| 1030 | <li><label class="property name">message</label><label class="property type">string</label><label class="property description">contents of the output line</label></li>
|
| 1031 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">type of output, either message or previewurl</label></li>
|
| 1032 | <li><label class="property name">url</label><label class="property type">string</label><label class="property description">URL for an image generated by the runtime</label></li>
|
| 1033 | </ul>
|
| 1034 | <h3 id="network-error" class="message name"><a href="#network-error">error</a></h3>
|
| 1035 | <p>An error from a running network, roughly similar to STDERR output of a Unix process, or a line of console.error in JavaScript.'</p>
|
| 1036 | <ul class="message properties">
|
| 1037 | <li><label class="property name">message</label><label class="property type">string</label><label class="property description">contents of the error message</label></li>
|
| 1038 | <li><label class="property name">stack</label><label class="property type">string</label><label class="property description">stack trace</label></li>
|
| 1039 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1040 | </ul>
|
| 1041 | <h3 id="network-processerror" class="message name"><a href="#network-processerror">processerror</a></h3>
|
| 1042 | <p>When in debug mode, a network can signal an error happening inside a process.</p>
|
| 1043 | <ul class="message properties">
|
| 1044 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">identifier of the node</label></li>
|
| 1045 | <li><label class="property name">error</label><label class="property type">string</label><label class="property description">error from the component</label></li>
|
| 1046 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1047 | </ul>
|
| 1048 | <h3 id="network-icon" class="message name"><a href="#network-icon">icon</a></h3>
|
| 1049 | <p>Icon of a component instance has changed.</p>
|
| 1050 | <ul class="message properties">
|
| 1051 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">identifier of the node</label></li>
|
| 1052 | <li><label class="property name">icon</label><label class="property type">string</label><label class="property description">new icon for the component instance</label></li>
|
| 1053 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1054 | </ul>
|
| 1055 | <h3 id="network-connect" class="message name"><a href="#network-connect">connect</a></h3>
|
| 1056 | <p>Beginning of transmission on an edge.</p>
|
| 1057 | <ul class="message properties">
|
| 1058 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">textual edge identifier, usually in form of a FBP language line</label></li>
|
| 1059 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 1060 | <ul class="properties">
|
| 1061 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1062 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1063 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1064 | </ul>
|
| 1065 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 1066 | <ul class="properties">
|
| 1067 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1068 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1069 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1070 | </ul>
|
| 1071 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1072 | <li><label class="property name">subgraph</label><label class="property type">array</label><label class="property description">Subgraph identifier for the event. An array of node IDs.</label></li>
|
| 1073 | </ul>
|
| 1074 | <h3 id="network-begingroup" class="message name"><a href="#network-begingroup">begingroup</a></h3>
|
| 1075 | <p>Beginning of a group (bracket IP) on an edge.</p>
|
| 1076 | <ul class="message properties">
|
| 1077 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">textual edge identifier, usually in form of a FBP language line</label></li>
|
| 1078 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 1079 | <ul class="properties">
|
| 1080 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1081 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1082 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1083 | </ul>
|
| 1084 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 1085 | <ul class="properties">
|
| 1086 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1087 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1088 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1089 | </ul>
|
| 1090 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1091 | <li><label class="property name">subgraph</label><label class="property type">array</label><label class="property description">Subgraph identifier for the event. An array of node IDs.</label></li>
|
| 1092 | </ul>
|
| 1093 | <h3 id="network-data" class="message name"><a href="#network-data">data</a></h3>
|
| 1094 | <p>Data transmission on an edge.</p>
|
| 1095 | <ul class="message properties">
|
| 1096 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">textual edge identifier, usually in form of a FBP language line</label></li>
|
| 1097 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 1098 | <ul class="properties">
|
| 1099 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1100 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1101 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1102 | </ul>
|
| 1103 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 1104 | <ul class="properties">
|
| 1105 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1106 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1107 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1108 | </ul>
|
| 1109 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1110 | <li><label class="property name">subgraph</label><label class="property type">array</label><label class="property description">Subgraph identifier for the event. An array of node IDs.</label></li>
|
| 1111 | </ul>
|
| 1112 | <h3 id="network-endgroup" class="message name"><a href="#network-endgroup">endgroup</a></h3>
|
| 1113 | <p>Ending of a group (bracket IP) on an edge.</p>
|
| 1114 | <ul class="message properties">
|
| 1115 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">textual edge identifier, usually in form of a FBP language line</label></li>
|
| 1116 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 1117 | <ul class="properties">
|
| 1118 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1119 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1120 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1121 | </ul>
|
| 1122 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 1123 | <ul class="properties">
|
| 1124 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1125 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1126 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1127 | </ul>
|
| 1128 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1129 | <li><label class="property name">subgraph</label><label class="property type">array</label><label class="property description">Subgraph identifier for the event. An array of node IDs.</label></li>
|
| 1130 | </ul>
|
| 1131 | <h3 id="network-disconnect" class="message name"><a href="#network-disconnect">disconnect</a></h3>
|
| 1132 | <p>End of transmission on an edge.</p>
|
| 1133 | <ul class="message properties">
|
| 1134 | <li><label class="property name">id</label><label class="property type">string</label><label class="property description">textual edge identifier, usually in form of a FBP language line</label></li>
|
| 1135 | <li><label class="property name">src</label><label class="property type">object</label><label class="property description">source node for the edge</label></li>
|
| 1136 | <ul class="properties">
|
| 1137 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1138 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1139 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1140 | </ul>
|
| 1141 | <li><label class="property name">tgt</label><label class="property type">object</label><label class="property description">target node for the edge</label></li>
|
| 1142 | <ul class="properties">
|
| 1143 | <li><label class="property name">node</label><label class="property type">string</label><label class="property description">node identifier</label></li>
|
| 1144 | <li><label class="property name">port</label><label class="property type">string</label><label class="property description">port name</label></li>
|
| 1145 | <li><label class="property name">index</label><label class="property type">string,number</label><label class="property description">connection index, for addressable ports</label></li>
|
| 1146 | </ul>
|
| 1147 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">graph the action targets</label></li>
|
| 1148 | <li><label class="property name">subgraph</label><label class="property type">array</label><label class="property description">Subgraph identifier for the event. An array of node IDs.</label></li>
|
| 1149 | </ul>
|
| 1150 | <h2 class="protocol name">Trace protocol</h2>
|
| 1151 | <p class="protocol description">This protocol is utilized for triggering and transmitting [Flowtrace](https://github.com/flowbased/flowtrace)s</p>
|
| 1152 | <h3 id="trace-start" class="message name"><a href="#trace-start">start</a></h3>
|
| 1153 | <p>Enable/start tracing of a network.</p>
|
| 1154 | <ul class="message properties">
|
| 1155 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize the client</label></li>
|
| 1156 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">Graph identifier the message targets</label></li>
|
| 1157 | <li><label class="property name">buffersize</label><label class="property type">integer</label><label class="property description">Size of tracing buffer to keep. In bytes</label></li>
|
| 1158 | </ul>
|
| 1159 | <h3 id="trace-stop" class="message name"><a href="#trace-stop">stop</a></h3>
|
| 1160 | <p>Stop/disable tracing of a network.</p>
|
| 1161 | <ul class="message properties">
|
| 1162 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize the client</label></li>
|
| 1163 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">Graph identifier the message targets</label></li>
|
| 1164 | </ul>
|
| 1165 | <h3 id="trace-dump" class="message name"><a href="#trace-dump">dump</a></h3>
|
| 1166 | <p>undefined</p>
|
| 1167 | <ul class="message properties">
|
| 1168 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">Graph identifier the message targets</label></li>
|
| 1169 | <li><label class="property name">type</label><label class="property type">string</label><label class="property description">String describing type of trace.</label></li>
|
| 1170 | <li><label class="property name">flowtrace</label><label class="property type">string</label><label class="property description">A Flowtrace file of `type`</label></li>
|
| 1171 | </ul>
|
| 1172 | <h3 id="trace-clear" class="message name"><a href="#trace-clear">clear</a></h3>
|
| 1173 | <p>Clear current tracing buffer.</p>
|
| 1174 | <ul class="message properties">
|
| 1175 | <li><label class="property name">secret</label><label class="property type">string</label><label class="property description">access token to authorize the client</label></li>
|
| 1176 | <li><label class="property name">graph</label><label class="property type">string</label><label class="property description">Graph identifier the message targets</label></li>
|
| 1177 | </ul>
|
| 1178 | <h3 id="trace-error" class="message name"><a href="#trace-error">error</a></h3>
|
| 1179 | <p>Error response to a command on trace protocol</p>
|
| 1180 | <ul class="message properties">
|
| 1181 | <li><label class="property name">message</label><label class="property type">string</label><label class="property description">Error message describing what went wrong</label></li>
|
| 1182 | </ul>
|
| 1183 |
|
| 1184 | </article>
|
| 1185 | </body>
|
| 1186 | </html>
|