Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions api/contract/api-docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -209,9 +209,9 @@ const operations: Record<ScopedOperationId, Operation> = {
}

const tagTitles = {
processings: { fr: 'Traitements', en: 'Processings' },
runs: { fr: 'Exécutions', en: 'Runs' },
limits: { fr: 'Limites', en: 'Limits' }
processings: { en: 'Processings', fr: 'Traitements' },
runs: { en: 'Runs', fr: 'Exécutions' },
limits: { en: 'Limits', fr: 'Limites' }
}

export default (locale: ScopeLocale = 'fr') => {
Expand All @@ -230,7 +230,7 @@ export default (locale: ScopeLocale = 'fr') => {
return {
openapi: '3.1.0',
info: {
title: 'API Processings',
title: 'Processings API',
description: 'Periodic processings: plugins that ingest, transform and publish datasets, their configs and their runs.',
version: '1.0.0'
},
Expand Down
4 changes: 2 additions & 2 deletions api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@
"@types/ws": "^8.5.12"
},
"dependencies": {
"@data-fair/lib-common-types": "^1.27.0",
"@data-fair/lib-common-types": "^1.28.1",
"@data-fair/lib-express": "^1.34.1",
"@data-fair/lib-node": "^2.16.1",
"@data-fair/lib-node-registry": "0.7.2",
"@data-fair/lib-utils": "^1.13.1",
"@data-fair/lib-utils": "^1.15.0",
"@data-fair/lib-validation": "^1.0.2",
"@data-fair/processings-shared": "*",
"@json-layout/core": "^2.13.3",
Expand Down
82 changes: 41 additions & 41 deletions api/src/misc/utils/api-docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,24 +19,24 @@ export default (origin: string, options: { processing: Processing, plugin?: ApiD
const doc: Record<string, any> = {
openapi: '3.1.1',
info: {
title: options?.processing?.title ? `API du traitement : ${options.processing.title}` : 'API Traitements de données',
description: `Cette documentation interactive à destination des développeurs permet d'utiliser l'API du ${options?.processing?.title ? `traitement ${options.processing.title}` : 'service de traitements periodiques'}.`,
title: options?.processing?.title ? `API of the processing: ${options.processing.title}` : 'Processings API',
description: `This interactive documentation for developers covers the API of the ${options?.processing?.title ? `processing ${options.processing.title}` : 'periodic processings service'}.`,
version: packageJson.version,
termsOfService: 'https://koumoul.com/pages/conditions-generales-dutilisation'
},
servers: [{
url: `${origin}/processings/api/v1${options?.processing?._id ? `/processings/${options.processing?._id}` : ''}`,
description: `Instance DataFair - ${new URL(origin).hostname}`
description: `Data Fair instance - ${new URL(origin).hostname}`
}],
paths: {
'/api-docs.json': {
get: {
summary: 'Obtenir la documentation OpenAPI',
description: 'Accéder à cette documentation au format OpenAPI v3.',
summary: 'Get the OpenAPI documentation',
description: 'Get this documentation in the OpenAPI v3 format.',
operationId: 'getApiDoc',
responses: {
200: {
description: 'La documentation de l\'API',
description: 'The API documentation.',
content: {
'application/json': {
schema: {
Expand All @@ -51,32 +51,32 @@ export default (origin: string, options: { processing: Processing, plugin?: ApiD

'/': {
get: {
summary: 'Lire les informations de ce traitement',
description: 'Accéder aux données de ce traitement.',
summary: 'Read this processing',
description: 'Read the information of this processing.',
operationId: 'getProcessing',
responses: {
200: {
description: 'Le traitement trouvé.',
description: 'The processing.',
content: {
'application/json': {
schema: ProcessingSchema
}
}
},
403: {
description: 'L\'utilisateur n\'a pas le droit de voir ce traitement.'
description: 'The user is not allowed to read this processing.'
},
404: {
description: 'Traitement non trouvé.'
description: 'Processing not found.'
}
}
},
patch: {
summary: 'Mettre à jour ce traitement',
description: 'Mettre à jour ce traitement.',
summary: 'Update this processing',
description: 'Update some fields of this processing.',
operationId: 'patchProcessing',
requestBody: {
description: 'Le traitement à mettre à jour',
description: 'The fields of the processing to update.',
required: true,
content: {
'application/json': {
Expand All @@ -101,49 +101,49 @@ export default (origin: string, options: { processing: Processing, plugin?: ApiD
},
responses: {
200: {
description: 'Le traitement a été mis à jour avec succès.',
description: 'The updated processing.',
content: {
'application/json': {
schema: ProcessingSchema
}
}
},
400: {
description: 'Body de la requête invalide.'
description: 'Invalid request body.'
},
403: {
description: 'L\'utilisateur n\'a pas le droit de mettre à jour ce traitement ou de faire cette modification sur ce traitement'
description: 'The user is not allowed to update this processing or to make this change to it.'
},
404: {
description: 'Traitement non trouvé.'
description: 'Processing not found.'
}
}
},
delete: {
summary: 'Supprimer ce traitement',
description: 'Supprimer ce traitement.',
summary: 'Delete this processing',
description: 'Delete this processing and its runs.',
operationId: 'deleteProcessing',
responses: {
204: {
description: 'Le traitement a été supprimé avec succès.'
description: 'The processing was deleted.'
},
403: {
description: 'L\'utilisateur n\'a pas le droit de supprimer ce traitement.'
description: 'The user is not allowed to delete this processing.'
},
404: {
description: 'Traitement non trouvé.'
description: 'Processing not found.'
}
}
}
},
'/webhook-key': {
get: {
summary: 'Lire la clé de webhook de ce traitement',
description: 'Lire la clé de webhook de ce traitement.',
summary: 'Read the webhook key of this processing',
description: 'Read the key that triggers this processing through its webhook.',
operationId: 'getProcessingWebhookKey',
responses: {
200: {
description: 'La clé de webhook du traitement.',
description: 'The webhook key of the processing.',
content: {
'application/json': {
schema: {
Expand All @@ -153,63 +153,63 @@ export default (origin: string, options: { processing: Processing, plugin?: ApiD
}
},
403: {
description: 'L\'utilisateur n\'a pas le droit de voir ce traitement.'
description: 'The user is not allowed to read this processing.'
},
404: {
description: 'Traitement non trouvé.'
description: 'Processing not found.'
}
}
},
delete: {
summary: 'Recréer la clé de webhook de ce traitement',
description: 'Recréer la clé de webhook de ce traitement.',
summary: 'Renew the webhook key of this processing',
description: 'Replace the webhook key of this processing with a new one, the previous key stops working.',
operationId: 'deleteProcessingWebhookKey',
responses: {
200: {
description: 'La clé de webhook du traitement a été recréée avec succès.',
description: 'The webhook key was renewed.',
content: {
'application/json': {
schema: {
type: 'string',
description: 'La nouvelle clé de webhook du traitement.'
description: 'The new webhook key of the processing.'
}
}
}
},
403: {
description: 'L\'utilisateur n\'a pas le droit de voir ce traitement.'
description: 'The user is not allowed to read this processing.'
},
404: {
description: 'Traitement non trouvé.'
description: 'Processing not found.'
}
}
}
},
'/_trigger': {
post: {
summary: 'Déclencher ce traitement manuellement',
description: 'Déclencher ce traitement manuellement.',
summary: 'Trigger this processing',
description: 'Trigger a run of this processing now, with a session or with its webhook key.',
operationId: 'postProcessingTrigger',
parameters: [
{
name: 'key',
in: 'query',
description: 'La clé de déclenchement du traitement.',
description: 'The webhook key of the processing, to trigger it without a session.',
schema: {
type: 'string',
title: 'Clé de déclenchement'
title: 'Webhook key'
}
}
],
responses: {
200: {
description: 'Le traitement a été déclenché avec succès.'
description: 'The processing was triggered.'
},
403: {
description: 'L\'utilisateur n\'a pas le droit de déclencher ce traitement, ou la clé de déclenchement n\'est pas valide.'
description: 'The user is not allowed to trigger this processing, or the webhook key is invalid.'
},
404: {
description: 'Traitement non trouvé.'
description: 'Processing not found.'
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions api/src/processings/operations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ import { httpError } from '@data-fair/lib-utils/http-errors.js'

/**
* `lib-express/error-handler.js` collapses every AxiosRequestError to 500, so
* we translate registry failures into user-facing French messages at the
* we translate registry failures into user-facing messages at the
* boundary. 403/404 keep their status (the UI relies on them to show its
* "plugin broken" banner); anything else is a registry outage → 502.
*/
export const translateRegistryError = (err: any, processing: Pick<Processing, 'plugin' | 'owner'>) => {
const status = err?.status ?? err?.statusCode
const ownerLabel = processing.owner.name ?? processing.owner.id
if (status === 403) return httpError(403, `Le compte ${ownerLabel} n'a pas accès au plugin ${processing.plugin}.`)
if (status === 404) return httpError(404, `Le plugin ${processing.plugin} est introuvable dans le registre.`)
return httpError(502, 'Le registre des plugins est temporairement indisponible.')
if (status === 403) return httpError(403, `The account ${ownerLabel} has no access to the plugin ${processing.plugin}.`)
if (status === 404) return httpError(404, `The plugin ${processing.plugin} was not found in the registry.`)
return httpError(502, 'The plugins registry is temporarily unavailable.')
}
46 changes: 26 additions & 20 deletions api/src/processings/router.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ const ajv = ajvFormats(new Ajv({ strict: false, addUsedSchema: false }))
/**
* Ensure the plugin tarball is in the API's local cache (downloads on miss).
* Registry enforces that `processing.owner` has access to the artefact; a 403
* here surfaces directly to the caller as a user-facing French message.
* here surfaces directly to the caller as a user-facing message.
*
* The plugin's processing config schema is read from the conventional
* `processing-config-schema.json` shipped alongside the plugin (v6 convention),
Expand Down Expand Up @@ -120,21 +120,27 @@ async function fetchPluginArtefact (processing: Pick<Processing, 'plugin' | 'own

const sensitiveParts = ['permissions', 'webhookKey', 'config']

const processingTitles = {
create: (title: string) => ({ en: `The processing ${title} was created`, fr: `Le traitement ${title} a été créé` }),
patch: (title: string) => ({ en: `The processing ${title} was updated`, fr: `Le traitement ${title} a été modifié` }),
delete: (title: string) => ({ en: `The processing ${title} was deleted`, fr: `Le traitement ${title} a été supprimé` }),
trigger: (title: string) => ({ en: `The processing ${title} was triggered manually`, fr: `Le traitement ${title} a été déclenché manuellement` }),
'trigger-webhook': (title: string) => ({ en: `The processing ${title} was triggered by a webhook`, fr: `Le traitement ${title} a été déclenché par webhook` })
}

/**
* Helper function to send events related to processings
* @param processing The processing object
* @param actionText The text describing the action (e.g. "a été créé")
* @param topicAction The action part of the topic key (e.g. "create", "delete")
* @param sessionState Optional session state for authentication
* Send an event about a processing.
* @param topicAction The action part of the topic key
* @param textAction The text of the title, when it is more precise than the topic action
*/
const sendProcessingEvent = (
processing: Processing,
actionText: string,
topicAction: string,
sessionState?: SessionStateAuthenticated
topicAction: 'create' | 'patch' | 'delete' | 'trigger',
sessionState?: SessionStateAuthenticated,
textAction: keyof typeof processingTitles = topicAction
) => {
eventsQueue.pushEvent({
title: `Le traitement ${processing.title} ${actionText}`,
title: processingTitles[textAction](processing.title),
topic: { key: `processings:processing-${topicAction}:${processing._id}` },
sender: processing.owner,
resource: {
Expand All @@ -153,7 +159,7 @@ const sendProcessingEvent = (
* from the cached package.json#registry block, downloaded on cache miss)
*
* Skipped entirely when the processing has no config. Registry errors are
* translated to user-facing French messages inside ensurePluginAndReadSchema.
* translated to user-facing messages inside ensurePluginAndReadSchema.
*/
async function validateFullProcessing (processing: any): Promise<Processing> {
(await import('#types/processing/index.ts')).returnValid(processing)
Expand Down Expand Up @@ -358,14 +364,14 @@ router.get('', requireOperationScope('listProcessings'), async (req, res) => {
$filter: {
input: '$departments',
as: 'dept',
cond: { $ne: ['$$dept.department', null] } // Filtrer les départements null
cond: { $ne: ['$$dept.department', null] } // filter out null departments
}
}
}
}
]

// Ajout des `owners` dans le résultat final
// add the `owners` to the final result
aggregationPipeline[1].$replaceRoot.newRoot.owners = { $ifNull: ['$owners', []] }
} else {
aggregationPipeline.unshift({ $match: query })
Expand Down Expand Up @@ -407,7 +413,7 @@ router.post('', requireOperationScope('postProcessing'), async (req, res) => {
Object.assign(processing, await prepareProcessing(processing))
await mongo.processings.insertOne(processing)

sendProcessingEvent(processing, 'a été créé', 'create', sessionState)
sendProcessingEvent(processing, 'create', sessionState)
res.status(200).json(cleanProcessing(processing, sessionState))
})

Expand Down Expand Up @@ -440,7 +446,7 @@ const saveProcessingPatch = async (processing: Processing, body: Record<string,
await mongo.processings.updateOne({ _id: processing._id }, patch)
await mongo.runs.updateMany({ 'processing._id': processing._id }, { $set: { permissions: patchedProcessing.permissions || [] } })
await applyProcessing(mongo, patchedProcessing)
sendProcessingEvent(patchedProcessing, 'a été modifié', 'patch', sessionState)
sendProcessingEvent(patchedProcessing, 'patch', sessionState)
return patchedProcessing
}

Expand Down Expand Up @@ -551,7 +557,7 @@ router.delete('/:id', requireOperationScope('deleteProcessing'), async (req, res
if (permissions.getUserResourceProfile(processing.owner, processing.permissions, sessionState) !== 'admin') return res.status(403).send()
await mongo.processings.deleteOne({ _id: req.params.id })
if (processing) await deleteProcessing(mongo, processing)
sendProcessingEvent(processing, 'a été supprimé', 'delete', sessionState)
sendProcessingEvent(processing, 'delete', sessionState)
res.sendStatus(204)
})

Expand Down Expand Up @@ -580,16 +586,16 @@ router.post('/:id/_trigger', async (req, res) => {
const processing = await mongo.processings.findOne({ _id: req.params.id })
if (!processing) return res.status(404).send()
if (req.query.key) {
if (req.query.key !== processing.webhookKey) return res.status(403).send('Mauvaise clé de déclenchement')
sendProcessingEvent(processing, 'a été déclenché par webhook', 'trigger')
if (req.query.key !== processing.webhookKey) return res.status(403).send('Wrong trigger key')
sendProcessingEvent(processing, 'trigger', undefined, 'trigger-webhook')
} else {
// the webhook key path reads no session, so the scope is checked here rather than by a middleware
assertReqScope(req, acceptedScopes('processings', 'write'))
const sessionState = await session.reqAuthenticated(req)
if (!['admin', 'exec'].includes(permissions.getUserResourceProfile(processing.owner, processing.permissions, sessionState) ?? '')) return res.status(403).send()
sendProcessingEvent(processing, 'a été déclenché manuellement', 'trigger', sessionState)
sendProcessingEvent(processing, 'trigger', sessionState)
}
if (!processing.active) return res.status(409).send('Le traitement n\'est pas actif')
if (!processing.active) return res.status(409).send('The processing is not active')
res.send(await createNext(mongo.db, locks, processing, true, req.query.delay ? Number(req.query.delay) : 0))
})

Expand Down
Loading
Loading