Giao thức provider

Provider là nơi âm nhạc đến từ đó. Let’s DJ không kèm sẵn provider nào.

Provider là một dịch vụ HTTP, không bao giờ là mã mà chúng tôi nạp vào. Chúng tôi không thực thi bản triển khai của bạn, không đặt nó vào sandbox, và không quản lý vòng đời của nó. Điều đó có nghĩa là nó có thể được viết bằng bất kỳ ngôn ngữ nào, và nội dung của bạn không bao giờ đi qua hạ tầng của chúng tôi.

Đặc tả này được viết để đứng một mình. Mã nguồn của Let’s DJ là riêng tư, nên không có bản triển khai nào để đọc song song, và bất cứ thứ gì nó để người đọc tự suy ra sẽ là thứ bạn chỉ biết được khi bị từ chối. Ở chỗ nào đặc tả đưa ra một con số, một giá trị mặc định hay một mã lỗi, đó là cách dịch vụ hoạt động hiện nay. Ở chỗ nào nó không nói gì, chẳng hạn bạn viết bằng ngôn ngữ nào hay lưu tệp ra sao, lựa chọn là của bạn và không có gì ở đây phụ thuộc vào nó.

Các thuật ngữ dùng ở đây

Dịch vụ (the service) là phần backend của Let’s DJ, tại https://api.lets.dj. Mọi đường dẫn trong đặc tả này bắt đầu bằng /providers/ đều tính từ địa chỉ đó. Tất cả đều là HTTPS.

Thư viện (library) là tên gọi của một provider đã được kết nối trong ứng dụng. Người đã kết nối nó là chủ (owner) của thư viện, và một chủ có thể có nhiều thư viện. Mỗi thư viện có sync token riêng, nên hai provider trên cùng một máy là hai thư viện và cần mỗi bên một token.

Một phòng (party) là một phiên. Nó có một Stage, tức màn hình mà mọi người cùng xem: một trang web tại app.lets.dj, mở trong trình duyệt trên tivi hoặc laptop. Khách dùng điện thoại để tìm và xếp bài. Chỉ có Stage phát thứ gì đó.

Track là một bài hát hoặc một video. Danh mục (catalogue) là danh sách các track mà một provider có. Media là bản thân âm thanh hoặc video.

Sync token là bí mật xác định một thư viện với dịch vụ. Media token là một bí mật khác, do bạn tự tạo, để bảo vệ media của bạn.

Bridge là chương trình Let’s DJ phát hành để chia sẻ một thư mục tệp từ một máy tính. Nó là một provider bình thường, và được dùng làm ví dụ ở bất cứ đâu ví dụ có ích. Không có gì trong giao thức này cho nó một đặc quyền mà provider khác không có.

Hai nửa

Danh mục và media đi theo hai đường khác nhau, và sự phân tách này quan trọng.

Siêu dữ liệu danh mục đi đến dịch vụ. Khách tìm bài từ điện thoại, và điện thoại không nên cần liên lạc với máy chủ của bạn: nó có thể đang dùng mạng di động, hoặc ở một mạng hoàn toàn khác. Vì vậy danh mục được phản chiếu vào dịch vụ, và tìm kiếm là một truy vấn duy nhất trên mọi provider trong một phòng.

Media đi thẳng đến Stage. Màn hình lấy các byte trực tiếp từ bạn. Chúng không bao giờ đi qua chúng tôi. Đây là chủ ý: nó giữ độ trễ ở tốc độ mạng nội bộ cho các provider cục bộ, giữ chi phí băng thông của chúng tôi ở mức không, và giữ chúng tôi ngoài đường đi của nội dung.

Danh mục di chuyển theo hướng nào tùy vào việc chúng tôi có liên lạc được với bạn hay không:

• Bạn truy cập được từ internet (một danh mục có bản quyền, một dịch vụ được lưu trữ): chúng tôi kéo về (pull), theo lịch, bằng thông tin xác thực mà chủ thư viện đã đưa cho chúng tôi.
• Bạn không truy cập được (bất cứ thứ gì trong mạng gia đình): bạn đẩy lên (push), mỗi khi thư viện của bạn thay đổi.

