Integration Flows¶
Các integration gọi rendering service theo hai cách. Preview, export và các lời gọi từ backend gửi authenticated POST; sơ đồ nhúng trong trang GitLab hoặc website tài liệu dùng public encoded GET để browser tải ảnh trực tiếp.
Chọn cách gọi API¶
| Tình huống | Request | Nơi giữ credential | Source xuất hiện ở đâu | Kết quả |
|---|---|---|---|---|
| Preview, export, review MR hoặc render từ backend | Authenticated POST |
Client storage hoặc backend secret store | Request body | Output và warnings trong response |
| Sơ đồ nhúng trong tài liệu trên GitLab hoặc website tài liệu | Public encoded GET |
Không dùng token | URL path sau khi nén và encode | Image hoặc 304 Not Modified |
Authenticated POST được dùng khi ứng dụng phía người dùng hoặc backend có thể bảo vệ token. Encoded GET được dùng khi trang cần để browser tải sơ đồ như một image thông thường mà không gửi token.
Render qua authenticated POST¶
Playground, VS Code Extension, GitLab MR Browser Extension và Forge Resolver gửi
source trong request body. Mỗi thành phần đọc token từ nơi lưu trữ dành riêng
cho nó, chẳng hạn sessionStorage, VS Code SecretStorage, extension storage
hoặc Forge encrypted variable.
Gateway trả lỗi ngay khi xác thực thất bại hoặc request vượt quá giới hạn. Kết quả có sẵn trong cache được trả trực tiếp mà không khởi chạy renderer. Status code, header và payload được mô tả trong API Integration; timeout, metrics và xử lý sự cố nằm trong Operations.
Render qua public encoded GET¶
Tài liệu trên GitLab và website tài liệu nhúng image URL chứa source đã nén và encode. URL này là định dạng truyền dữ liệu, vì vậy người có đường dẫn vẫn có thể khôi phục source.
GitLab áp dụng quyền truy cập của repository, wiki hoặc trang; máy chủ website tài liệu áp dụng cơ chế truy cập được cấu hình cho website. Các quyền này chỉ quyết định ai có thể mở trang và không được chuyển tiếp tới encoded GET của Gateway. Endpoint này là public, có rate limit và giới hạn request, vì vậy source nhạy cảm phải dùng authenticated POST để không xuất hiện trong URL hoặc access log.
Luồng của từng integration¶
Playground và VS Code¶
Playground giữ token trong sessionStorage của tab. VS Code Extension đọc source
từ active editor hoặc Markdown fence và giữ token trong VS Code SecretStorage.
Cả hai gửi authenticated POST, sau đó hiển thị preview hoặc ghi output ra file.
Tài liệu trên GitLab và website tài liệu¶
GitLab Markdown pipeline và MkDocs Kroki plugin tạo encoded image URL trước khi trang được mở. Browser của người đọc tải ảnh từ Gateway khi hiển thị trang. GitLab Markdown Integration mở rộng fence processing trên self-managed GitLab; việc render vẫn diễn ra tại rendering service.
Review merge request trên GitLab¶
Browser Extension dùng GitLab session để đọc nội dung merge request, còn Gateway token được service worker đọc khi cần render sơ đồ. Hai credential được giữ ở đúng runtime sử dụng chúng.
Content script làm việc với nội dung của tab GitLab nhưng không nhận Gateway
token. Service worker gọi rendering API mà không cần truy cập GitLab session.
Khi đọc Markdown, content script ưu tiên diagram-id; tài liệu cũ tiếp tục được
ghép theo title, loại sơ đồ và thứ tự. Metadata pairing không được gửi tới
Gateway.
Macro trên Confluence¶
Custom UI chạy trong browser iframe và gọi Forge Resolver. Resolver đọc token từ encrypted variable, gửi authenticated POST tới Gateway rồi kiểm tra SVG trước khi trả về editor hoặc viewer.
Page Event xử lý một luồng khác trong Forge app: khi trang được tạo hoặc cập nhật, event chuyển code block hợp lệ thành macro và ghi lại page ADF. Quá trình render bắt đầu khi editor hoặc viewer gọi Resolver. Cache chỉ áp dụng cho viewer: key gồm renderer và SHA-256 của source, SVG hết hạn sau 24 giờ, còn live preview luôn gọi Gateway. Pydia và output vượt giới hạn KVS không được lưu cache; lỗi KVS chỉ tạo cache miss và không làm request render thất bại.