You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 564d88d
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,6 @@ Everything below documents only what differs from the Pimalaya standards.
16
16
Carillon owns no protocol code. It supervises watches, reads the configuration and fires the hooks, and everything on the wire belongs to the crate that speaks that protocol. Triage before patching:
17
17
18
18
- how a change is learned belongs to the protocol crate: [io-imap](https://github.com/pimalaya/io-imap) for the idle watch, [io-jmap](https://github.com/pimalaya/io-jmap) for the changes poll, [io-maildir](https://github.com/pimalaya/io-maildir) for the listing poll, [io-webdav](https://github.com/pimalaya/io-webdav) for the collection poll;
19
-
- the shared TOML shape, since one file backs three binaries, is settled with [himalaya](https://github.com/pimalaya/himalaya) rather than here;
20
19
- the configuration schema, the backend selection, the supervision and the hooks live here.
21
20
22
21
The clap, printer and logger primitives come from [pimalaya/cli](https://github.com/pimalaya/cli), the TOML loader and the secret resolution from [pimalaya/config](https://github.com/pimalaya/config), and the TCP and TLS plumbing from [pimalaya/stream](https://github.com/pimalaya/stream).
-**Multi-account** watch: every configured account at once, each reconnecting on its own
39
+
-**Interactive wizard**: `carillon configure` turns an email address into a tested account
29
40
30
41
> [!TIP]
31
42
> Carillon is written in [Rust](https://www.rust-lang.org/) and uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate backend support. The default feature set is declared in [Cargo.toml](./Cargo.toml).
32
43
33
-
## Coverage
34
-
35
-
| Spec | What is covered |
36
-
|--------------|-----------------|
37
-
|[2177]| IMAP idle: the held connection a watch waits on, woken by the server on every change |
38
-
|[2971]| IMAP identification, required by some providers right after authentication |
39
-
|[4505]| SASL anonymous, for servers accepting unauthenticated sessions |
40
-
|[4616]| SASL plain, the password mechanism |
41
-
|[4918]| WebDAV itself: the report a collection answers, and the etag that says an item moved |
42
-
|[4959]| SASL initial response, forced on or off for providers that advertise it and then refuse it |
43
-
|[6186]| Mail service SRV records, one of the ways the wizard finds a server from an address |
44
-
|[6578]| Collection synchronization: the token a poll carries, what changed since it, and what to do when the server refuses it |
45
-
|[6764]| CalDAV and CardDAV bootstrapping, how the wizard finds a calendar or an addressbook |
46
-
|[7162]| Quick mailbox resynchronization: server-named deltas where the server offers them, a local re-read and diff where it does not |
47
-
|[7628]| SASL oauthbearer, an OAuth 2.0 token issued by an external broker |
48
-
|[7677]| SASL scram-sha-256, the challenge-response mechanism |
49
-
|[8620]| The JMAP core: session discovery, the changes and get method shapes, request batching, and the event-source stream a push watch holds |
50
-
|[8621]| JMAP for mail: mailboxes, emails, and the change stream a watch polls |
51
-
|[autoconfig]| Thunderbird autoconfiguration, the widest-published source of provider settings |
52
-
|[maildir]| The original Maildir layout, plus the Maildir++ subfolder convention |
53
-
|[pacc]| Provider account configuration, the successor the wizard prefers when a domain publishes one |
Run `carillon` with no command: it offers to generate an account discovered from your email address, which `carillon configure` does again later. The wizard searches the services your provider publishes, asks which one to watch and how to authenticate, picks the best watch method the server supports, tests the connection, then saves the account, appends it to the configuration already there, or prints it for you to place by hand.
118
-
119
-
Everything discovery does not cover is written by hand: copy the annotated [config.sample.toml](./config.sample.toml), keep one backend and the hooks you want, delete the rest. It documents every key.
120
-
121
-
A configuration is loaded from the first valid path among:
88
+
The configuration is loaded from the first existing path among:
122
89
123
-
- $XDG_CONFIG_HOME/carillon/config.toml
124
-
- $HOME/.config/carillon/config.toml
125
-
- $HOME/.carillonrc
90
+
-`$XDG_CONFIG_HOME/carillon/config.toml`
91
+
-`$HOME/.config/carillon/config.toml`
92
+
-`$HOME/.carillonrc`
126
93
127
-
Override the path with `-c <PATH>` or `CARILLON_CONFIG=<PATH>`. Multiple paths can be passed at once, separated by `:`. The first one is the base and the rest are deep-merged on top. The full field reference lives in [config.sample.toml](./config.sample.toml).
94
+
Override the path with `carillon -c <PATH>` or `CARILLON_CONFIG=<PATH>`. Multiple paths can be passed at once, separated by `:`; the first is the base and the rest are deep-merged on top. The full field reference lives in [config.sample.toml](./config.sample.toml).
128
95
129
-
Those are the paths [himalaya](https://github.com/pimalaya/himalaya) and [himalaya-tui](https://github.com/pimalaya/himalaya-tui) read too, and an account block is written the same way, but one file does not load in all three: every backend block is strict on each side and carries keys the others do not know.
96
+
Run `carillon` with no command to launch the wizard, `carillon configure` to run it again later. It discovers from your email address the services your provider publishes, asks which one to watch and how to authenticate, picks the best watch method the server supports, tests the connection, then saves the account or prints it for you to place by hand.
130
97
131
-
An account declares one backend block (`imap`, `jmap`, `maildir`, `caldav`, `carddav`) carrying everything that backend needs: the collection it watches under its own name, how it watches (`watch`), and what it fires (`hook`). Declaring several backends is allowed;`-b/--backend` then picks one.
98
+
An account declares one backend block (`imap`, `jmap`, `maildir`, `caldav`, `carddav`) carrying the collection it watches, how it watches it (`watch`) and what it fires (`hook`). Declaring several is allowed,`-b/--backend` then selecting one.
0 commit comments