Utilisation de feature

7 min

Développement

Toutes les features doivent partager la même signature.

Input

{
  service?: {
    url: string;
    apiKey: string;
  };
  rabbitmq?: {
    messageBuilder: (response: unknown) => { message: unknown; queue: string };
  };
  onUpdateTaskState?: (args: { error?: string; metadata?: unknown; state: { status: string; statusCode: number } }) => Promise<void>;
};

Paramètres

service : porte l'url et la clé d'API permettant de se connecter au service dont dépend la feature

rabbitmq : porte un handler de construction de message afin d'envoyer des evènements dans une queue rabbit lors de l'exécution de la feature. messageBuilder est responsable de la construction du message et doit à minima renvoyer le nom de la queue rabbit destinataire du message dans une variable queue.

onUpdateTaskState : un handler pour la gestion des notifications. Le handler onUpdateTaskState sert à notifier un évènement relatif à la tâche dont la feature fait partie. Il est donc uniquement pertinent quand la feature est utilisée dans le contexte d'une tâche, pour mettre à jour l'état de celle-ci.

Ouput

En sortie, une feature retourne un dictionnaire de l'ensemble des APIs qu'elle propose. Chaque élément de ce dictionnaire est une fonction qui doit prendre la signature suivante :

func1: (
    projectEntity: Object,
    args?: unknown,
    taskState?: TaskState
  ) => Promise<{ projectEntity: Object; metadata?: unknown }>;

Des données complémentaires peuvent être passés directement aux fonctions exposées par la feature dans l'objet args

Lorsque vous utilisez une feature OIP dans le contexte d'une task, le paramètre taskState permet de définir les status que vous souhaitez appliquer à cette task lors du traitement de la feature.

export type TaskState = {
  starting: { status: string; statusCode: number };
  success: { status: string; statusCode: number };
  failure: { status: string; statusCode: number };
};

Utilisation

Comment déclarer une feature

La convention est de suffixer le nom d'une feature par Feature.

Considérons la feature DocumentFeature qui offre trois services :

uploadDocument : étant donné un objet document, upload ce document vers le service file_storage et enregistre ce document sous forme d'entité Document au sein de l'entité Project.

downloadDocument : étant donné l'identifiant d'une entié Document, télécharge ce document depuis le service file_storage.

deleteDocument : étant donné l'identifiant d'une entié Document, supprime ce document auprès du service file_storage et ainsi que l'entité Document correspondante.

import { updateTaskStateHandler, rabbitmqHandler } from '@fasstech/oip-features-utils';
import { $download } from './download.js';
import { $delete } from './delete.js';
import { $upload } from './upload.js';

/**
 * Initialise la feature Document.
 *
 * @param {import('@fasstech/oip-features-utils').FeatureOptions} options - Options de configuration de la feature :
 *   - service?: { url: string, apiKey: string }
 *   - rabbitmq?: { messageBuilder: function }
 *   - onUpdateTaskState?: function
 * @returns {Object} Objet contenant les fonctions uploadDocument, downloadDocument, deleteDocument
 */
export function DocumentFeature(options) {
  const updateTaskState = updateTaskStateHandler(options?.onUpdateTaskState);
  const sendMessage = rabbitmqHandler(options?.rabbitmq);
  return {
    uploadDocument: $upload({ updateTaskState, sendMessage, options }),
    downloadDocument: $download({ updateTaskState, sendMessage, options }),
    deleteDocument: $delete({ updateTaskState, sendMessage, options }),
  };
}

Comment déclarer un service d'une feature

/**
 * Sauvegarde un document dans FileStorage (stratégie DB slt pour l'instant) et l'entité projet.
 * @param {Object} params
 * @param {Object} params.projectEntity - L'entité projet concernée.
 * @param {Object} params.args
 * @param {Object} params.args.document - Le document à sauvegarder.
 * @param {string} params.args.document.type - Type du document.
 * @param {string} params.args.document.fileName - Nom du fichier.
 * @param {string} [params.args.document.originalFileName] - Nom du fichier.
 * @param {string} params.args.document.path - Chemin du fichier.
 * @param {string} [params.args.document.mimeType] - Type MIME du fichier.
 * @param {string} [params.args.document.key] - Clé de stockage.
 * @param {unknown} [params.args.document.metadata] - Métadonnées associées.
 * @param {Object} [params.taskState] - États de tâche optionnels ({ success, failure }).
 * @returns {Promise<{ projectEntity: Object, metadata?: unknown }>}
*/
export const $upload = ({ updateTaskState, sendMessage, options }) => async ({ projectEntity, args, taskState }) => {
  // 1. upload file to file_storage
  // 2. get the file_storage uploadId
  // 3. Create a Document entity & set externalId, fileName, mimeType, etc..
  // 4. Save it to Project entity
  // 5. Return the updated project entity & the newly created Document entity id
};

Comment appeler une feature

import { DocumentFeature } from '@fasstech/oip-features-document';

const document = {
  fileName: 'test.txt',
  mimeType: 'text/plain',
  path: `/tmp/test.txt`,
  type: DocumentTypeEnum.OTHER
};

const { uploadDocument } = DocumentFeature({ service: { url: SERVICE_FILESTORAGE_URL }});
const { projectEntity: updatedProjectEntity, metadata } = await uploadDocument({
  projectEntity,
  args: { document }
});