Integration Flows¶
Các trải nghiệm của Code To UML cùng dùng một rendering service, nhưng cách gửi source phụ thuộc nơi hiển thị kết quả. Interactive preview và export dùng POST có xác thực; sơ đồ được nhúng trong document preview dùng encoded GET công khai.
1. Hai luồng render chính¶
| Luồng | Dùng khi nào | Source được gửi ở đâu | Xác thực |
|---|---|---|---|
| POST có xác thực | Preview, export hoặc tích hợp backend | Request body | Bearer token trong Authorization header |
| Encoded GET công khai | Hiển thị sơ đồ bằng image URL | Source đã nén và encode trong URL | Không dùng token |
Gateway áp dụng rate limit và cache cho cả hai luồng. Khác biệt quan trọng nằm ở cách bảo vệ source: POST giữ source trong request body, còn encoded GET để source xuất hiện trong URL dưới dạng có thể giải mã.
2. Preview và export¶
Playground, VS Code Live Preview/export và GitLab MR browser extension gọi
POST /{engine}/{format}. Confluence Forge resolver cũng dùng endpoint này,
nhưng gửi request từ backend thay vì từ trình duyệt của người đọc.
Trong GitLab MR browser extension, POST chỉ dùng cho diagram preview. Preview toàn bộ Markdown dùng nội dung Before/After do GitLab trả về theo phiên đăng nhập hiện tại và không gọi Gateway để render Markdown.
Nếu cache hit, Gateway trả kết quả ngay và không đi tiếp tới Java core. Token chỉ được giữ trong vùng tin cậy của từng tích hợp:
| Tích hợp | Nơi giữ token |
|---|---|
| Playground | sessionStorage của tab trình duyệt |
| VS Code extension | VS Code SecretStorage |
| GitLab MR browser extension | Ngữ cảnh tin cậy của extension trong chrome.storage.local |
| Confluence | Forge encrypted variable ở backend |
Confluence Custom UI không nhận token hoặc gọi Gateway trực tiếp. Khi hiển thị macro, Forge resolver đọc source từ macro context; khi preview trong editor, resolver nhận source qua Forge invocation. Resolver gọi Gateway và chuyển SVG về Custom UI qua cùng kênh invocation.
3. Sơ đồ được nhúng trong tài liệu¶
GitLab Markdown, VS Code Markdown Preview và website MkDocs cần một image URL mà
trình duyệt có thể tải không kèm Authorization header. Source được nén, encode
vào path và gọi bằng GET /{engine}/{format}/{encodedSource}.
Encoded không phải mã hóa bảo mật. Người có URL có thể khôi phục source; không dùng luồng này cho sơ đồ chứa dữ liệu nhạy cảm.
4. Cách từng loại tích hợp chuẩn bị request¶
| Tích hợp | Bước chuẩn bị | Luồng render |
|---|---|---|
| Playground | Ghép lựa chọn trên giao diện với source đang soạn | POST có xác thực |
| VS Code Live Preview/export | Đọc file hoặc fence và lấy token từ SecretStorage | POST có xác thực |
| VS Code Markdown Preview | Tạo image URL từ fenced diagram | Encoded GET công khai |
| GitLab document preview | Tạo image URL; self-managed GitLab có thể chuyển fence params trong Markdown pipeline | Encoded GET công khai |
| GitLab MR browser extension | Đọc Before/After từ GitLab; dùng GitLab preview cho Markdown và gửi diagram source khi người đánh giá mở panel | POST có xác thực cho diagram |
| Confluence | Macro editor hoặc page event chuẩn bị source; Forge resolver gửi source khi preview hoặc hiển thị macro | POST có xác thực |
Trong GitLab document integration, bước xử lý fence params chạy trên self-managed GitLab trước Markdown rendering. MR browser extension dùng quy trình khác: nó đọc file qua GitLab API và hiện gửi body của fence; params trên dòng mở fence chưa được chuyển vào source gửi đi render.
5. Ràng buộc bảo mật khi chọn luồng¶
Không đưa Bearer token vào query string để biến authenticated POST thành image URL. Nếu source không được phép xuất hiện trong encoded URL, hãy render từ một backend tin cậy hoặc trong CI, sau đó phân phối kết quả theo chính sách của nơi lưu tài liệu.
6. Điều kiện kết nối tới Gateway¶
| Tích hợp | Điều kiện để gọi được Gateway |
|---|---|
| Playground | Gateway phục vụ cùng origin hoặc CORS cho origin Playground; browser có token trong tab |
| VS Code extension | Máy người dùng phân giải được DNS, tin cậy TLS và có token cho POST |
| GitLab document preview và static website | Browser người đọc truy cập được public encoded GET; CSP của trang cho phép Gateway trong img-src |
| GitLab MR browser extension | Manifest cho phép cả GitLab host và Gateway host; service worker có token |
| Confluence | Forge manifest cho phép backend egress tới Gateway host; encrypted variable có token |