feat(jmap): add @type Event, Stalwart Docker test server, session URL port rewriting

Author: SashankBhamidi

caldav/jmap/async_client.py

@@ -396,6 +396,7 @@ async def delete_event(self, event_id: str) -> None:
     async def _get_object_by_uid(
         self, uid: str, calendar_id: str | None = None, parent: JMAPCalendar | None = None
     ) -> JMAPCalendarObject:
+        # RFC 8984 FilterCondition has no uid field; UID matching is done client-side.
         for obj in await self._search(calendar_id=calendar_id, parent=parent):
             if obj.data.get("uid") == uid:
                 return obj

caldav/jmap/convert/ical_to_jscal.py

@@ -332,6 +332,7 @@ def ical_to_jscal(ical_str: str, calendar_id: str | None = None) -> dict:
         duration = "P0D"
 
     jscal: dict = {
+        "@type": "Event",
         "uid": uid,
         "title": title,
         "start": start,

caldav/jmap/session.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlparse, urlunparse
 
 try:
     import niquests as requests
@@ -57,6 +57,15 @@ def _parse_session_data(url: str, data: dict) -> Session:
     # return a relative path. Resolve it against the session endpoint URL.
     api_url = urljoin(url, api_url)
 
+    # Some servers (e.g. Stalwart behind a port-remapping proxy) advertise an
+    # api_url whose host matches ours but whose port reflects the internal
+    # listener rather than the port we actually connected through. Rewrite to
+    # match the session endpoint's authority so subsequent calls succeed.
+    session_parsed = urlparse(url)
+    api_parsed = urlparse(api_url)
+    if api_parsed.hostname == session_parsed.hostname and api_parsed.port != session_parsed.port:
+        api_url = urlunparse(api_parsed._replace(netloc=session_parsed.netloc))
+
     state = data.get("state", "")
     server_capabilities = data.get("capabilities", {})
     accounts = data.get("accounts", {})

tests/docker-test-servers/stalwart/docker-compose.yml

@@ -0,0 +1,20 @@
+version: '3.8'
+
+services:
+  stalwart:
+    image: stalwartlabs/stalwart:latest
+    container_name: stalwart-test
+    hostname: localhost
+    ports:
+      - "8806:8080"  # HTTP (JMAP + admin UI)
+      # Note: Stalwart advertises its internal port (8080) in JMAP session URLs.
+      # The client must rewrite api_url to use the host-side port (8806) when
+      # the session URL host matches the configured server hostname.
+    tmpfs:
+      - /opt/stalwart:size=200m
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:8080/"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s

tests/docker-test-servers/stalwart/setup_stalwart.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# Setup script for Stalwart JMAP test server.
+# Waits for the container to be ready, extracts the auto-generated admin
+# password, creates a test user via the Management REST API, and verifies
+# the JMAP endpoint is reachable.
+
+set -e
+
+BASE_URL="http://localhost:8806"
+
+echo "Waiting for Stalwart HTTP..."
+for i in $(seq 1 30); do
+    if curl -sf "${BASE_URL}/" >/dev/null 2>&1; then
+        echo "HTTP ready."
+        break
+    fi
+    [ "$i" -eq 30 ] && { echo "ERROR: Stalwart did not start in time"; exit 1; }
+    sleep 2
+done
+
+# Stalwart prints the auto-generated admin password on first run.
+# Example log line: "Your administrator account is 'admin' with password 'XYZ'."
+ADMIN_PASS=$(docker logs stalwart-test 2>&1 | grep -o "password '[^']*'" | head -1 | sed "s/password '//;s/'//")
+if [ -z "$ADMIN_PASS" ]; then
+    echo "ERROR: Could not extract admin password from container logs"
+    echo "Container logs:"
+    docker logs stalwart-test 2>&1 | tail -20
+    exit 1
+fi
+echo "Admin password extracted."
+
+# Create the test domain (required before creating users with that domain).
+HTTP_STATUS=$(curl -s -o /tmp/stalwart_domain.json -w "%{http_code}" \
+    -u "admin:${ADMIN_PASS}" \
+    -X POST "${BASE_URL}/api/principal" \
+    -H "Content-Type: application/json" \
+    -d '{"type":"domain","name":"localhost"}')
+
+if [ "$HTTP_STATUS" != "200" ]; then
+    echo "ERROR: Failed to create domain (HTTP ${HTTP_STATUS})"
+    cat /tmp/stalwart_domain.json 2>/dev/null || true
+    exit 1
+fi
+echo "Domain 'localhost' created."
+
+# Create test user via Stalwart Management REST API (POST /api/principal).
+# The "user" role grants standard JMAP access permissions.
+HTTP_STATUS=$(curl -s -o /tmp/stalwart_create.json -w "%{http_code}" \
+    -u "admin:${ADMIN_PASS}" \
+    -X POST "${BASE_URL}/api/principal" \
+    -H "Content-Type: application/json" \
+    -d '{"type":"individual","name":"user1","secrets":["x"],"emails":["user1@localhost"],"roles":["user"]}')
+
+if [ "$HTTP_STATUS" != "200" ]; then
+    echo "ERROR: Failed to create test user (HTTP ${HTTP_STATUS})"
+    cat /tmp/stalwart_create.json 2>/dev/null || true
+    exit 1
+fi
+echo "Test user created: user1 / x"
+
+# Verify JMAP endpoint is reachable with test credentials.
+echo "Verifying JMAP endpoint..."
+for i in $(seq 1 15); do
+    if curl -sf -u "user1:x" "${BASE_URL}/.well-known/jmap" >/dev/null 2>&1; then
+        echo "JMAP ready."
+        break
+    fi
+    [ "$i" -eq 15 ] && { echo "ERROR: JMAP endpoint not reachable after user creation"; exit 1; }
+    sleep 2
+done
+
+echo ""
+echo "Stalwart setup complete."
+echo "  JMAP URL:  ${BASE_URL}/.well-known/jmap"
+echo "  Username:  user1"
+echo "  Password:  x"

tests/docker-test-servers/stalwart/start.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Quick start script for Stalwart JMAP test server.
+#
+# Usage: ./start.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "Cleaning up previous Stalwart instance..."
+docker-compose down 2>/dev/null || true
+
+echo "Starting Stalwart Mail Server..."
+docker-compose up -d
+
+echo ""
+echo "Waiting for Stalwart to initialize..."
+./setup_stalwart.sh
+
+echo ""
+echo "To stop Stalwart: ./stop.sh"
+echo "To view logs: docker-compose logs -f stalwart"

tests/docker-test-servers/stalwart/stop.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Stop script for Stalwart JMAP test server.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "Stopping Stalwart and removing volumes..."
+docker-compose down -v
+
+echo "Stalwart stopped."

tests/test_jmap_integration.py

@@ -1,17 +1,18 @@
 """
-Integration tests for the caldav.jmap package against a live Cyrus IMAP server.
-
-These tests require the Cyrus Docker container to be running:
+Integration tests for the caldav.jmap package against live JMAP servers.
 
+Cyrus (port 8802):
     docker-compose -f tests/docker-test-servers/cyrus/docker-compose.yml up -d
 
-If the server is not reachable on port 8802 the entire module is skipped
-automatically — no failure, no noise.
+Stalwart (port 8806):
+    docker-compose -f tests/docker-test-servers/stalwart/docker-compose.yml up -d
+    ./tests/docker-test-servers/stalwart/setup_stalwart.sh
 
-Cyrus JMAP endpoint: http://localhost:8802/.well-known/jmap
-Test credentials:    user1 / x
+Each server's test classes are skipped automatically when that server is not
+reachable — no failure, no noise.
 """
 
+import socket
 import uuid
 from datetime import datetime, timedelta, timezone
 
@@ -31,23 +32,32 @@
 
 CYRUS_HOST = "localhost"
 CYRUS_PORT = 8802
-JMAP_URL = f"http://{CYRUS_HOST}:{CYRUS_PORT}/.well-known/jmap"
+CYRUS_JMAP_URL = f"http://{CYRUS_HOST}:{CYRUS_PORT}/.well-known/jmap"
 CYRUS_USERNAME = "user1"
 CYRUS_PASSWORD = "x"
 
+STALWART_HOST = "localhost"
+STALWART_PORT = 8806
+STALWART_JMAP_URL = f"http://{STALWART_HOST}:{STALWART_PORT}/.well-known/jmap"
+STALWART_USERNAME = "user1"
+STALWART_PASSWORD = "x"
 
-def _cyrus_reachable() -> bool:
-    import socket
 
+def _reachable(host: str, port: int) -> bool:
     try:
-        with socket.create_connection((CYRUS_HOST, CYRUS_PORT), timeout=2):
+        with socket.create_connection((host, port), timeout=2):
             return True
     except OSError:
         return False
 
 
+_cyrus_up = _reachable(CYRUS_HOST, CYRUS_PORT)
+_stalwart_up = _reachable(STALWART_HOST, STALWART_PORT)
+
+# Backward-compatible alias used by the module-level pytestmark below.
+# The mark only gates tests that don't carry their own skipif marker.
 pytestmark = pytest.mark.skipif(
-    not _cyrus_reachable(),
+    not _cyrus_up,
     reason=f"Cyrus Docker not reachable on {CYRUS_HOST}:{CYRUS_PORT} — "
     "start it with: docker-compose -f tests/docker-test-servers/cyrus/docker-compose.yml up -d",
 )
@@ -74,12 +84,12 @@ def _minimal_ical(title: str = "Test Event", start: datetime | None = None) -> s
 
 @pytest.fixture(scope="module")
 def client():
-    return JMAPClient(url=JMAP_URL, username=CYRUS_USERNAME, password=CYRUS_PASSWORD)
+    return JMAPClient(url=CYRUS_JMAP_URL, username=CYRUS_USERNAME, password=CYRUS_PASSWORD)
 
 
 @pytest.fixture(scope="module")
 def session():
-    return fetch_session(JMAP_URL, auth=HTTPBasicAuth(CYRUS_USERNAME, CYRUS_PASSWORD))
+    return fetch_session(CYRUS_JMAP_URL, auth=HTTPBasicAuth(CYRUS_USERNAME, CYRUS_PASSWORD))
 
 
 @pytest.fixture(scope="module")
@@ -101,7 +111,7 @@ def created_event_id(client, calendar_id):
 
 @pytest_asyncio.fixture
 async def async_client():
-    return AsyncJMAPClient(url=JMAP_URL, username=CYRUS_USERNAME, password=CYRUS_PASSWORD)
+    return AsyncJMAPClient(url=CYRUS_JMAP_URL, username=CYRUS_USERNAME, password=CYRUS_PASSWORD)
 
 
 @pytest_asyncio.fixture
@@ -123,6 +133,37 @@ async def async_created_event_id(async_client, async_calendar_id):
         pass
 
 
+_stalwart_skip = pytest.mark.skipif(
+    not _stalwart_up,
+    reason=f"Stalwart Docker not reachable on {STALWART_HOST}:{STALWART_PORT} — "
+    "start it with: cd tests/docker-test-servers/stalwart && ./start.sh",
+)
+
+
+@pytest.fixture(scope="module")
+def stalwart_client():
+    return JMAPClient(url=STALWART_JMAP_URL, username=STALWART_USERNAME, password=STALWART_PASSWORD)
+
+
+@pytest.fixture(scope="module")
+def stalwart_calendar_id(stalwart_client):
+    calendars = stalwart_client.get_calendars()
+    assert calendars, "Stalwart did not return any calendars for user1"
+    return calendars[0].id
+
+
+@pytest.fixture
+def stalwart_event_id(stalwart_client, stalwart_calendar_id):
+    event_id = stalwart_client.create_event(
+        stalwart_calendar_id, _minimal_ical("Stalwart Test Event")
+    )
+    yield event_id
+    try:
+        stalwart_client.delete_event(event_id)
+    except Exception:
+        pass
+
+
 class TestJMAPSessionIntegration:
     def test_session_fetch_returns_api_url(self, session):
         assert session.api_url
@@ -256,3 +297,60 @@ async def test_ical_roundtrip(self, async_client, async_calendar_id):
             assert "20260715" in fetched
         finally:
             await async_client.delete_event(event_id)
+
+
+@_stalwart_skip
+class TestStalwartJMAPCalendarListIntegration:
+    def test_list_calendars_returns_list(self, stalwart_client):
+        calendars = stalwart_client.get_calendars()
+        assert isinstance(calendars, list)
+
+    def test_calendars_have_id_and_name(self, stalwart_client):
+        calendars = stalwart_client.get_calendars()
+        assert len(calendars) >= 1, "Expected at least one calendar on Stalwart for user1"
+        for cal in calendars:
+            assert cal.id, f"Calendar missing id: {cal}"
+            assert cal.name, f"Calendar has empty name: {cal}"
+
+
+@_stalwart_skip
+class TestStalwartJMAPEventIntegration:
+    def test_event_create_get(self, stalwart_client, stalwart_event_id):
+        obj = stalwart_client.get_event(stalwart_event_id)
+        ical = jscal_to_ical(obj.get_data())
+        assert "BEGIN:VCALENDAR" in ical
+        assert "Stalwart Test Event" in ical
+
+    def test_event_update(self, stalwart_client, stalwart_event_id):
+        stalwart_client.update_event(stalwart_event_id, _minimal_ical("Stalwart Updated Title"))
+        obj = stalwart_client.get_event(stalwart_event_id)
+        assert "Stalwart Updated Title" in jscal_to_ical(obj.get_data())
+
+    def test_event_delete(self, stalwart_client, stalwart_calendar_id):
+        event_id = stalwart_client.create_event(
+            stalwart_calendar_id, _minimal_ical("Stalwart To Be Deleted")
+        )
+        stalwart_client.delete_event(event_id)
+        with pytest.raises(JMAPMethodError):
+            stalwart_client.get_event(event_id)
+
+    def test_event_query_time_range(self, stalwart_client, stalwart_event_id):
+        # Stalwart does not support the inCalendars filter; query without calendar_id.
+        results = stalwart_client.search_events(
+            start="2026-06-01T00:00:00",
+            end="2026-06-02T00:00:00",
+        )
+        assert len(results) >= 1
+        assert any("Stalwart Test Event" in jscal_to_ical(r.get_data()) for r in results)
+
+    def test_ical_roundtrip(self, stalwart_client, stalwart_calendar_id):
+        start = datetime(2026, 7, 15, 9, 0, 0, tzinfo=timezone.utc)
+        event_id = stalwart_client.create_event(
+            stalwart_calendar_id, _minimal_ical("Stalwart Roundtrip Event", start=start)
+        )
+        try:
+            fetched = jscal_to_ical(stalwart_client.get_event(event_id).get_data())
+            assert "Stalwart Roundtrip Event" in fetched
+            assert "20260715" in fetched
+        finally:
+            stalwart_client.delete_event(event_id)

tests/test_jmap_unit.py

@@ -984,6 +984,7 @@ class TestIcalToJscal:
     def test_minimal_event(self):
         ical = _make_ical("DTSTART:20240615T100000Z\r\nDURATION:PT1H\r\nSUMMARY:Test Event\r\n")
         result = ical_to_jscal(ical)
+        assert result["@type"] == "Event"
         assert result["uid"] == "test-uid@example.com"
         assert result["title"] == "Test Event"
         assert result["start"] == "2024-06-15T10:00:00"