Component used for OTT applications to limit the number of parallel streaming sessions per registered user, remember the progress where user stopped last time and provide data to analyze detailed play history.
nodejs, version 8.10.0+- install via
nvm(recommended) or any other source
- install via
redisserver, tested with version 3.0.6 (for now, the only supported in-memory storage)
- create
.envfile in root directory.env.examplefile is an example of configuration.envfilePORT,SHARED_KEYandSTORAGEare required, while others are optional
# get dependencies
npm install
# start the system for development
npm start
# start the system for production
npm run startProd# run unit tests with mocha
npm test# run integration tests
npm run integrationTest; PASSED=$?
echo $PASSED # 0 - success, 1 - failClone repository to machine where system will be deployed. Create and configure .env
file.
Install next dependencies:
docker(official instructions)docker-compose(official instructions)
# build (rebuild) and start heartbeat server
docker-compose up --buildHeartbeat server will be ready on port specified in PORT variable inside .env file.
docker build -t heartbeat_server .
docker run -d -e STORAGE=redis -e REDIS_URL='redis://192.168.18.95:4545' -e SHARED_KEY=asdfasdf -p 5555:3000 heartbeat_server:latestHeartbeat server needs configured clients and backend server to work properly.
The process starts with requesting resource URL from backend. On client's request with resource id, user authentication token and
other necessary data, backend responds with: heartbeat_token, heartbeat_cycle and progress.
Client saves heartbeat_token in local storage and begins to reproduce the resource at position defined
by progress variable (which describes the time elapsed from beginning of the resource). In the same moment,
client sets periodic timer with period of time defined in heartbeat_cycle variable. Periodic timer is active
during entire player session.
Every time when timer expires, client sends request to heartbeat server.
POST https://path.to.heartbeat.server/
Headers:
Content-Type: "application/json"
Request body:
{
"heartbeat_token": "U2FsdGVkX1...", // last received heartbeat_token
"progress": 42 // current progress of playing content
}
Path to heartbeat server has to be hardcoded into client application. heartbeat_token represents the last received
token from heartbeat server or backend that is located in local storage. progress stands for number of seconds
elapsed from beginning of playing content in the moment of sending the heartbeat.
Heartbeat server responds in two different ways; positive and negative
When response is positive, it means that client receives new heartbeat_token and continues to reproduce current
content. Newly received heartbeat_token has to be saved in local storage and be used for next heartbeat request.
Status: 200 OK
Response body:
{
"heartbeat_token": "VkX1844Ibx..." // new heartbeat token
}
When response is negative, it means that client has to stop reproducing the content and inform user about reasons. The negative response contains appropriate message to the user. The message always remains the same, so client application can rely on HTTP status code (412 Precondition Failed).
Status: 412 Precondition Failed
Response body:
{
"error": "Your session limit has been exceeded."
}
Another negative response occurs when heartbeat_token cannot be parsed by heartbeat server which
responds with HTTP status code (406 Not Acceptable).
Status: 406 Not Acceptable
Response body:
{
"error": "Heartbeat token is not valid."
}
Client sends request to backend in order to get resource URL of playable content. Backend then forms heartbeat_data.
heartbeat_data = {
"user_id": 13, // int
"asset_id": 14, // int
"heartbeat_cycle": 3, // decimal
"reject_strategy": "LEAST_RECENT", // string
"cycle_lower_tolerance": 0.3, // decimal
"cycle_upper_tolerance": 0.8, // decimal
"timestamp": "2018-06-05T16:16:14.418Z", // string
"session_limit": 1, // int
"checking_threshold": 3, // int
"sessions_edge": 10 // int
}
heartbeat_data consists of:
user_id- represents user identifier in database.asset_id- playable resource identifier in database.heartbeat_cycle- number of seconds which represents a period of sending heartbeat requestsreject_strategy- strategy for rejecting users. supported strategies: ['LEAST_RECENT', 'MOST_RECENT']cycle_lower_tolerance- number of seconds which represents time tolerance on receiving heartbeat request before time set inheartbeat_cycle.cycle_upper_tolerance- number of seconds which represents time tolerance on receiving heartbeat request after time set inheartbeat_cycle.timestamp- time of sending heartbeat in ISO 8601 format (Combined date and time representation).session_limit- number of allowed parallel active sessions for particular user.checking_threshold- number of heartbeats in current session after which the system starts to check active session limit. used for tracking only real active sessions and ignoring ones that have only been started.sessions_edge- maximum number of active sessions that can persist in local in-memory database. used for preventing cache overfill while spamming heartbeat requests.
After forming heartbeat_data, it has to be encrypted into heartbeat_token
with the same key that heartbeat server uses for encrypting heartbeat_data.
- Algorithm: AES 256 CBC
- IV - random generated 16 bytes (32 bytes when converted to hex)
- Salt - random generated 16 bytes (32 bytes when converted to hex)
- Key derivation function (used to generate key from passphrase) - PBKDF2
- Iterations: 3
- Hashing algorithm: SHA1
- Key size: 32 bytes
- Encrypted data is being encoded in Base64
After data is encrypted, the heartbeat_token is created by concatenating
Salt (16 bytes converted in hex - 32 bytes), IV (16 bytes converted in hex - 32 bytes)
and AES-256-CBC encrypted data encoded with base64. Format is shown below:
"[Salt (0-31 bytes)] | [IV (32-63 bytes)] | [Encrypted data (64> bytes)]"