nandi/frq · README.md

nandi/frqpublic⑂ Fork 0

⑂ 1d062fd7d8aaa93a4b016aef0c0327ee18ca14b5

README.md · 129 lines · 5.7 KBmarkdown    Blame HistoryRaw
A freeq client in jolt, as glimmer components on Vidya   1
3A **[freeq](https://github.com/codegod100/freeq)** client written in
4**[jolt](https://github.com/jolt-lang/jolt)**, as
5[glimmer](https://github.com/jolt-lang/glimmer) components painted by
6**[Vidya](https://tangled.org/nandi.uk/vidya)**/egui.
8It is a proof of concept port of [sleek](../sleek), which is the same client in
9Rust against egui directly. The screens are sleek's — connect, chats, chat,
10discover, settings, under a tab bar — but each is hiccup over glimmer's widget
11tags rather than immediate-mode drawing code, and state lives in ratoms instead
12of an `AppState` struct.
Sign in with Bluesky OAuth, through freeq's broker   15src/frq/atproto.jolt handle → DID → PDS → session, and the SASL payloads
16src/frq/oauth.jolt   the broker flow: login URL, loopback capture, /session
Remember an OAuth sign-in across restarts   17src/frq/store.jolt   the saved sign-in, mode 600 in the config directory
Show the pictures people paste   18src/frq/media.jolt   image links: spot them, fetch them once, cache on disk
Sign in with a Bluesky identity   19src/frq/irc.jolt     IRC over TLS or TCP: parser, reader thread, SASL, PRIVMSG
A freeq client in jolt, as glimmer components on Vidya   20src/frq/state.jolt   the ratoms every screen reads, and `apply-msg!`
21src/frq/app.jolt     the screens
Stop mistaking a quiet connection for a closed one   24
26`FRQ_TRACE=1` prints every IRC line sent and received to stderr, which on
27Android is logcat.
A freeq client in jolt, as glimmer components on Vidya   29
31`libvidya` from Vidya's Rust/egui backend, then the app:
38`just run` is `jolt -M:frq` with `LD_LIBRARY_PATH` pointed at the built
39library. It connects to `irc.freeq.at:6697` over TLS and joins `#test`. Untick
40TLS on the connect screen (or point it at `127.0.0.1`) for a local server's
41plain listener:
44cargo run --release --bin freeq-server        # in the freeq checkout
Sign in with a Bluesky identity   47## Signing in
Sign in with Bluesky OAuth, through freeq's broker   49Three modes on the connect screen.
Sign in with a Bluesky identity   50
Sign in with Bluesky OAuth, through freeq's broker   51**Bluesky** (OAuth, the default way in) follows sleek's flow: frq binds a
52loopback port, puts it in `return_to`, and opens
53`auth.freeq.at/auth/login?handle=…`. The broker runs the OAuth dance with the
54PDS and redirects back to that port with the handoff in the URL *fragment*, so
55it never reaches a server as a query string. The page frq serves there has one
56job: POST the fragment back to itself. What comes back is a single-use SASL
57`web-token` and a durable `broker_token`; later connections mint a fresh token
58from the durable one at `/session` and skip the browser.
Sign in with a Bluesky identity   59
Remember an OAuth sign-in across restarts   60The durable token is saved to `$XDG_CONFIG_HOME/frq/session.edn` (mode 600) so
Connect on launch when an account is remembered   61a restart resumes without one, along with the handle and nick it belongs to —
62and it connects on its own at launch when one is there.
Remember an OAuth sign-in across restarts   63The web-token beside it is single-use and deliberately not saved. A token the
64broker no longer honours is dropped — from disk and memory — and the browser
65flow runs once more, rather than failing the same way on every Connect.
Sign in with Bluesky OAuth, through freeq's broker   67**App password** signs in without a browser, straight to the user's own PDS:
68`resolveHandle` → DID → PDS from the DID document → `createSession`. The
69password goes to that PDS and nowhere else, is never written to disk, and is
70dropped once the session exists.
Sign in with a Bluesky identity   71
Sign in with Bluesky OAuth, through freeq's broker   72Either way freeq sees only a token. The SASL mechanism is
73`ATPROTO-CHALLENGE` in both cases — `method: "web-token"`, which the server
74resolves through its own token store, or `method: "pds-session"` with the
75server's nonce echoed back so the token cannot be replayed elsewhere.
77A refused sign-in is reported and the connection carries on as a guest.
Sign in with a Bluesky identity   78
A freeq client in jolt, as glimmer components on Vidya   79
81An APK with two shared libraries and no Java: `libvidya.so` (vidya's Rust/egui
82C ABI, which owns the event loop as the NativeActivity's own library) and
83`libjoltapp.so` (frq compiled to a Chez boot image). Both native halves come
84from the vidya checkout; only the boot image is frq's.
87./android/build-apk.sh run      # build, install, launch on a connected device
88./android/build-apk.sh log      # logcat, filtered
91Needs what vidya's Android build needs — SDK, NDK r29, and a cross-built Chez
92in `~/.cache/vidya-chez-android`.
94TLS does not work there: jolt reaches OpenSSL through the dynamic loader, and
95Android has no public `libssl` to load. The connect screen falls back to the
96plain `:6667` listener on its own, which is why the plain transport is the raw
97`socket`/`connect`/`send`/`recv` calls rather than jolt's `java.net.Socket`
98surface — that surface does not work on Android either, while the syscalls do.
100## What the PoC covers
102* TLS (`:6697`, via jolt.mvn-http's OpenSSL bindings) or plain TCP (`:6667`)
103* Guest connect (`NICK`/`USER`), `001` welcome, `PING`/`PONG` keepalive
104* Auto-joins `#test` on `irc.freeq.at`
105* Join channels, channel buffers with unread counts, send and receive `PRIVMSG`
Ask for the backlog freeq restores channels without   106* Backlog on join, and `CHATHISTORY` for the channels freeq restores instead
Show the pictures people paste   107* Inline previews for PNG links, fetched once and cached under
Click a picture to see it full size   108  `$XDG_CACHE_HOME/frq/media`; click one to see it full size
A freeq client in jolt, as glimmer components on Vidya   109* Join/part notices, DMs bucketed under the sender's nick
110* Discover list, search over buffers, disconnect
Remember which rooms this client has been in   111* The rooms you have opened, remembered across runs and listed in the order
112  you last used them (`$XDG_CONFIG_HOME/frq/channels.edn`)
Order the chat list by what you were last in   113* Conversations listed most recently opened first
A freeq client in jolt, as glimmer components on Vidya   114
115
117* **TLS and plain TCP only** — no WebSocket, no iroh. On Android, plain only.
Sign in with Bluesky OAuth, through freeq's broker   118* **No `did:key` signing, no credential gates, no E2EE.** Sign-in of either
119  kind needs TLS, so it is desktop-only — the Android build connects as a
120
Remember an OAuth sign-in across restarts   121* **Only the broker token is persisted**, and only for OAuth. An app-password
122  sign-in is not remembered.
Show the pictures people paste   123* **Previews are PNG only** — the tree backend's decoder reads no other
124  format, and a fetch needs TLS, so the phone shows links. The link is left in
125  place either way.
126* **Nothing evicts the media cache.**
A freeq client in jolt, as glimmer components on Vidya   127* **No scrollback trimming, avatars, reactions, threads, or calls.**
Stop mistaking a quiet connection for a closed one   128* A sent line waits up to 200ms for the reader thread to flush it.
A freeq client in jolt, as glimmer components on Vidya   129* Message lists are keyed vboxes; glimmer-vidya has no `:listbox` yet.

A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	1	# frq
	2
	3	A [freeq](https://github.com/codegod100/freeq) client written in
	4	[jolt](https://github.com/jolt-lang/jolt), as
	5	[glimmer](https://github.com/jolt-lang/glimmer) components painted by
	6	[Vidya](https://tangled.org/nandi.uk/vidya)/egui.
	7
	8	It is a proof of concept port of [sleek](../sleek), which is the same client in
	9	Rust against egui directly. The screens are sleek's — connect, chats, chat,
	10	discover, settings, under a tab bar — but each is hiccup over glimmer's widget
	11	tags rather than immediate-mode drawing code, and state lives in ratoms instead
	12	of an `AppState` struct.
	13
	14	```
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	15	src/frq/atproto.jolt handle → DID → PDS → session, and the SASL payloads
	16	src/frq/oauth.jolt the broker flow: login URL, loopback capture, /session
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	17	src/frq/store.jolt the saved sign-in, mode 600 in the config directory
Show the pictures people paste 56cdac3 nandi 19d ago	18	src/frq/media.jolt image links: spot them, fetch them once, cache on disk
Sign in with a Bluesky identity 5192124 nandi 20d ago	19	src/frq/irc.jolt IRC over TLS or TCP: parser, reader thread, SASL, PRIVMSG
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	20	src/frq/state.jolt the ratoms every screen reads, and `apply-msg!`
	21	src/frq/app.jolt the screens
	22	```
	23
Stop mistaking a quiet connection for a closed one a225fb1 nandi 19d ago	24	## Tracing
	25
	26	`FRQ_TRACE=1` prints every IRC line sent and received to stderr, which on
	27	Android is logcat.
	28
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	29	## Running
	30
	31	`libvidya` from Vidya's Rust/egui backend, then the app:
	32
	33	```bash
	34	just lib
	35	just run
	36	```
	37
	38	`just run` is `jolt -M:frq` with `LD_LIBRARY_PATH` pointed at the built
	39	library. It connects to `irc.freeq.at:6697` over TLS and joins `#test`. Untick
	40	TLS on the connect screen (or point it at `127.0.0.1`) for a local server's
	41	plain listener:
	42
	43	```bash
	44	cargo run --release --bin freeq-server # in the freeq checkout
	45	```
	46
Sign in with a Bluesky identity 5192124 nandi 20d ago	47	## Signing in
Sign in with a Bluesky identity 5192124 nandi 20d ago	48
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	49	Three modes on the connect screen.
Sign in with a Bluesky identity 5192124 nandi 20d ago	50
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	51	Bluesky (OAuth, the default way in) follows sleek's flow: frq binds a
	52	loopback port, puts it in `return_to`, and opens
	53	`auth.freeq.at/auth/login?handle=…`. The broker runs the OAuth dance with the
	54	PDS and redirects back to that port with the handoff in the URL fragment, so
	55	it never reaches a server as a query string. The page frq serves there has one
	56	job: POST the fragment back to itself. What comes back is a single-use SASL
	57	`web-token` and a durable `broker_token`; later connections mint a fresh token
	58	from the durable one at `/session` and skip the browser.
Sign in with a Bluesky identity 5192124 nandi 20d ago	59
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	60	The durable token is saved to `$XDG_CONFIG_HOME/frq/session.edn` (mode 600) so
Connect on launch when an account is remembered 9237cf4 nandi 19d ago	61	a restart resumes without one, along with the handle and nick it belongs to —
	62	and it connects on its own at launch when one is there.
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	63	The web-token beside it is single-use and deliberately not saved. A token the
	64	broker no longer honours is dropped — from disk and memory — and the browser
	65	flow runs once more, rather than failing the same way on every Connect.
	66
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	67	App password signs in without a browser, straight to the user's own PDS:
	68	`resolveHandle` → DID → PDS from the DID document → `createSession`. The
	69	password goes to that PDS and nowhere else, is never written to disk, and is
	70	dropped once the session exists.
Sign in with a Bluesky identity 5192124 nandi 20d ago	71
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	72	Either way freeq sees only a token. The SASL mechanism is
	73	`ATPROTO-CHALLENGE` in both cases — `method: "web-token"`, which the server
	74	resolves through its own token store, or `method: "pds-session"` with the
	75	server's nonce echoed back so the token cannot be replayed elsewhere.
	76
	77	A refused sign-in is reported and the connection carries on as a guest.
Sign in with a Bluesky identity 5192124 nandi 20d ago	78
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	79	## Android
	80
	81	An APK with two shared libraries and no Java: `libvidya.so` (vidya's Rust/egui
	82	C ABI, which owns the event loop as the NativeActivity's own library) and
	83	`libjoltapp.so` (frq compiled to a Chez boot image). Both native halves come
	84	from the vidya checkout; only the boot image is frq's.
	85
	86	```bash
	87	./android/build-apk.sh run # build, install, launch on a connected device
	88	./android/build-apk.sh log # logcat, filtered
	89	```
	90
	91	Needs what vidya's Android build needs — SDK, NDK r29, and a cross-built Chez
	92	in `~/.cache/vidya-chez-android`.
	93
	94	TLS does not work there: jolt reaches OpenSSL through the dynamic loader, and
	95	Android has no public `libssl` to load. The connect screen falls back to the
	96	plain `:6667` listener on its own, which is why the plain transport is the raw
	97	`socket`/`connect`/`send`/`recv` calls rather than jolt's `java.net.Socket`
	98	surface — that surface does not work on Android either, while the syscalls do.
	99
	100	## What the PoC covers
	101
	102	* TLS (`:6697`, via jolt.mvn-http's OpenSSL bindings) or plain TCP (`:6667`)
	103	* Guest connect (`NICK`/`USER`), `001` welcome, `PING`/`PONG` keepalive
	104	* Auto-joins `#test` on `irc.freeq.at`
	105	* Join channels, channel buffers with unread counts, send and receive `PRIVMSG`
Ask for the backlog freeq restores channels without 94e59a2 nandi 19d ago	106	* Backlog on join, and `CHATHISTORY` for the channels freeq restores instead
Show the pictures people paste 56cdac3 nandi 19d ago	107	* Inline previews for PNG links, fetched once and cached under
Click a picture to see it full size 563ada3 nandi 19d ago	108	`$XDG_CACHE_HOME/frq/media`; click one to see it full size
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	109	* Join/part notices, DMs bucketed under the sender's nick
	110	* Discover list, search over buffers, disconnect
Remember which rooms this client has been in 1d062fd nandi 19d ago	111	* The rooms you have opened, remembered across runs and listed in the order
	112	you last used them (`$XDG_CONFIG_HOME/frq/channels.edn`)
Order the chat list by what you were last in 75e557e nandi 19d ago	113	* Conversations listed most recently opened first
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	114
	115	## Limits
	116
	117	* TLS and plain TCP only — no WebSocket, no iroh. On Android, plain only.
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	118	* No `did:key` signing, no credential gates, no E2EE. Sign-in of either
	119	kind needs TLS, so it is desktop-only — the Android build connects as a
	120	guest.
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	121	* Only the broker token is persisted, and only for OAuth. An app-password
	122	sign-in is not remembered.
Show the pictures people paste 56cdac3 nandi 19d ago	123	* Previews are PNG only — the tree backend's decoder reads no other
	124	format, and a fetch needs TLS, so the phone shows links. The link is left in
	125	place either way.
	126	* Nothing evicts the media cache.
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	127	* No scrollback trimming, avatars, reactions, threads, or calls.
Stop mistaking a quiet connection for a closed one a225fb1 nandi 19d ago	128	* A sent line waits up to 200ms for the reader thread to flush it.
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	129	* Message lists are keyed vboxes; glimmer-vidya has no `:listbox` yet.