API Server
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;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 :
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
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.
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;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
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
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',
});
};