nandi/frq · README.md

nandi/frqpublic⑂ Fork 0

⑂ dcd31d9fc7fd137826da39c11d8f678b8842a850

README.md · 89 lines · 4.3 KBmarkdown    Blame HistoryRaw
One frontend where there were three, and a core that is not Clojure   1# The Nim core
The last of the Clojure   3The program. It owns the state, the screens, the IRC connection and the
4message signing; Flutter is a renderer over the widget tree it emits, and
5`dart/frq_core` is the FFI binding between them.
One frontend where there were three, and a core that is not Clojure   6
8src/frq_core.nim        the C ABI: every exported symbol, and nothing else
The last of the Clojure   9src/frq/ui.nim          the widget tree, in the screens' own tag vocabulary
10src/frq/cells.nim       every piece of state the screens read
11src/frq/reducer.nim     every event they can send, and what it does
12src/frq/model.nim       what a message and a room are
13src/frq/rooms.nim       the list, the overview, and the read marker
14src/frq/members.nim     who is in a channel, and what the server says of them
15src/frq/conn.nim        the socket, the TLS, the line framing
One frontend where there were three, and a core that is not Clojure   16src/frq/ircparse.nim    the IRC wire format
The last of the Clojure   17src/frq/handshake.nim   CAP and the SASL exchange inside it
18src/frq/atproto.nim     handle → DID → PDS → session
19src/frq/crypto.nim      OpenSSL, bound: SHA-256 and Ed25519
20src/frq/msgsig.nim      signing a mutation so freeq will accept it
21src/frq/emoji.nim       1,884 emoji — generated, see below
22src/frq/glyphs.nim      a line split into words and pictures
23src/frq/clock.nim       server time in the reader's own zone
24src/frq/store.nim       what survives a restart
25src/frq/screens/        connect, chats, chat, discover, settings
One frontend where there were three, and a core that is not Clojure   26
28
The last of the Clojure   30Strings in, strings out, and JSON where the answer is not a single string —
31deliberately, against a struct-based ABI: a struct means both sides agreeing
32on a memory layout, and a field added later is a version skew that segfaults
33instead of failing.
35Two rules, both of which cost a segfault to rediscover:
37* Every string the core returns is the **caller's** to free, with `frq_free`.
38  Nim's allocator is not Dart's.
39* `frq_init` exists and does nothing. It used to call `NimMain`, and on Linux
40  `--app:lib` already runs the module initialisers from a library constructor
41  — so calling it again ran every module's top-level code a second time, which
42  for `conn.nim` meant `open()` on channels that were already open.
44## Things that will bite
46* **Nothing is shared with the socket threads.** There are two — one reader,
47  one writer — and they speak only in channels. `recvLine(timeout)` does not
48  time out on a TLS socket, so a single thread cannot both wait for the server
49  and notice what the client wants to say.
50* **`--mm:orc`, not refc.** refc gives each thread its own GC heap, so the
51  `Socket` the two threads share is a ref from another heap and dereferencing
52  it segfaults.
53* **Every intra-package import says `frq/…`.** `import conn` and
54  `import frq/conn` name the same file by two paths and Nim compiles it twice,
55  giving two sets of globals and two states.
56* **`emoji.nim` is generated.** It was `tools/emoji2nim.py` reading the
57  ClojureDart catalogue, which is gone; regenerating it now means going back to
58  Unicode's `emoji-test.txt` and filtering to what the Twemoji pack draws.
59* **The crypto is bindings, not implementations.** `crypto.nim` is OpenSSL
60  through EVP. The RFC 8032 vectors in `tests/tcrypto.nim` check that this
61  drives it correctly — the seed in the right place, the one-shot signing form,
62  the bytes out in the right order — and not that Ed25519 is implemented
63  correctly, which is OpenSSL's problem.
A message in #test, from Nim   64
The last of the Clojure   66just test nim              # the whole suite
67just test nim tircparse    # one file
68just build lib             # libfrqcore.so into build/nim
Delete the spike that owned the screens   69
The window connects   70
The last of the Clojure   71## What is not here
One frontend where there were three, and a core that is not Clojure   72
A face that opens someone   73`frq.replies` was never ported and went with the ClojureDart: asking freeq
74what a collapsed msgid was, for a reply pointing at a line that arrived
75already collapsed. It had no screen in this app to appear on, and the chip
76says "an earlier message" where that happens.
One frontend where there were three, and a core that is not Clojure   77
A face that opens someone   78`frq.profile` came back — recovered from the commit that deleted it and
79ported, since a face that opens nothing is worse than no face.
Three buttons that did nothing now do what they say   80
A face that opens someone   81The emoji picker, the overview strip, the lightbox and the profile card all
82have screens — the picker under the message it is for, the overview
Three buttons that did nothing now do what they say   83as a pane above the compose bar, the lightbox as a panel over the
84conversation — so the 🙂 chip, the Overview toggle and clicking a picture all
85do what they look like they do.
One frontend where there were three, and a core that is not Clojure   86
The last of the Clojure   87Untested against a real account: nobody has watched freeq accept a SASL
88challenge response or a signature. The shapes are checked and the curve is
89OpenSSL's, but the server has not said yes.

One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	1	# The Nim core
	2
The last of the Clojure 284b59c nandi 23h ago	3	The program. It owns the state, the screens, the IRC connection and the
	4	message signing; Flutter is a renderer over the widget tree it emits, and
	5	`dart/frq_core` is the FFI binding between them.
