|
| 1 | +# Architecture Refactoring Summary |
| 2 | + |
| 3 | +## What We've Done |
| 4 | + |
| 5 | +### 1. Created New Server-Only Binary |
| 6 | + |
| 7 | +**File:** `cmd/go-trust/main.go` |
| 8 | + |
| 9 | +A clean AuthZEN PDP server that: |
| 10 | +- ✅ No pipeline processing |
| 11 | +- ✅ No background updates |
| 12 | +- ✅ Loads TSLs from pre-processed files (PEM bundles or XML) |
| 13 | +- ✅ Supports multiple registries (ETSI, OpenID Federation, DID Web) |
| 14 | +- ✅ Configurable via command-line flags |
| 15 | +- ✅ Production-ready logging |
| 16 | + |
| 17 | +**Binary name:** `go-trust` (unchanged from v1) |
| 18 | + |
| 19 | +### 2. Updated Build System |
| 20 | + |
| 21 | +**File:** `Makefile` |
| 22 | + |
| 23 | +Changes: |
| 24 | +- Build from `cmd/go-trust/main.go` instead of `main.go` |
| 25 | +- Output binary named `go-trust` (was `gt`) |
| 26 | +- Updated swagger generation path |
| 27 | +- Updated all build targets |
| 28 | + |
| 29 | +### 3. Created Migration Documentation |
| 30 | + |
| 31 | +**Files:** |
| 32 | +- `MIGRATION-TO-V2.md` - User-facing migration guide |
| 33 | +- `MOVING-TO-G119612.md` - Developer guide for moving code |
| 34 | + |
| 35 | +## Architecture Overview |
| 36 | + |
| 37 | +### Before (v1) |
| 38 | +``` |
| 39 | +┌────────────────────────────────────┐ |
| 40 | +│ go-trust (monolith) │ |
| 41 | +├────────────────────────────────────┤ |
| 42 | +│ • Pipeline processing (background) │ |
| 43 | +│ • XSLT transformations │ |
| 44 | +│ • XML signing (PKCS#11) │ |
| 45 | +│ • TSL publishing │ |
| 46 | +│ • AuthZEN server │ |
| 47 | +│ • Multi-registry support │ |
| 48 | +└────────────────────────────────────┘ |
| 49 | +``` |
| 50 | + |
| 51 | +### After (v2) |
| 52 | +``` |
| 53 | +┌──────────────────────┐ ┌─────────────────────┐ |
| 54 | +│ tsl-tool (g119612) │ │ go-trust (server) │ |
| 55 | +├──────────────────────┤ ├─────────────────────┤ |
| 56 | +│ • Load TSLs │───▶│ • AuthZEN API │ |
| 57 | +│ • Transform (XSLT) │ │ • ETSI registry │ |
| 58 | +│ • Publish XML │ │ • OpenID Fed reg │ |
| 59 | +│ • Sign (PKCS#11) │ │ • DID Web reg │ |
| 60 | +│ │ │ • Future registries │ |
| 61 | +│ Runs from cron │ │ Runs as service │ |
| 62 | +└──────────────────────┘ └─────────────────────┘ |
| 63 | +``` |
| 64 | + |
| 65 | +## Command Line Changes |
| 66 | + |
| 67 | +### Old (v1) |
| 68 | +```bash |
| 69 | +# Server with background pipeline |
| 70 | +go-trust --frequency 6h pipeline.yaml |
| 71 | +``` |
| 72 | + |
| 73 | +### New (v2) |
| 74 | +```bash |
| 75 | +# Separate concerns |
| 76 | + |
| 77 | +# 1. Pipeline processing (cron) |
| 78 | +tsl-tool pipeline.yaml # From g119612 |
| 79 | + |
| 80 | +# 2. Server (systemd) |
| 81 | +go-trust \ |
| 82 | + --etsi-cert-bundle /var/lib/go-trust/eu-certs.pem \ |
| 83 | + --host 0.0.0.0 \ |
| 84 | + --port 6001 |
| 85 | +``` |
| 86 | + |
| 87 | +## Key Benefits |
| 88 | + |
| 89 | +1. **Clean Separation** |
| 90 | + - Batch processing vs. online service |
| 91 | + - Each tool has a single, focused purpose |
| 92 | + |
| 93 | +2. **Better Deployment** |
| 94 | + - Pipeline: cron/systemd timer (periodic) |
| 95 | + - Server: systemd service (continuous) |
| 96 | + |
| 97 | +3. **Lighter Server** |
| 98 | + - No XSLT dependencies |
| 99 | + - No XML signing libraries |
| 100 | + - No pipeline overhead |
| 101 | + |
| 102 | +4. **Clearer Ownership** |
| 103 | + - g119612: "Complete ETSI TSL solution" |
| 104 | + - go-trust: "Multi-framework trust PDP" |
| 105 | + |
| 106 | +## Next Steps |
| 107 | + |
| 108 | +### For go-trust Repository |
| 109 | + |
| 110 | +1. ✅ Created `cmd/go-trust/main.go` - Server binary |
| 111 | +2. ✅ Updated `Makefile` - Build configuration |
| 112 | +3. ✅ Created migration guides - Documentation |
| 113 | +4. ⏳ Regenerate swagger docs |
| 114 | +5. ⏳ Test server startup |
| 115 | +6. ⏳ Update README.md - Remove pipeline documentation |
| 116 | +7. ⏳ Delete old `main.go` |
| 117 | +8. ⏳ Tag v2.0.0 release |
| 118 | + |
| 119 | +### For g119612 Repository |
| 120 | + |
| 121 | +1. ⏳ Move `pkg/pipeline/` from go-trust |
| 122 | +2. ⏳ Move `pkg/dsig/` from go-trust |
| 123 | +3. ⏳ Move `xslt/` from go-trust |
| 124 | +4. ⏳ Create `cmd/tsl-tool/main.go` |
| 125 | +5. ⏳ Update `go.mod` dependencies |
| 126 | +6. ⏳ Update `Makefile` with build targets |
| 127 | +7. ⏳ Update README.md - Add CLI tool docs |
| 128 | +8. ⏳ Tag release |
| 129 | + |
| 130 | +### Testing |
| 131 | + |
| 132 | +1. ⏳ Build and test tsl-tool |
| 133 | +2. ⏳ Run pipeline from cron |
| 134 | +3. ⏳ Build and test go-trust server |
| 135 | +4. ⏳ Verify server loads pre-processed files |
| 136 | +5. ⏳ Test AuthZEN API endpoints |
| 137 | +6. ⏳ Integration tests |
| 138 | + |
| 139 | +### User Communication |
| 140 | + |
| 141 | +1. ⏳ Announce v2 breaking changes |
| 142 | +2. ⏳ Provide migration examples |
| 143 | +3. ⏳ Update documentation links |
| 144 | +4. ⏳ Offer migration support |
| 145 | + |
| 146 | +## Files Created/Modified |
| 147 | + |
| 148 | +### New Files |
| 149 | +- ✅ `cmd/go-trust/main.go` - Server binary |
| 150 | +- ✅ `MIGRATION-TO-V2.md` - User migration guide |
| 151 | +- ✅ `MOVING-TO-G119612.md` - Developer guide |
| 152 | +- ✅ `ARCHITECTURE-REFACTORING.md` - This file |
| 153 | + |
| 154 | +### Modified Files |
| 155 | +- ✅ `Makefile` - Build targets updated |
| 156 | + |
| 157 | +### To Be Deleted (after migration) |
| 158 | +- ⏳ `main.go` - Replaced by cmd/go-trust/main.go |
| 159 | +- ⏳ `pkg/pipeline/` - Moving to g119612 |
| 160 | +- ⏳ `pkg/dsig/` - Moving to g119612 |
| 161 | +- ⏳ `xslt/` - Moving to g119612 |
| 162 | +- ⏳ `pkg/registry/etsi/pipeline_backed.go` - No longer needed |
| 163 | + |
| 164 | +## Example Deployment |
| 165 | + |
| 166 | +### Production Setup |
| 167 | + |
| 168 | +**1. Install both tools:** |
| 169 | +```bash |
| 170 | +# Install from g119612 |
| 171 | +go install github.com/sirosfoundation/g119612/cmd/tsl-tool@latest |
| 172 | + |
| 173 | +# Install from go-trust |
| 174 | +go install github.com/sirosfoundation/go-trust/cmd/go-trust@latest |
| 175 | +``` |
| 176 | + |
| 177 | +**2. Configure TSL pipeline:** |
| 178 | +```yaml |
| 179 | +# /etc/tsl/fetch-eu-lotl.yaml |
| 180 | +- load: https://ec.europa.eu/tools/lotl/eu-lotl.xml |
| 181 | +- select: [include-referenced] |
| 182 | +- publish: [/var/lib/go-trust/eu-certs.pem] |
| 183 | +``` |
| 184 | +
|
| 185 | +**3. Set up cron:** |
| 186 | +```bash |
| 187 | +# /etc/cron.d/update-tsls |
| 188 | +0 */6 * * * root /usr/local/bin/tsl-tool /etc/tsl/fetch-eu-lotl.yaml && systemctl reload go-trust |
| 189 | +``` |
| 190 | + |
| 191 | +**4. Configure systemd:** |
| 192 | +```ini |
| 193 | +# /etc/systemd/system/go-trust.service |
| 194 | +[Unit] |
| 195 | +Description=Go-Trust AuthZEN PDP |
| 196 | +After=network.target |
| 197 | + |
| 198 | +[Service] |
| 199 | +Type=simple |
| 200 | +ExecStart=/usr/local/bin/go-trust \ |
| 201 | + --host 0.0.0.0 \ |
| 202 | + --port 6001 \ |
| 203 | + --etsi-cert-bundle /var/lib/go-trust/eu-certs.pem \ |
| 204 | + --external-url https://pdp.example.com |
| 205 | +Restart=always |
| 206 | +ExecReload=/bin/kill -HUP $MAINPID |
| 207 | + |
| 208 | +[Install] |
| 209 | +WantedBy=multi-user.target |
| 210 | +``` |
| 211 | + |
| 212 | +**5. Start services:** |
| 213 | +```bash |
| 214 | +# Initial TSL fetch |
| 215 | +tsl-tool /etc/tsl/fetch-eu-lotl.yaml |
| 216 | + |
| 217 | +# Start server |
| 218 | +systemctl enable --now go-trust |
| 219 | +``` |
| 220 | + |
| 221 | +## Breaking Changes Summary |
| 222 | + |
| 223 | +| Aspect | v1 | v2 | |
| 224 | +|--------|----|----| |
| 225 | +| Binary | `go-trust` | `go-trust` (server only) | |
| 226 | +| Pipeline | Background in server | `tsl-tool` (separate) | |
| 227 | +| TSL Updates | `--frequency` flag | Cron job | |
| 228 | +| Input | pipeline.yaml | Pre-processed files | |
| 229 | +| Dependencies | Many (XSLT, signing, etc.) | Minimal (API only) | |
| 230 | +| Deployment | Single service | Server + cron job | |
| 231 | + |
| 232 | +## Success Criteria |
| 233 | + |
| 234 | +- ✅ go-trust binary builds successfully |
| 235 | +- ⏳ go-trust starts without pipeline config |
| 236 | +- ⏳ go-trust loads TSLs from PEM/XML files |
| 237 | +- ⏳ AuthZEN API endpoints work |
| 238 | +- ⏳ tsl-tool processes pipelines correctly |
| 239 | +- ⏳ Integration works (cron → tsl-tool → files → go-trust) |
| 240 | +- ⏳ Documentation is clear and complete |
| 241 | +- ⏳ Migration path is tested |
| 242 | + |
| 243 | +## Notes |
| 244 | + |
| 245 | +- No backwards compatibility needed (small user base) |
| 246 | +- Direct communication with users for migration |
| 247 | +- Clean break, no deprecation period |
| 248 | +- Focus on clarity over gradual transition |
0 commit comments