Tổng quan

System event trong GraphQL plugin là cơ chế cho phép một hệ thống gọi vào event bus của platform thông qua một API trung gian. Thay vì expose trực tiếp toàn bộ event handler, plugin chỉ cho phép gọi những event name đã được cấu hình trong danh sách cho phép. Đây là một trong những tính năng cần thiết để EzyPlatform hoạt động trong môi trường microservices.
Ở runtime, payload đầu vào có dạng khái quát:
{
  "eventName": "some_event_name",
  "data": {
    "key": "value"
  }
}
Plugin nhận request, kiểm tra eventName, rồi chuyển data vào event manager để tìm và chạy handler tương ứng.

Kiến trúc tổng quát

Cơ chế này gồm bốn phần chính:
  • API system event: nhận request từ bên ngoài hoặc từ system endpoint.
  • Danh sách event được phép xử lý: cấu hình bảo vệ để không phải event nào cũng gọi được.
  • Event manager của platform: điều phối handler theo event name.
  • GraphQL event handler dạng script: handler động được lưu như nội dung post và chạy bằng JavaScript runtime.
Luồng xử lý tổng quát: 
flowchart TD
    A[Client hoặc system endpoint] --> B[POST /api/v1/system-event]
    B --> C{eventName có trong danh sách cho phép?}
    C -- Không --> D[403 Forbidden]
    C -- Có --> E[Event manager handleEvent]
    E --> F[Handler Java đã đăng ký]
    E --> G[Handler script từ GraphQL plugin]
    F --> H[Trả kết quả đầu tiên khác null]
    G --> H
    H --> I[Response body hoặc 204 No Content]

Luồng gọi system event

Khi API /api/v1/system-event nhận request, nó đọc eventName và data từ body.
Trước khi gọi event bus, plugin lấy danh sách event name được phép xử lý từ setting. Nếu eventName không nằm trong danh sách này, request bị chặn bằng 403 Forbidden.
Nếu hợp lệ, plugin gọi event manager với:
  • tên event: eventName
  • dữ liệu truyền vào handler: data
Kết quả trả về có hai trường hợp:
  • Nếu handler trả về giá trị khác null, API trả thẳng giá trị đó về client.
  • Nếu không handler nào trả về kết quả, hoặc toàn bộ handler trả về null, API trả 204 No Content.

Cách event manager chọn handler

Event manager không chỉ chạy handler do GraphQL plugin tạo ra. Nó chạy theo thứ tự:
  1. Các event handler Java đã được đăng ký như singleton trong platform.
  2. Các event handler động được cung cấp bởi EventHandlerProvider.
GraphQL plugin đóng vai trò một provider động. Provider này tìm các event handler script đã publish trong hệ thống nội dung, sau đó bọc mỗi script thành một event handler runtime.
Một điểm quan trọng: với event bình thường, event manager dừng ở handler đầu tiên trả về kết quả khác null. Vì vậy đây không phải lúc nào cũng là cơ chế broadcast qua toàn bộ handler. Nếu handler đầu tiên đã trả kết quả, các handler phía sau sẽ không chạy tiếp.

Event handler dạng script

GraphQL plugin lưu event handler script như một post đặc biệt.
Một event handler script có các thành phần chính:
  • eventName: tên event, đồng thời là định danh để event manager tìm handler.
  • summary: JSON mô tả schema/contract của event.
  • content: mã JavaScript thực thi handler.
  • status: chỉ handler đã publish mới được provider runtime tìm thấy.
  • metadata event_name: dùng để query handler theo event name.
Khi handler được gọi, plugin nạp lại content đã publish theo post id. Nếu post không còn tồn tại hoặc không còn publish tại thời điểm chạy, handler trả lỗi not found.
Script được chạy với các tham số:
  • eventData: dữ liệu truyền vào từ request.
  • eventName: tên event đang được xử lý.
  • content: nội dung script hiện tại.
