tildefriends/apps/cory/docs/structure.md

Tilde Friends Structure

Back to 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/ and an SSB server.

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.