Bỏ qua

Developer Guide

Tài liệu này dành cho contributor của Playground, Gateway, VS Code Extension, GitLab integrations, Confluence app, Java Core và rendering runtime.

1. Toolchain

Công cụ Version hoặc nguồn
JDK 21
Maven Maven Wrapper trong repository
Node.js 24
Docker Multi-stage build và Compose
VS Code ^1.95.0 cho extension
Forge CLI Bản tương thích runtime nodejs24.x cho Confluence PoC
Python Tạo virtual environment và cài requirements-docs.txt

Trên Windows dùng mvnw.cmd; trên Linux và macOS dùng ./mvnw.

2. Bản đồ mã nguồn

Khu vực Trách nhiệm
server/src/main/resources/web/playground.html Playground UI và browser state
gateway/ Public API, auth, rate limit, cache và ETag
vscode-extension/ Commands, parser, preview và export
deploy/gitlab-krokup/ GitLab fence params và custom image
browser-extension/ GitLab MR Markdown preview và diagram diff
confluence-code-to-uml-poc/ Forge event, ADF transformer, resolver, macro editor và viewer Custom UI
server/ Java core, route, renderer profile và integration customizations
mermaid/, bpmn/, excalidraw/, diagrams.net/ Browser renderer companions
pydia/, Dockerfile.pydia Isolated Pydia sidecar
deploy/gvisor/ Cài đặt và kiểm tra OCI runtime của Pydia trên production
deploy/, Compose, Dockerfile.render Rendering runtime và deployment
mkdocs.yml, requirements-docs.txt Cấu hình và dependencies của website tài liệu
docs/ Markdown, stylesheet, JavaScript, font và OpenAPI contract

3. Playground

Playground được Java core phục vụ tại /playground. Khi sửa giao diện:

  1. Giữ token trong sessionStorage và source theo renderer trong localStorage.
  2. Hủy preview cũ và chỉ hiển thị kết quả request mới nhất.
  3. Giữ Fenced block và %%krokup tương đương về request gửi đi.
  4. Đồng bộ controls với renderer catalog và universal option schema.
  5. Hiển thị X-Diagram-Warnings mà không biến warning thành lỗi.
  6. Kiểm tra desktop, mobile, keyboard và trạng thái lỗi.

