From 83bf3019c532111962f653bc4d8a51c2f706e034 Mon Sep 17 00:00:00 2001 From: Steve Cliff Date: Sun, 21 Jun 2026 23:55:30 +0100 Subject: [PATCH] =?UTF-8?q?feat(mail):=20IMAP=20client=20=E2=80=94=20selec?= =?UTF-8?q?t,=20fetch=20headers/full,=20search?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 9 +- go.sum | 8 + internal/mail/imap.go | 199 +++++++++++++++++++++++++ internal/mail/imap_integration_test.go | 59 ++++++++ 4 files changed, 273 insertions(+), 2 deletions(-) create mode 100644 internal/mail/imap.go create mode 100644 internal/mail/imap_integration_test.go diff --git a/go.mod b/go.mod index 79b9d76..eb819f4 100644 --- a/go.mod +++ b/go.mod @@ -2,16 +2,21 @@ module git.dcglab.co.uk/steve/emcli go 1.25.0 -require modernc.org/sqlite v1.53.0 +require ( + github.com/emersion/go-imap v1.2.1 + github.com/emersion/go-message v0.18.2 + modernc.org/sqlite v1.53.0 +) require ( github.com/dustin/go-humanize v1.0.1 // indirect - github.com/emersion/go-message v0.18.2 // indirect + github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21 // indirect github.com/google/uuid v1.6.0 // indirect github.com/mattn/go-isatty v0.0.20 // indirect github.com/ncruces/go-strftime v1.0.0 // indirect github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect golang.org/x/sys v0.44.0 // indirect + golang.org/x/text v0.14.0 // indirect modernc.org/libc v1.73.4 // indirect modernc.org/mathutil v1.7.1 // indirect modernc.org/memory v1.11.0 // indirect diff --git a/go.sum b/go.sum index 3f9f4c3..09522c9 100644 --- a/go.sum +++ b/go.sum @@ -1,7 +1,13 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY= github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto= +github.com/emersion/go-imap v1.2.1 h1:+s9ZjMEjOB8NzZMVTM3cCenz2JrQIGGo5j1df19WjTA= +github.com/emersion/go-imap v1.2.1/go.mod h1:Qlx1FSx2FTxjnjWpIlVNEuX+ylerZQNFE5NsmKFSejY= +github.com/emersion/go-message v0.15.0/go.mod h1:wQUEfE+38+7EW8p8aZ96ptg6bAb1iwdgej19uXASlE4= github.com/emersion/go-message v0.18.2 h1:rl55SQdjd9oJcIoQNhubD2Acs1E6IzlZISRTK7x/Lpg= github.com/emersion/go-message v0.18.2/go.mod h1:XpJyL70LwRvq2a8rVbHXikPgKj8+aI0kGdHlg16ibYA= +github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21 h1:OJyUGMJTzHTd1XQp98QTaHernxMYzRaOasRir9hUlFQ= +github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21/go.mod h1:iL2twTeMvZnrg54ZoPDNfJaJaqy0xIQFuBdrLsmspwQ= +github.com/emersion/go-textwrapper v0.0.0-20200911093747-65d896831594/go.mod h1:aqO8z8wPrjkscevZJFVE1wXJrLpC5LtJG7fqLOsPb2U= github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs= github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= @@ -44,8 +50,10 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= +golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= +golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= diff --git a/internal/mail/imap.go b/internal/mail/imap.go new file mode 100644 index 0000000..52d76b0 --- /dev/null +++ b/internal/mail/imap.go @@ -0,0 +1,199 @@ +package mail + +import ( + "fmt" + "io" + "sort" + "time" + + "github.com/emersion/go-imap" + "github.com/emersion/go-imap/client" +) + +type IMAPConfig struct { + Host string + Port int + Security string // tls | starttls + Username string + Password string +} + +type Client struct { + c *client.Client +} + +func Dial(cfg IMAPConfig) (*Client, error) { + addr := fmt.Sprintf("%s:%d", cfg.Host, cfg.Port) + var ( + ic *client.Client + err error + ) + switch cfg.Security { + case "tls": + ic, err = client.DialTLS(addr, nil) + case "starttls": + ic, err = client.Dial(addr) + if err == nil { + err = ic.StartTLS(nil) + } + default: + return nil, fmt.Errorf("unknown imap security %q", cfg.Security) + } + if err != nil { + return nil, err + } + if err := ic.Login(cfg.Username, cfg.Password); err != nil { + ic.Logout() + return nil, err + } + return &Client{c: ic}, nil +} + +func (c *Client) Logout() error { return c.c.Logout() } + +func (c *Client) SelectFolder(folder string) (uint32, uint32, error) { + mbox, err := c.c.Select(folder, true) // read-only select + if err != nil { + return 0, 0, err + } + var maxUID uint32 + if mbox.Messages > 0 { + // UIDNext-1 is an upper bound for the highest existing UID. + if mbox.UidNext > 0 { + maxUID = mbox.UidNext - 1 + } + } + return mbox.UidValidity, maxUID, nil +} + +func (c *Client) fetchByUIDSet(folder string, set *imap.SeqSet, full bool) ([]Message, error) { + if _, err := c.c.Select(folder, true); err != nil { + return nil, err + } + section := &imap.BodySectionName{Peek: true} // entire message, no \Seen side-effect + items := []imap.FetchItem{imap.FetchUid, section.FetchItem()} + + msgCh := make(chan *imap.Message, 16) + done := make(chan error, 1) + go func() { done <- c.c.UidFetch(set, items, msgCh) }() + + var out []Message + for m := range msgCh { + r := m.GetBody(section) + if r == nil { + continue + } + raw, _ := io.ReadAll(r) + parsed, err := ParseMessage(m.Uid, raw) + if err != nil { + return nil, err + } + if !full { + parsed.Attachments = nil + parsed.BodyText = "" + } + out = append(out, parsed) + } + if err := <-done; err != nil { + return nil, err + } + sort.Slice(out, func(i, j int) bool { return out[i].Header.UID > out[j].Header.UID }) + return out, nil +} + +func (c *Client) FetchHeaders(folder string, uids []uint32) ([]Header, error) { + set := new(imap.SeqSet) + if len(uids) == 0 { + set.AddRange(1, 0) // 1:* — all + } else { + for _, u := range uids { + set.AddNum(u) + } + } + msgs, err := c.fetchByUIDSet(folder, set, false) + if err != nil { + return nil, err + } + return headersOf(msgs), nil +} + +func (c *Client) FetchHeadersRange(folder string, sinceUID, beforeUID uint32, limit int) ([]Header, error) { + set := new(imap.SeqSet) + lo := sinceUID + 1 + if sinceUID == 0 { + lo = 1 + } + hi := uint32(0) // '*' + if beforeUID > 1 { + hi = beforeUID - 1 + } + set.AddRange(lo, hi) + msgs, err := c.fetchByUIDSet(folder, set, false) + if err != nil { + return nil, err + } + h := headersOf(msgs) + if limit > 0 && len(h) > limit { + h = h[:limit] + } + return h, nil +} + +func (c *Client) FetchFull(folder string, uid uint32) (Message, error) { + set := new(imap.SeqSet) + set.AddNum(uid) + msgs, err := c.fetchByUIDSet(folder, set, true) + if err != nil { + return Message{}, err + } + if len(msgs) == 0 { + return Message{}, fmt.Errorf("uid %d not found in %s", uid, folder) + } + return msgs[0], nil +} + +type SearchCriteria struct { + From string + SubjectContains string + Text string + Since time.Time + Before time.Time +} + +func (c *Client) Search(folder string, sc SearchCriteria, limit int) ([]Header, error) { + if _, err := c.c.Select(folder, true); err != nil { + return nil, err + } + crit := imap.NewSearchCriteria() + if sc.From != "" { + crit.Header.Add("From", sc.From) + } + if sc.SubjectContains != "" { + crit.Header.Add("Subject", sc.SubjectContains) + } + if sc.Text != "" { + crit.Text = []string{sc.Text} + } + if !sc.Since.IsZero() { + crit.Since = sc.Since + } + if !sc.Before.IsZero() { + crit.Before = sc.Before + } + uids, err := c.c.UidSearch(crit) + if err != nil { + return nil, err + } + if len(uids) == 0 { + return nil, nil + } + return c.FetchHeaders(folder, uids) +} + +func headersOf(msgs []Message) []Header { + out := make([]Header, 0, len(msgs)) + for _, m := range msgs { + out = append(out, m.Header) + } + return out +} diff --git a/internal/mail/imap_integration_test.go b/internal/mail/imap_integration_test.go new file mode 100644 index 0000000..b5e7cca --- /dev/null +++ b/internal/mail/imap_integration_test.go @@ -0,0 +1,59 @@ +//go:build integration + +package mail + +import ( + "os" + "strconv" + "testing" +) + +// These tests require a GreenMail server reachable via env vars: +// +// EMCLI_TEST_IMAP_HOST, EMCLI_TEST_IMAP_PORT, EMCLI_TEST_USER, EMCLI_TEST_PASS +// +// Run: go test -tags=integration ./internal/mail/ +func testCfg(t *testing.T) IMAPConfig { + t.Helper() + host := os.Getenv("EMCLI_TEST_IMAP_HOST") + if host == "" { + t.Skip("EMCLI_TEST_IMAP_HOST not set; skipping IMAP integration test") + } + return IMAPConfig{ + Host: host, + Port: atoiEnv(t, "EMCLI_TEST_IMAP_PORT"), + Security: "starttls", + Username: os.Getenv("EMCLI_TEST_USER"), + Password: os.Getenv("EMCLI_TEST_PASS"), + } +} + +func TestSelectAndFetch(t *testing.T) { + c, err := Dial(testCfg(t)) + if err != nil { + t.Fatalf("Dial: %v", err) + } + defer c.Logout() + + uidv, maxUID, err := c.SelectFolder("INBOX") + if err != nil { + t.Fatalf("SelectFolder: %v", err) + } + if uidv == 0 { + t.Fatal("uidvalidity should be non-zero") + } + headers, err := c.FetchHeaders("INBOX", nil) + if err != nil { + t.Fatalf("FetchHeaders: %v", err) + } + t.Logf("inbox has %d messages, maxUID=%d", len(headers), maxUID) +} + +func atoiEnv(t *testing.T, k string) int { + t.Helper() + n, err := strconv.Atoi(os.Getenv(k)) + if err != nil { + t.Fatalf("bad int env %s: %v", k, err) + } + return n +}