Hướng đẩy là cái bridge dùng, và là cái phần còn lại của đặc tả này mô tả. Hướng kéo hiện được triển khai cho một loại provider, một bucket tương thích S3, mô tả tại Lưu trữ đám mây, và vẫn để ngỏ cho bất kỳ nguồn nào khác truy cập được sau này.

Một provider làm gì, theo thứ tự

1. Kết nối. Lấy một sync token bằng cách cho chủ thư viện xem một mã và chờ họ duyệt. Xem Kết nối một provider.
2. Để trình duyệt truy cập được. Stage là một trang HTTPS, nên media của bạn cần một địa chỉ HTTPS với chứng chỉ mà trình duyệt đã tin cậy sẵn. Một provider trong mạng gia đình có thể xin chúng tôi một cái tên và chứng chỉ đi kèm, hoặc tự mang theo. Xem Một cái tên và một chứng chỉ.
3. Phát media. Một đường dẫn, có hỗ trợ yêu cầu range. Xem Phát nội dung media.
4. Gửi danh mục, và ảnh bìa nếu có, và nói bạn là gì: Gửi danh mục và Khả năng (capabilities).
5. Giữ cho nó đúng. Gửi lại khi thư viện thay đổi. Lấy chứng chỉ mới trước khi cái cũ hết hạn. Nếu bạn đã chọn tham gia, nhận và trả lời các job: Trả lời theo yêu cầu.

Quy ước

Nội dung yêu cầu là JSON mã hóa UTF-8, trừ media là các byte, và ảnh bìa là một hình ảnh. Các trường mà đặc tả này không nhắc đến bị bỏ qua. Một chuỗi rỗng được coi là vắng mặt. Số phải là số hữu hạn.

Xác thực là Authorization: Bearer <sync token> trên mọi yêu cầu tới /providers/…, với hai ngoại lệ thuộc về việc kết nối: bắt đầu một pairing không cần thông tin xác thực, và thăm dò (poll) một pairing dùng poll secret thay thế. Xem Kết nối một provider.

Lỗi là một mã trạng thái không phải 2xx và một nội dung JSON, { "error": "<words>" }. Các route thêm gần đây, cho pairing, địa chỉ và chứng chỉ, còn kèm "code": "<machine-readable>". Hãy xử lý theo mã trạng thái, và theo code nếu có. Đừng bao giờ xử lý theo câu chữ, vì chúng viết cho người đọc và có thể thay đổi.

• 400 nghĩa là yêu cầu sai định dạng, và error cho biết phần nào.
• 401 nghĩa là không có bearer token.
• 403 nghĩa là token không được biết đến. Với một sync token, đó là vĩnh viễn: thư viện đã bị xóa. Hãy ngừng thử lại, bỏ token, và kết nối lại, và chỉ khi có ai đó ở đó để duyệt. Mở một lời nhắc pairing trước mặt một người đã đi khỏi còn tệ hơn là cứ dừng.
• 404 nghĩa là thứ bạn nêu tên không có ở đó: một track không xác định khi gửi ảnh bìa, một job không xác định.
• 429, 502 và 503 là lỗi từ phía chúng tôi và đáng thử lại. Hãy chờ đúng khoảng Retry-After nói khi có, và giãn dần khoảng chờ khi không có.

Tương thích. Mọi trường được thêm vào giao thức này cho đến nay đều là tùy chọn, và vắng mặt có nghĩa như trước khi trường đó tồn tại. Một provider viết trước khi có bất kỳ trường nào trong số đó không bị ảnh hưởng.

Tần suất. Dịch vụ hiện không giới hạn tốc độ các route này, và đó không phải là lời mời. Hãy gửi khi thư viện của bạn thay đổi; bridge cũng quét lại mỗi năm phút như một biện pháp dự phòng, vì theo dõi một thư mục âm thầm bỏ sót thay đổi trên các ổ chia sẻ mạng. Thăm dò job khoảng một lần mỗi giây, và chỉ khi bạn đã chọn tham gia.