docs: Add the Tilde Friends gitea wiki as a git submodule to replace the docs directory. Maybe I will succeed at doing something with it if it is more web-facing.
Some checks failed
Build Tilde Friends / Build-All (push) Has been cancelled
Some checks failed
Build Tilde Friends / Build-All (push) Has been cancelled
This commit is contained in:
parent
0da6abeb98
commit
2e95d6ea63
3
.gitmodules
vendored
3
.gitmodules
vendored
@ -26,3 +26,6 @@
|
||||
[submodule "deps/c-ares"]
|
||||
path = deps/c-ares
|
||||
url = https://github.com/c-ares/c-ares.git
|
||||
[submodule "docs"]
|
||||
path = docs
|
||||
url = https://dev.tildefriends.net/cory/tildefriends.wiki.git
|
||||
|
||||
1
docs
Submodule
1
docs
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 47f91bd302b68079840b6fef42add771fc3e019a
|
||||
@ -1,63 +0,0 @@
|
||||
# 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)
|
||||
166
docs/guide.md
166
docs/guide.md
@ -1,166 +0,0 @@
|
||||
# Tilde Friends Developer's Guide
|
||||
|
||||
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.
|
||||
|
||||
## Example 1: Hello, world!
|
||||
|
||||
Of course we must start with a classic.
|
||||
|
||||
### app.js
|
||||
|
||||
```
|
||||
app.setDocument('<h1 style="color: #fff">Hello, world!</h1>');
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
<iframe srcdoc="<h1 style="color: #fff">Hello, world!</h1>"></iframe>
|
||||
|
||||
### Explanation
|
||||
|
||||
At a glance, this might seem mundane, but for it to work:
|
||||
|
||||
- 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
|
||||
|
||||
But you don't have to think about all that. Call a function, and you see the result.
|
||||
|
||||
## Example 2: Hit Counter
|
||||
|
||||
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.
|
||||
|
||||
### app.js
|
||||
|
||||
```
|
||||
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(`
|
||||
<h1 style="color: #fff">Welcome, visitor #${count}!</h1>
|
||||
`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
<iframe srcdoc="<h1 style="color: #fff">Welcome, visitor #1!</h1>"></iframe>
|
||||
|
||||
### Explanation
|
||||
|
||||
Just as pure browser apps have access to `localStorage`, Tilde Friends apps have access to key-value storage on the server.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Example 3: Files
|
||||
|
||||
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.
|
||||
|
||||
### app.js
|
||||
|
||||
```
|
||||
async function main() {
|
||||
let html = utf8Decode(await getFile('index.html'));
|
||||
app.setDocument(html);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
### index.html
|
||||
|
||||
```
|
||||
<html>
|
||||
<head>
|
||||
<script type="module" src="script.js"></script>
|
||||
</head>
|
||||
<body style="color: #fff">
|
||||
<h1>File Test</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### script.js
|
||||
|
||||
```
|
||||
window.addEventListener('load', function() {
|
||||
document.body.appendChild(document.createTextNode('Hello, world');
|
||||
});
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
<iframe srcdoc="<body style="color: #fff"><h1>File Test</h1>Hello, world!</body>"></iframe>
|
||||
|
||||
### Explanation
|
||||
|
||||
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 `<script src="my_script.js"></script>` and such to access them.
|
||||
|
||||
## Example 4: Remote Procedure Call
|
||||
|
||||
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.
|
||||
|
||||
### app.js
|
||||
|
||||
```
|
||||
import * as tf from '/tfrpc.js';
|
||||
|
||||
function sum() {
|
||||
let s = 0
|
||||
for (let x of arguments) {
|
||||
s += x;
|
||||
}
|
||||
return s;
|
||||
}
|
||||
tf.register(sum);
|
||||
|
||||
async function main() {
|
||||
app.setDocument(utf8Decode(await getFile('index.html')));
|
||||
}
|
||||
main();
|
||||
```
|
||||
|
||||
### index.html
|
||||
|
||||
```
|
||||
<html>
|
||||
<body>
|
||||
<h1 id='result'>Calculating...</h1>
|
||||
</body>
|
||||
<script type="module" src="script.js"></script>
|
||||
</html>
|
||||
```
|
||||
|
||||
### script.js
|
||||
|
||||
```
|
||||
import * as tf from '/static/tfrpc.js';
|
||||
|
||||
window.addEventListener('load', async function() {
|
||||
document.getElementById('result').innerText = await tf.rpc.sum(1, 2, 3);
|
||||
});
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
<iframe srcdoc="<body style="color: #fff"><h1>6</h1></body>"></iframe>
|
||||
|
||||
### Explanation
|
||||
|
||||
Here the browser makes an asynchronous call to the server to do some basic math and update its DOM with the result.
|
||||
|
||||
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.
|
||||
|
||||
## Conclusion
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
@ -1,19 +0,0 @@
|
||||
# Release Checklist
|
||||
|
||||
- make sure ci is passing
|
||||
- run the tests
|
||||
- format + prettier
|
||||
- update metadata/en-US/changelogs
|
||||
- git tag
|
||||
- push
|
||||
- make dist
|
||||
- make a release on gitea
|
||||
- upload the artifacts
|
||||
- nix
|
||||
- comment out the hash in default.nix
|
||||
- update the version
|
||||
- run `nix-build`
|
||||
- update the hash
|
||||
- bump the versions in GNUmakefile for the next release
|
||||
- make
|
||||
- commit
|
||||
@ -1,64 +0,0 @@
|
||||
# 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.
|
||||
Loading…
Reference in New Issue
Block a user