tildefriends/apps/cory/docs/structure.md

65 lines
2.9 KiB
Markdown

# Tilde Friends Structure
[Back to index](#index)
Tilde Friends is a mostly-self-contained executable written in C.
In combines the following key components:
- A Secure Scuttlebutt (SSB) client/server. This talks with other SSB
instances, storing messages and blobs for anyone visible to local
users as they are encountered and sharing anything published locally
as appropriate.
- An sqlite database. This is where the SSB instance stores its data.
The general schema involves a `messages` table, storing mostly JSON,
a `blobs` table storing arbitrary blob data, and a `properties` table,
storing arbitrary state gleaned from `messages` and `blobs`, generally
updated on demand and incrementally.
- A QuickJS runtime. The core process runs stock scripts and has access
and permission to use all resources. All other processes, which
includes everything which runs untrusted code created by Tilde Friends
users, are strictly sandboxed in ways similar to how web browsers run
untrusted code. All attempts to access potentially sensitive resources
are mediated through the core process.
When run with no arguments, it starts a web server on
[http://localhost:12345/](http://localhost:12345/) and an SSB node.
## Web Interface
The Tilde Friends web server provides access to Tilde Friends applications,
which are arbitrary user-defined web applications.
At the top left, in addition to some basic navigation links, is an `edit`
link. Anyone can view, modify, and run in-place the code to any Tilde
Friends application by using the in-browser editor.
At the top right, one can `login` (to save work in their own space)
or `logout` (proceeding as a guest).
The rest of the page is an iframe belonging to the application.
## Special Paths
- `/~user/app/` - Tilde Friends application paths take the form `/~user/app/`, where `user`
is a username of a Tilde Friends account, and `app` is an arbitrary name
of an application saved by the given user.
- `/~user/app/file` - A raw file in an app.
- `/&blobid.ed25519` - A raw blob. Content-Type is inferred for at least
a few common image types.
## Communication Channels
Web Browser <-> Core <-> Sandbox
Visiting an application path delivers stock HTML and JavaScript which
establishes a WebSocket connection back to the server.
At this point, a new sandbox process is started in Tilde Friends, much
as a new sandboxed process might be started for a new tab in a web
browser. This process has a custom RPC connection to the core process
which holds the WebSocket connection to the browser.
The custom RPC communication between the sandbox process and the core
process facilitates passing and calling functions remotely. Calling a
function in another process returns a `Promise`.
An application will typically call `app.setDocument()` at startup to
populate the app's iframe in the web browser with its own client web
application resources.