server/pom.xml loại web/** khỏi resource filtering rồi copy lại nguyên trạng. Không bật Maven filtering cho Playground vì JavaScript template literal có thể bị thay đổi trong artifact.

4. VS Code extension

Set-Location vscode-extension
npm ci
npm test
npm run package

Khi thêm setting hoặc command, cập nhật contributes, behavior, unit test và smoke test bằng Extension Development Host hoặc VSIX. Parser Markdown phải giữ các invariant:

  • Chỉ {...} sau language được coi là params.
  • Giá trị title="..." không trở thành render option.
  • Fence params thắng directive trong preamble.
  • Fence không có params giữ source directive.
  • Source gửi đi chỉ có một dòng %%krokup.
  • Mermaid init directive %%{...}%% được giữ nguyên.

Live Preview dùng parser này để dựng tài liệu trong webview. Webview phải sanitize Markdown và SVG, đồng thời giữ CSP giới hạn.

5. Gateway

Set-Location gateway
npm ci
npm test
npm start

Các invariant của auth, cache và rate limit:

  • Không log token và dùng constant-time token comparison.
  • Cache byte accounting không âm.
  • Entry quá lớn không được lưu.
  • TTL và LRU cùng thỏa max bytes/max entries.
  • Export background không phân mảnh upstream cache.
  • ETag được tính từ output cuối.
  • Hủy upstream khi subscriber cuối disconnect.
  • Metrics callback không làm thay đổi request correctness.

Thay đổi cache key cần test chứng minh request nào dùng chung và request nào tách cache identity.

6. GitLab integrations

Kiểm tra ba lớp độc lập:

  1. Encoded GET: URL, source confidentiality, rate limit và Markdown/AsciiDoc.
  2. Fence params: rewriter, fail-open, renderer allow-list và custom image trên GitLab version đích.
  3. MR review: activation theo tab, script injection, Markdown Before/After, GitLab API adapter, stable ID pairing, vị trí diagram action, lazy render, queue, cache và browser package.

Fence params của GitLab Markdown Integration hiện không được browser extension chuyển đổi. MR review dùng %%krokup trong body. Extension dùng activeTab trên GitLab HTTPS; tab mới hoặc GitLab origin khác cần được người dùng kích hoạt riêng.

Diagram pairing phải giữ thứ tự ưu tiên sau:

  1. Ghép diagram-id hợp lệ và duy nhất ở hai phía.
  2. Ghép legacy identity từ title và renderer khi stable ID không quyết định cặp.
  3. Fallback theo renderer và thứ tự xuất hiện cho tài liệu cũ.

Hai stable ID khác nhau không được ghép. ID trùng hoặc sai định dạng phải tạo cảnh báo và không được tham gia fallback theo occurrence. Trường hợp chỉ một phía có ID có thể dùng legacy metadata nhưng phải báo migration warning. diagram-id chỉ là metadata của MR extension: Browser Extension, VS Code parser và GitLab fence rewriter phải loại nó khỏi directive hoặc source gửi tới Gateway.

Browser extension:

Set-Location browser-extension
npm install
npm test
npm run package:zip

GitLab fence pre-filter:

ruby deploy/gitlab-krokup/test/krokup_fence_rewriter_test.rb
docker build --file deploy/gitlab-krokup/Dockerfile `
  --tag gitlab-ce-kroki:test deploy/gitlab-krokup

Docker build kiểm tra patch target trong GitLab image và chạy lại unit test bằng Ruby được đóng gói trong image. Integration smoke dùng deploy/gitlab-krokup/test/run_gitlab_smoke.sh trên GitLab instance thử nghiệm.

7. Confluence

Set-Location confluence-code-to-uml-poc
npm.cmd install
npm.cmd --prefix static/code-to-uml install
npm.cmd test
npm.cmd run build
forge.cmd lint

Giữ các invariant sau:

  • Page event không tạo vòng lặp update.
  • Publish source không đổi giữ macro identity.
  • Macro được tạo từ code block lưu source trong macro config và được chỉnh sửa bằng macro editor.
  • Macro được tạo từ editor không bị page event chuyển đổi lại.
  • Prose, heading và non-diagram fence giữ đúng thứ tự.
  • Token chỉ nằm trong encrypted Forge variable và backend resolver.
  • Resolver kiểm tra source hash, renderer, Pydia policy, timeout, MIME, kích thước và active SVG content.
  • Viewer cache dùng key gồm renderer và SHA-256 source, TTL 24 giờ và chỉ lưu SVG không vượt 220 KiB.
  • Cache hit vẫn chạy validateSvg; lỗi KVS phải fallback sang live render.
  • Live preview và Pydia không dùng cache.
  • Thiết lập ENABLE_RENDER_CACHE=false tắt cache mà không làm thay đổi render response.
  • Scope storage:app được giữ trong Forge manifest và thay đổi scope phải được install upgrade trên site.
  • Live preview áp dụng renderer allow-list, giới hạn source và Pydia policy trước khi gọi Gateway.
  • Pydia cần global opt-in và numeric space allow-list.

Đổi Gateway host cần cập nhật cả RENDER_BASE_URL và backend fetch allow-list trong manifest.yml.

8. Java core và renderer

.\mvnw.cmd -pl server test
.\mvnw.cmd -pl server -DskipTests package

Thay đổi core hoặc renderer cần giữ route/format compatibility, cập nhật renderer profile, capability và adapter liên quan, rồi test source/options/output đại diện. Thay đổi runtime binary hoặc companion cần smoke test production image.

Thêm renderer mới tác động đồng thời tới service, metadata, image dependency, Gateway allow-list, VS Code mapping, OpenAPI và tests. Pydia còn cần opt-in, Unix socket delegation, sandbox limits và kiểm tra network/token isolation. Thay đổi Pydia trên production còn phải giữ runtime runsc-pydia và đường Unix socket giữa container gVisor với rendering container dùng runc.

9. API, params và runtime

Khi thêm universal option hoặc theme, cập nhật schema/registry, capability, adapter hoặc output processor, tests và các UI đọc catalog.

Khi thay đổi API:

  1. Cập nhật docs/api-docs.yaml.
  2. Cập nhật source và tests theo contract.
  3. Chạy request mẫu qua Local Gateway.
  4. Cập nhật API Integration và OpenAPI.

Build topology local:

docker build --file Dockerfile.render --tag code-to-uml-render:dev .
docker build --file Dockerfile.pydia --tag code-to-uml-pydia:dev .
Copy-Item .env.example .env
docker compose -f compose.code-to-uml.yml up -d --build

ci/scripts/smoke-production.sh kiểm tra Gateway, core và renderer đại diện trong production image.

10. Website tài liệu

Chỉnh sửa tài liệu và giao diện trong docs/; không chỉnh trực tiếp file sinh ra trong site/. CSS nguồn nằm tại docs/stylesheets/, JavaScript tại docs/javascripts/ và font tại docs/assets/fonts/.

Tạo môi trường tài liệu riêng:

python -m venv artifacts\docs-venv
.\artifacts\docs-venv\Scripts\python -m pip install -r requirements-docs.txt

Chạy preview local:

$env:KROKI_SERVER_URL = "https://kroki-render-vsf.duckdns.org"
.\artifacts\docs-venv\Scripts\python -m mkdocs serve

Trước khi hoàn tất thay đổi, tạo lại toàn bộ website và bật strict validation:

$env:KROKI_SERVER_URL = "https://kroki-render-vsf.duckdns.org"
.\artifacts\docs-venv\Scripts\python -m mkdocs build --clean --strict
node --test ci/tests/docs-navigation.test.js
node --test ci/tests/docs-links.test.js

Build phải tạo lại HTML, search index, stylesheet, JavaScript và font trong site/. Sau khi có URL chính thức, đặt site_url trong mkdocs.yml rồi build lại để canonical URL và sitemap dùng đúng địa chỉ. Kiểm tra navigation, mục lục, search, liên kết OpenAPI và ít nhất một diagram trên website đã phát hành; diagram chỉ hiển thị khi browser truy cập được public Gateway qua HTTPS.

Vì use_directory_urls: false, HTML link viết tay phải trỏ tới output .html. Khi đổi tên trang, cập nhật navigation, landing page và toàn bộ link nội bộ trong cùng thay đổi; chỉ giữ file canonical trong nhóm tài liệu được publish.

11. Test matrix

Lớp Vị trí
Java unit/integration server/src/test/java
Gateway gateway/test
VS Code extension vscode-extension/test-*.js
GitLab MR extension browser-extension/test
GitLab fence params deploy/gitlab-krokup/test
Confluence PoC confluence-code-to-uml-poc/test, Vite build, Forge lint
Pydia pydia/test_render.py, gateway/test/pydia-sandbox.test.js, deploy/gvisor/verify-pydia.sh
Production image ci/scripts/smoke-production.sh
Website tài liệu mkdocs build --clean --strict, navigation, link/anchor và diagram smoke test
Benchmark ci/scripts/render-benchmark.mjs
Manual UI Playground, VSIX, GitLab MR extension và Confluence Custom UI

12. Hoàn tất thay đổi

  • Test liên quan pass và ghi lại test chưa chạy trong pull request.
  • UI change có runtime hoặc snapshot check phù hợp.
  • Runtime change có production image smoke test.
  • Thay đổi Markdown, navigation hoặc giao diện tài liệu có strict build và kiểm tra website tương ứng.
  • Token và source nhạy cảm không xuất hiện trong log.
  • API, params, settings và deployment docs phản ánh behavior mới.
  • GitLab và Confluence change được test trên môi trường tích hợp tương ứng trước khi phát hành.