PlayifyRpc 1.9.5

This library allows calling functions across different devices. It works for:

• C# Applications
• Web Applications (and Node.js)
• Microcontrollers (ESP8266 and ESP32)

Web Interface

You can access http://127.0.0.1:4590/rpc to get to a simple web interface, where you can evaluate simple RPC calls directly from the browser (and the browser devtools).

Additionally, you can call functions directly using http://127.0.0.1:4590/rpc/EXPRESSION.

For example, if you want to call Rpc.getRegistrations(), you can access http://127.0.0.1:4590/rpc/Rpc.getRegistrations() and get the return value from the HTTP response.

Using http://127.0.0.1:4590/rpc/EXPRESSION/pretty you can get a prettified JSON back.

Using http://127.0.0.1:4590/rpc/EXPRESSION/void you don't get any response back (HTTP Status Code 204).

Using http://127.0.0.1:4590/rpc/EXPRESSION/download=test.txt you get the response as file download<br/> Using http://127.0.0.1:4590/rpc/EXPRESSION/file=test.html you open the response directly in the browser

Using http://127.0.0.1:4590/rpc/EXPRESSION/headers and http://127.0.0.1:4590/rpc/EXPRESSION/cookies an object will be appended to the argument list, that contains the requested special data. Using http://127.0.0.1:4590/rpc/EXPRESSION/body=binary, http://127.0.0.1:4590/rpc/EXPRESSION/body=string, http://127.0.0.1:4590/rpc/EXPRESSION/body=json, http://127.0.0.1:4590/rpc/EXPRESSION/body=auto or http://127.0.0.1:4590/rpc/EXPRESSION/body, the body will be appended to the argument list, based on the specified format. If no format is specified, it gets auto-detected based on the Content-Type Header.

Using http://127.0.0.1:4590/rpc/EXPRESSION/http you can get a customizable http response. The Expression should result in an object with optional keys:

• status:
  • number ⇒ represents the HTTP status code
• headers:
  • string ⇒ containing one or more lines with the format of "Key: Value"
  • strign[] ⇒ each a single line with the format of "Key: Value"
  • object ⇒ each key value pair represents a single header
• body:
  • string ⇒ Response will be a text (utf-8 encoding)
  • byte[] (Uint8Array in JavaScript) ⇒ Response will have binary content
  • any ⇒ Response will be in a json representation
  • missing ⇒ Response will be empty *

Using http://127.0.0.1:4590/rpc/EXPRESSION/serve or http://127.0.0.1:4590/rpc/EXPRESSION/serve=html you can directly use the return value as http content. If the content type is not chosen based on the file type parameter, it will be chosen based on the return value.

• null ⇒ No Content = HTTP Status 204
• string ⇒ Response will be a text (utf-8 encoding)
• byte[] (Uint8Array in JavaScript) ⇒ Response will have binary content
• any ⇒ Response will be in a json representation as text

Server

The RPC Server is only available for C#, clients are available in other languages as well. The server should run on a device that is reachable by all its clients. Clients can only communicate with each other if they are connected to the server, direct connections between clients are not supported.

Installation (Server)

Make sure dotnet 6 (or above) is installed.

Install the server files into an empty directory using one of the following commands.

Linux:

curl -sSL https://raw.githubusercontent.com/Playify/PlayifyRpc/master/PlayifyRpc_CSharp/_run/get-rpc.sh | bash

Windows:

powershell "irm https://raw.githubusercontent.com/Playify/PlayifyRpc/master/PlayifyRpc_CSharp/_run/get-rpc.ps1|iex"

Now you can use the rpc.sh or the rpc.bat script to run the RPC server.

Security

When the server sets the RPC_TOKEN environment variable to some arbitrary passphrase, only clients that also have the RPC_TOKEN set to the same passphrase are accepted.

• Web clients need the RPC_TOKEN cookie.
• NodeJs clients need to define the RPC_TOKEN environment variable.
• C# clients either need to define the RPC_TOKEN environment variable or pass it into Rpc.Connect.
• PlatformIO clients need to pass it into Rpc::connect.

Nginx

If you want to use Nginx (e.g., for HTTPS or having multiple web pages on a single server), you should use the following location block:

location ~ ^/rpc {
	proxy_http_version 1.1;
	proxy_set_header Host $http_host;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection "upgrade";
	proxy_pass http://127.0.0.1:4590;
}

PlayifyRpc needs access to /rpc.js, /rpc.js.map, /rpc (HTTP & WebSockets), and /rpc/*.

Client

Call Rpc.connect() to connect to a server. By default, it uses the RPC_URL and RPC_TOKEN environment variables, but you can specify them as well.

Calling Functions

Remote functions can be called using Rpc.CallFunction(type,method,arg1,arg2,...), using RpcObject.CallFunction or using RpcFunction.Call.

RpcObject also supports dynamic invoking, e.g. dynamic obj=new RpcObject("Type"); obj.Test(1,2,3) will call Type.Test(1,2,3) directly

Additionally, you can template whole Types directly, using [RpcConsumer] e.g.

[RpcConsumer]
public class Type{
    public partial static PendingCall<int> Test(int a,int b,int c);
}

the corresponding implementation will be generated by a SourceGenerator, and supports return types of PendingCall, Task and synchronous types like int directly

When calling a function, you get a PendingCall, which acts like a Task. It can be cast to a Task<?> of any supported data type.

A PendingCall has a Cancel() method to signal to the other end that the operation should be cancelled. This is only useful if the executing end also handles the cancellation, otherwise, nothing will happen.

A PendingCall also has a SendMessage() method, which is used to send arbitrary messages to the executor. Using the AddMessageListener() method, you can listen to messages that get sent by the executor. Alternatively, you can use it as an IAsyncEnumerable to consume the messages within an await foreach loop.

Registering Types

Using Rpc.RegisterType(), you can register a:

• Type (using typeof(XXX)) to make a static class accessible to others.
• Instance (using new XXX).
• Invoker, preferably DictionaryInvoker, to register methods one by one.

You can also use the RpcProviderAttribute to register a static class.

Receiving function calls

A method on a registered type can have any number of parameters, even params is supported. The parameters should be use supported types. The return type should be a Task, Task<?>, a supported type, or void.

Additionally, some special parameters will be filled out automatically, so a method Test(FunctionCallContext ctx,int i), will be called from other clients using just Type.Test(123):

• FunctionCallContext: similar to PendingCall, can be used to access infos, such as who called the function

  has a SendMessage() and AddMessageListener() method and can also be used as an IAsyncEnumerable.

• CancellationToken: shorthand for FunctionCallContext.CancellationToken:

  will be tied to the PendingCall.Cancel() method, can be additionally triggered using FunctionCallContext.CancelSelf()