Tài liệu tham khảo SDK frontend cho plugin

Mã frontend của plugin chạy trong iframe được cách ly bằng sandbox. Tài liệu này là tài liệu tham khảo cấp thấp. Để xem phần giới thiệu ở cấp cao hơn, xem README.md.

Mô hình bảo mật

Thuộc tính	Giá trị
Sandbox của iframe	Chỉ có `allow-scripts` (không có `allow-same-origin`)
CSP `script-src`	Giới hạn bằng nonce; chỉ tải tập lệnh tại điểm vào
CSP `connect-src`	`'self'` - plugin có thể gửi POST đến `/plugins/{id}/api/*` và truy vấn định kỳ `/plugins/{id}/events/poll`
CSP `default-src`	`'none'`
Truy cập DOM của trang cha	Bị chặn (không có `allow-same-origin`)
Cookie phiên Ogma	Plugin không thể truy cập
Giao tiếp giữa các plugin	Không khả dụng

Các lệnh gọi dữ liệu qua cầu nối được kiểm tra quyền ở phía máy chủ với mỗi yêu cầu; thao tác hiển thị và điều hướng do giao diện ứng dụng chủ xử lý. Bộ nhớ đệm quyền hiển thị trong thẻ Quyền chỉ dùng để hiển thị; nó không kiểm soát quyền truy cập dữ liệu.

Giao thức cầu nối

JavaScript của plugin giao tiếp với ứng dụng chủ Ogma qua postMessage. Thành phần chủ nằm trong PluginsView.vue và xử lý thông điệp bridge_request.

Cấu trúc bao của yêu cầu

interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}

Tổng kích thước thông điệp tối đa: 65 536 byte.

Cấu trúc bao của phản hồi

interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}

Dùng SDK (khuyến nghị)

Không gửi thủ công yêu cầu cầu nối thô bằng postMessage. Dùng đối tượng toàn cục ogmaSDK:

ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});

SDK bao bọc toàn bộ giao tiếp cầu nối và xử lý việc đối chiếu yêu cầu, quản lý sessionId và hoàn tất Promise.

Tài liệu tham khảo lệnh

`ogma.meta.get`

Không cần payload.

Trả về { pluginId, packageId, name, version, ogmaVersion }.

`ogma.requests.get`

Payload: { id: string }

Trả về mục HTTP dưới dạng bản chiếu. Các trường: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Bản chiếu này không bao gồm header hoặc byte nội dung.

Yêu cầu: read_http_history (được cấp tự động).

`ogma.requests.getRaw`

Payload: { id: string }. Gọi thông qua sdk.requests.getRaw(id).

