Matrix JavaScript SDK: Thư Viện Client-Server Cho JS
/matrix-js-sdk
Matrix JavaScript SDK là thư viện TypeScript chính thức mà các ứng dụng web và desktop của Element dùng để giao tiếp với giao thức Matrix. Nó bọc Client-Server HTTP API, duy trì luồng sự kiện /sync, và cung cấp các đối tượng Room, User ở mức cao thay vì JSON thô. Hãy chọn SDK này nếu bạn đang xây client Matrix thực sự trên Node.js hoặc trình duyệt; bỏ qua nếu chỉ cần gửi một tin nhắn từ script, vì dựng sync và mã hoá cho việc đó là thừa.
Matrix JavaScript SDK Là Gì?
Matrix JavaScript SDK là SDK client-server cho giao thức Matrix, viết bằng TypeScript và dùng được như một Matrix Node.js SDK hay một Matrix browser SDK tuỳ nơi bạn import vào. Nó bọc Matrix Client-Server API thành một mô hình đối tượng — Room, RoomMember, User — và phát ra sự kiện khi có sync, gõ phím, thay đổi thành viên, hay tin nhắn mới, được Element bảo trì cho chính client web và desktop của họ.
SDK Này Dành Cho Ai?
Matrix JavaScript SDK phù hợp với nhà phát triển đang xây một client nhắn tin phi tập trung hoặc công cụ cộng tác trên giao thức Matrix, không muốn tự viết vòng lặp /sync, tự theo dõi trạng thái room, hay tự tích hợp stack mã hoá dựa trên Rust. Là một SDK client Matrix, nó phù hợp cho cả ứng dụng trình duyệt, qua Webpack hoặc Vite, lẫn backend/bot chạy Node.js, theo danh sách nền tảng hỗ trợ trong README — chính Element cũng xây client web và desktop của họ trên SDK này. Bỏ qua nếu bạn không nhắm tới Matrix, hoặc cần một client cho ngôn ngữ khác ngoài JavaScript/TypeScript, vì thư viện này chỉ phủ phần JS/TS của giao thức.
Năng Lực Cốt Lõi Của SDK
- ✓Bọc toàn bộ Matrix Client-Server API thành một mô hình đối tượng — Room, RoomState, RoomMember, User — và phát sự kiện mỗi khi các đối tượng này thay đổi, theo README.
- ✓Tự xử lý polling /sync, phân trang, và đồng bộ ban đầu của room khi chấp nhận lời mời, nên bạn không phải tự gọi HTTP API bằng tay.
- ✓Local echo hiển thị ngay tin nhắn đang gửi trên timeline, gắn nhãn còn đang gửi, cho tới khi server xác nhận — nên không có khoảng trống nhìn thấy giữa lúc bấm gửi và lúc tin nhắn thực sự tới nơi.
- ✓Tự động thử lại khi gửi gặp lỗi mạng hoặc bị rate-limit, và đánh dấu các tin nhắn gửi thất bại là chưa gửi, theo README.
- ✓Mã hoá đầu-cuối chạy qua initRustCrypto(), tải các binding WebAssembly của thư viện Rust matrix-sdk-crypto thay vì một cài đặt mã hoá thuần JavaScript.
- ✓Bao phủ sẵn các luồng mã hoá phức tạp: khởi tạo secret storage, thiết lập cross-signing, key backup, và xác minh thiết bị, tất cả qua interface CryptoApi.
- ✓Cung cấp các entry point riêng cho crypto (matrix-js-sdk/lib/crypto-api), type theo spec (matrix-js-sdk/lib/types), và đăng nhập QR-code/rendezvous theo MSC4108 (matrix-js-sdk/lib/rendezvous), để bạn chỉ import phần cần dùng.
- ✓Xử lý tải media đã xác thực qua mxcUrlToHttp cùng header Authorization dạng bearer, cho các server hỗ trợ MSC3916 (Matrix 1.11).
Bắt Đầu Cài Đặt
Matrix JavaScript SDK cài đặt chỉ bằng một lệnh: pnpm add matrix-js-sdk — README khuyên dùng pnpm hơn npm, và dẫn tới hướng dẫn cài đặt riêng của pnpm cho ai chưa có sẵn công cụ này. Sau khi cài, import * as sdk from "matrix-js-sdk" rồi gọi sdk.createClient({ baseUrl: "https://matrix.org" }) để lấy một instance MatrixClient trỏ tới homeserver. Phiên bản Matrix server tối thiểu mà SDK nhắm tới là v1.1, và README cảnh báo trước rằng một số server yêu cầu header Authorization khi tải media, nên hãy xem phần ghi chú về authenticated media trước khi đi xa hơn. Từ đó, client.startClient({ initialSyncLimit: 10 }) bắt đầu vòng lặp sync để nạp dữ liệu room và timeline.
Xây Dựng Với SDK: Ví Dụ Code
Gửi tin nhắn bằng client.sendEvent(roomId, "m.room.message", { body: "message text", msgtype: "m.text" }, "", callback), rồi lắng nghe nó qua client.on(RoomEvent.Timeline, (event, room, toStartOfTimeline) => { ... }), lọc theo event.getType() === "m.room.message". Với trạng thái kết nối, client.on(ClientEvent.sync, (state) => { ... }) báo khi client đạt trạng thái PREPARED sau lần sync đầu tiên, còn RoomMemberEvent.Typing và RoomStateEvent.Members phủ chỉ báo gõ phím và danh sách thành viên. Store mặc định là MemoryStore trong bộ nhớ, giữ sự kiện khi chúng tới, nên client.store.rooms cho bạn timeline đang được cache của từng room mà không cần thêm một vòng gọi tới server. Với mã hoá, await matrixClient.initRustCrypto() bật stack mã hoá dựa trên Rust trước khi bạn gọi matrixClient.getCrypto() cho cross-signing, secret storage, hay key backup.
Điểm mạnh
- ✓Được Element đứng sau — chính client web và desktop của Element chạy trên SDK này, nên đội bảo trì cũng là người dùng nặng ký hàng ngày.
- ✓Mã hoá đầu-cuối dùng chung engine Rust matrix-sdk-crypto, qua WebAssembly, với các SDK chính thức khác của Matrix, thay vì một cài đặt mã hoá JS riêng phải giữ đồng bộ.
- ✓Đã lo sẵn phần việc theo dõi trạng thái không mấy hào nhoáng — local echo, retry khi bị rate-limit hoặc lỗi mạng, xếp hàng tin nhắn, phân trang — thứ mà bạn sẽ phải tự viết nếu gọi thẳng HTTP API.
- ✓Giấy phép Apache-2.0, không kèm ràng buộc độc quyền nào.
- ✓Cung cấp các entry point tách riêng (crypto-api, types, rendezvous, testing) để bạn chỉ import phần cần, thay vì một bundle độc khối.
Lưu Ý Quan Trọng Và Giới Hạn
- △Stack mã hoá được ghi rõ là không thread-safe: trỏ nhiều instance MatrixClient vào cùng một IndexedDB có nguy cơ làm hỏng dữ liệu và phá vỡ quá trình giải mã, nên tầng ứng dụng phải tự đảm bảo chỉ có một instance chạy tại một thời điểm.
- △Di chuyển từ crypto stack cũ sang Rust crypto đòi hỏi truyền cryptoStore và pickleKey cũ vào createClient, và README nói nhiều phương thức MatrixClient đã deprecated không còn được hỗ trợ dưới stack Rust crypto mới.
- △Nếu không dùng store IndexedDB bền vững (ví dụ chạy phía server với useIndexedDB: false), README nói bạn cần đăng nhập như một thiết bị mới mỗi khi ứng dụng khởi động lại.
- △README thừa nhận entry point chính vẫn còn nhiều code cũ cần dọn dẹp, nên bề mặt API ở cấp cao nhất chưa đồng nhất.
- △README cảnh báo hỗ trợ authenticated media đang chuyển từ tuỳ chọn sang bắt buộc — một phiên bản tương lai sẽ chỉ trả về URL yêu cầu header Authorization, một thay đổi hành vi có thể phá vỡ code cũ cần chuẩn bị trước.
- △Hỗ trợ Deno tồn tại qua import npm:matrix-js-sdk nhưng README ghi rõ đây không phải hỗ trợ chính thức.
Khám Phá Các SDK Matrix Khác
Câu Hỏi Thường Gặp
Matrix JavaScript SDK chạy trên Node.js (bản LTS mới nhất) và trên trình duyệt qua bundler như Webpack hoặc Vite. README cũng liệt kê hỗ trợ Deno qua import npm:matrix-js-sdk, dù ghi rõ Deno chưa được hỗ trợ chính thức.
Matrix JavaScript SDK có hỗ trợ mã hoá đầu-cuối, qua initRustCrypto(), tải các binding WebAssembly của thư viện Rust matrix-sdk-crypto thay vì một cài đặt thuần JavaScript. SDK cũng phủ secret storage, cross-signing, và key backup qua interface CryptoApi.
README ghi v1.1 là phiên bản Matrix server tối thiểu cho Matrix JavaScript SDK. Một tính năng bị gỡ khỏi spec vẫn được SDK hỗ trợ thêm ít nhất 4 bản release nữa sau khi gỡ, theo cam kết tương thích riêng của README.
Gọi initRustCrypto() thay vì initLegacyCrypto() trên Matrix JavaScript SDK, kèm truyền cryptoStore và pickleKey cũ vào createClient — quá trình di chuyển sẽ chạy tự động. Theo dõi tiến độ qua sự kiện CryptoEvent.LegacyCryptoStoreMigrationProgress, báo hoàn tất khi progress và total đều bằng -1.
Matrix JavaScript SDK phát hành theo giấy phép Apache-2.0, theo repository GitHub của dự án.
Matrix JavaScript SDK cung cấp mxcUrlToHttp() để chuyển một mxc:// URI thành URL tải hoặc thumbnail, sau đó cần header Authorization dạng bearer dựng từ client.getAccessToken() cho server yêu cầu theo MSC3916 (Matrix 1.11). README cảnh báo một phiên bản tương lai sẽ chỉ trả về các URL bắt buộc header này.
Vấn đề mà nó giải quyết
Phát triển ứng dụng chat trên mạng liên hợp (federated network) của Matrix nghĩa là phải tự viết polling /sync cho giao tiếp thời gian thực, tự theo dõi trạng thái room và thành viên qua hàng chục loại sự kiện, tự retry khi bị rate limit, và giờ còn phải tự tích hợp một stack mã hoá dựa trên WebAssembly cho mã hoá đầu-cuối — tất cả trước khi viết được một dòng UI chat nào. Matrix JavaScript SDK ra đời vì Element cần đúng bộ công cụ đó cho chính client web và desktop của họ, và họ mở mã nguồn kết quả thay vì để mỗi tác giả client Matrix khác tự viết lại sync, theo dõi trạng thái, và binding Rust-crypto từ đầu.
Trường hợp sử dụng tốt nhất
- •Xây một client chat Matrix chạy trên trình duyệt bằng bundler như Webpack hoặc Vite, dùng mô hình đối tượng Room và RoomMember của SDK thay vì tự phân tích response /sync.
- •Viết một bot hoặc bridge Matrix chạy Node.js, lắng nghe RoomEvent.Timeline để nhận tin nhắn tới và trả lời qua sendEvent, có sẵn tự động thử lại khi bị rate-limit.
- •Thêm mã hoá đầu-cuối vào client Matrix qua initRustCrypto(), gồm cả xác minh thiết bị bằng cross-signing và key backup, mà không phải tự viết lại binding Rust crypto.
- •Di chuyển một client hiện có từ crypto stack cũ sang Rust crypto, theo dõi qua sự kiện CryptoEvent.LegacyCryptoStoreMigrationProgress.
- •Thử nghiệm với một homeserver Matrix trên Deno, dù README ghi rõ đường này chưa chính thức.
Repo liên quan
Vẫn đang phân vân về matrix-js-sdk?
Một cú bấm sẽ gửi câu hỏi kèm trang này cho AI — xem AI nói gì về matrix-js-sdk.