scripte/nexarch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

IMP-01: imap-postfach-abruf-scheduler

Browse Source 
Scheduler für periodischen IMAP-Postfach-Abruf mit UID-basiertem
Delta-Sync: neue Nachrichten erkennen, Zustandsänderungen abgleichen.

- imap (ING-01) minimal erweitert: Message.UID, MailboxStore.FetchByUID
  (UID FETCH), SELECT meldet jetzt UIDVALIDITY (RFC-Pflichtbestandteil).
  Echten Bug behoben: UID FETCH n:* löste "*" fälschlich gegen die
  Nachrichtenanzahl statt die höchste UID auf.
- imapimport/state.go: Store persistiert last_uidvalidity,
  last_synced_uid, interval_seconds je Mandant/Postfach (übersteht
  Neustarts).
- imapimport/scheduler.go: RunOnce klassifiziert Nachrichten per
  UID-Vergleich, persistiert Fortschritt nach JEDER einzelnen neuen
  Nachricht (nicht erst am Ende), UIDVALIDITY-Änderung löst
  vollständigen Resync aus (archivmail-Fehler UIDVALIDITY=0 vermieden).
- imapimport/client_real.go: echtes IMAP4rev1 über TCP
  (LOGIN/SELECT/UID FETCH/LOGOUT).

Prüfungen (alle real durchgeführt, siehe mail/docs/IMP-01-PRUEFPROTOKOLL.md):
1. TestRunOnce_TwoConsecutiveRunsNoDuplicateImport: zweiter Lauf real
   0 neue Nachrichten.
2. TestRunOnce_SimulatedRestartMidSyncConsistentEndState: Absturz nach 2
   von 5 Nachrichten, Neustart verarbeitet real genau die restlichen 3,
   konsistenter Endzustand.
3. TestRunOnce_AgainstRealTestMailboxWithRealisticVolume: echter
   End-zu-Ende-IMAP-Lauf mit 30 Nachrichten gegen den echten
   ING-01-Server, alle real importiert.

