Add a Fastmail import source #80

Merged
jcoffey-dev merged 1 commits from feat/fastmail-source into main 2026-11-13 18:29:36 +00:00
7 changed files with 266 additions and 1 deletions

No files matched your search

+7
View File
@@ -7,6 +7,13 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a
## [Unreleased]
### Added
- `import fastmail` imports from a Fastmail account over JMAP. It is `import
jmap` with Fastmail's server and bearer-token sign-in filled in, so it needs
only an API token; with no `--account-*` it imports the account Fastmail
marks primary. Mail always; calendars and contacts where that account
advertises them.
## [27.1-rc.13]
The thirteenth release candidate of the 27.1 series: shell completions and a
+3
View File
@@ -73,6 +73,9 @@ command reference is in [docs/usage.md](docs/usage.md).
## Sources
- **JMAP** -- any JMAP account, including an inbuxa or Stalwart server.
- **Fastmail** -- JMAP, with its server and token filled in: just an API
token. Mail always; calendars and contacts where the account advertises
them.
- **IMAP** -- mail only. Folders are chosen by name or by pattern.
- **CalDAV, CardDAV** -- calendars and events, address books and contacts.
- **WebDAV** -- a plain file collection, kept as a file tree.
+22
View File
@@ -111,6 +111,28 @@ The out-of-office reply, the server's `VacationResponse`, comes with
and `type`, as inbuxa and other servers on the 0.16 line do, or `@type` and
`mediaType`, as draft-ietf-jmap-filenode-18 servers such as Stalwart 1.0 do.
### Fastmail
```
inbuxa-migrate import fastmail \
[--token [TOKEN]] \
[--url <URL>] \
[--account-id <ID> | --account-name <NAME>] \
[--objects <list>] \
<ARCHIVE>
```
The same as `import jmap`, with Fastmail's server
(`https://api.fastmail.com/jmap/session`) and bearer-token sign-in already
filled in, so it needs only a token. Create one in Fastmail at **Settings >
Privacy & Security > API tokens** with read access to Mail, Calendars and
Contacts; pass it with `--token`, in `$INBUXA_MIGRATE_API_KEY`, or at the
prompt. With no `--account-*` it imports the account Fastmail marks primary,
which is the one you want unless you have several. What crosses over is
whatever that account's session advertises: mail always, calendars and
contacts where Fastmail offers them over JMAP. `--url` overrides the server
for a Fastmail-compatible host.
### IMAP
```
+165
View File
@@ -129,6 +129,16 @@ enum Command {
enum Source {
#[command(about = "JMAP server")]
Jmap(Box<JmapImportArgs>),
#[command(
about = "Fastmail (JMAP)",
name = "fastmail",
long_about = "Fastmail, over JMAP: a preset for `import jmap` already pointed at \
Fastmail's server, so it needs only an API token. Create one in Fastmail at \
Settings > Privacy & Security > API tokens, with read access to Mail, Calendars \
and Contacts. What it brings across depends on what that account's JMAP session \
offers: mail always, calendars and contacts where Fastmail advertises them."
)]
Fastmail(Box<FastmailImportArgs>),
#[command(about = "IMAP server")]
Imap(Box<ImapImportArgs>),
#[command(about = "CalDAV server")]
@@ -286,6 +296,52 @@ struct JmapImportArgs {
archive: PathBuf,
}
#[derive(Args)]
struct FastmailImportArgs {
#[arg(
long,
value_name = "TOKEN",
num_args = 0..=1,
help = "Fastmail API token (value optional: falls back to $INBUXA_MIGRATE_API_KEY or a prompt)"
)]
token: Option<Option<String>>,
#[arg(
long,
value_name = "URL",
help = "Override Fastmail's JMAP session URL (default: https://api.fastmail.com/jmap/session)"
)]
url: Option<String>,
#[arg(long, value_name = "ID", help = "Source account id")]
account_id: Option<String>,
#[arg(long, value_name = "NAME", help = "Source account name")]
account_name: Option<String>,
#[arg(
long,
value_name = "LIST",
help = "Comma-separated type list (default: all supported)"
)]
objects: Option<String>,
#[arg(
long,
help = "Permit importing when the archive records a different JMAP source"
)]
allow_source_change: bool,
#[command(flatten)]
global: GlobalArgs,
#[arg(
value_name = "ARCHIVE",
help = "Local SQLite archive (created if absent)"
)]
archive: PathBuf,
}
#[derive(Args)]
#[command(group(clap::ArgGroup::new("auth").required(true).args(["auth_basic", "auth_bearer", "google_key", "google_key_from_env"])))]
struct ImapImportArgs {
@@ -1162,6 +1218,7 @@ impl Cli {
fn resolve_import(source: Source) -> Result<Action, Error> {
match source {
Source::Jmap(args) => resolve_jmap_import(*args),
Source::Fastmail(args) => resolve_fastmail_import(*args),
Source::Imap(args) => resolve_imap_import(*args),
Source::Caldav(args) => resolve_dav_import(*args, DavKindArg::Caldav),
Source::Carddav(args) => resolve_dav_import(*args, DavKindArg::Carddav),
@@ -1469,6 +1526,35 @@ fn resolve_jmap_import(args: JmapImportArgs) -> Result<Action, Error> {
))
}
/// Fastmail's JMAP session endpoint. Every Fastmail account reaches JMAP
/// through this host, custom domains included, so it is a fixed default.
const FASTMAIL_SESSION_URL: &str = "https://api.fastmail.com/jmap/session";
/// resolve_fastmail_import is resolve_jmap_import with Fastmail's server and
/// token filled in: the same JMAP import, so what it brings across is whatever
/// that account's session advertises. Fastmail's JMAP takes a bearer token
/// only, so there is no --auth-basic here.
fn resolve_fastmail_import(args: FastmailImportArgs) -> Result<Action, Error> {
let common = common_config(&args.global, args.archive);
let auth = resolve_auth(None, None, args.token.as_ref(), None)?;
let account = resolve_account_or_primary(args.account_id, args.account_name)?;
let objects = args.objects.as_deref().map(parse_object_list).transpose()?;
Ok(Action::Import(
common,
ImportConfig {
connect: ConnectConfig {
stay_on_url: false,
url: args.url.unwrap_or_else(|| FASTMAIL_SESSION_URL.to_owned()),
auth,
account,
},
objects,
allow_source_change: args.allow_source_change,
},
))
}
fn resolve_imap_import(args: ImapImportArgs) -> Result<Action, Error> {
let common = common_config(&args.global, args.archive);
let auth = match (&args.google_key, args.google_key_from_env) {
@@ -2312,6 +2398,22 @@ fn resolve_account(
}
}
/// Like resolve_account, but neither given means the session's primary account
/// -- so a single-account import need not name it.
fn resolve_account_or_primary(
account_id: Option<String>,
account_name: Option<String>,
) -> Result<AccountSelector, Error> {
match (account_id, account_name) {
(Some(id), None) => Ok(AccountSelector::Id(id)),
(None, Some(name)) => Ok(AccountSelector::Name(name)),
(None, None) => Ok(AccountSelector::Primary),
(Some(_), Some(_)) => Err(Error::Usage(
"give only one of --account-id / --account-name".to_owned(),
)),
}
}
#[cfg(test)]
mod tests {
use super::*;
@@ -2347,6 +2449,69 @@ mod tests {
assert!(matches!(cli.resolve().unwrap(), Action::Man));
}
#[test]
fn fastmail_defaults_to_fastmails_server_with_a_bearer_token() {
let cli = Cli::try_parse_from([
"inbuxa-migrate",
"import",
"fastmail",
"--token",
"fmu-secret",
"archive.sqlite",
])
.unwrap_or_else(|e| panic!("clap rejected: {e}"));
match cli.resolve().unwrap() {
Action::Import(_, c) => {
assert_eq!(c.connect.url, "https://api.fastmail.com/jmap/session");
assert!(!c.connect.stay_on_url);
assert!(matches!(c.connect.auth, Auth::Bearer { token } if token == "fmu-secret"));
// No --account given: default to the session's primary.
assert!(matches!(c.connect.account, AccountSelector::Primary));
}
_ => panic!("expected Action::Import"),
}
}
#[test]
fn fastmail_url_can_be_overridden() {
let cli = Cli::try_parse_from([
"inbuxa-migrate",
"import",
"fastmail",
"--token",
"t",
"--url",
"https://api.messagingengine.com/jmap/session",
"archive.sqlite",
])
.unwrap_or_else(|e| panic!("clap rejected: {e}"));
match cli.resolve().unwrap() {
Action::Import(_, c) => {
assert_eq!(
c.connect.url,
"https://api.messagingengine.com/jmap/session"
);
}
_ => panic!("expected Action::Import"),
}
}
#[test]
fn fastmail_takes_no_basic_auth() {
// Fastmail's JMAP is bearer-only; --auth-basic is not a flag here.
assert!(
Cli::try_parse_from([
"inbuxa-migrate",
"import",
"fastmail",
"--auth-basic",
"[email protected]",
"archive.sqlite",
])
.is_err()
);
}
#[test]
fn graph_max_rps_is_off_by_default_and_parsed_when_given() {
assert_eq!(graph_config(&[]).unwrap().max_rps, None);
+62
View File
@@ -17,6 +17,9 @@ use std::fmt::Write;
pub enum AccountSelector {
Id(String),
Name(String),
/// The account the session marks primary for mail, or the only one it
/// enumerates. Lets a single-account import run without naming it.
Primary,
}
const PRINCIPALS_URN: &str = "urn:ietf:params:jmap:principals";
@@ -36,6 +39,25 @@ pub fn resolve(
}
resolve_via_principal(name, session, client)
}
AccountSelector::Primary => {
const MAIL_URN: &str = "urn:ietf:params:jmap:mail";
if let Some(id) = session.primary_accounts.get(MAIL_URN) {
return Ok(id.clone());
}
// No primary named: fall back to the only account, or ask which.
let mut ids = session.accounts.keys();
match (ids.next(), ids.next()) {
(Some(id), None) => Ok(id.clone()),
(Some(_), Some(_)) => Err(Error::Account(format!(
"this session has {} accounts and names no primary for mail; \
choose one with --account-name or --account-id",
session.accounts.len()
))),
_ => Err(Error::Account(
"this session enumerates no account to import".to_owned(),
)),
}
}
}
}
@@ -185,6 +207,46 @@ mod tests {
)
}
#[test]
fn primary_selector_uses_primary_accounts() {
let raw = serde_json::json!({
"apiUrl": "https://example.org/api",
"uploadUrl": "https://example.org/upload",
"downloadUrl": "https://example.org/download",
"capabilities": {},
"accounts": { "a": { "name": "alice" }, "b": { "name": "bob" } },
"primaryAccounts": { "urn:ietf:params:jmap:mail": "b" }
});
let s: Session = serde_json::from_value(raw).unwrap();
assert_eq!(
resolve(&AccountSelector::Primary, &s, &client()).unwrap(),
"b"
);
}
#[test]
fn primary_selector_falls_back_to_the_sole_account() {
// No primaryAccounts, but only one account: that is the one.
let s = session_with("[email protected]", "only");
assert_eq!(
resolve(&AccountSelector::Primary, &s, &client()).unwrap(),
"only"
);
}
#[test]
fn primary_selector_is_ambiguous_with_several_and_no_primary() {
let raw = serde_json::json!({
"apiUrl": "https://example.org/api",
"uploadUrl": "https://example.org/upload",
"downloadUrl": "https://example.org/download",
"capabilities": {},
"accounts": { "a": { "name": "alice" }, "b": { "name": "bob" } }
});
let s: Session = serde_json::from_value(raw).unwrap();
assert!(resolve(&AccountSelector::Primary, &s, &client()).is_err());
}
#[test]
fn id_selector_is_verbatim() {
let s = session_with("alice", "a");
+5
View File
@@ -22,6 +22,11 @@ pub struct Session {
pub download_url: String,
pub capabilities: IndexMap<String, Value>,
pub accounts: IndexMap<String, Account>,
/// The account the user treats as primary for each capability (RFC 8620),
/// which lets an import default to the right one without being told. Not
/// every server sends it, so it is optional.
#[serde(default)]
pub primary_accounts: IndexMap<String, String>,
}
#[derive(Debug, Clone, Deserialize)]
+2 -1
View File
@@ -217,7 +217,8 @@ fn run_into(
} else {
let account_name = match &config.connect.account {
crate::jmap::account::AccountSelector::Name(n) => Some(n.clone()),
crate::jmap::account::AccountSelector::Id(_) => None,
crate::jmap::account::AccountSelector::Id(_)
| crate::jmap::account::AccountSelector::Primary => None,
};
Some(
db::sources::upsert_source(