socketshark 0.5.0

身份验证

WebSocket客户端可以使用auth事件通过票证认证进行认证。有关票证认证的更多信息，请参阅基于票证的会话应用程序认证部分。

认证事件（auth）可以接收一个可选的method参数（目前仅支持默认的ticket认证方式），以及一个包含登录票据的ticket参数。

示例客户端请求

{"event": "auth", "method": "ticket", "ticket": "SECRET_AUTH_TICKET"}

示例服务器响应（成功和失败的情况）

{"event": "auth", "status": "ok"}

{"event": "auth", "status": "error", "error": "Authentication failed."}

订阅

WebSocket客户端可以订阅任意数量的主题。在订阅主题的同时，客户端可以随时将消息传递给服务器，服务器也可以将消息推送给客户端。例如，客户端可以订阅一个对象ID，服务器在对象更新时可以发送消息。在订阅或取消订阅时，服务器可能包含额外的数据。例如，服务器可能在订阅时发送对象的当前状态。

主题是唯一的，客户端最多只能订阅每个主题一次。可以与订阅关联额外的字段，这些字段会随着所有订阅命令一起传递。例如，客户端可能需要指定特定对象订阅的组织ID，以便服务正确授权和处理消息。

{"event": "subscribe", "subscription": "books.book_1"}

{"event": "subscribe", "subscription": "books.book_1", "status": "ok"}

{
  "event": "subscribe",
  "subscription": "books.book_1",
  "status": "error",
  "error": "Book does not exist."
}

{
  "event": "subscribe",
  "subscription": "books.book_1",
  "status": "ok",
  "data": {
    "title": "Everyone poops"
  }
}

{"event": "subscribe", "subscription": "books.book_1", "author_id": "author_1"}

{
  "event": "subscribe",
  "subscription": "books.book_1",
  "author_id": "author_1",
  "status": "ok"
}

{
  "event": "message",
  "subscription": "books.book_1",
  "data": {
     "action": "update",
     "title": "New book title"
  }
}

{
  "event": "message",
  "subscription": "books.book_1",
  "status": "ok",
  "data": {"status": "Book was updated."}
}

{
  "event": "message",
  "subscription": "books.book_1",
  "status": "error",
  "error": "Book could not be updated."
}

{"event": "unsubscribe", "subscription": "books.book_1"}

{"event": "unsubscribe", "subscription": "books.book_1", "status": "ok"}

{
  "event": "unsubscribe",
  "subscription": "books.book_1",
  "status": "error",
  "error": "Subscription does not exist."
}

{"event": "ping", "data": "foobar"}

{"event": "pong", "data": "foobar"}

HTTP回调

可以配置一个可选的HTTP端点来验证WebSocket会话。认证端点可以返回可以配置的认证相关字段（例如，用户ID和/或会话ID）。

以下可选的HTTP端点可以为每个SocketShark服务配置

• 授权器：调用以授权新订阅的URL。

• 在订阅之前：客户端尝试订阅时调用的URL。

• 在订阅后：客户端订阅主题后调用的URL。

• 在发送消息时：客户端向主题发送消息时调用的URL。

• 在取消订阅之前：客户端尝试取消订阅时调用的URL。

• 在取消订阅后：客户端从主题取消订阅后调用的URL。

• 在授权变更后：如果在定期授权过程中任何授权器字段发生变化，则调用此URL。

每个HTTP端点通过包含JSON主体的POST请求访问。

特定于服务的端点接收为特定服务配置的任何客户端提供的额外字段以及由认证端点返回的认证相关字段。

HTTP端点应返回一个包含具有值ok或error的status字段的JSON字典。如果发生错误，可以在error字段中指定错误文本。

{"ticket": "SECRET_AUTH_TICKET"}

{"status": "ok", "user_id": "user_1", "session_id": "session_1"}

{"status": "error", "error": "Authentication failed."}

{
  "subscription": "books.book_1",
  "user_id": "user_1",
  "session_id": "session_1",
  "author_id": "author_1"
}

{"status": "ok"}

{"status": "error", "error": "Author ID does not match book ID."}

{
  "event": "unsubscribe",
  "subscription": "books.book_1",
  "error": "Unauthorized."
}

{
  "subscription": "books.book_1",
  "user_id": "user_1",
  "session_id": "session_1",
  "author_id": "author_1",
  "data": {
    "action": "update",
    "title": "New book title"
  }
}

{"status": "ok"}

