jabber.developer2
22977846a3
Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.
Layers:
- architecture/ stable structural reference (overview, source-map,
test-map, data-flow)
- patterns/ memory, commands, autocomplete, events, xmpp,
encryption, ui, plugins
- testing/ unit-tests, stubs, functional-tests, bench
- build/ local, docker, ci
- playbooks/ add-command, add-test, add-autocomplete,
add-event-handler, add-encryption
- gotchas.md append-only dated entries (seven seed entries)
- wip/ branch-specific notes; deleted on merge to master
Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.
INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.
77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
# Data flow
|
|
|
|
High-level paths through the codebase. Use this when reasoning about where a
|
|
change should land or where a bug originates.
|
|
|
|
## User input → action
|
|
|
|
```
|
|
keypress
|
|
→ src/ui/inputwin.c (line editor, key dispatch)
|
|
→ src/command/cmd_ac.c (autocomplete on Tab)
|
|
→ src/command/cmd_defs.c (parse / lookup)
|
|
→ src/command/cmd_funcs.c (handler: cmd_<name>)
|
|
→ side effects: src/xmpp/, src/config/, src/ui/, src/event/
|
|
```
|
|
|
|
- Tab triggers autocomplete via `cmd_ac.c` lookup in `ac_funcs` hash table
|
|
(key: `/cmd`, value: per-command `_<cmd>_autocomplete` function).
|
|
- Enter parses input via `parse_args()` (`src/tools/parser.c`), looks up the
|
|
`Command*` via `cmd_get()` (`src/command/cmd_defs.c`), invokes the handler
|
|
declared with `CMD_MAINFUNC` or one of the `CMD_SUBFUNCS`.
|
|
|
|
## Outgoing chat message
|
|
|
|
```
|
|
cmd_msg / typing-into-chatwin
|
|
→ src/xmpp/message.c (build message stanza)
|
|
→ src/xmpp/stanza.c (assemble XML)
|
|
→ libstrophe (send)
|
|
→ src/chatlog.c (persist locally)
|
|
→ src/ui/chatwin.c (echo into window)
|
|
```
|
|
|
|
Encryption injects between message build and send:
|
|
|
|
- OMEMO via `src/xmpp/omemo.c` → `src/omemo/omemo.c` (libsignal-protocol).
|
|
- OTR via `src/otr/otr.c` (libotr).
|
|
- PGP / OX via `src/pgp/gpg.c` / `src/pgp/ox.c` → `src/xmpp/ox.c`.
|
|
|
|
## Incoming stanza
|
|
|
|
```
|
|
libstrophe callback
|
|
→ src/xmpp/{message,presence,iq,muc,roster}.c (parse, validate)
|
|
→ src/event/server_events.c (sv_ev_*)
|
|
→ src/ui/{chatwin,mucwin,console,...}.c (render)
|
|
→ src/chatlog.c (persist)
|
|
```
|
|
|
|
`server_events.c` is the chokepoint — every inbound XMPP event flows through a
|
|
`sv_ev_*` function. UI updates and persistence fan out from there.
|
|
|
|
## Client-initiated events
|
|
|
|
`src/event/client_events.c` mirrors `server_events.c` for events that
|
|
originate locally (UI actions, command-driven state changes) but need the
|
|
same downstream fan-out.
|
|
|
|
## Connection state
|
|
|
|
- `src/xmpp/connection.c` owns the `jabber_conn_status_t` (declared in
|
|
`connection.h`).
|
|
- `connection_get_status()` returns the current state. Many code paths gate
|
|
on `JABBER_CONNECTED` — see `patterns/xmpp.md`.
|
|
- Tests must `will_return(connection_get_status, JABBER_CONNECTED)` (or the
|
|
desired state) before exercising any code path that consults it. See
|
|
`gotchas.md`.
|
|
|
|
## Plugin hook points
|
|
|
|
Plugin callbacks (`src/plugins/callbacks.c`) sit on:
|
|
- Pre/post message send and receive (around `src/xmpp/message.c` flow).
|
|
- Connection lifecycle (around `src/xmpp/session.c`).
|
|
- Window-switch events (around `src/ui/window_list.c`).
|
|
|
|
See `patterns/plugins.md`.
|