socketshark 0.3.0

Authentication

WebSockets clients can authenticate using the auth event using ticket authentication. For more information about ticket authentication see the Ticket-based authentication for session-based apps section.

The auth event takes an optional method (ticket is the only currently supported authentication method, and the default), and a ticket argument, containing the login ticket.

Example client request:

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

Example server responses (successful and unsuccessful):

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

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

Subscriptions

WebSocket clients can subscribe to any number of topics. Messages can be passed from the client to the server, and pushed from the server to the client at any time while subscribed to a topic. For example, a client may subscribe to an object ID, and the server may send a message whenever the object is updated. The server may include extra data when subscribing or unsubscribing. For example, the server might send the current state of the object when subscribing.

Topics are unique, and a client can be subscribed to each topic at most once. Extra fields can be associated with a subscription which are passed along with all subscription commands. For example, a client could be required to indicate the organization ID for a particular object subscription so that the service can authorize and process the message properly.

{"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 callbacks

An optional HTTP endpoint can be configured to authenticate a WebSocket session. The authentication endpoint can return authentication-related fields that can be configured (e.g. a user ID and/or session ID).

The following optional HTTP endpoints can be configured for each SocketShark service:

• authorizer: URL to call to authorize a new subscription.

• before_subscribe: URL to call when a client attempts to subscribe.

• on_subscribe: URL to call after a client subscribed to a topic.

• on_message: URL to call when a client sends a message to a topic.

• before_unsubscribe: URL to call when a client attempts to unsubscribe.

• on_unsubscribe: URL to call after a client unsubscribed from a topic.

• on_authorization_change: URL to call after if any authorizer fields change during periodic authorization.

Each HTTP endpoint is accessed via a POST request containing a JSON body.

Service-specific endpoints receive any client-supplied extra fields that are configured for the particular service, as well as authentication-related fields returned by the authentication endpoint.

HTTP endpoints should return a JSON dict containing a status field with the value ok or error. In case of an error, an error text may be specified in the error field.

{"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."}

Publishing messages to clients

To publish a message, a service needs to publish a Redis message to the appropriate subscription. The message must be JSON-formatted, and contain the subscription field, a free-form data dict and any optional filters (if the service has configured filter fields). The channel name corresponds to the subscription (service.topic), but a Redis channel prefix may be optionally configured.

When a filter field is specified, the message is only published to sessions that match the filter. For example, a message could only be sent to sessions matching a specific user ID.

Example Redis PUBLISH command:

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

Out-of-order message filtering

Since messages published by services may not necessarily arrive in the desired order, SocketShark supports message filtering. For example, you might be publishing updates for a versioned object to Redis but they may arrive out-of-order due to network latency. Messages can be tagged with an order, and SocketShark will filter out older messages if a newer message arrives first. A float order can be supplied both in the before_subscribe callback’s return value and in any published message using the order option in the options dict. Incoming messages with an order that is lower or equal to the last received highest order will be filtered out. Multiple independent orders can be specified using the optional order_key option.

In the following example, the “initiating” and “completed” messages, as well as the “h” and “hello” messages will be delivered to subscribers:

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",
  }
}

Message throttling

Messages published by services can be throttled by specifying the time in seconds using the throttle option in the options dict in the published message.

For a constant stream of messages that are coming in shorter than the throttle period, the client will receive the first message immediately, then a message every throttle period until the stream ends, and then the final message will be sent after another throttle period elapses.

Multiple independent throttles can be specified using the optional throttle_key option. Throttling is performed per subscription per session.

In the example below, if the three messages are published at the same time, the first one will be delivered to subscribers immediately, the second one will be ignored, and the third message will be delivered to subscribers after 100ms pass.

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,
  }
}

Ticket-based authentication for session-based apps

Most web applications use an HTTP-only cookie that stores a session ID for authentication. Since WebSocket connections are initiated via JavaScript, there is no access to the session ID via the cookie. To facilitate authentication of WebSocket connections, authentication with single-use tickets should be used:

• Implement a public “ticket” endpoint in your application. The endpoint should validate the user’s session and return a random-generated short-lived ticket associated to the user’s session ID. For example, a UUID4 ticket may be computed and stored in Redis with a 30 second expiration using the SETEX command, where the key name corresponds to the ticket (the UUID4), and the key value is the user’s session ID.

• Implement an internal ticket validation in your application. The endpoint should be configured as the auth endpoint in SocketShark. It should retrieve and return the user’s session ID, and at the same time invalidate the ticket. Any other user information (e.g. user ID) may also be returned. A Redis pipeline should be used to retrieve and delete the ticket.

• When the JavaScript code connects to SocketShark, it should first request a ticket via the public ticket endpoint, then connect to SocketShark and issue the authentication event with the obtained ticket.

Authorization with microservices

Suppose a user can access products from a set of authorized organization IDs. The auth service stores a list of users and corresponding organization IDs that users have access to. The product service stores a list of products with corresponding organization IDs but is not aware whether a user is authorized to access a specific organization (and therefore product). Subscriptions are per product and should only be authorized if the user can access the product’s organization. To solve this problem without requiring the services to directly talk to each other, extra fields can be used in SocketShark:

• Add the user ID in SocketShark’s authentication configuration under auth_fields, and the organization ID as under the product service’s extra_fields.

• Return the user ID in the auth service’s authorization endpoint. SocketShark will supply it in all subsequent requests to service endpoints.

• When the client subscribes to the product service (subscription example: product.PROD_ID), it must also supply the product’s organization ID as an extra field.

• Set up an authorizer URL for the product service that points to the auth service. The auth service should authorize a subscription if the given user has access to the given organization. Since the authorizer doesn’t have access to the product database, it doesn’t validate the product ID.

• Set up a before_subscribe URL for the product service that points to the product service. The product service should allow a subscription if the subscription’s product ID matches the given organization ID. Since the organization ID is already validated by the authorizer, no further validation is necessary.