Trả về requestBodyBase64, responseBodyBase64, độ dài sau khi giải mã của chúng (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated và maxBodyBytes. Dù có tên như vậy, thao tác này trả về byte nội dung, không phải toàn bộ thông điệp HTTP thô. Các kiểu mã hóa nội dung được hỗ trợ sẽ được giải mã trước khi tạo bản chiếu. Mỗi phần nội dung bị giới hạn ở 256 KiB; kiểm tra cờ cắt ngắn trước khi xử lý một tài nguyên hoàn chỉnh.

Yêu cầu: read_http_history (được cấp tự động).

`ogma.requests.search`

Payload: { limit?: number, offset?: number, query?: string }

query hỗ trợ biểu thức lọc HTTPQL. limit tối đa: 20. Trả về { items: [...], total: number, limit: number, offset: number }.

Yêu cầu: read_http_history (được cấp tự động).

`ogma.findings.list`

Payload: { limit?: number, offset?: number }

Trả về { items: [...], total: number, limit: number, offset: number }, với tối đa 20 phát hiện mỗi trang. Các mục là bản tóm tắt; các trường bao gồm id, title, severity, status, reporter, tags và created_at.

Yêu cầu: read_findings (được cấp tự động).

`ogma.scope.getActive`

Không có payload. Trả về bộ thiết lập sẵn cho phạm vi đang hoạt động hoặc null.

Yêu cầu: read_scope (được cấp tự động).

`ogma.projects.getCurrent`

Không có payload. Trả về { id, name, status } hoặc null.

Yêu cầu: read_projects (được cấp tự động).

`ogma.log`

Payload: { message: string }

Ghi vào bộ đệm nhật ký của plugin.

`ogma.ui.resize`

Payload: { height: number } (tối đa 2000)

Yêu cầu ứng dụng chủ đặt chiều cao iframe.

`ogma.ui.sidebar.registerItem`

Payload: { name: string, path: string } (tên tối đa 64 ký tự, đường dẫn tối đa 256 ký tự)

Đăng ký điều hướng trong bảng plugin. Tối đa 20 mục cho mỗi plugin. Đăng ký nội dung các trang tương ứng bằng sdk.navigation.addPage(path, { title, body }); chọn mục sẽ hiển thị trang đó trong iframe, không phải một tuyến cấp cao nhất mới của không gian làm việc Ogma.

`ogma.backend.call`

Payload: { method: string, args: unknown[] }

Gọi hàm xử lý RPC backend được đăng ký qua sdk.api.register(method, fn). Độ dài tên phương thức tối đa là 64 ký tự.

Trả về giá trị hàm xử lý backend đã trả về, được tuần tự hóa thành JSON.

`ogma.backend.onEvent`

Payload: không cần.

Chỉ xác nhận đã nhận. Dùng ogma.events.poll để thực sự lấy sự kiện.

`ogma.events.poll`

Payload: { since: number } (chỉ số từ lần truy vấn định kỳ trước; bắt đầu ở 0)

Trả về { events: [{ event: string, args: unknown[] }], next_since: number }.

`ogma.navigation.addPage`

Payload: { path: string, title?: string }

Cầu nối xác nhận đã nhận đường dẫn trang. SDK được chèn vào còn chấp nhận { body: HTMLElement } làm tùy chọn cho sdk.navigation.addPage(path, options), gắn nội dung trong iframe và chuyển trạng thái hiển thị trang khi ứng dụng chủ chọn mục tương ứng trên thanh bên. Nút DOM vẫn ở cục bộ; nó không được tuần tự hóa qua cầu nối.

`ogma.window.showToast`

Payload: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

Hiển thị thông báo tạm thời trong bảng plugin. Thời lượng tính bằng ms (tối đa 10000, mặc định 3000).

`ogma.commands.register`

Payload: { id: string, name: string }

Đăng ký lệnh plugin vào kho lệnh của ứng dụng chủ. Khi thực thi, ứng dụng chủ gửi thông điệp plugin_command chứa commandId và ngữ cảnh trở lại iframe; plugin phải cung cấp callback tương ứng. Chỉ đăng ký không thực thi lệnh.

`ogma.menu.registerItem`

Payload: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

Đăng ký mục menu ngữ cảnh gắn với lệnh plugin. Đăng ký lệnh trước. Nhãn mặc định là tên đã đăng ký của lệnh, nếu không có thì dùng ID; khi bỏ qua type, mặc định là Request. Cầu nối của ứng dụng chủ không sử dụng leadingIcon.

Hàm hỗ trợ chủ đề giao diện

SDK được chèn vào cũng cung cấp sdk.theme.get() và sdk.theme.onChange(callback). Các hàm này đọc chủ đề giao diện của iframe và đăng ký nhận cập nhật chủ đề từ ứng dụng chủ mà không cần lệnh dữ liệu cầu nối riêng. Dùng chúng để giao diện plugin nhất quán với giao diện sáng/tối của Ogma.

Mã lỗi

Mã	Ý nghĩa
`PERMISSION_DENIED`	Plugin thiếu quyền cần thiết.
`PLUGIN_DISABLED`	Plugin hiện chưa được bật.
`UNKNOWN_COMMAND`	Lệnh không nằm trong danh sách được hỗ trợ.
`INVALID_PAYLOAD`	Trường payload bắt buộc bị thiếu hoặc có kiểu không đúng.
`NOT_FOUND`	Tài nguyên được yêu cầu không tồn tại.
`LIMIT_EXCEEDED`	Đã đạt giới hạn số lượng cho mỗi plugin (ví dụ: mục trên thanh bên).
`SERVER_ERROR`	Lỗi nội bộ. Kiểm tra nhật ký plugin.

Danh sách lệnh được hỗ trợ

ogma.meta.get, ogma.log, ogma.ui.resize, ogma.ui.sidebar.registerItem, ogma.requests.get, ogma.requests.getRaw, ogma.requests.search, ogma.findings.list, ogma.scope.getActive, ogma.projects.getCurrent, ogma.backend.call, ogma.backend.onEvent, ogma.events.poll, ogma.navigation.addPage, ogma.window.showToast, ogma.commands.register, ogma.menu.registerItem.

Tài liệu tham khảo SDK frontend cho plugin ​

Mô hình bảo mật ​

Giao thức cầu nối ​

Cấu trúc bao của yêu cầu ​

Cấu trúc bao của phản hồi ​

Dùng SDK (khuyến nghị) ​

Tài liệu tham khảo lệnh ​

ogma.meta.get ​

ogma.requests.get ​

ogma.requests.getRaw ​

ogma.requests.search ​

ogma.findings.list ​

ogma.scope.getActive ​

ogma.projects.getCurrent ​

ogma.log ​

ogma.ui.resize ​

ogma.ui.sidebar.registerItem ​

ogma.backend.call ​

ogma.backend.onEvent ​

ogma.events.poll ​

ogma.navigation.addPage ​

ogma.window.showToast ​

ogma.commands.register ​

ogma.menu.registerItem ​

Hàm hỗ trợ chủ đề giao diện ​

Mã lỗi ​

Danh sách lệnh được hỗ trợ ​

Tài liệu tham khảo SDK frontend cho plugin

Mô hình bảo mật

Giao thức cầu nối

Cấu trúc bao của yêu cầu

Cấu trúc bao của phản hồi

Dùng SDK (khuyến nghị)

Tài liệu tham khảo lệnh

`ogma.meta.get`

`ogma.requests.get`

`ogma.requests.getRaw`

`ogma.requests.search`

`ogma.findings.list`

`ogma.scope.getActive`

`ogma.projects.getCurrent`

`ogma.log`

`ogma.ui.resize`

`ogma.ui.sidebar.registerItem`

`ogma.backend.call`

`ogma.backend.onEvent`

`ogma.events.poll`

`ogma.navigation.addPage`

`ogma.window.showToast`

`ogma.commands.register`

`ogma.menu.registerItem`

Hàm hỗ trợ chủ đề giao diện

Mã lỗi

Danh sách lệnh được hỗ trợ