diff --git a/.gitea/workflows/build.yaml b/.gitea/workflows/build.yaml index 9b82077b..923c3678 100644 --- a/.gitea/workflows/build.yaml +++ b/.gitea/workflows/build.yaml @@ -29,7 +29,7 @@ jobs: - run: docker build . - uses: actions/upload-artifact@v3 with: - path: out/TildeFriends-release.fdroid.apk + path: out/TildeFriends-release.fdroid.apk - uses: actions/upload-artifact@v3 with: path: out/winrelease/tildefriends.exe diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md new file mode 100644 index 00000000..f4b4e226 --- /dev/null +++ b/docs/cheatsheet.md @@ -0,0 +1,63 @@ +# Tilde Friends Cheat Sheet + +Making apps for the impatient tilde friend. + +## Prerequisites + +- either run your own instance or use [tildefriends.net](https://www.tildefriends.net/) +- register and login +- [optional] use the `ssb` app to create yourself an SSB identity + +## Development Process + +1. hit the `edit` link from any app or new app URL +2. make sure the path in the text box is under your username: `/~username/app/` +3. write server-side code in `app.js` +4. click the `save` button or press the save hotkey (Alt+S or _[browser-specific modifiers]_+S) +5. see the app reload on the right side + +## Output + +- **`app.setDocument(html)`** - send HTML to the browser +- **`print(...)`** - send values to the browser's developer console + +## Persistence + +- **`app.localStorageGet(key)`** -> **`value`** +- **`app.localStorageSet(key, value)`** +- **`database()`**, **`shared_database(key)`**, **`my_shared_database(package, key)`** + - **`db.get(key)`** -> **`value`** + - **`db.set(key, value)`** + - **`db.exchange(key, expected, value)`** -> **`exchanged`** + - **`db.remove(key)`** + - **`db.getAll()`** -> **`[key1, ...]`** + - **`db.getLike(pattern)`** -> **`{key1: value1, ...}`** + +## SSB + +- **`ssb.createIdentity()`** -> **`id`** +- **`ssb.getIdentities()`** -> **`[id1, ...]`** +- **`ssb.appendMessageWithIdentity(id, content)`** -> **`message_id`** +- **`ssb.blobStore(blob)`** -> **`blob_id`** +- **`ssb.blobGet(id)`** -> **`blob`** +- **`ssb.sqlAsync(query, args, row_callback)`** + +## TF-RPC + +Stock helper code for calling functions across the web server and browser boundary. + +- on the server: `import * as tfrpc from '/tfrpc.js';` +- in the browser: `import * as tfrpc from '/static/tfrpc.js';` +- either direction: + - register a function: `tfrpc.register(function my_function() {});` + - call a remote function: `let promise = tfrpc.rpc.my_function();` + +## Share + +- give out web links: [https://www.tildefriends.net/~cory/screwble/](https://www.tildefriends.net/~cory/screwble/) +- use the `Attach App` button when composing a post in [the SSB app](https://www.tildefriends.net/~core/ssb/) + +## More Docs + +- [api reference](https://www.tildefriends.net/~cory/api/) +- [source code](https://dev.tildefriends.net/cory/tildefriends/releases) diff --git a/docs/guide.md b/docs/guide.md index f4aaa57c..eb296dd3 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,209 +1,166 @@ -# Philosophy +# Tilde Friends Developer's Guide -Tilde Friends is a platform for making, running, and sharing web applications. +A Tilde Friends application starts with code that runs on a Tilde Friends server, possibly far away from where you wrote it, in a little JavaScript environment, in its own restricted process, with the only access to the outside world being the ability to send messages to the server. This document gives some recipes showing how that can be used to build a functional user-facing application in light of the unique constraints present. -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. +## Example 1: Hello, world! -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. +Of course we must start with a classic. -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. +### app.js -# Architecture +``` +app.setDocument('

Hello, world!

