@lengelhard/imap-email-mcp 1.6.0 → 1.7.0

package/lib/imap-session.js

@@ -0,0 +1,251 @@
+/**
+ * IMAP session helpers for imap-email-mcp.
+ *
+ * - SessionManager keeps one authenticated IMAP connection open and hands it
+ *   out as a lease, one tool call at a time. A lease's end() releases the lock;
+ *   it never logs out. The socket is closed after a period of inactivity.
+ * - fetchMessages() fetches an explicit UID list without the search-then-fetch
+ *   pattern of imap-simple (which fetched every match and could hang if a
+ *   message vanished between SEARCH and FETCH).
+ * - queryUids() returns matching UIDs newest first, using server-side SORT when
+ *   available and a UID sort otherwise.
+ *
+ * @license MIT
+ */
+
+import imaps from 'imap-simple';
+
+const DEFAULT_IDLE_CLOSE_MS = 5 * 60 * 1000;
+const DEFAULT_LEASE_TIMEOUT_MS = 5 * 60 * 1000;
+
+function withKeepalive(config) {
+  // NOOP-based keepalive is more predictable than IDLE behind proxies.
+  return {
+    ...config,
+    imap: {
+      keepalive: { interval: 60000, idleInterval: 300000, forceNoop: true },
+      ...config.imap
+    }
+  };
+}
+
+export class SessionManager {
+  constructor(config, { idleCloseMs = DEFAULT_IDLE_CLOSE_MS, leaseTimeoutMs = DEFAULT_LEASE_TIMEOUT_MS, label = 'tools', log = console.error } = {}) {
+    this.config = withKeepalive(config);
+    this.idleCloseMs = idleCloseMs;
+    this.leaseTimeoutMs = leaseTimeoutMs;
+    this.label = label;
+    this.log = log;
+    this.conn = null;
+    this.connecting = null;
+    this.tail = Promise.resolve();
+    this.idleTimer = null;
+  }
+
+  _isUsable(conn) {
+    return !!conn && conn.imap && conn.imap.state === 'authenticated';
+  }
+
+  _drop(conn, reason) {
+    if (!conn) return;
+    if (this.conn === conn) this.conn = null;
+    if (conn._mcpDropped) return;
+    conn._mcpDropped = true;
+    if (reason) this.log(`[imap:${this.label}] dropping connection: ${reason}`);
+    try {
+      // Call node-imap directly. imap-simple's end() sets a flag that makes
+      // its own error handler throw on errors without a code.
+      conn.imap.end();
+    } catch {
+      try { conn.imap.destroy(); } catch { /* ignore */ }
+    }
+  }
+
+  async _connect() {
+    if (this._isUsable(this.conn)) return this.conn;
+    if (!this.connecting) {
+      this.connecting = (async () => {
+        const conn = await imaps.connect(this.config);
+        // Without an 'error' listener an idle socket error would crash the process.
+        conn.on('error', (err) => this._drop(conn, `error: ${err && err.message}`));
+        conn.imap.once('close', () => { if (this.conn === conn) this.conn = null; });
+        conn.imap.once('end', () => { if (this.conn === conn) this.conn = null; });
+        this.conn = conn;
+        return conn;
+      })().finally(() => { this.connecting = null; });
+    }
+    return this.connecting;
+  }
+
+  _armIdleTimer() {
+    clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      if (this.conn) this._drop(this.conn, null);
+    }, this.idleCloseMs);
+    if (this.idleTimer.unref) this.idleTimer.unref();
+  }
+
+  /**
+   * Acquire the shared connection. Resolves to a proxy whose end() releases the
+   * lease. Every call site must call end() in a finally block.
+   */
+  acquire() {
+    let releaseLock;
+    const lock = new Promise((resolve) => { releaseLock = resolve; });
+    const previous = this.tail;
+    this.tail = previous.then(() => lock);
+
+    return previous.then(async () => {
+      clearTimeout(this.idleTimer);
+      let conn;
+      try {
+        conn = await this._connect();
+      } catch (err) {
+        releaseLock();
+        this._armIdleTimer();
+        throw err;
+      }
+
+      let released = false;
+      const release = () => {
+        if (released) return;
+        released = true;
+        clearTimeout(watchdog);
+        if (!this._isUsable(conn)) this._drop(conn, 'unusable after call');
+        this._armIdleTimer();
+        releaseLock();
+      };
+
+      // A hung command must not block every later tool call.
+      const watchdog = setTimeout(() => {
+        this._drop(conn, `lease exceeded ${Math.round(this.leaseTimeoutMs / 1000)}s`);
+        release();
+      }, this.leaseTimeoutMs);
+      if (watchdog.unref) watchdog.unref();
+
+      return new Proxy(conn, {
+        get(target, prop) {
+          if (prop === 'end') return release;
+          const value = target[prop];
+          return typeof value === 'function' ? value.bind(target) : value;
+        }
+      });
+    });
+  }
+
+  close() {
+    clearTimeout(this.idleTimer);
+    if (this.conn) this._drop(this.conn, null);
+  }
+}
+
+/** Open a mailbox. readOnly uses EXAMINE, which never changes flags. */
+export function openBox(connection, name, readOnly = false) {
+  return new Promise((resolve, reject) => {
+    try {
+      connection.imap.openBox(name, readOnly, (err, box) => (err ? reject(err) : resolve(box)));
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+export function serverSupports(connection, cap) {
+  try { return !!connection.imap.serverSupports(cap); } catch { return false; }
+}
+
+/**
+ * Return matching UIDs, newest first.
+ * order 'arrival' uses the server's internal date (delivery time, preserved on
+ * moves). order 'date' uses the Date header.
+ */
+export function queryUids(connection, criteria, { order = 'arrival' } = {}) {
+  const imap = connection.imap;
+  const crit = criteria && criteria.length ? criteria : ['ALL'];
+  const key = order === 'date' ? '-DATE' : '-ARRIVAL';
+  return new Promise((resolve, reject) => {
+    const done = (err, uids) => (err ? reject(err) : resolve((uids || []).map(Number)));
+    try {
+      if (serverSupports(connection, 'SORT')) {
+        imap.sort([key], crit, done);
+      } else {
+        imap.search(crit, (err, uids) => {
+          if (err) return reject(err);
+          resolve((uids || []).map(Number).sort((a, b) => b - a));
+        });
+      }
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+/**
+ * Fetch an explicit list of UIDs. Resolves to a Map uid -> { attributes, parts }
+ * where parts maps the body section name to a Buffer. Messages that no longer
+ * exist are simply absent from the result.
+ */
+export function fetchMessages(connection, uids, options) {
+  return new Promise((resolve, reject) => {
+    const out = new Map();
+    if (!uids || !uids.length) return resolve(out);
+    let f;
+    try {
+      f = connection.imap.fetch(uids, options);
+    } catch (err) {
+      return reject(err);
+    }
+    f.on('message', (msg) => {
+      const rec = { attributes: null, parts: {} };
+      msg.on('body', (stream, info) => {
+        const chunks = [];
+        stream.on('data', (c) => chunks.push(c));
+        stream.once('end', () => { rec.parts[info.which] = Buffer.concat(chunks); });
+      });
+      msg.once('attributes', (attrs) => { rec.attributes = attrs; });
+      msg.once('end', () => {
+        if (rec.attributes && rec.attributes.uid != null) out.set(Number(rec.attributes.uid), rec);
+      });
+    });
+    f.once('error', reject);
+    f.once('end', () => resolve(out));
+  });
+}
+
+/** Find the header buffer in a fetched record and parse it into { name: [values] }. */
+export function headerOf(rec, parseHeader) {
+  const key = Object.keys(rec.parts).find((k) => k.toUpperCase().includes('HEADER'));
+  if (!key) return {};
+  return parseHeader(rec.parts[key].toString('utf8'));
+}
+
+/**
+ * Parse YYYY-MM-DD as a local calendar date. new Date('2026-09-01') is UTC
+ * midnight, which node-imap would render as the previous day west of UTC.
+ */
+export function localDate(value) {
+  if (value instanceof Date) return value;
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value).trim());
+  if (m) return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) throw new Error(`Invalid date: ${value} (use YYYY-MM-DD)`);
+  return d;
+}
+
+/** Build node-imap search criteria from tool arguments shared by list and search tools. */
+export function buildCriteria(args = {}) {
+  const c = [];
+  if (args.subject) c.push(['SUBJECT', args.subject]);
+  if (args.from) c.push(['FROM', args.from]);
+  if (args.to) c.push(['TO', args.to]);
+  if (args.cc) c.push(['CC', args.cc]);
+  if (args.body) c.push(['BODY', args.body]);
+  if (args.text) c.push(['TEXT', args.text]);
+  if (args.since_date) c.push(['SINCE', localDate(args.since_date)]);
+  if (args.before_date) c.push(['BEFORE', localDate(args.before_date)]);
+  if (args.unseen_only) c.push('UNSEEN');
+  if (args.seen_only) c.push('SEEN');
+  if (args.flagged_only) c.push('FLAGGED');
+  if (args.unflagged_only) c.push('UNFLAGGED');
+  return c.length ? c : ['ALL'];
+}