The plurid-routes-server is to be used alongside plurid applications spanning multiple origins in order to resolve the plurid plane routes at client request time.

Contents

• About
• Install
• Setup
• Requests
• Codeophon

About

The plurid-routes-server will respond to a route request with the suitable element identification data, based on calling the functions (queryRoute, registerRoute, verifyToken) which are passed at instantiation time.

Install

Install the package

npm install @plurid/plurid-routes-server

or

yarn add @plurid/plurid-routes-server

Install the peer dependencies

npm install \
    @plurid/deon \
    @plurid/plurid-functions \
    body-parser \
    express

or

yarn add \
    @plurid/deon \
    @plurid/plurid-functions \
    body-parser \
    express

Setup

The PluridRoutesServer must be instantiated with the following functions:

• queryRoute: QueryRoute
• registerRoute: RegisterRoute
• verifyToken: VerifyToken

which will provide the functionality.

An example (tests/index.xs), with a mock-up initialRoutes, and in-memory (Map) routes registration.

// #region imports
import PluridRoutesServer, {
    QueryRoute,
    RegisterRoute,
    VerifyToken,
    RouteElement,
} from '@plurid/plurid-routes-server';
// #endregion imports



// #region data
/**
 * Mock-up data.
 *
 * In the real case, the `initialRoutes` would be loaded from a database,
 * and the `validToken` would assume an authentication/authorization mechanism.
 */

/**
 * Record of `RouteElement | any` to account for the invalid example
 */
const initialRoutes: Record<string, RouteElement | any> = {
    '/example-valid-registered': {
        id: '/example-valid-registered',
    },
    '/example-valid-elementql': {
        elementql: '/example-valid-elementql',
    },
    '/example-invalid': {
    },
};

/**
 * Map of `any` to account for the invalid example.
 * Regular case assumes `Map<string, RouteElement>`
 */
const routes: Map<string, any> = new Map(
    Object.entries(initialRoutes),
);

const validToken = 'token';
// #endregion data



// #region functions
const queryRoute: QueryRoute = async (
    route,
) => {
    console.log('queryRoute', route);

    return routes.get(route);
}

const registerRoute: RegisterRoute = async (
    route,
    data,
) => {
    console.log('registerRoute', route, data);

    routes.set(route, data);

    return true;
}

const verifyToken: VerifyToken = async (
    token,
) => {
    console.log('verifyToken', token);

    return token === validToken;
}
// #endregion functions



// #region server
const server = new PluridRoutesServer({
    queryRoute,
    registerRoute,
    verifyToken,
});


server.handle().post(
    '/cache-reset',
    (request, response) => {
        try {
            if (!request.body.token) {
                console.log('cacheReset bad request');
                response
                    .status(405)
                    .send('Bad Request');
                return;
            }

            if (request.body.token !== validToken) {
                console.log('cacheReset invalid token');
                response
                    .status(403)
                    .send('Forbidden');
                return;
            }

            console.log('cacheReset');
            server.cacheReset();

            response.send('Cache Reseted');
        } catch (error) {
            console.log('cacheReset error', error);

            response
                .status(500)
                .send('Server Error');
        }
    }
);

server.cacheLoad(routes);

server.start();
// #endregion server

The example server can be tested with cURL (more examples in tests/requests.md)

Request:

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"route":"/example-valid-registered"}' \
    -H "Authorization: Bearer token" \
    "http://localhost:8080/route"

Expected:

{"id":"/example-valid-registered"}

The Content-Type header can be application/json or application/deon, with the adequate data serialized into the body (json or deon).

The authentication token can be passed in the Authorization: Bearer header, or directly as a data field in the body.

Requests

The PluridRoutesServer handles two HTTP POST endpoints:

• ENDPOINT_ROUTE
• ENDPOINT_REGISTER

The ENDPOINT_ROUTE body must respect the interface

interface EndpointRoute {
    token?: string;
    route: string;
}

The ENDPOINT_REGISTER body must respect the interface

interface EndpointRegister {
    token?: string;
    route: string;
    data: RouteElement;
}

The default endpoint values are

• ENDPOINT_ROUTE : /route
• ENDPOINT_REGISTER : /register

and they can be overwritten by environment variables

• ENDPOINT_ROUTE : process.env.PLURID_ROUTES_SERVER_ENDPOINT_ROUTE
• ENDPOINT_REGISTER : process.env.PLURID_ROUTES_SERVER_ENDPOINT_REGISTER

Codeophon

• licensing: delicense
• versioning: αver