nandi/frq · README.md

nandi/frqpublic⑂ Fork 0

⑂ 563ada3ba5f0066b95bc39e9a63095a09c5f05da

README.md · 126 lines · 5.5 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
61a restart resumes without one, along with the handle and nick it belongs to.
62The web-token beside it is single-use and deliberately not saved. A token the
63broker no longer honours is dropped — from disk and memory — and the browser
64flow runs once more, rather than failing the same way on every Connect.
Sign in with Bluesky OAuth, through freeq's broker   66**App password** signs in without a browser, straight to the user's own PDS:
67`resolveHandle` → DID → PDS from the DID document → `createSession`. The
68password goes to that PDS and nowhere else, is never written to disk, and is
69dropped once the session exists.
Sign in with a Bluesky identity   70
Sign in with Bluesky OAuth, through freeq's broker   71Either way freeq sees only a token. The SASL mechanism is
72`ATPROTO-CHALLENGE` in both cases — `method: "web-token"`, which the server
73resolves through its own token store, or `method: "pds-session"` with the
74server's nonce echoed back so the token cannot be replayed elsewhere.
76A refused sign-in is reported and the connection carries on as a guest.
Sign in with a Bluesky identity   77
A freeq client in jolt, as glimmer components on Vidya   78
80An APK with two shared libraries and no Java: `libvidya.so` (vidya's Rust/egui
81C ABI, which owns the event loop as the NativeActivity's own library) and
82`libjoltapp.so` (frq compiled to a Chez boot image). Both native halves come
83from the vidya checkout; only the boot image is frq's.
86./android/build-apk.sh run      # build, install, launch on a connected device
87./android/build-apk.sh log      # logcat, filtered
90Needs what vidya's Android build needs — SDK, NDK r29, and a cross-built Chez
91in `~/.cache/vidya-chez-android`.
93TLS does not work there: jolt reaches OpenSSL through the dynamic loader, and
94Android has no public `libssl` to load. The connect screen falls back to the
95plain `:6667` listener on its own, which is why the plain transport is the raw
96`socket`/`connect`/`send`/`recv` calls rather than jolt's `java.net.Socket`
97surface — that surface does not work on Android either, while the syscalls do.
99## What the PoC covers
101* TLS (`:6697`, via jolt.mvn-http's OpenSSL bindings) or plain TCP (`:6667`)
102* Guest connect (`NICK`/`USER`), `001` welcome, `PING`/`PONG` keepalive
103* Auto-joins `#test` on `irc.freeq.at`
104* Join channels, channel buffers with unread counts, send and receive `PRIVMSG`
Ask for the backlog freeq restores channels without   105* Backlog on join, and `CHATHISTORY` for the channels freeq restores instead
Show the pictures people paste   106* Inline previews for PNG links, fetched once and cached under
Click a picture to see it full size   107  `$XDG_CACHE_HOME/frq/media`; click one to see it full size
A freeq client in jolt, as glimmer components on Vidya   108* Join/part notices, DMs bucketed under the sender's nick
109* Discover list, search over buffers, disconnect
Order the chat list by what you were last in   110* Conversations listed most recently opened first
A freeq client in jolt, as glimmer components on Vidya   111
112
114* **TLS and plain TCP only** — no WebSocket, no iroh. On Android, plain only.
Sign in with Bluesky OAuth, through freeq's broker   115* **No `did:key` signing, no credential gates, no E2EE.** Sign-in of either
116  kind needs TLS, so it is desktop-only — the Android build connects as a
117
Remember an OAuth sign-in across restarts   118* **Only the broker token is persisted**, and only for OAuth. An app-password
119  sign-in is not remembered.
Show the pictures people paste   120* **Previews are PNG only** — the tree backend's decoder reads no other
121  format, and a fetch needs TLS, so the phone shows links. The link is left in
122  place either way.
123* **Nothing evicts the media cache.**
A freeq client in jolt, as glimmer components on Vidya   124* **No scrollback trimming, avatars, reactions, threads, or calls.**
Stop mistaking a quiet connection for a closed one   125* A sent line waits up to 200ms for the reader thread to flush it.
A freeq client in jolt, as glimmer components on Vidya   126* 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 20d 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 20d 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
	61	a restart resumes without one, along with the handle and nick it belongs to.
	62	The web-token beside it is single-use and deliberately not saved. A token the
	63	broker no longer honours is dropped — from disk and memory — and the browser
	64	flow runs once more, rather than failing the same way on every Connect.
	65
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	66	App password signs in without a browser, straight to the user's own PDS:
	67	`resolveHandle` → DID → PDS from the DID document → `createSession`. The
	68	password goes to that PDS and nowhere else, is never written to disk, and is
	69	dropped once the session exists.
Sign in with a Bluesky identity 5192124 nandi 20d ago	70
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	71	Either way freeq sees only a token. The SASL mechanism is
	72	`ATPROTO-CHALLENGE` in both cases — `method: "web-token"`, which the server
	73	resolves through its own token store, or `method: "pds-session"` with the
	74	server's nonce echoed back so the token cannot be replayed elsewhere.
	75
	76	A refused sign-in is reported and the connection carries on as a guest.
Sign in with a Bluesky identity 5192124 nandi 20d ago	77
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	78	## Android
	79
	80	An APK with two shared libraries and no Java: `libvidya.so` (vidya's Rust/egui
	81	C ABI, which owns the event loop as the NativeActivity's own library) and
	82	`libjoltapp.so` (frq compiled to a Chez boot image). Both native halves come
	83	from the vidya checkout; only the boot image is frq's.
	84
	85	```bash
	86	./android/build-apk.sh run # build, install, launch on a connected device
	87	./android/build-apk.sh log # logcat, filtered
	88	```
	89
	90	Needs what vidya's Android build needs — SDK, NDK r29, and a cross-built Chez
	91	in `~/.cache/vidya-chez-android`.
	92
	93	TLS does not work there: jolt reaches OpenSSL through the dynamic loader, and
	94	Android has no public `libssl` to load. The connect screen falls back to the
	95	plain `:6667` listener on its own, which is why the plain transport is the raw
	96	`socket`/`connect`/`send`/`recv` calls rather than jolt's `java.net.Socket`
	97	surface — that surface does not work on Android either, while the syscalls do.
	98
	99	## What the PoC covers
	100
	101	* TLS (`:6697`, via jolt.mvn-http's OpenSSL bindings) or plain TCP (`:6667`)
	102	* Guest connect (`NICK`/`USER`), `001` welcome, `PING`/`PONG` keepalive
	103	* Auto-joins `#test` on `irc.freeq.at`
	104	* Join channels, channel buffers with unread counts, send and receive `PRIVMSG`
Ask for the backlog freeq restores channels without 94e59a2 nandi 20d ago	105	* Backlog on join, and `CHATHISTORY` for the channels freeq restores instead
Show the pictures people paste 56cdac3 nandi 20d ago	106	* Inline previews for PNG links, fetched once and cached under
Click a picture to see it full size 563ada3 nandi 20d ago	107	`$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	108	* Join/part notices, DMs bucketed under the sender's nick
	109	* Discover list, search over buffers, disconnect
Order the chat list by what you were last in 75e557e nandi 20d ago	110	* Conversations listed most recently opened first
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	111
	112	## Limits
	113
	114	* 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	115	* No `did:key` signing, no credential gates, no E2EE. Sign-in of either
	116	kind needs TLS, so it is desktop-only — the Android build connects as a
	117	guest.
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	118	* Only the broker token is persisted, and only for OAuth. An app-password
	119	sign-in is not remembered.
Show the pictures people paste 56cdac3 nandi 20d ago	120	* Previews are PNG only — the tree backend's decoder reads no other
	121	format, and a fetch needs TLS, so the phone shows links. The link is left in
	122	place either way.
	123	* Nothing evicts the media cache.
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	124	* No scrollback trimming, avatars, reactions, threads, or calls.
Stop mistaking a quiet connection for a closed one a225fb1 nandi 20d ago	125	* 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	126	* Message lists are keyed vboxes; glimmer-vidya has no `:listbox` yet.