---
title: Comprendre la configuration du serveur
slug: oip-next/AcMc-comprendre-la-con
icon: {"lucideIcon":"📘"}
createdAt: 2026-04-16T07:26:15.000Z
---

# 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*.

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

```javascript
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.

```typescript
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](https://github.com/expressjs/session?tab=readme-ov-file#cookie).

La configuration par défaut est :

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

Exemple :

```javascript
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](https://github.com/expressjs/cors).

La configuration par défaut est :

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

Exemple :

```javascript
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 :

:::CodeblockTabs
index.mjs

```javascript
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](https://github.com/helmetjs/helmet).

La configuration par défaut est :

```javascript
{ xPoweredBy: false }
```

Exemple :

```javascript
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`*&#x20;;*
  - `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`*&#x20;;*
  - `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`*&#x20;;*
  - `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](https://escape.tech/graphql-armor/docs/plugins/cost-limit/)
    - [field suggestions](https://escape.tech/graphql-armor/docs/plugins/block-field-suggestions/)
    - [max aliases](https://escape.tech/graphql-armor/docs/plugins/max-aliases/)
    - [max depth](https://escape.tech/graphql-armor/docs/plugins/max-depth/)
    - [max directives](https://escape.tech/graphql-armor/docs/plugins/max-directives/)
    - [max tokens](https://escape.tech/graphql-armor/docs/plugins/max-tokens/)

Exemple :

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

### logger

Objet exposant des fonctions de journalisation.

Exemple :

```javascript
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 :

:::CodeblockTabs
index.mjs

```javascript
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 :

```javascript
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` ;&#x20;
  - `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.
