jcoffey-dev
4568f9abbf
Found by running preflight against a real Stalwart 0.15.5 in a VM. Two defects, the second worse than the first. 1. AccountSnapshot could not read the version this tool migrates FROM. 0.15.5 advertises no urn:stalwart:jmap capability and POST /api returns 404 - the JMAP management API and x:Account are 0.16 features. 0.15.x exposes a REST API at GET /api/principal instead. So preflight's account-snapshot check warned and moved on, and every run against a real source instance had no "before" data at all. AccountSnapshot now dispatches on the capability the session document advertises - a positive signal, not an inference from a failed call - and internal/stalwartapi/principal.go implements the 0.15.x REST path, including its 1-based page/limit pagination so an install larger than one page isn't silently truncated. 2. With no "before" counts, the content-integrity comparison iterated an empty map, checked nothing, and reported "all message counts match". That is the strongest claim this tool makes - ARCHITECTURE 4.7 calls it the actual no-data-loss guarantee - made vacuously, and it would have passed on a migration that lost every message. The comparison now derives its account set from whatever the source could report, verifies every account and domain survived either way, and carries MessageCountsCompared so the report says plainly "MESSAGE COUNTS NOT COMPARED ... no-data-loss is NOT verified here" rather than implying otherwise. What can and cannot be checked across the 0.15/0.16 boundary, now that a real server has answered: 0.15.x has no per-mailbox message count at any endpoint, and the impersonation login 0.16 offers returns 401 there, so before/after message counts are impossible for the boundary migration this tool exists for. Both versions do report per-account used quota (usedQuota in 0.15's REST list, usedDiskQuota on 0.16's x:Account), so that is captured on both sides. It is recorded and reported, not asserted on: 4.5 notes the 0.16 migration resets quotas to zero pending recalculation, so comparing those bytes across the boundary would be a false alarm generator. Test servers across preflight, validate and stalwartapi now advertise urn:stalwart:jmap, since they stand in for 0.16 instances and that capability is what says so. Verified end to end against the smoke VM: all nine preflight checks pass, and the checkpoint records 2 accounts, 1 domain and per-account used quota where it previously recorded nothing.
83 lines
2.9 KiB
Go
83 lines
2.9 KiB
Go
// SPDX-FileCopyrightText: 2026 LINUXexpert-org
|
|
// SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
package stalwartapi
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"net/http"
|
|
"strings"
|
|
"time"
|
|
)
|
|
|
|
// Client is the shared JMAP/management-API client every migration phase
|
|
// uses to talk to a Stalwart instance. It stays deliberately thin: phases
|
|
// that need Stalwart-specific behavior (recovery-mode control, apply-plan
|
|
// replay, account/mailbox introspection) get methods added here only as
|
|
// their wire-level details are confirmed against Stalwart's actual source
|
|
// and documentation, never guessed - see management.go and mailbox.go for
|
|
// what that grounding looked like for account enumeration and mailbox
|
|
// counts respectively.
|
|
type Client struct {
|
|
BaseURL string // e.g. "https://mail.example.com"
|
|
Username string
|
|
Password string
|
|
HTTPClient *http.Client
|
|
}
|
|
|
|
func (c *Client) httpClient() *http.Client {
|
|
if c.HTTPClient != nil {
|
|
return c.HTTPClient
|
|
}
|
|
return &http.Client{Timeout: 15 * time.Second}
|
|
}
|
|
|
|
// Ping confirms the instance is reachable and the given credentials are
|
|
// accepted, via JMAP session discovery (RFC 8620 §2, the well-known
|
|
// /.well-known/jmap endpoint) over HTTP Basic auth. This is preflight's
|
|
// "dry-run" reachability check (ARCHITECTURE.md §4.1): it does nothing but
|
|
// read the session document, so it's safe to run against a live production
|
|
// server before anything else in the migration happens.
|
|
func (c *Client) Ping(ctx context.Context) error {
|
|
url := strings.TrimRight(c.BaseURL, "/") + "/.well-known/jmap"
|
|
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
req.SetBasicAuth(c.Username, c.Password)
|
|
resp, err := c.httpClient().Do(req)
|
|
if err != nil {
|
|
return fmt.Errorf("stalwartapi: reach %s: %w", url, err)
|
|
}
|
|
defer resp.Body.Close()
|
|
if resp.StatusCode != http.StatusOK {
|
|
return fmt.Errorf("stalwartapi: session request to %s returned %s", url, resp.Status)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Snapshot mirrors checkpoint.PreflightSnapshot's shape without this
|
|
// package depending on the checkpoint package's format.
|
|
type Snapshot struct {
|
|
AccountCount int
|
|
Domains []string
|
|
MailboxCounts map[string][]MailboxCount // account email -> its mailboxes
|
|
// UsedQuota is each account's used storage in bytes. Unlike
|
|
// MailboxCounts it is available from both API generations - 0.15.x's
|
|
// REST principal list and 0.16's x:Account both report it - which
|
|
// makes it the only per-account content measure that can be compared
|
|
// across the 0.15/0.16 boundary. See principal.go.
|
|
UsedQuota map[string]int64
|
|
// MailboxErrors records, per account email, why that account's mailbox
|
|
// counts couldn't be captured (e.g. impersonation not permitted for
|
|
// that account). A non-empty entry here means MailboxCounts has no
|
|
// entry for that account - it's not silently treated as zero messages.
|
|
MailboxErrors map[string]string
|
|
}
|
|
|
|
type MailboxCount struct {
|
|
Mailbox string
|
|
Messages int
|
|
}
|