this repo has no description
more
+153
-22
+153
-22
jmap/TODO.md
+153
-22
jmap/TODO.md
···
108
108
109
109
---
110
110
111
-
## **📋 Remaining Work**
111
+
## **🚨 CRITICAL ARCHITECTURAL ISSUES IDENTIFIED (January 2025)**
112
+
113
+
### **Issue 1: Eio Dependency Leakage in jmap-email** 🔴
114
+
115
+
**Problem**: The `jmap-email` library incorrectly depends on `Eio_unix.Stdenv.base` in several modules, violating the layered architecture.
116
+
117
+
**Files Affected**:
118
+
- `jmap-email/jmap_email_methods.mli` - 5+ functions taking `env:Eio_unix.Stdenv.base`
119
+
- `jmap-email/jmap_email_query.mli` - 2 functions with Eio parameters
120
+
- `jmap-email/jmap_email_batch.mli` - 5+ functions with Eio parameters
121
+
122
+
**Impact**:
123
+
- ❌ Makes `jmap-email` non-portable (should be platform-agnostic)
124
+
- ❌ Creates circular dependency risk between `jmap-email` and `jmap-unix`
125
+
- ❌ Violates clean architecture principles
126
+
127
+
**Solution**: Move all Eio-dependent functions to `jmap-unix`, keeping `jmap-email` pure.
128
+
129
+
### **Issue 2: Property Type Duplication** 🔴
130
+
131
+
**Problem**: Email properties are defined in TWO incompatible formats:
132
+
133
+
1. **Regular Variants** in `jmap_email_property.mli`:
134
+
```ocaml
135
+
type t = ReceivedAt | MessageId | Size | ...
136
+
```
137
+
138
+
2. **Polymorphic Variants** in `jmap_email_query.mli`:
139
+
```ocaml
140
+
type property = [`ReceivedAt | `MessageId | `Size | ...]
141
+
```
142
+
143
+
**Impact**:
144
+
- ❌ Code duplication and maintenance burden
145
+
- ❌ Type incompatibility between modules
146
+
- ❌ API confusion for developers
147
+
- ❌ Potential for divergence over time
148
+
149
+
**Solution**: Unify on a single property representation with conversion functions.
150
+
151
+
### **Issue 3: Inconsistent Module Architecture** 🟡
152
+
153
+
**Problem**: Mixed architectural patterns across the codebase:
154
+
- Some modules use abstract `type t` correctly
155
+
- Others expose implementation details
156
+
- Inconsistent use of JSONABLE signatures
157
+
- Method integration varies by module
158
+
159
+
**Solution**: Standardize on canonical `type t` pattern throughout.
160
+
161
+
---
162
+
163
+
## **📋 UPDATED ARCHITECTURAL PLAN**
164
+
165
+
### **PHASE 1: Fix Critical Architecture Issues (URGENT)**
166
+
167
+
#### 1A. **Resolve Eio Dependency Leakage** 🔴
168
+
- [ ] **Move Eio functions** from `jmap-email/jmap_email_methods.mli` to `jmap-unix/jmap_unix.mli`
169
+
- [ ] **Move Eio functions** from `jmap-email/jmap_email_query.mli` to `jmap-unix/jmap_unix.mli`
170
+
- [ ] **Move Eio functions** from `jmap-email/jmap_email_batch.mli` to `jmap-unix/jmap_unix.mli`
171
+
- [ ] **Remove all Eio imports** from `jmap-email/` modules
172
+
- [ ] **Update `jmap-email/dune`** to remove any Eio-related dependencies
173
+
- [ ] **Test clean separation**: Verify `jmap-email` builds without Eio dependencies
174
+
175
+
#### 1B. **Unify Property Type Systems** 🔴
176
+
- [ ] **Choose canonical format**: Decide between regular variants vs polymorphic variants
177
+
- [ ] **Consolidate definitions**: Remove duplicate property definitions
178
+
- [ ] **Update all references**: Fix modules using the deprecated format
179
+
- [ ] **Add conversion functions**: If needed for backward compatibility
180
+
- [ ] **Test full integration**: Ensure property selection works end-to-end
181
+
182
+
### **PHASE 2: Strengthen Module Architecture** 🟡
183
+
184
+
#### 2A. **Standardize Type Patterns**
185
+
- [ ] **Audit all modules** for consistent `type t` usage
186
+
- [ ] **Fix abstract type leaks** where implementation is exposed
187
+
- [ ] **Standardize JSONABLE usage** across all wire types
188
+
- [ ] **Ensure consistent error handling** with `Jmap_error.error`
189
+
190
+
#### 2B. **Complete Method Integration**
191
+
- [ ] **Move method implementations** from `jmap-email` to `jmap-unix` where needed
192
+
- [ ] **Create high-level client interface** in `jmap-unix` that combines all functionality
193
+
- [ ] **Implement connection management** using Eio's structured concurrency
194
+
- [ ] **Add proper authentication handling** (OAuth2, bearer tokens)
195
+
196
+
### **PHASE 3: Example Applications & Usage** ✨
197
+
198
+
#### 3A. **Update Example Applications**
199
+
- [ ] **Fix Eio dependency usage** in `bin/fastmail_connect.ml`
200
+
- [ ] **Remove manual JSON parsing** and use proper `of_json` functions
201
+
- [ ] **Demonstrate unified property system** in examples
202
+
- [ ] **Show best practices** for each architectural layer
112
203
113
-
### Priority 1: **Update Example Applications** ✨
204
+
#### 3B. **Create High-Level API**
205
+
- [ ] **Design client interface** that hides architectural complexity
206
+
- [ ] **Implement common operations** (list emails, send email, manage folders)
207
+
- [ ] **Add helper functions** for typical use cases
208
+
- [ ] **Document usage patterns** with comprehensive examples
114
209
115
-
The core library restructuring is complete, but the example applications need updates:
210
+
### **PHASE 4: Testing & Documentation** 📚
116
211
117
-
- [ ] **Update `bin/` examples** to use new module structure (`Jmap.Id.t`, `Jmap_email_address.t`, etc.)
118
-
- [ ] **Fix import statements** in example binaries to reference correct modules
119
-
- [ ] **Replace manual JSON parsing** with proper `of_json` function calls
120
-
- [ ] **Use new JSONABLE interfaces** throughout examples to demonstrate library capabilities
212
+
#### 4A. **Comprehensive Testing**
213
+
- [ ] **Unit tests** for all modules with proper `type t` encapsulation
214
+
- [ ] **Integration tests** across architectural layers
215
+
- [ ] **Real server testing** against JMAP providers
216
+
- [ ] **Performance benchmarks** comparing old vs new approaches
121
217
122
-
### Priority 2: **Complete Method Integration**
218
+
#### 4B. **Documentation & Migration**
219
+
- [ ] **Update architectural documentation** explaining the layered design
220
+
- [ ] **Create migration guide** for users of previous versions
221
+
- [ ] **Document best practices** for each use case
222
+
- [ ] **Create comprehensive API reference** with examples
223
+
224
+
---
225
+
226
+
## **🏗️ RECOMMENDED ARCHITECTURE DESIGN**
123
227
124
-
While individual modules have method support, end-to-end integration needs work:
228
+
### **Clean Layered Architecture**
229
+
230
+
```
231
+
┌─────────────────────────────────────┐
232
+
│ User Applications │ <- Examples, user code
233
+
├─────────────────────────────────────┤
234
+
│ jmap-unix │ <- Eio, TLS, HTTP, networking
235
+
│ (Platform-specific) │ Connection management
236
+
├─────────────────────────────────────┤
237
+
│ jmap-email │ <- Email objects, methods
238
+
│ (Email Extensions) │ Pure OCaml, no I/O
239
+
├─────────────────────────────────────┤
240
+
│ jmap │ <- Core protocol, types
241
+
│ (Core Protocol) │ Pure OCaml, portable
242
+
├─────────────────────────────────────┤
243
+
│ jmap-sigs │ <- Shared interfaces
244
+
│ (Module Signatures) │ Type signatures only
245
+
└─────────────────────────────────────┘
246
+
```
125
247
126
-
- [ ] **Update `jmap_method.ml`** to create proper method objects using new modules
127
-
- [ ] **Connect method responses** to use new JSONABLE parsers
128
-
- [ ] **Test full request/response cycle** with real JMAP servers
248
+
### **Dependency Rules**
249
+
1. **jmap-sigs**: No dependencies (signatures only)
250
+
2. **jmap**: Only depends on jmap-sigs + standard library
251
+
3. **jmap-email**: Depends on jmap + jmap-sigs (NO Eio/networking)
252
+
4. **jmap-unix**: Depends on all above + Eio/TLS/HTTP libraries
253
+
5. **Applications**: Use jmap-unix for I/O, can import others for types
129
254
130
-
### Priority 3: **Enhanced JSONABLE Implementations**
255
+
### **Type System Design**
256
+
- **Unified Properties**: Single property type system across all modules
257
+
- **Abstract Types**: Consistent `type t` with smart constructors
258
+
- **JSONABLE**: Complete serialization for all wire types
259
+
- **Error Handling**: Structured errors using `Jmap_error.error` throughout
131
260
132
-
Current implementations are functional but could be enhanced:
261
+
---
133
262
134
-
- [ ] **Property Selection**: Complete `to_json_with_properties` implementations
135
-
- [ ] **Validation**: Add comprehensive input validation to `of_json` functions
136
-
- [ ] **Performance**: Optimize JSON parsing/generation for large objects
263
+
## **⚡ IMMEDIATE ACTION ITEMS**
137
264
138
-
### Priority 4: **Testing & Validation**
265
+
1. **🔥 Priority 1**: Fix Eio dependency leakage (breaks clean architecture)
266
+
2. **🔥 Priority 2**: Unify property type systems (eliminates confusion)
267
+
3. **🔧 Priority 3**: Update examples to use corrected architecture
268
+
4. **📋 Priority 4**: Complete method integration with proper layer separation
139
269
140
-
- [ ] **Comprehensive Testing**: Create test suite for all new modules with ppx_expect
141
-
- [ ] **Round-trip Testing**: Verify JSON serialization/deserialization is lossless
142
-
- [ ] **Real Server Testing**: Validate against live JMAP servers (Fastmail, Cyrus, etc.)
143
-
- [ ] **Performance Benchmarking**: Measure JSON parsing performance vs manual approaches
270
+
**Success Criteria**:
271
+
- `jmap-email` builds without any Eio dependencies
272
+
- Single property type system used consistently
273
+
- Examples demonstrate clean layered usage
274
+
- All layers respect dependency boundaries
144
275
145
276
---
146
277