{"status": "ok", "data": {"status": "Book was updated."}

{"status": "error", "error": "Book could not be updated."}

向客户端发布消息

要发布一条消息，服务需要将一条 Redis 消息发布到相应的订阅。消息必须是 JSON 格式，并包含 subscription 字段、自由格式的 data 字典以及任何可选的过滤器（如果服务已配置过滤器字段）。通道名称对应订阅（service.topic），但可以可选地配置 Redis 通道前缀。

当指定过滤器字段时，消息只会被发布到与过滤器匹配的会话。例如，一条消息可能只能发送给匹配特定用户 ID 的会话。

Redis PUBLISH 命令示例

PUBLISH books.book_1 {
  "subscription": "books.book_1",
  "data": {
    "action": "update",
    "title": "New title"
  }
}

过滤顺序错误的消息

由于服务发布的消息可能不一定按预期顺序到达，SocketShark 支持消息过滤。例如，您可能正在将版本化对象的更新发布到 Redis，但由于网络延迟，它们可能到达顺序不正确。消息可以标记为顺序，并且 SocketShark 会在新消息首先到达时过滤掉旧消息。可以在 before_subscribe 回调函数的返回值和任何发布消息中使用 options 字典中的 order 选项提供浮点顺序。具有较低或等于最后收到的最高顺序的顺序的传入消息将被过滤掉。可以使用可选的 order_key 选项指定多个独立的顺序。

在以下示例中，“initiating”和“completed”消息，以及“h”和“hello”消息将被投递给订阅者。

PUBLISH calls.call_1 {
  "subscription": "calls.call_1",
  "options": {
      "order": 1,
      "order_key": "call_1.status",
  },
  "data": {
    "status": "initiating",
  }
}

PUBLISH calls.call_1 {
  "subscription": "calls.call_1",
  "options": {
      "order": 3,
      "order_key": "call_1.status",
  },
  "data": {
    "status": "completed",
  }
}

PUBLISH calls.call_1 {
  "subscription": "calls.call_1",
  "options": {
      "order": 2,
      "order_key": "call_1.status",
  },
  "data": {
    "status": "ringing",
  }
}

PUBLISH calls.call_1 {
  "subscription": "calls.call_1",
  "options": {
      "order": 1,
      "order_key": "call_1.note",
  },
  "data": {
    "note": "h",
  }
}

PUBLISH calls.call_1 {
  "subscription": "calls.call_1",
  "options": {
      "order": 3,
      "order_key": "call_1.note",
  },
  "data": {
    "note": "hello",
  }
}

PUBLISH calls.call_1 {
  "subscription": "calls.call_1",
  "options": {
      "order": 2,
      "order_key": "call_1.note",
  },
  "data": {
    "note": "hell",
  }
}

消息节流

可以在发布消息的 options 字典中使用 throttle 选项指定秒数来限制服务发布消息的速度。

对于短于限制周期的恒定消息流，客户端将立即接收到第一条消息，然后每隔限制周期接收一条消息，直到流结束，然后在另一个限制周期结束后发送最后一条消息。

可以使用可选的 throttle_key 选项指定多个独立的限制。限制是按订阅和会话进行的。

在以下示例中，如果三条消息同时发布，第一条将立即投递给订阅者，第二条将被忽略，第三条消息将在 100 毫秒后投递给订阅者。

PUBLISH calls.stats {
  "subscription": "calls.stats",
  "options": {
      "throttle" 0.1,
  },
  "data": {
    "n_calls": 1,
  }
}

PUBLISH calls.stats {
  "subscription": "calls.stats",
  "options": {
      "throttle" 0.1,
  },
  "data": {
    "n_calls": 2,
  }
}

PUBLISH calls.stats {
  "subscription": "calls.stats",
  "options": {
      "throttle" 0.1,
  },
  "data": {
    "n_calls": 3,
  }
}

基于票据的身份验证用于基于会话的应用程序

大多数网络应用程序使用只包含 HTTP 的 cookie 存储用于认证的会话 ID。由于 WebSocket 连接是通过 JavaScript 初始化的，因此无法通过 cookie 访问会话 ID。为了便于 WebSocket 连接的认证，应使用一次性票据进行认证。

• 在您的应用程序中实现一个公开的“ticket”端点。端点应验证用户的会话，并返回与用户会话 ID 关联的随机生成的短期票据。例如，可以计算 UUID4 票据并将其存储在 Redis 中，使用 SETEX 命令设置 30 秒的过期时间，其中键名对应于票据（UUID4），键值是用户的会话 ID。

• 在您的应用程序中实现内部票据验证。端点应配置为 SocketShark 中的认证端点。它应检索并返回用户的会话 ID，同时使票据失效。还可以返回其他用户信息（例如，用户 ID）。应使用 Redis 管道检索和删除票据。

• 当 JavaScript 代码连接到 SocketShark 时，它应首先通过公共票据端点请求票据，然后连接到 SocketShark 并使用获得的票据发出认证事件。

与微服务进行授权

假设用户可以从一组授权的组织ID访问产品。认证服务存储用户及其可访问的组织ID列表。产品服务存储具有相应组织ID的产品列表，但不知道用户是否有权访问特定组织（因此产品）。订阅是按产品进行的，并且只有在用户可以访问产品的组织时才应授权。为了在不要求服务直接通信的情况下解决这个问题，可以在SocketShark中使用额外字段。

• 在SocketShark的认证配置中的 auth_fields 下添加用户ID，在产品服务的 extra_fields 下添加组织ID。

• 在认证服务的授权端点返回用户ID。SocketShark将在所有后续请求中向服务端点提供它。

• 当客户端订阅产品服务时（订阅示例：product.PROD_ID），它还必须作为额外字段提供产品的组织ID。

• 为产品服务设置一个指向认证服务的 authorizer URL。如果给定用户有权访问给定组织，认证服务应授权订阅。由于授权器无法访问产品数据库，它不验证产品ID。

• 为产品服务设置一个指向产品服务的 before_subscribe URL。如果订阅的产品ID与给定组织ID匹配，产品服务应允许订阅。由于组织ID已经通过授权器验证，因此不需要进一步验证。