API Server

23 min

L'API server expose les éléments suivants (named exports) :

la méthode start qui permet d'initialiser l'application Express

la méthode getPubSub qui permet de récupérer l'instance PubSub pour la gestion des subscriptions graphQL

les utilitaires des resolvers graphQL OK et KO

Les imports depuis l'OAV :

import {
  start,
  getPubSub,
  OK,
  KO
} from '@fasstech/oip-starter-utils/server';

Méthode start

La méthode start initialise l'application Express de l'OAV. Elle prend en paramètre un objet de configuration. La méthode retourne l'application Express app

Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // options
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Options requises

graphql

Un objet qui contient la liste des définitions des types et des resolvers graphQL de l'OAV est attendu en valeur. Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  graphql: {
    resolvers: { /* ... */ },
    typeDefs: { /* ... */ }
  }
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

[info] À partir de la version 3.4.5 de @fasstech/oip-starter-utils, l'option graphql accepte également une propriété optionnelle security

[info] À partir de la version 3.7.0 de @fasstech/oip-starter-utils, l'option graphql.security accepte deux propriétés optionnelles supplémentaires : - maxCoercionErrors - maxErrors

La propriété graphql.security permet de configurer certaines limites de protection contre les attaques de type DoS au niveau de l'endpoint graphQL.

Un objet de configuration est attendu en valeur de la forme suivante :

const security = {
  payloadLimit: '50kb',
  armorConfig: { /* ...graphql-armor config */ },
  maxCoercionErrors: 50,
  maxErrors: 10
};

la propriété payloadLimit permet de définir la taille maximale autorisée de la payload des requêtes graphQL entrantes. Par défaut, la limite est définie sur 50kb.

la propriété maxCoercionErrors permet de configurer le nombre maximal d'erreurs de coercition de variables (variable coercion errors) qu'Apollo Server acceptera avant de rejeter une requête avec un code d'état 400. Limite définie à 50 par défaut.

la propriété maxErrors permet de limiter le nombre maximal d'erreurs de validation GraphQL accumulées avant qu'Apollo Server n'arrête le processus de validation et ne rejette la requête. Limite définie à 10 par défaut.

la propriété armorConfig permet de configurer les valeurs des seuils de sécurité gérés par la lib graphql-armor. Les règles de validation suivantes sont configurables :

field suggestions

cost limit

max aliases

max depth

max directives

max tokens

Concernant l'option graphql.security.armorConfig, @fasstech/oip-starter-utils utilise par défaut les valeurs de la configuration par défaut de la lib graphql-armor sauf pour la limite costLimit.maxCost qui est définie sur 100 au lieu de 5000

Se référer à la documentation de la lib graphql-armor pour connaitre le type attendu des objets de configuration acceptés et leurs valeurs par défaut.

Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  graphql: {
    // ...
    security: {
      payloadLimit: '1kb',
      maxCoercionErrors: 20,
      maxErrors: 5,
      armorConfig: {
        maxDepth: {
          n: 3,
        },
        costLimit: {
          maxCost: 20,
        },
        maxTokens: {
          n: 100,
        },
      },
    },
  },
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

session

[info] À partir de la version 3.4.1, sessionId qui correspond à l’identifiant de la session de navigation en cours, est désormais transmis en paramètre à la callback de résolution de l’entité Project.

Un objet qui contient les méthodes de résolution de l'entité Project à partir du contexte client est attendu en valeur. Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { initProjectFromContext } from './init-project-from-context.mjs';
import { getMockContext } from './get-mock-context.mjs';

