nandi/frq · README.md

nandi/frqpublic⑂ Fork 0

⑂ 94e59a238f4a79970530ffba810161fafa01c917

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