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',
});
};