'); +``` -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. +### Output -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. +### Explanation -## Communication +At a glance, this might seem mundane, but for it to work: -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. +- the server starts a real process for your app and loads your code into it +- your code runs +- `app.setDocument()` sends a message back to the server +- the server interprets the message and redirects it to the browser +- `core/client.js` in the browser receives the message and puts your HTML into an iframe +- your HTML is presented by the browser in an iframe sandbox -There are several distinct classes of APIs. +But you don't have to think about all that. Call a function, and you see the result. -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. +## Example 2: Hit Counter - // Displays some text to the server's console. - print("Hello, world!"); +Let's take advantage of code running on the server and create a little hit counter using a key value store shared between all visitors. -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. +### app.js - // 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; }}); +``` +async function main() { + let db = await shared_database('visitors'); + let count = parseInt((await db.get('visitors')) ?? '0') + 1; + await db.set('visitors', count.toString()); + await app.setDocument(` +

Welcome, visitor #${count}!

+ `); +} - // Receive the above message and call the function. - core.register("onMessage", function(sender, message) { - message.add(3, 4).then(x => terminal.print(x.toString())); - }); +main(); +``` -Finally, there is a core web interface that runs on the client's browser that -extends access to a running Tilde Friends script. +### Output - // Displays a message in the client's browser. - terminal.print("Hello, world!"); + -## API Documentation +### Explanation -The Tilde Friends API is very much evolving. +Just as pure browser apps have access to `localStorage`, Tilde Friends apps have access to key-value storage on the server. -All currently registered methods can be explored in the -[documentation](https://www.tildefriends.net/~cory/documentation) app. +The interface is a bit clunky and will likely change someday, but this example gets a database object, from which you can get and set string values by key. There are various on `shared_database` that let you store data that is private to the user or shared by different criteria. -All browser-facing methods are implemented in [client.js](core/client.js). -Most process-related methods are implemented in [core.js](core/core.js). +Also, even though any browser-side code is sandboxed, it is allowed to access browser local storage by going through Tilde Friends API, because sometimes that is useful. -Higher-level behaviors are often implemented within library-style apps -themselves and are beyond the scope of this document. +## Example 3: Files -### Terminal +Suppose you don't want to create your entire app in a single server-side file as we've done with the previous examples. There are some tools to allow you to begin to organize. -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. +### app.js -#### terminal.print(arguments...) +``` +async function main() { + let html = utf8Decode(await getFile('index.html')); + app.setDocument(html); +} -Print to the terminal. Arguments and lists are recursively expanded. Numerous -special values are supported as implemented in client.cs. +main(); +``` - // Create a link. - terminal.print({href: "http://www.tildefriends.net/", value: "Tilde Friends!"}); +### index.html - // Create an iframe. - terminal.print({iframe: "<b>Hello, world!</b>", width: 640, height: 480}); +``` + + + + + +

File Test

