Comprendre la configuration du serveur

15 min

Vue d'ensemble

Vous trouverez dans cette page une explication détaillée de la configuration du serveur.

Fonction start

La bibliothèque @fasstech/oip-starter-utils exporte une fonction start qui prend en paramètre votre configuration et se charge d'initialiser l'application Express.

Info Il est recommandé de placer la configuration du serveur dans le fichier server/index.mjs.

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

const serverConfig = {
  /* The server config */
};

await startServer(serverConfig);

Paramètres

La fonction start prend en paramètre un objet.

type ServerConfig = {
  cookieOptions?: CookieOptions;
  corsOptions?: CorsOptions;
  routes?: RequestHandler[];
  securityHeadersOptions?: HelmetOptions;
  graphql: {
    resolvers?: IResolvers[];
    typeDefs?: DocumentNode[];
    security?: {
      payloadLimit?: string;
      armorConfig?: GraphQLArmorConfig;
      maxCoercionErrors?: number;
      maxErrors?: number;
    };
  };
  logger: {
    info: (message: unknown) => void;
    warn: (message: unknown) => void;
    error: (message: unknown) => void;
  };
  process: {
    resolveFirstView: (args: { projectId: string; viewId?: string; metadata?: object }) => Promise<string>;
    extendWith?: (process: Process) => Promise<Process & object>;
  };
  session: {
    validateProjectId: (args: { projectId: string; sessionId: string | null | undefined }) => Promise<boolean>;
    resolveProjectFromContext: (args: { sessionId: string | null | undefined }) => Promise<string>;
    resolveContext?: (token: string) => Promise<object>;
  };
};

cookieOptions

Objet de configuration pour le cookie d’ID de session. Il accepte les mêmes options que l'objet cookie de la bibliothèque express-sessions.

La configuration par défaut est :

{
  maxAge: process.env.SESSION_COOKIE_MAX_AGE ?? 60,
  secret: process.env.SESSION_SECRET,
  secure: process.env.SECURE_COOKIE ?? false
}

Exemple :

const isProductionEnv = process.env.NODE_ENV === 'production';

const serverConfig = {
  cookieOptions: {
    httpOnly: isProductionEnv,
    sameSite: isProductionEnv ? 'none' : false,
    secure: isProductionEnv
  }
};

corsOptions

Objet de configuration pour définir les en-têtes de réponse CORS. Il accepte les mêmes options que la bibliothèque cors.

La configuration par défaut est :

{ origin: '*', allowedHeaders: '*' }

Exemple :

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

routes

Objet de configuration utilisé pour ajouter des routes. Il prend comme valeur une instance du routeur Express.

Exemple :

import express from 'express';

const router = express.Router();

router.get('/custom-api/test', (req, res) => {
  console.log('GET /custom-api/test');
  res.send({ message: 'Hello world!' });
});

const serverConfig = {
  routes: router
};

securityHeadersOptions

Objet de configuration pour définir des en-têtes de sécurité. Il accepte les mêmes options que la bibliothèque Helmet.

La configuration par défaut est :

{ xPoweredBy: false }

Exemple :

const serverConfig = {
  securityHeadersOptions: {
    crossOriginResourcePolicy: { 
      policy: "same-site",
    },
  },
};

graphql

Objet de configuration pour la couche GraphQL. Il accepte les options suivantes :

resolvers : liste des resolvers GraphQL ;

typeDefs : liste des définitions des types GraphQL ;

security :

payloadLimit : taille maximale autorisée de la payload des requêtes GraphQL entrantes. Par défaut, la valeur est définie à 50kb ;

maxCoercionErrors : nombre maximum d'erreurs de coercition de variables acceptées par le serveur Apollo avant qu'une requête ne soit rejetée avec le code 400. Par défaut, la valeur est définie à 50 ;

maxErrors : nombre maximum d'erreurs de validation GraphQL acceptées par le serveur Apollo avant le rejet d’une requête. Par défaut, la valeur est définie à 10 ;

armorConfig : objet définissant des règles de sécurité. La bibliothèque GraphQL Armor est utilisée pour la configuration de ces règles. Les règles configurables sont :

cost limit

field suggestions

max aliases

max depth

max directives

max tokens

Exemple :

const serverConfig = {
  graphql: {
    security: {
      payloadLimit: '1kb',
      armorConfig: {
        costLimit: { maxCost: 20 },
        maxDepth: { n: 3 },
        maxTokens: {  n: 100 }
      }
    }
  }
};

logger

Objet exposant des fonctions de journalisation.

Exemple :

import { logger } from '@fasstech/logger';

const serverConfig = {
  logger
};

process

Objet de configuration pour l'objet Process. Il accepte les options suivantes :

