Connecting Resonite to Other Applications: Difference between revisions

From Resonite Wiki
cleanup + redo headings + add links
added info on security limitations, fixed links to ProtoFlux
 
(2 intermediate revisions by one other user not shown)
Line 8: Line 8:


== Options ==
== Options ==
You have a number of options to achieve communication with other applications. With all of these options do remember that we '''does not''' support JSON or Collections/Arrays so you will have to handle parsing these yourself within [[ProtoFlux|Protoflux]].
You have a number of options to achieve communication with other applications. With all of these options do remember that we '''does not''' support JSON or Collections/Arrays so you will have to handle parsing these yourself within [[ProtoFlux]].


=== Webserver Communication using HTTP ===
=== Webserver Communication using HTTP ===


Resonite has two nodes that can allow you to make HTTP Requests:
Resonite has two nodes that can allow you to make HTTP Requests:
* [[GET String (ProtoFlux_node)| HTTP GET]] - Submits an HTTP GET Request
* [[ProtoFlux:GET String|HTTP GET]] - Submits an HTTP GET Request
* [[POST String (ProtoFlux_node)| HTTP POST]] - Submits an HTTP POST Request  
* [[ProtoFlux:POST String|HTTP POST]] - Submits an HTTP POST Request  


You can use these to communicate with any HTTP capable webserver, API or system.  
You can use these to communicate with any HTTP capable webserver, API or system.  


=== Web Socket Communication ===
=== Web Socket Communication ===
Protoflux has [[WebSocket| WebSocket capabilities]]. These allow Resonite to communicate with any WebSocket capable server. This is useful for real time communication between Resonite and an Application.
ProtoFlux has [[WebSocket| WebSocket capabilities]]. These allow Resonite to communicate with any WebSocket capable server. This is useful for real time communication between Resonite and an Application.


=== Sending other Protocols over WebSockets ===
=== Sending other Protocols over WebSockets ===
Line 38: Line 38:


== Security / Consent ==
== Security / Consent ==
Always consider Security, talking to outside systems can open up all sorts of security issues. At this time anything involving Payments, Passwords or personal information is not recommended.
Always consider Security, talking to outside systems can open up all sorts of security issues.
As of version <code>2024.4.26.1258</code> be aware that:
* HTTP requests and websockets cannot be authenticated. (Userinfo in URIs like <code>https://'''''user:password'''''@host/</code> will be ignored!)
* Without a permission system the World Model is open to everyone. With enough effort any user can read local values and trigger ProtoFlux of another.
This means that at this time anything involving Payments, Passwords or personal information is not recommended.


Additionally, outside connections via HTTP and WebSockets are controlled by a User's Consent, They can block and allow access to specific domain names and servers. Always use the [[Is Host Access Allowed_(Protoflux node)| Is Host Access Allowed]] and [[Request Host Access (Protoflux node)| Request Host Access]] Nodes to check if a User has blocked a connection and to request access to a host. When requesting access, please specify a logical reason.
Additionally, outside connections via HTTP and WebSockets are controlled by a User's Consent, They can block and allow access to specific domain names and servers. Always use the [[ProtoFlux:Is Host Access Allowed|Is Host Access Allowed]] and [[ProtoFlux:Request Host Access|Request Host Access]] Nodes to check if a User has blocked a connection and to request access to a host. When requesting access, please specify a logical reason.


If a user has blocked access, try to make your systems gracefully fail with a clear message about what is going on.
If a user has blocked access, try to make your systems gracefully fail with a clear message about what is going on.

Latest revision as of 14:32, 28 April 2024

When creating items and worlds within Resonite, you may want to connect Resonite to the outside world. To applications, software and systems that are outside of it. This guide will provide some information on how you can achieve that.

Example Scenarios

Some example things you might want to do this with are:

  • Communicating with Web Servers
  • Talking to Real world Hardware or devices such as Heart Rate Sensors, Lights or Sound Equipment
  • Receiving data such as stock information, the weather and more

Options

You have a number of options to achieve communication with other applications. With all of these options do remember that we does not support JSON or Collections/Arrays so you will have to handle parsing these yourself within ProtoFlux.

Webserver Communication using HTTP

Resonite has two nodes that can allow you to make HTTP Requests:

You can use these to communicate with any HTTP capable webserver, API or system.

Web Socket Communication

ProtoFlux has WebSocket capabilities. These allow Resonite to communicate with any WebSocket capable server. This is useful for real time communication between Resonite and an Application.

Sending other Protocols over WebSockets

While Resonite only supports HTTP and WebSockets you can send messages over WebSockets which resemble or contain messages in other protocols. Users have done this with:

  • DMX
  • MIDI
  • OSC

Using a WebSocket / HTTP Proxy

You can also use WebSockets or HTTP as a proxy to communicate to another device. Users have done this with:

  • Heart Rate Sensors
  • Calendars
  • Complex APIs that needed simplifying

Using Plugins

Resonite has Plugins which allow you to write custom functionality into Resonite. This functionality can be vast and varied as you have full implementation control in C#. When you use plugins you will be isolated from the rest of the Resonite Community as they will only be able to join your sessions if they have the same Plugins installed. Please see the plugin page for more information.

Security / Consent

Always consider Security, talking to outside systems can open up all sorts of security issues. As of version 2024.4.26.1258 be aware that:

  • HTTP requests and websockets cannot be authenticated. (Userinfo in URIs like https://user:password@host/ will be ignored!)
  • Without a permission system the World Model is open to everyone. With enough effort any user can read local values and trigger ProtoFlux of another.

This means that at this time anything involving Payments, Passwords or personal information is not recommended.

Additionally, outside connections via HTTP and WebSockets are controlled by a User's Consent, They can block and allow access to specific domain names and servers. Always use the Is Host Access Allowed and Request Host Access Nodes to check if a User has blocked a connection and to request access to a host. When requesting access, please specify a logical reason.

If a user has blocked access, try to make your systems gracefully fail with a clear message about what is going on.

Recommendations

When deciding what to do here, it's entirely up to you but some recommendations are presented here to assist you in making a decision.

  • Only use WebSockets if you need real time communication - WebSockets have extra overhead for both servers and clients/Resonite users. If you just need to make requests and receive responses consider HTTP instead.
  • Ensure that you're running the requests / connections from the right users. Connections need to be made from a user. For example when you make a request a single user is in charge of running that request. Make sure this is the correct user and that you're not running requests for more than one user.