+ + +``` - // Use style. - terminal.print({style: "color: #f00", value: "Hello, world!"}); +### script.js - // Create a link that when clicked will act as if the user typed a command. - terminal.print({command: "exit", value: "Get out of here."}); +``` +window.addEventListener('load', function() { + document.body.appendChild(document.createTextNode('Hello, world'); +}); +``` -#### terminal.clear() +### Output -Clears the terminal output. + -#### terminal.readLine() +### Explanation -Read a line of input from the user. +On the server, `utf8Decode(await getFile(fileName))` lets you load a file from your app. In the browser, your app files are made available by HTTP, so you can `` and such to access them. -#### terminal.setEcho(echo) +## Example 4: Remote Procedure Call -Controls whether the terminal will automatically echo user input. Defaults to true. +While making calls between the client and the server, it is possible to pass functions across that boundary. `tfrpc.js` is a tiny script which builds on that feature to try to hide some of the complexities. -#### terminal.setPrompt(prompt) +### app.js -Sets the terminal prompt. The default is ">". +``` +import * as tf from '/tfrpc.js'; -#### terminal.setTitle(title) +function sum() { + let s = 0 + for (let x of arguments) { + s += x; + } + return s; +} +tf.register(sum); -Sets the browser window/tab title. +async function main() { + app.setDocument(utf8Decode(await getFile('index.html'))); +} +main(); +``` -#### terminal.split(terminalList) +### index.html -Reconfigures the terminal layout, potentially into multiple split panes. +``` + + +

Calculating...

+ + + +``` - 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}, - ], - }, - ]); +### script.js -#### terminal.select(name) +``` +import * as tf from '/static/tfrpc.js'; -Directs subsequent output to the named terminal. +window.addEventListener('load', async function() { + document.getElementById('result').innerText = await tf.rpc.sum(1, 2, 3); +}); +``` -#### terminal.postMessageToIframe(iframeName, message) +### Output -Sends a message to the iframe that was created with the given name, using the -browser's window.postMessage. + -### Database +### Explanation -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. +Here the browser makes an asynchronous call to the server to do some basic math and update its DOM with the result. -#### database.get(key) +With your favorite Vue/Lit/React/... library on the client-side and your favorite Tilde Friends API calls registered with tfrpc, it becomes pretty easy to start extracting interesting information from, say, SQL queries over Secure Scuttlebutt data, and generating complicated, dynamic user interface. These are the building blocks I used to make the current Tilde Friends SSB client interface. -Retrieve the database value associated with the given key. +## Conclusion -#### database.set(key, value) +Tilde Friends is currently a pile of all the parts that I thought I needed to build interesting web applications, tied together by code that tries to walk the fine line between being secure enough to let us safely run code on the same device and being usable enough that you can open a tab in your browser and start building just by typing code. -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. +I don't claim it thoroughly accomplishes either yet, but I believe it is at a stage where it is showing how promising this approach can be, and I am excited for you to take it for a spin and share. diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 00000000..5d74f80b --- /dev/null +++ b/docs/vision.md @@ -0,0 +1,64 @@ +# Tilde Friends Vision + +Tilde Friends is a tool for making and sharing. + +It is both a peer-to-peer social network client, participating in Secure +Scuttlebutt, and an environment for creating and running web applications. + +## Why + +This is a thing that I wanted to exist and wanted to work on. No other reason. +There is not a business model. I believe it is interesting and unique. + +## Goals + +1. Make it **easy and fun** to run all sorts of web applications. + +2. Provide **security** that is easy to understand and protects your data. + +3. Make **creating and sharing** web applications accessible to anyone with a + browser. + +## Ways to Use Tilde Friends + +1. **Social Network User**: This is a social network first. You are just here, + because your friends are. Or you like how we limit your message length or + short videos or whatever the trend is. If you are ambitious, you click links + and see interactive experiences (apps) that you wouldn't see elsewhere. + +2. **Web Visitor**: You get links from a friend to meeting invites, polls, games, + lists, wiki pages, ..., and you interact with them as though they were + cloud-hosted by a megacorporation. They just work, and you don't think twice. + +3. **Group leader**: You host or use a small public instance, installing apps for + a group of friends to use as web visitors. + +4. **Developer**: You like to write code and make or improve apps for fun or to + solve problems. When you encounter a Tilde Friends app on a strange server, + you know you can trivially modify it or download it to your own instance. + +## Future Goals / Endgame + +1. Mobile apps. This can run on your old phone. Maybe you won't be hosting + the web interface publicly, but you can sync, install and edit apps, and + otherwise get the full experience from a tiny touch screen. + +2. The universal application runtime. The web browser is the universal + platform, but even for the simplest application that you might want to host + for your friends, cloud hosting, containers, and complicated dependencies might + all enter the mix. Tilde Friends, though it is yet another thing to host, + includes everything you need out of the box to run a vast variety of interesting + apps. + + Tilde Friends will be built out, gradually providing safe access to host + resources and client resources the same way web browsers extended access to + resources like GPU, persistent storage, cameras, ... over the years. + + Not much effort has been put forward yet to having a robust, long-lasting API, + but since the client side longevity is already handled by web browsers, it + seems possible that the server-side API can be managed in a similar way. + +3. An awesome development environment. Right now it runs JavaScript from the + first embeddable text editor I could poorly configure enough to edit code, + but it could incorporate a debugger, source control integration a la ssb-git, + merge tools, and transpiling from all sorts of different languages.