Handling API calls

In general, you should statically check if you handled all possible API call types and never trust user input.

API handler object

A pattern for handling API calls we use is handler objects. They are defined such that:

async function HandleCallCategory ( req: API.CallCategory, ws?: Socket ): Promise<API.CallResponseType> {
    if ( req.type in SomeHandler ) {
        return await SomeHandler[req.type]( req, ws );
    }
}

const SomeHandler: {
    [Key in API.CallCategory['type']]: (req: Uncertain<Extract<API.CallCategory, { type: Key }>>, ws?: Socket) => Promise<RequestResponseMap[Key]>
} = {
    'request-type-A': async (req, ws) => { ... },
    ...
}

This pattern makes sure all API calls of a given type are handled and that they return the correct response type.

Request handler wrapper

Sometimes, for example when handling several requests that require a session we find ourselves repeating code.

In order to amend this, we can create a function which generates a handler. An example of this is SessionHandler, which translates an async (session, req, ws) => res function into an async (req, ws) => res | API.InvalidSession. It is used like this:

const SomeHandler: { ... } = {
    'some-session-request': SessionHandler( async (session, req, ws) => { ... } )
}

A small caveat with this is that typescript might not have enough computing power to infer the generic types of the wrapper and not provide you with intellisense. You might need to provide it with the generic types in such case.

Types

The handlers are fed an Uncertain<T> request. This type makes it so all fields are possibly undefined (and omits the request type for your convenience, since its already known). This is done so that you need to check if user input if valid, preferably with typeof rather than != undefined.

Subscribing Web Sockets

API.Subscribe* calls will subscribe a Web Socket to a Heartbeat event. The pattern for handling this is as follows:

if ( wsSubscriptions.canSubscribe( ws, 'subscription-type' ) ) {
    function addOrUpdate ( data: Tdata, kind: 'added' | 'updated' ) {
        ws.send( {
            type: 'heartbeat-type',
            kind: kind,
            data: { id: data.id, ... }
        } );
    }

    function remove ( data: Tdata ) {
        ws.send( {
            type: 'heartbeat-type',
            kind: 'removed',
            dataId: data.id // do not use "id:". it is reserved
        } );
    }

    var subscription = CreatePoolSubscription<Tdata>(
        somePool,
        data => addOrUpdate( data, 'added' ),
        data => remove( data ), {
            ignoreExistingEntries: true // we ignore existing entries because they are sent with the response to this request
        }
    ).ReactTo( 
        data => data.reactiveA, 
        data => addOrUpdate( data, 'updated' )
    ).ReactTo( 
        data => data.reactiveB,   
        data => addOrUpdate( data, 'updated' )
    );

    wsSubscriptions.createSubscription( ws, 'subscription-type', subscription.unsubscribe );
}