docs: move documentation out of guide.md
This commit is contained in:
parent
7d77e398d4
commit
ae3430bf56
SSH Key Fingerprint:
SHA256:KiRjUay5C9i6objsEOIycygBHn54pDBB3Lj7fyJ0Elw
213
docs/.guide.md
213
docs/.guide.md
@ -1,213 +0,0 @@
|
||||
# Tilde Friends
|
||||
|
||||
## Philosophy
|
||||
|
||||
Tilde Friends is a platform for making, running, and sharing web applications.
|
||||
|
||||
When you visit Tilde Friends in a web browser, you are presented with a
|
||||
terminal interface, typically with a big text output box covering most of the
|
||||
page and an input box at the bottom, into which text or commands can be
|
||||
entered. A script runs to produce text output and consume user input.
|
||||
|
||||
The script is a Tilde Friends application, and it runs on the server, which
|
||||
means that unlike client-side JavaScript, it can have the ability to read and
|
||||
write files on the server or create network connections to other machines.
|
||||
Unlike node.js or other server-side runtime environments, applications are
|
||||
limited for security reasons to not interfere with each other or bring the
|
||||
entire server down.
|
||||
|
||||
Above the terminal, an "Edit" link brings a visitor to the source code for the
|
||||
current Tilde Friends application, which they can then edit, save as their own,
|
||||
and run.
|
||||
|
||||
## Architecture
|
||||
|
||||
Tilde Friends is a C++ application with a JavaScript runtime that provides
|
||||
restricted access to filesystem, network, and other system resources. The core
|
||||
process runs a core set of scripts that implement a web server, typically
|
||||
starting a new process for each visitor's session which runs scripts for the
|
||||
active application and stopping it when the visitor leaves.
|
||||
|
||||
Only the core process has access to most system resources, but session
|
||||
processes can be given accesss through the core process.
|
||||
|
||||
Service processes are identical to session processes, but they are not tied to
|
||||
a user session.
|
||||
|
||||
## 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.
|
||||
181
docs/apps/api.md
Normal file
181
docs/apps/api.md
Normal file
@ -0,0 +1,181 @@
|
||||
<!--
|
||||
|
||||
## 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.
|
||||
|
||||
-->
|
||||
31
docs/in-depth.md
Normal file
31
docs/in-depth.md
Normal file
@ -0,0 +1,31 @@
|
||||
# Tilde Friends in depth
|
||||
# Tilde Friends
|
||||
|
||||
## Philosophy
|
||||
|
||||
Tilde Friends is a platform for making, running, and sharing web applications.
|
||||
|
||||
<!-- When you visit Tilde Friends in a web browser, you are presented with a
|
||||
terminal interface, typically with a big text output box covering most of the
|
||||
page and an input box at the bottom, into which text or commands can be
|
||||
entered. A script runs to produce text output and consume user input.
|
||||
|
||||
The script is a Tilde Friends application, and it runs on the server, which
|
||||
means that unlike client-side JavaScript, it can have the ability to read and
|
||||
write files on the server or create network connections to other machines.
|
||||
Unlike node.js or other server-side runtime environments, applications are
|
||||
limited for security reasons to not interfere with each other or bring the
|
||||
entire server down.
|
||||
|
||||
Above the terminal, an "Edit" link brings a visitor to the source code for the
|
||||
current Tilde Friends application, which they can then edit, save as their own,
|
||||
and run. -->
|
||||
|
||||
## Architecture
|
||||
|
||||
Tilde Friends is a C++ application with a JavaScript runtime that provides restricted access to filesystem, network, and other system resources.
|
||||
The core process runs a core set of scripts that implement a web server, typically starting a new process for each visitor's session which runs scripts for the active application and stopping it when the visitor leaves.
|
||||
|
||||
Only the core process has access to most system resources, but session processes can be given accesss through the core process.
|
||||
|
||||
Service processes are identical to session processes, but they are not tied to a user session.
|
||||
Loading…
Reference in New Issue
Block a user