@zencastr/socket-transactions

@zencastr/socket-transactions

Package that enables running transactions over socket.io.

The API is tailored to our use case, namely it expects the action names to be start, stop, pause, resume and recording-check (even though you an use whatever you want), and also that the recordingId is sent as a parameter in the transaction (this just flows from initiator to members in the transaction, the idea was to check if everyone is in the same recording).

Housekeeping

Build: npm run build

Publish new version:

npm run build
npm version path
npm publsh

Or npm version path or npm version major

Run tests:

npm run test

Run tests in watch mode:

npm run test:watch

How-to

Server (sockets service)

1. Install @zencastr/socket-transactions

   npm install @zencastr/socket-transactions -S

2. Call init with the socket.io's server instance (usually called io):

   import { recordingTransactionsCoordinator, connectedSocketsTracker } from '@zencastr/socket-transactions';

   //...

   recordingTransactionsCoordinator.init(io, /optional server timeout for transactions, default is 1000ms/ )

3. When a socket joins a recording:

   connectedSocketsTracker.add(roomId, socket.user.username, socket);

   //roomId is the projectId

4. When a socket disconnects:

   connectedSocketsTracker.removeBySocketId(socket.id);

Client

1. Install @zencastr/socket-transactions

   npm install @zencastr/socket-transactions -S

2. Call init on the connected socket

   import { recordingTransactionsClient } from '@zencastr/socket-transactions';

   //...

   recordingTransactionsClient.init(socket, /optional client side timeout for transactions, default is 1000ms/);

Start a transaction:

try {
    await recordingTransactionsClient.startTransaction({
                actionType: 'start',
                members: ['participantUsername1', 'participantUsername2'],
                roomId: 'projectId',
                recordingId: 'recordingId'
            });
    //transaction completed successfully (everyone in the member list was able to start recording)
} catch(error) {            recordingTransactionsClient.unRegisterActionHandler('start');
        recordingTransactionsClient.unRegisterAbortHandler('start');

    //error is of type FailureReason
    /*
        interface FailureReason {
            failedMemberId?: string;
            /** Timeout occurred at the coordinator level waiting for members to reply */
            isTimeout?: boolean;
            /** Timeout happened at the initiator of the transaction waiting for the coordinator(server) to complete or abort the transaction */
            isInitiatorTimeout?: boolean;
            description: string}        
    */
}

Handle transactions

The client needs to provide a transaction handler. The registration of this handler is done per action type, for example for start:

recordingTransactionsClient.registerActionHandler('start', async recordingId => {
    //check if we are in the right recording
    //start recording
    //throwing an error will make the transaction fail and abort to be sent to all members of the transaction                
});

Optionally the client can supply an abort action handler, for example for start:

recordingTransactionsClient.registerAbortHandler('start', async recordingId => {
    //if recording, stop
    //throwing an error here won't affect the transaction (it's already aborted at this point). It will just log the error to the console
});

There can only be on handler for each action type. It is possible to "unregister" handlers, e.g.:

recordingTransactionsClient.unRegisterActionHandler('start');
recordingTransactionsClient.unRegisterAbortHandler('start');

Edge cases

Transaction is started for participant1 and participant2. Both reply positively, transaction completes. participant3 also replies positively. An abort of the transaction type is sent to the room (e.g. if the transaction was to start recording then the room will get an abort recording) but there's no TransactionAborted sent to the initiator (host).

Notes

• When a participant fails a transaction is aborted immediately, irrespectively of what happens with the others participants.
• The clients can ignore aborts (e.g. abort recording check)
• Only the initiator (host) gets the reason for the failure (via TransactionAborted) and this event only happens once per transaction.