One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	6
	7	```
	8	src/frq_core.nim the C ABI: every exported symbol, and nothing else
The last of the Clojure 284b59c nandi 23h ago	9	src/frq/ui.nim the widget tree, in the screens' own tag vocabulary
	10	src/frq/cells.nim every piece of state the screens read
	11	src/frq/reducer.nim every event they can send, and what it does
	12	src/frq/model.nim what a message and a room are
	13	src/frq/rooms.nim the list, the overview, and the read marker
	14	src/frq/members.nim who is in a channel, and what the server says of them
	15	src/frq/conn.nim the socket, the TLS, the line framing
One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	16	src/frq/ircparse.nim the IRC wire format
The last of the Clojure 284b59c nandi 23h ago	17	src/frq/handshake.nim CAP and the SASL exchange inside it
	18	src/frq/atproto.nim handle → DID → PDS → session
	19	src/frq/crypto.nim OpenSSL, bound: SHA-256 and Ed25519
	20	src/frq/msgsig.nim signing a mutation so freeq will accept it
	21	src/frq/emoji.nim 1,884 emoji — generated, see below
	22	src/frq/glyphs.nim a line split into words and pictures
	23	src/frq/clock.nim server time in the reader's own zone
	24	src/frq/store.nim what survives a restart
	25	src/frq/screens/ connect, chats, chat, discover, settings
One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	26	```
	27
	28	## The ABI
	29
The last of the Clojure 284b59c nandi 23h ago	30	Strings in, strings out, and JSON where the answer is not a single string —
	31	deliberately, against a struct-based ABI: a struct means both sides agreeing
	32	on a memory layout, and a field added later is a version skew that segfaults
	33	instead of failing.
	34
	35	Two rules, both of which cost a segfault to rediscover:
	36
	37	* Every string the core returns is the caller's to free, with `frq_free`.
	38	Nim's allocator is not Dart's.
	39	* `frq_init` exists and does nothing. It used to call `NimMain`, and on Linux
	40	`--app:lib` already runs the module initialisers from a library constructor
	41	— so calling it again ran every module's top-level code a second time, which
	42	for `conn.nim` meant `open()` on channels that were already open.
	43
	44	## Things that will bite
	45
	46	* Nothing is shared with the socket threads. There are two — one reader,
	47	one writer — and they speak only in channels. `recvLine(timeout)` does not
	48	time out on a TLS socket, so a single thread cannot both wait for the server
	49	and notice what the client wants to say.
	50	* `--mm:orc`, not refc. refc gives each thread its own GC heap, so the
	51	`Socket` the two threads share is a ref from another heap and dereferencing
	52	it segfaults.
	53	* Every intra-package import says `frq/…`. `import conn` and
	54	`import frq/conn` name the same file by two paths and Nim compiles it twice,
	55	giving two sets of globals and two states.
	56	* `emoji.nim` is generated. It was `tools/emoji2nim.py` reading the
	57	ClojureDart catalogue, which is gone; regenerating it now means going back to
	58	Unicode's `emoji-test.txt` and filtering to what the Twemoji pack draws.
	59	* The crypto is bindings, not implementations. `crypto.nim` is OpenSSL
	60	through EVP. The RFC 8032 vectors in `tests/tcrypto.nim` check that this
	61	drives it correctly — the seed in the right place, the one-shot signing form,
	62	the bytes out in the right order — and not that Ed25519 is implemented
	63	correctly, which is OpenSSL's problem.
A message in #test, from Nim 35994d4 nandi yesterday	64
A message in #test, from Nim 35994d4 nandi yesterday	65	```bash
The last of the Clojure 284b59c nandi 23h ago	66	just test nim # the whole suite
	67	just test nim tircparse # one file
	68	just build lib # libfrqcore.so into build/nim
Delete the spike that owned the screens 1bb3f77 nandi yesterday	69	```
The window connects 1d62d1a nandi yesterday	70
The last of the Clojure 284b59c nandi 23h ago	71	## What is not here
One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	72
A face that opens someone 9bb81a1 nandi 23h ago	73	`frq.replies` was never ported and went with the ClojureDart: asking freeq
	74	what a collapsed msgid was, for a reply pointing at a line that arrived
	75	already collapsed. It had no screen in this app to appear on, and the chip
	76	says "an earlier message" where that happens.
One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	77
A face that opens someone 9bb81a1 nandi 23h ago	78	`frq.profile` came back — recovered from the commit that deleted it and
A face that opens someone 9bb81a1 nandi 23h ago	79	ported, since a face that opens nothing is worse than no face.
Three buttons that did nothing now do what they say 98d6135 nandi 23h ago	80
A face that opens someone 9bb81a1 nandi 23h ago	81	The emoji picker, the overview strip, the lightbox and the profile card all
A face that opens someone 9bb81a1 nandi 23h ago	82	have screens — the picker under the message it is for, the overview
Three buttons that did nothing now do what they say 98d6135 nandi 23h ago	83	as a pane above the compose bar, the lightbox as a panel over the
	84	conversation — so the 🙂 chip, the Overview toggle and clicking a picture all
	85	do what they look like they do.
One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday	86
The last of the Clojure 284b59c nandi 23h ago	87	Untested against a real account: nobody has watched freeq accept a SASL
	88	challenge response or a signature. The shapes are checked and the curve is
	89	OpenSSL's, but the server has not said yes.