Suggestion for message types. #56
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,3 +7,4 @@ dependencies: | |
| - sphinx=5.3.0 | ||
| - sphinxcontrib-mermaid=0.8.1 | ||
| - sphinx_rtd_theme=1.1.1 | ||
| - sphinx-jsonschema=1.19.1 | ||
|
There was a problem hiding this comment. I don't get jsonschema to work. It still shows There was a problem hiding this comment. I've never used it before. Maybe an unexpected interaction with myst parser? There was a problem hiding this comment.
I commented the myst parser (and mermaid), but to no avail.
Yes
At least it does not show any errors locally or in the CI. There was a problem hiding this comment. I even used the jsonschema in the rst file from: https://sphinx-jsonschema.readthedocs.io/en/latest/directive.html#usage There was a problem hiding this comment. I got it to work: This does not work, however, for referencing files, only for showing a code snippet. It does not render our schemata nicely 😭 (it does not render anything at all, as it does not recognize the keywords...). There was a problem hiding this comment. well, some progress at least I guess? :-/ There was a problem hiding this comment. I went with the data-viewer, that works better (but does not allow examples...). |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,171 @@ | ||
| { | ||
| "openrpc": "1.2.6", | ||
| "info": { | ||
| "title": "Actor", | ||
| "version": "0.1.0" | ||
| }, | ||
| "methods": [ | ||
| { | ||
| "name": "get_parameters", | ||
| "description": "Get the values for parameters.", | ||
| "params": [ | ||
| { | ||
| "name": "parameters", | ||
| "schema": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "required": true | ||
| } | ||
| ], | ||
| "result": { | ||
| "name": "result", | ||
| "schema": { | ||
| "type": "object", | ||
| "description": "Object with parameter-value pairs", | ||
| "additionalProperties": true | ||
| }, | ||
| "required": true | ||
| }, | ||
| "examples": [ | ||
| { | ||
| "name": "Get parameters example", | ||
| "params": [ | ||
| { | ||
| "name": "parameters", | ||
| "value": ["parameter1", "parameter2"] | ||
| } | ||
| ], | ||
| "result": { | ||
| "name": "result", | ||
| "value": { | ||
| "parameter1": "value_of_parameter1", | ||
| "parameter2": "some_other_value" | ||
| } | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "name": "set_parameters", | ||
| "params": [ | ||
| { | ||
| "name": "parameters", | ||
| "schema": { | ||
| "type": "object", | ||
| "description": "Object with parameter-value pairs", | ||
| "additionalProperties": true | ||
|
|
||
| }, | ||
| "required": true | ||
| } | ||
| ], | ||
| "result": { | ||
| "name": "result", | ||
| "schema": { | ||
| "type": "null" | ||
| }, | ||
| "required": true | ||
| }, | ||
| "examples": [ | ||
| { | ||
| "name": "Set parameters example", | ||
| "params": [ | ||
| { | ||
| "name": "parameters", | ||
| "value": { | ||
| "parameter1": "value_of_parameter1", | ||
| "parameter2": "some_other_value" | ||
| } | ||
| } | ||
| ], | ||
| "result": { | ||
| "name": "result", | ||
| "value": null | ||
| } | ||
| } | ||
| ] | ||
|
|
||
| }, | ||
| { | ||
| "name": "call_action", | ||
| "description": "Call an Action of this Component. All other arguments are handed to the action.", | ||
| "params": [ | ||
| { | ||
| "name": "action", | ||
| "schema": { | ||
| "type": "string" | ||
| }, | ||
| "required": true | ||
| }, | ||
| { | ||
| "name": "args", | ||
| "schema": { | ||
| "type": "array", | ||
| "description": "List of positional arguments.", | ||
| "items": { | ||
| "$ref": "#/components/any" | ||
| } | ||
| }, | ||
| "required": false | ||
| } | ||
| ], | ||
BenediktBurger marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "result": { | ||
| "name": "result", | ||
| "description": "Result of the action.", | ||
| "schema": { | ||
| "$ref": "#/components/any" | ||
| }, | ||
| "required": true | ||
| }, | ||
| "examples": [ | ||
| { | ||
| "name": "Calling some action with keyword arguments only.", | ||
| "params": [ | ||
| { | ||
| "name": "action", | ||
| "value": "super_action" | ||
| }, | ||
| { | ||
| "name": "args", | ||
| "value": null | ||
|
|
||
| }, | ||
| { | ||
| "name": "argument1", | ||
| "value": 5 | ||
| } | ||
| ], | ||
| "result": { | ||
| "name": "result", | ||
| "value": "result of 'super_action(argument1=5)'." | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "components": { | ||
| "any" : { | ||
| "anyOf": [ | ||
| { | ||
| "description": "Value of the parameter.", | ||
| "type": "integer" | ||
| }, | ||
| { | ||
| "type": "number" | ||
| }, | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| }, | ||
| { | ||
| "type": "object" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| { | ||
| "openrpc": "1.2.6", | ||
| "info": { | ||
| "title": "Component", | ||
| "version": "0.1.0" | ||
| }, | ||
| "methods": [ | ||
| { | ||
| "name": "pong", | ||
| "description": "Respond to a ping.", | ||
| "params": [], | ||
| "result": { | ||
| "name": "result", | ||
| "schema": { | ||
| "type": "null" | ||
| }, | ||
| "required": true | ||
| } | ||
| } | ||
| ] | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| { | ||
| "openrpc": "1.2.6", | ||
| "info": { | ||
| "title": "Component-optional", | ||
| "version": "0.1.0" | ||
| }, | ||
| "methods": [ | ||
| { | ||
| "name": "set_log_level", | ||
| "params": [ | ||
| { | ||
| "name": "level", | ||
| "schema": { | ||
| "type": "integer", | ||
| "multipleOf": 10, | ||
| "minimum": 0, | ||
| "maximum": 100 | ||
| }, | ||
|
There was a problem hiding this comment. See #56 (comment)
Idea is to change to a set of possible values. I don't know yet, how to define it properly. There was a problem hiding this comment. I found a way to define a set of possible values in json-schema ( There was a problem hiding this comment. Hm, for language (and logging-framework) independence, I think a fixed set of level names seems most clear (the python ones seem fine to me). There was a problem hiding this comment. I changed it to strings. |
||
| "required": true | ||
| } | ||
| ], | ||
| "description": "Set the logging level.", | ||
| "result": { | ||
| "name": "result", | ||
| "schema": { | ||
| "type": "null" | ||
| }, | ||
| "required": true | ||
| } | ||
| }, | ||
| { | ||
| "name": "shut_down", | ||
| "params": [], | ||
| "description": "Shut down the Component.", | ||
| "result": { | ||
| "name": "result", | ||
| "schema": { | ||
|
|
||
| "type": "null" | ||
| }, | ||
| "required": true | ||
| } | ||
| } | ||
| ] | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm curious about the optional methods. What happens if some component calls another one's
shutdown, but that is not implemented? Do we need some common fallback method? Do you get a not implemented error back or somesuch?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
jsonrpc has a "method not found" error defined.
My reasoning is: There are some methods necessary, such that a Component fulfills it role (as a component, it has to be pingable), these are necessary.
Some features are nice to have, for example logging is not essential (maybe the Component does not have logging capabilities).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I realise why optional methods can be useful. We should have a clear approach how do deal with that optionality, though -- there are several possibilities (do we error? ignore? publish/discover/supply a list of implemented methods? how should the initiating party deal with that? ...)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Components MUST adhere to openRPC, therefore they MUST offer a "rpc.discover" methods, which tells about all the implemented methods (the output is exactly that, what is part of this PR).
If you try to call a method, a Component does not have, you get an appropriate error.
So, you (as a user) can either query beforehand and use only methods present, or you can try a method name and handle the error.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO, yes.
It's more a LECO implementor that has to deal with that. As we are designing for different implementations to talk to each other, I'm wondering if we should standardise the expectations around what happens with optional methods. The answer might as well be "no", or "use what
rpc.discovergives you as you see fit".There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's my stance 😁