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 | Rendered body; ETag và warning, nếu có, nằm trong response header |
| 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.
Pydia là trường hợp rủi ro cao hơn các engine khai báo thông thường: public encoded GET của Pydia cũng không yêu cầu Bearer token và có thể làm server thực thi Python do người gọi cung cấp. gVisor cô lập tiến trình khỏi host nhưng không thay thế xác thực hoặc kiểm soát quyền sử dụng. Operator chỉ nên bật Pydia có chủ đích và phải duy trì rate limit, giới hạn source, CPU, memory, process, timeout cùng việc chặn network của sandbox. Các giới hạn này giảm phạm vi ảnh hưởng; chúng không biến route public thành route riêng tư.
Luồng của từng integration¶
Playground¶
Playground giữ token trong sessionStorage của tab và gửi source qua
authenticated POST. Khi preview thành công, response body chứa SVG; cảnh báo
không làm render thất bại được trả riêng trong header X-Diagram-Warnings và
hiển thị trong warning strip.
Export gửi một POST khác theo format được chọn và ghi response body thành file;
token vẫn được đọc từ sessionStorage.
VS Code¶
Live Preview và Export đọc source từ active editor hoặc Markdown fence, lấy token từ VS Code SecretStorage rồi gửi authenticated POST. Hai chức năng này sử dụng rendered bytes trong response body.
Tài liệu trên GitLab và website tài liệu¶
Trên self-managed GitLab, GitLab Markdown Integration chuyển options của diagram
fence thành directive trước MarkdownFilter; Kroki integration trong Markdown
renderer sau đó tạo HTML chứa encoded image URL. Với website tài liệu, MkDocs
Kroki plugin tạo image URL trong lúc build. Browser của người đọc tải ảnh từ
Gateway khi hiển thị trang; cả hai trường hợp đều thực thi renderer 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 id trong {...}; tài liệu cũ tiếp
tục được ghép theo legacy identity rồi same-engine occurrence fallback. ID được
loại khỏi comparisonSource, nhưng directive đầy đủ vẫn được gửi trong
renderSource để các render param có hiệu lực; Java Core bỏ qua option id.
Macro trên Confluence Forge¶
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.
Integration này có lifecycle riêng: source trong repository không đồng nghĩa app đã được deploy hoặc cài trên một site. Mỗi Forge environment/site phải được deploy, install và kiểm chứng độc lập; workflow deploy rendering service không thực hiện các bước đó.