181 lines
5.4 KiB
Markdown
181 lines
5.4 KiB
Markdown
<!--
|
|
|
|
## Communication
|
|
|
|
In the same way that web browsers expose APIs for scripts running in the
|
|
browser to modify the document, play sounds and video, and draw, Tilde Friends
|
|
exposes APIs for scripts running on a Tilde Friends server to interact with a
|
|
visitor's web browser, read and write files on the server, and otherwise
|
|
interact with the world.
|
|
|
|
There are several distinct classes of APIs.
|
|
|
|
First, there are low-level functions exposed from C++ to JavaScript. Most of
|
|
these are only available to the core process. These typically only go through
|
|
a basic JavaScript to C++ transition and are relatively fast and immediate.
|
|
|
|
// Displays some text to the server's console.
|
|
print("Hello, world!");
|
|
|
|
There is a mechanism for communicating between processes. Functions can be
|
|
exported and called across process boundaries. When this is done, any
|
|
arguments are serialized to a network protocol, deserialized by the other
|
|
process, the function called, and finally any return value is passed back in
|
|
the same way. Any functions referenced by the arguments or return value are
|
|
also exported and can be subsequently called across process boundaries.
|
|
Functions called across process boundaries are always asynchronous, returning a
|
|
Promise. Care must be taken for security reasons to not pass dangerous
|
|
functions ("deleteAllMydata()") to untrusted processes, and it is best for
|
|
performance reasons to minimize the data size transferred between processes.
|
|
|
|
// Send an "add" function to any other running processes. When called, it
|
|
// will run in this process.
|
|
core.broadcast({add: function(x, y) { return x + y; }});
|
|
|
|
// Receive the above message and call the function.
|
|
core.register("onMessage", function(sender, message) {
|
|
message.add(3, 4).then(x => terminal.print(x.toString()));
|
|
});
|
|
|
|
Finally, there is a core web interface that runs on the client's browser that
|
|
extends access to a running Tilde Friends script.
|
|
|
|
// Displays a message in the client's browser.
|
|
terminal.print("Hello, world!");
|
|
|
|
## API Documentation
|
|
|
|
The Tilde Friends API is very much evolving.
|
|
|
|
All currently registered methods can be explored in the
|
|
[documentation](https://www.tildefriends.net/~cory/documentation) app.
|
|
|
|
All browser-facing methods are implemented in [client.js](core/client.js).
|
|
Most process-related methods are implemented in [core.js](core/core.js).
|
|
|
|
Higher-level behaviors are often implemented within library-style apps
|
|
themselves and are beyond the scope of this document.
|
|
|
|
### Terminal
|
|
|
|
All interaction with a human user is through a terminal-like interface. Though
|
|
it is somewhat limiting, it makes simple things easy, and it is possible to
|
|
construct complicated interfaces by creating and interacting with an iframe.
|
|
|
|
#### terminal.print(arguments...)
|
|
|
|
Print to the terminal. Arguments and lists are recursively expanded. Numerous
|
|
special values are supported as implemented in client.cs.
|
|
|
|
// Create a link.
|
|
terminal.print({href: "http://www.tildefriends.net/", value: "Tilde Friends!"});
|
|
|
|
// Create an iframe.
|
|
terminal.print({iframe: "<b>Hello, world!</b>", width: 640, height: 480});
|
|
|
|
// Use style.
|
|
terminal.print({style: "color: #f00", value: "Hello, world!"});
|
|
|
|
// Create a link that when clicked will act as if the user typed a command.
|
|
terminal.print({command: "exit", value: "Get out of here."});
|
|
|
|
#### terminal.clear()
|
|
|
|
Clears the terminal output.
|
|
|
|
#### terminal.readLine()
|
|
|
|
Read a line of input from the user.
|
|
|
|
#### terminal.setEcho(echo)
|
|
|
|
Controls whether the terminal will automatically echo user input. Defaults to true.
|
|
|
|
#### terminal.setPrompt(prompt)
|
|
|
|
Sets the terminal prompt. The default is ">".
|
|
|
|
#### terminal.setTitle(title)
|
|
|
|
Sets the browser window/tab title.
|
|
|
|
#### terminal.split(terminalList)
|
|
|
|
Reconfigures the terminal layout, potentially into multiple split panes.
|
|
|
|
```javascript
|
|
terminal.split(
|
|
[{
|
|
type: "horizontal",
|
|
children: [
|
|
{name: "left", basis: "2in", grow: 0, shrink: 0},
|
|
{name: "middle", grow: 1},
|
|
{name: "right", basis: "2in", grow: 0, shrink: 0},
|
|
],
|
|
}]
|
|
);
|
|
```
|
|
|
|
#### terminal.select(name)
|
|
|
|
Directs subsequent output to the named terminal.
|
|
|
|
#### terminal.postMessageToIframe(iframeName, message)
|
|
|
|
Sends a message to the iframe that was created with the given name, using the
|
|
browser's window.postMessage.
|
|
|
|
### Database
|
|
|
|
Tilde Friends uses lmdb as a basic key value store. Keys and values are all
|
|
expected to be of type String. Each application gets its own isolated
|
|
database.
|
|
|
|
#### database.get(key)
|
|
|
|
Retrieve the database value associated with the given key.
|
|
|
|
#### database.set(key, value)
|
|
|
|
Sets the database value for the given key, overwriting any existing value.
|
|
|
|
#### database.remove(key)
|
|
|
|
Remove the database entry for the given key.
|
|
|
|
#### database.getAlll()
|
|
|
|
Retrieve a list of all key names.
|
|
|
|
### Network
|
|
|
|
Network access is generally not extended to untrusted users.
|
|
|
|
It is necessary to grant network permissions to an app owner through the
|
|
administration app.
|
|
|
|
Apps that require network access must declare it like this:
|
|
|
|
//! { "permissions": ["network"] }
|
|
|
|
#### network.newConnection()
|
|
|
|
Creates a Connection object.
|
|
|
|
#### connection.connect(host, port)
|
|
|
|
Opens a TCP connection to host:port.
|
|
|
|
#### connection.read(readCallback)
|
|
|
|
Begins reading and calls readCallback(data) for all data received.
|
|
|
|
#### connection.write(data)
|
|
|
|
Writes data to the connection.
|
|
|
|
#### connection.close()
|
|
|
|
Closes the connection.
|
|
|
|
--> |