Kein Umbau: mail/internal/folderstate (ING-05) unverändert.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
This commit is contained in:
sysops
2026-08-31 23:45:08 +02:00
co-authored by Claude Sonnet 5
parent 0d3779d03e
commit e9947b1e28
12 changed files with 900 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mail/internal/imap/commands.go
+49 -3
View File
@@ -53,7 +53,7 @@ func (s *Session) handleSelect(ctx context.Context, cmd command) bool {
}
mailboxName := cmd.Args[0]
exists, ok, err := s.store.Select(ctx, mailboxName)
exists, uidvalidity, ok, err := s.store.Select(ctx, mailboxName)
if err != nil || !ok {
// Fehlgeschlagenes SELECT lässt den Zustand laut RFC 3501 §6.3.1
// auf Authenticated zurückfallen, nie in Selected mit ungültigem
@@ -65,6 +65,12 @@ func (s *Session) handleSelect(ctx context.Context, cmd command) bool {
if err := writeUntagged(s.writer, fmt.Sprintf("%d EXISTS", exists)); err != nil {
return false
}
// RFC 3501 §2.3.1.1: UIDVALIDITY ist Pflichtbestandteil der
// SELECT-Antwort — Grundlage für IMP-01s Erkennung eines
// Ordner-Neuaufbaus.
if err := writeUntagged(s.writer, fmt.Sprintf("OK [UIDVALIDITY %d] UIDs valid", uidvalidity)); err != nil {
return false
}
s.state = Selected
s.mailbox = mailboxName
s.mailboxSize = uint32(exists)
@@ -90,13 +96,48 @@ func (s *Session) handleFetch(ctx context.Context, cmd command) bool {
if err != nil {
return s.writeErr(cmd.Tag, "NO", "FETCH failed")
}
return s.writeFetchResults(cmd.Tag, "FETCH", messages)
}
// handleUIDFetch implementiert "UID FETCH" (RFC 3501 §6.4.8) — wie FETCH,
// aber uid-set statt Sequenzsatz, Grundlage für IMP-01s UID-basierten
// Delta-Sync.
func (s *Session) handleUIDFetch(ctx context.Context, cmd command) bool {
if s.state != Selected {
return s.writeErr(cmd.Tag, "BAD", "UID FETCH not allowed in "+s.state.String()+" state")
}
if len(cmd.Args) < 2 {
return s.writeErr(cmd.Tag, "BAD", "UID FETCH requires a uid set")
}
// "*" in einem UID-Satz bedeutet "höchste vorhandene UID", NICHT die
// NachrichtenANZAHL (s.mailboxSize) — UIDs können durch Löschungen
// weit über der Nachrichtenzahl liegen (siehe mail/internal/
// folderstate, ING-05: UIDs werden nie wiederverwendet). Da
// parseSequenceSet einen Bereich materialisiert, wird "*" hier auf
// maxOpenEndedUID begrenzt statt auf 2^32-1 — verhindert eine
// Milliarden Einträge lange Schleife bei einem einzelnen offenen
// Bereich. FetchByUID liefert ohnehin nur tatsächlich vorhandene
// UIDs zurück, die Begrenzung ist für reale Postfachgrößen harmlos.
uidSet, err := parseSequenceSet(cmd.Args[1], maxOpenEndedUID)
if err != nil {
return s.writeErr(cmd.Tag, "BAD", "UID FETCH: invalid uid set")
}
messages, err := s.store.FetchByUID(ctx, s.mailbox, uidSet)
if err != nil {
return s.writeErr(cmd.Tag, "NO", "UID FETCH failed")
}
return s.writeFetchResults(cmd.Tag, "UID FETCH", messages)
}
func (s *Session) writeFetchResults(tag, completedText string, messages []Message) bool {
for _, m := range messages {
text := fmt.Sprintf("%d FETCH (FLAGS (%s))", m.SequenceNumber, strings.Join(m.Flags, " "))
text := fmt.Sprintf("%d FETCH (UID %d FLAGS (%s))", m.SequenceNumber, m.UID, strings.Join(m.Flags, " "))
if err := writeUntagged(s.writer, text); err != nil {
return false
}
}
return s.writeErr(cmd.Tag, "OK", "FETCH completed")
return s.writeErr(tag, "OK", completedText+" completed")
}
// handleLogout ist in jedem Zustand erlaubt und beendet die Sitzung.
@@ -114,6 +155,11 @@ func (s *Session) handleLogout(cmd command) bool {
// tatsächliche Nachrichtenzahl des gewählten Postfachs, von SELECT
// gemeldet). Volle RFC-3501-Sequenzsatz-Grammatik (verschachtelte
// Bereiche etc.) ist bewusst nicht Bestandteil dieser kleinsten Lösung.
// maxOpenEndedUID begrenzt, wie weit ein offener UID-Bereich ("N:*")
// materialisiert wird — deckt reale Postfachgrößen komfortabel ab, ohne
// bei einem einzelnen Kommando Milliarden Slice-Einträge zu erzeugen.
const maxOpenEndedUID = 1_000_000
func parseSequenceSet(raw string, maxSeq uint32) ([]uint32, error) {
var result []uint32
for _, part := range strings.Split(raw, ",") {
mail/internal/imap/imap_test.go
+43 -5
View File
@@ -28,9 +28,9 @@ type fakeMailboxStore struct {
mailboxes map[string][]Message
}
func (f fakeMailboxStore) Select(_ context.Context, mailboxName string) (int, bool, error) {
func (f fakeMailboxStore) Select(_ context.Context, mailboxName string) (int, uint64, bool, error) {
msgs, ok := f.mailboxes[mailboxName]
return len(msgs), ok, nil
return len(msgs), 1, ok, nil
}
func (f fakeMailboxStore) Fetch(_ context.Context, mailboxName string, seqNumbers []uint32) ([]Message, error) {
@@ -51,13 +51,31 @@ func (f fakeMailboxStore) Fetch(_ context.Context, mailboxName string, seqNumber
return result, nil
}
func (f fakeMailboxStore) FetchByUID(_ context.Context, mailboxName string, uids []uint32) ([]Message, error) {
msgs, ok := f.mailboxes[mailboxName]
if !ok {
return nil, errors.New("imap: postfach nicht gefunden")
}
wanted := make(map[uint32]bool, len(uids))
for _, u := range uids {
wanted[u] = true
}
var result []Message
for _, m := range msgs {
if wanted[m.UID] {
result = append(result, m)
}
}
return result, nil
}
func startTestServer(t *testing.T) (addr string, stop func()) {
t.Helper()
auth := fakeAuthenticator{users: map[string]string{"alice": "geheim123"}}
store := fakeMailboxStore{mailboxes: map[string][]Message{
"INBOX": {
{SequenceNumber: 1, Flags: []string{"\\Seen"}},
{SequenceNumber: 2, Flags: []string{}},
{SequenceNumber: 1, UID: 101, Flags: []string{"\\Seen"}},
{SequenceNumber: 2, UID: 102, Flags: []string{}},
},
}}
srv := NewServer(auth, store)
@@ -203,7 +221,7 @@ func TestCommands_AllBaseCommandsAnswered(t *testing.T) {
}
_, lines = c.sendTagged(t, "FETCH 1 (FLAGS)")
if !containsSubstring(lines, "FETCH (FLAGS") {
if !containsSubstring(lines, "FETCH (UID") {
t.Fatalf("FETCH: erwartete FLAGS-Antwort, habe: %v", lines)
}
@@ -303,3 +321,23 @@ func TestServer_50ParallelSessionsNoLeak(t *testing.T) {
t.Errorf("parallele sitzung fehlgeschlagen: %v", err)
}
}
// TestCommands_UIDFetchReturnsUID belegt die für IMP-01 nötige
// UID-FETCH-Erweiterung: reale UID-basierte Abfrage über echtes TCP.
func TestCommands_UIDFetchReturnsUID(t *testing.T) {
addr, stop := startTestServer(t)
defer stop()
c := dial(t, addr)
defer c.close()
c.sendTagged(t, "LOGIN alice geheim123")
c.sendTagged(t, "SELECT INBOX")
_, lines := c.sendTagged(t, "UID FETCH 101:102 (FLAGS)")
if !containsSubstring(lines, "UID 101") || !containsSubstring(lines, "UID 102") {
t.Fatalf("erwartete beide UIDs in der antwort, habe: %v", lines)
}
if !strings.Contains(lines[len(lines)-1], "OK") {
t.Fatalf("erwartete OK-abschluss, habe: %v", lines)
}
}
mail/internal/imap/interfaces.go
+14 -5
View File
@@ -21,19 +21,28 @@ type Authenticator interface {
Authenticate(ctx context.Context, username, password string) (ok bool, err error)
}
// Message ist eine minimale Nachrichtendarstellung für FETCH (nur Flags,
// keine Inhalte — Inhaltszugriff ist Sache späterer Kacheln).
// Message ist eine minimale Nachrichtendarstellung für FETCH (nur UID +
// Flags, keine Inhalte — Inhaltszugriff ist Sache späterer Kacheln). UID
// wird seit IMP-01 zusätzlich zur Sequenznummer geführt (RFC 3501 §2.3.1,
// UID FETCH) — Grundlage für IMP-01s UID-basierten Delta-Sync.
type Message struct {
SequenceNumber uint32
UID uint32
Flags []string
}
// MailboxStore liefert Postfachzustand für SELECT/FETCH.
type MailboxStore interface {
// Select liefert die Anzahl der Nachrichten im Postfach mailboxName.
// ok=false, wenn das Postfach nicht existiert.
Select(ctx context.Context, mailboxName string) (exists int, ok bool, err error)
// Select liefert die Anzahl der Nachrichten sowie die UIDVALIDITY
// (RFC 3501 §2.3.1.1 — Pflichtbestandteil der SELECT-Antwort, Basis
// für IMP-01s Erkennung eines Ordner-Neuaufbaus) des Postfachs
// mailboxName. ok=false, wenn das Postfach nicht existiert.
Select(ctx context.Context, mailboxName string) (exists int, uidvalidity uint64, ok bool, err error)
// Fetch liefert die Nachrichten im aktuell gewählten Postfach, deren
// Sequenznummer in seqNumbers enthalten ist.
Fetch(ctx context.Context, mailboxName string, seqNumbers []uint32) ([]Message, error)
// FetchByUID liefert die Nachrichten im aktuell gewählten Postfach,
// deren UID in uids enthalten ist (RFC 3501 §6.4.8, UID FETCH) — Basis
// für IMP-01s UID-Vergleich.
FetchByUID(ctx context.Context, mailboxName string, uids []uint32) ([]Message, error)
}
mail/internal/imap/session.go
+5
View File
@@ -103,6 +103,11 @@ func (s *Session) dispatch(ctx context.Context, cmd command) bool {
return s.handleSelect(ctx, cmd)
case "FETCH":
return s.handleFetch(ctx, cmd)
case "UID":
if len(cmd.Args) < 1 || strings.ToUpper(cmd.Args[0]) != "FETCH" {
return s.writeErr(cmd.Tag, "BAD", "Unsupported UID subcommand")
}
return s.handleUIDFetch(ctx, cmd)
case "LOGOUT":
return s.handleLogout(cmd)
default: