this repo has no description
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

more

+153 -22
+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