nandi/frq · README.md

nandi/frqpublic⑂ Fork 0

⑂ dbf3b86562a33f33daab5c6b5247433590c1ccf1

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