const serverCfg = {
  session: {
    resolveMockProject: () => initProjectFromContext(getMockContext()),
    resolveProject: initProjectFromContext
  }
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Se référer à cette documentation pour plus de détails.

[info] À partir de la version 3.4.6, l'option session accepte également une propriété optionnelle resolveContext qui permet de définir la callback de résolution du contexte client à partir du token lors du décrochage sur l'OAV.

Par défaut, la lib résout le contexte client grâce à un appel au service Fasst Sessions ou équivalent avec le token passé en paramètre. L'URL du service est résolu grâce à la variable d'environnement SESSIONS_SERVICE_URL

Si vous souhaitez implémenter votre logique personnalisée de résolution du contexte client à partir du token de décrochage, vous devez utiliser la propriété session.resolveContext pour définir la callback de résolution du contexte client.

Signature de resolveContext : async (token) => context

La callback reçoit en paramètre le token de décrochage et doit impérativement retournée un objet représentant le contexte client résolu.

Exemple :

import { resolveContext } from './resolve-context.mjs';

const serverCfg = {
  session: {
    resolveMockProject,
    resolveProject,
    resolveContext,
  }
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

[info] À partir de la version 3.8.0, l'option session accepte également une propriété optionnelle resolveMetadata qui permet de définir la fonction de rappel de résolution des métadonnées de session.

Si définie, cette fonction de rappel permet de résoudre les métadonnées qui seront injectées dans l'objet session (gérer par la dépendance express-session) pour le projet en cours.

Signature : async ({ projectId: string, sessionId: string }) => Promise<object>

La fonction de rappel reçoit en paramètre un objet qui contient projectId et sessionId et doit retourner un objet qui représente les métadonnées de la session.

Exemple :

import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { resolveMetadata } from './resolve-metadata.mjs';

const serverCfg = {
  session: {
    // ...
    resolveMetadata
  }
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

businessRoutes

Une instance d'un router express est attendu en valeur. Les routes et les fonctions middleware spécifiques à l'OAV seront alors chargées et initialisées par l'application express. Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';
import businessRoutes from './routes.mjs';

const serverCfg = {
  businessRoutes
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Se référer à cette documentation pour plus de détails.

extendProcess

À partir de la version 3.4.1, le sessionId est désormais accessible depuis l’objet Process reçu en paramètre de la callback extendProcess.

La callback qui permet d'étendre le type Process est attendue en valeur. Cette callback reçoit en paramètre l'objet Process. Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { extendProcess } from './extend-process.mjs';

const serverCfg = {
  extendProcess
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Se référer à cette documentation pour plus de détails.

logger

[info] Propriété disponible à partir de la version 3.8.0 de la bibliothèque.

L'instance d'un logger est attendu en valeur.

Exemple :

import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { logger } from '@fasstech/logger';

const serverCfg = {
  logger,
  // ...
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Options optionnelles

basePath

[info] Disponible à partir de la version 3.8.0 de la bibliothèque @fasstech/oip-starter-utils.

Une chaîne de caractères qui définit le préfixe des URLs exposées par le serveur :

/u/token

/session

/graphqlwsurl

/graphql

Exemple :

import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  basePath: '/api'
};

// /u/token       -> /api/u/token
// /session       -> /api/session
// /graphql       -> /api/graphql
// /graphqlwsurl  -> /api/graphqlwsurl

const { app } = await start(serverCfg);

// init your business logic here
void app;

corsOptions

Option disponible à partir de la version 3.4.0

Un objet permettant la configuration de la mécanique CORS est attendu en valeur. La lib utilise la dépendance npm cors. Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation de la dépendance npm cors

Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const WHITE_LIST = [ /* URLs */ ]

const serverCfg = {
  // ...
  corsOptions: {
      origin: (origin, callback) => {
      if (!origin || WHITE_LIST.includes(origin)) {
        callback(null, true);
      } else {
        callback(new Error('Origin not allowed!'));
      }
    },
    credentials: true,
    methods: 'GET,HEAD,OPTIONS,PUT,PATCH,POST,DELETE',
    allowedHeaders: ['Origin', 'Content-Type', 'Accept', 'Authorization'],
    preflightContinue: false
  }
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Se référer à cette documentation pour plus de détails.

cookieOptions

Option disponible à partir de la version 3.4.0

Un objet permettant la configuration des attributs du cookie de session est attendu en valeur. La lib utilise la dépendance npm express-session. Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation des options liées au cookie de la dépendance npm express-session

Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  cookieOptions: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: process.env.NODE_ENV === 'production',
    sameSite: process.env.NODE_ENV === 'production' ? 'none' : false
  }
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Se référer à cette documentation pour plus de détails.

resolveFirstView

Option disponible à partir de la version 3.4.0

La callback de la résolution conditionnelle de la première vue du parcours est attendue en valeur. Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { resolveFirstView } from './resolve-first-view.mjs';

const serverCfg = {
  // ...
  resolveFirstView,
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Se référer à cette documentation pour plus de détails.

dataProtectionConfigPath

Option disponible à partir de la version 3.4.4

Le path du fichier de configuration des règles de politiques de données de l'OAV est attendu en valeur. Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  dataProtectionConfigPath: './data-protection.config.mjs',
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

helmetConfig

Option disponible à partir de la version 3.6.0

Un objet permettant la configuration des headers de sécurité est attendu en valeur. La lib utilise la dépendance npm helmet. Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation de la dépendance.

Ex. :

import { start as startServer } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  helmetConfig: {
    crossOriginResourcePolicy: { 
      policy: "same-site",
    },
  },
};

const { app } = await startServer(serverCfg);

// init your business logic here
void app;

Méthode getPubSub

La méthode getPubSub permet de récupérer l'instance PubSub nécessaire à la gestion des subscriptions graphQL. L'instance PubSub doit être définie au niveau du fichier de configuration OIP de l'OAV. Ex. :

import { getPubSub } from '@fasstech/oip-starter-utils/server';

export default {
  debug: true,
  database: {
    url: process.env.OIP_MONGO_DB_URL
  },
  rabbitMQ: {
    name: 'fasst-oip-core'
  },
  views: {
    config: '../viewsConfig'
  },
  tasks: {
    // ...
  },
  pubsub: getPubSub() // PubSub
};

L'instance PubSub est initialisée grâce à la dépendance @fasstech/rabbitmq-helper qui nécessite un service RabbitMQ.

Les utilitaires graphQL OK et KO

Les utilitaires OK et KO permettent de standardiser les réponses des resolvers graphQL de l'OAV.

Signature des fonctions :

OK = (additionalFields = {}) => ({ ok: true, ...additionalFields })

KO = (error, additionalFields = {}) => ({ error, ok: false, ...additionalFields })

Ex. :

import { OK, KO } from '@fasstech/oip-starter-utils/server';

export const getCustomer = (args, context) => {
  if (/* something */) {
    const error = new Error('Something goes wrong!');
    
    return KO(error, {
      firstName: null,
      lastName: null,
    });
  }
  
  return OK({ 
    firstName: 'John',
    lastName: 'Doe',
  });
};