Giá trị return của script chính là kết quả event handler. Nếu return khác null, event manager có thể dùng nó làm response cuối cùng.

Schema của event

Schema của event được lấy từ phần summary của event handler script. Summary là JSON mô tả contract, gồm các trường chính:
{
  "description": "Mô tả event làm gì",
  "argumentSchema": {
    "dataType": "java.util.Map",
    "name": "eventData",
    "description": "Dữ liệu đầu vào"
  },
  "resultSchema": {
    "dataType": "java.util.Map",
    "description": "Kết quả trả về"
  },
  "examples": [
    "{"some":"payload"}"
  ]
}
argumentSchema và resultSchema hỗ trợ các thông tin như kiểu dữ liệu, kiểu item trong array, kiểu key/value trong map, tên field, required, mô tả, ví dụ, properties và danh sách field con.
Nếu summary rỗng, plugin tạo schema rỗng. Nếu summary không parse được hoặc tham chiếu class không hợp lệ, schema có thể trả về null và lỗi được ghi log.

Công bố schema

GraphQL plugin có generator để xuất schema event thành JSON. Nó lấy toàn bộ schema fetcher đã đăng ký trong event manager, bao gồm cả schema fetcher từ provider động của GraphQL plugin.
Có hai kiểu lấy schema:
  • Lấy toàn bộ event schema.
  • Lấy schema theo một eventName cụ thể.
Admin runtime có thể trả schema của admin event trực tiếp. Với web event, admin runtime gọi sang management endpoint của web runtime để lấy schema tương ứng.

System endpoint

Ngoài API gọi event trực tiếp, plugin còn có khái niệm system endpoint. Đây là danh sách endpoint bên ngoài được cấu hình trong admin, gồm:
  • link
  • bearer token
  • description
  • status visible/invisible
Khi event nội bộ ezy_system_event được phát ra, handler hệ thống sẽ duyệt các system endpoint đang visible, lấy token đã lưu, rồi POST payload tới từng link với header Authorization: Bearer ....
Cơ chế này dùng để forward một system payload tới các endpoint đã đăng ký. Endpoint nhận request có thể là /api/v1/system-event của một GraphQL plugin khác hoặc một endpoint tương thích.

Bảo mật

Có hai lớp bảo vệ thể hiện rõ trong GraphQL plugin:
  • Chỉ endpoint có status visible và có token mới được handler forward gọi tới.
  • API /api/v1/system-event chỉ xử lý event name nằm trong danh sách cho phép.
Bearer token được lưu ở metadata của link và được mã hóa qua setting service. Khi forward request, token được giải mã và đưa vào header Authorization.
Riêng API /api/v1/system-event, phần code GraphQL plugin kiểm tra whitelist event name. Việc xác thực Bearer token ở tầng HTTP/interceptor phụ thuộc vào cấu hình platform/runtime bao quanh endpoint đó, nên không nên xem whitelist là thay thế hoàn toàn cho authentication.

Giới hạn cần lưu ý

System event không tự động expose mọi event handler. Event name phải được đưa vào danh sách cho phép.
Handler script chỉ được tìm thấy khi post ở trạng thái published.
Event manager trả về kết quả đầu tiên khác null, nên nhiều handler cùng event name có thể không chạy hết nếu một handler trước đó đã có result.
Schema chỉ là contract mô tả từ summary. Nó không tự đảm bảo payload runtime luôn đúng schema nếu không có tầng validate riêng.

Kết luận

System event trong GraphQL plugin là một lớp cầu nối có kiểm soát giữa HTTP endpoint và event bus của platform. Plugin cho phép tạo handler động bằng JavaScript, mô tả contract bằng schema JSON, expose schema cho công cụ bên ngoài, và forward system payload qua các endpoint đã cấu hình.
Điểm cốt lõi của thiết kế là: event bus vẫn là trung tâm xử lý, còn GraphQL plugin bổ sung khả năng authoring handler, công bố schema, và kiểm soát event nào được phép gọi qua HTTP.