resolveFirstView : fonction de rappel pour la résolution de la première vue du parcours ;

La fonction reçoit en paramètre :

projectId : identifiant de l'entité Project actuelle ;

viewId : identifiant de la dernière vue active du parcours ; cette valeur n'est non nulle que si l'entité Project est associée à une session ;

metadata : métadonnées associées à la vue ;

La fonction retourne l'identifiant de la première vue du parcours ;

extendWith : fonction de rappel pour la résolution des propriétés personnalisées de l'objet Process ;

la fonction reçoit en paramètre l'objet Process ;

la fonction retourne un objet représentant l'objet Process étendu. Le type de cet objet doit correspondre au type GraphQL ExtendedProcess définit dans le fichier server/graphql/types/extended-process-type.mjs.

Exemple :

const extendWith = async (process) => {
 // Add your business logic to retrieve additional process properties
 let properties;
  
  return {
    ...process,
    properties
  };
};

const resolveFirstView = async ({ projectId, viewId, metadata }) => {
  // A session exists, continue where you left off
  if (viewId != null) return viewId;
  
  // Add your business logic to determine the first view
  let firstView;
  
  return firstView;
};

const serverConfig = {
  process: { resolveFirstView, extendWith }
};

session

Objet de configuration pour la résolution du contexte client. Il accepte les options suivantes :

validateProjectId : fonction de rappel pour la validation d'un identifiant projet ; cette fonction est appelée lors d'un décrochage avec le paramètre projectId ;

La fonction reçoit en paramètre :

projectId : paramètre utilisé lors du décrochage ;

sessionId : identifiant de la session si elle existe ;

La fonction retourne un booléen : true si l'identifiant du projet est valide, false sinon ;

resolveProjectFromContext : fonction de rappel pour résoudre l'entité Project correspondant au contexte client ; cette fonction est appelée lors du décrochage ;

La fonction reçoit en paramètre :

Dans un environnement de production ou dans un environnement de développement avec la variable SECURE_SESSION définie à true, la fonction reçoit en paramètre un objet qui représente le contexte client résolu ainsi que la propriété sessionId ;

Dans un environnement de développement avec la variable SECURE_SESSION définie à false, la fonction reçoit uniquement la propriété sessionId. Un mock peut alors être utilisé pour résoudre l'entité Project ;

La fonction retourne l'identifiant de l'entité Project correspondant au contexte client ;

resolveContext : fonction de rappel permettant de spécifier la fonction à utiliser pour la résolution du contexte client à partir d'un token ; par défaut, le contexte client est résolu par un appel à un service tiers (fasst-sessions ou équivalent) avec le token passé en paramètre ; l'URL de ce service tiers est définie par la variable d'environnement SESSIONS_SERVICE_URL ;

La fonction reçoit en paramètre :

token : paramètre utilisé lors du décrochage ;

La fonction retourne un objet représentant le contexte résolu.

Exemple :

const validateProjectId = async ({ projectId }) => {
  const project = await getProject(projectId);
  return project != null;
};

const resolveProjectFromContext = async (args) => {
  let externalId;

  if (getEnv('SECURE_SESSION')) {
    externalId = args.externalId;
  } else {
    const { getMockContext } = await import('../mocks/context.mjs');
    externalId = getMockContext().externalId;
  }

  let project = await getProject({ externalId });

  if (project == null) {
    project = await createProject();
    if (externalId != null) project = setProjectExternalId(externalId, project);
    project = await updateProject(project);
  }

  return getProjectId(project);
};

const serverConfig = {
  session: { validateProjectId, resolveProjectFromContext, resolveContext }
};

Initialisation

L'appel à la fonction start de la bibliothèque @fasstech/oip-starter-utils initialise l'application Express à partir de votre configuration.

Il réalise également des traitements complémentaires :

vérification des variables d'environnement à partir du fichier env-vars.yml ;

consolidation des variables d'environnement ;

configuration de paramètres de l'application Express :

trust proxy = 1 ;

view engine = 'ejs' ;

views = path.join(ROOT_DIR, VIEWS_DIR) ;

le chemin pour les fichiers statiques est défini avec la valeur path.join(ROOT_DIR, 'public') ;

initialisation du serveur GraphQL :

mise en place d'un mécanisme de nettoyage des entrées utilisateur (sanitizer) ;

conditionnement de certaines fonctionnalités à l'environnement d'exécution :

introspection = !isProductionEnv ;

hideSchemaDetailsFromClientErrors: isProductionEnv ;

dans un environnement de production, les erreurs sont remplacées par un objet générique : { message: 'Error' } ;

dans un environnement de production, la page d'accueil du plugin Apollo Server est désactivé (ApolloServerPluginLandingPageDisabled).

démarrage du service AMQP.