From ae3430bf56fdb76c4eeb411dfbc358b0e1c4a48c Mon Sep 17 00:00:00 2001 From: Tasia Iso Date: Sun, 12 May 2024 10:58:56 +0200 Subject: [PATCH] docs: move documentation out of guide.md --- docs/.guide.md | 213 ----------------------------------------------- docs/apps/api.md | 181 ++++++++++++++++++++++++++++++++++++++++ docs/in-depth.md | 31 +++++++ 3 files changed, 212 insertions(+), 213 deletions(-) create mode 100644 docs/apps/api.md create mode 100644 docs/in-depth.md diff --git a/docs/.guide.md b/docs/.guide.md index 086f7b12..e69de29b 100644 --- a/docs/.guide.md +++ b/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. diff --git a/docs/apps/api.md b/docs/apps/api.md new file mode 100644 index 00000000..f2cfb34c --- /dev/null +++ b/docs/apps/api.md @@ -0,0 +1,181 @@ + \ No newline at end of file diff --git a/docs/in-depth.md b/docs/in-depth.md new file mode 100644 index 00000000..6f4d3c93 --- /dev/null +++ b/docs/in-depth.md @@ -0,0 +1,31 @@ +# Tilde Friends in depth +# Tilde Friends + +## Philosophy + +Tilde Friends is a platform for making, running, and sharing web applications. + + + +## 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.