Guide

Inngest : des tâches de fond pilotées par événements

Inngest exécute des tâches de fond déclenchées par des événements. Licence SSPL, steps, retries, flow control, auto-hébergement, tarifs et alternatives.

L'équipe CodeWorlds20 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Inngest est une plateforme pour exécuter des tâches de fond où l'on n'appelle pas une tâche directement, mais où l'on envoie un événement, et où les fonctions déclarent elles-mêmes à quels événements elles réagissent. Le paquet inngest est en version 4.18.1, le serveur du dépôt inngest/inngest compte environ 5,7 mille étoiles, et sa licence est la SSPL avec un passage différé à Apache 2.0, ce qu'il faut vérifier avant de déployer.

Ce que fait et ne fait pas Inngest

La différence entre Inngest et une file de tâches ordinaire tient au sens de la dépendance. Dans une file, le code qui produit du travail doit connaître le nom de la tâche à exécuter : tu poses une entrée send-welcome-email avec un identifiant d'utilisateur. Dans Inngest, le code qui produit du travail annonce un fait qui vient de se produire, disons app/user.signup, et ne sait pas combien de fonctions y réagiront. Ajouter une seconde réaction, par exemple une écriture dans un système d'analyse, ne demande aucun changement à l'endroit d'où vient l'événement.

Cette distinction est pratique plutôt qu'académique. Le modèle d'événements facilite l'ajout d'une fonction et rend plus difficile de retracer ce qui se déclenche réellement après un seul événement, car la liste des destinataires n'est pas visible à l'endroit d'envoi. Si ton projet a cinq tâches et que chacune a exactement un appelant, le modèle d'événements ajoute une couche d'indirection sans rien rapporter. Si tu as un événement métier et sept choses qui doivent se produire après lui, le modèle commence à payer.

Le serveur lui-même est composé de plusieurs services séparés qu'il vaut la peine de connaître, car ils apparaissent dans les journaux et dans la configuration d'auto-hébergement. L'Event API accepte des événements en HTTP et les authentifie avec une clé d'événement. Un flux d'événements les met en tampon avant le Runner, qui crée de nouvelles exécutions de fonctions, reprend les fonctions mises en pause par waitForEvent et annule celles qui correspondent aux expressions cancelOn. La file est multi-locataire et c'est là que sont implémentés les mécanismes de flow control. L'Executor exécute les étapes et écrit l'état intermédiaire dans le magasin d'état.

Ce qu'Inngest ne fait pas. Ce n'est pas une base de données, donc les résultats qui doivent survivre à l'historique des exécutions doivent être persistés par toi. Il ne remplace pas la surveillance des erreurs de l'application, pour quoi existe Sentry. Il n'envoie pas de messages, donc pour l'e-mail transactionnel il te faut encore quelque chose comme Resend. Il n'héberge pas ton code : les fonctions vivent dans ton application et Inngest les appelle en HTTP.

Licence, trois sources et trois réponses différentes

C'est le point pour lequel ce texte a été écrit. L'API GitHub pour le dépôt inngest/inngest renvoie NOASSERTION, ce qui signifie que le détecteur n'a pas reconnu de licence standard. Ce n'est pas un bug mais une réponse correcte, car le fichier de licence de ce dépôt n'est aucune des licences de la liste.

Le fichier LICENSE.md s'ouvre sur deux titres : Server Side Public License version 1.0 datée du 16 octobre 2018, et Apache 2.0 Future License. L'essentiel du texte est la SSPL complète, une licence créée par MongoDB et non approuvée par l'Open Source Initiative. Sa section treize, intitulée Offering the Program as a Service, énonce clairement que si tu rends les fonctionnalités du programme disponibles à des tiers sous forme de service, tu dois rendre le code source de tout ce service disponible à tous gratuitement, téléchargeable via un réseau, selon les termes de la même licence. La définition de l'offre en tant que service est large dans le texte et couvre le fait de permettre à des tiers d'interagir avec les fonctionnalités à distance via un réseau informatique.

À la fin du fichier se trouve une section Grant of Future License. Elle accorde de façon irrévocable une licence Apache 2.0 supplémentaire, effective au troisième anniversaire de la date à laquelle une version donnée du logiciel a été rendue disponible. Après cette date, la même version du code est un logiciel ordinaire sous licence permissive. La construction ressemble à la Business Source License, même si le texte de base est différent.

La divergence entre les sources se voit ici d'un coup d'œil. Le registre npm pour le paquet inngest-cli en version 1.43.0 met le champ license à SEE LICENSE IN LICENSE.md, ce qui déclare une licence non standard et pointe vers le fichier. GitHub dit NOASSERTION. Le fichier dit SSPL avec Apache 2.0 différé. Les trois réponses s'accordent sur le fait qu'il ne s'agit pas d'une licence ouverte standard, mais aucun outil automatique ne te dira ce qui en découle.

Le paquet client est une autre affaire, et là la divergence est réelle. Le paquet inngest en version 4.18.1 a son champ license du registre à Apache-2.0. Décompresser l'archive publiée le confirme : la racine du paquet contient un LICENSE.md avec le texte complet de l'Apache License version 2.0. Le fichier packages/inngest/LICENSE.md du dépôt inngest/inngest-js contient exactement le même texte. L'API GitHub pour ce dépôt indique pourtant GPL-3.0, alors que la racine du dépôt ne contient aucun fichier de licence. Si ton outil d'audit de dépendances lit les métadonnées depuis GitHub plutôt que depuis les paquets, il enregistrera une licence copyleft pour une bibliothèque qui est en fait sous Apache 2.0.

La conclusion pratique est facile à retenir. La bibliothèque que tu intègres à ton propre code est permissive et ne pose aucun problème. Le serveur que tu pourrais monter toi-même est sous SSPL, et le revendre comme service est là où la clause de la section treize commence à mordre. Pour un usage interne en entreprise, la SSPL ne pose aucun souci, car tu n'offres pas le programme à des tiers. Pour construire un produit de plateforme au service de clients externes par-dessus, le problème est sérieux.

Client, événements et première fonction

L'installation tient en un seul paquet. Node 20 ou plus récent est requis, ainsi que TypeScript 5.8 ou plus récent si tu utilises les types. Le paquet dépend entre autres de zod en version 3.25, et accepte zod 3.25 ou 4 comme dépendance de pair.

TSsrc/inngest/client.ts
// src/inngest/client.ts
import { Inngest, eventType } from 'inngest'

export const userSignup = eventType('app/user.signup').data<{
  userId: string
  email: string
  accountId: string
}>()

export const inngest = new Inngest({
  id: 'shop-api',
  eventKey: process.env.INNGEST_EVENT_KEY
})

Une fonction se crée avec createFunction, qui prend un objet de configuration et un handler. Dans la version quatre du paquet, les déclencheurs vont dans le champ triggers, sous forme de tableau, et c'est un changement par rapport à la version trois où le deuxième argument était un seul objet de déclencheur.

TSsrc/inngest/functions/onboarding.ts
// src/inngest/functions/onboarding.ts
import { NonRetriableError } from 'inngest'
import { inngest, userSignup } from '../client'

export const onboarding = inngest.createFunction(
  {
    id: 'user-onboarding',
    name: 'Welcome a new user',
    triggers: [{ event: 'app/user.signup' }],
    retries: 6
  },
  async ({ event, step }) => {
    const user = await step.run('fetch-user', async () => {
      const record = await db.users.findById(event.data.userId)
      if (!record) throw new NonRetriableError('No such user in the database')
      return record
    })

    await step.run('send-welcome', () =>
      mailer.send({ to: user.email, template: 'welcome' })
    )

    await step.sleep('wait-three-days', '3d')

    const activated = await step.waitForEvent('wait-for-activation', {
      event: 'app/project.created',
      match: 'data.userId',
      timeout: '7d'
    })

    if (!activated) {
      await step.run('send-nudge', () =>
        mailer.send({ to: user.email, template: 'nudge' })
      )
    }

    return { userId: user.id, activated: Boolean(activated) }
  }
)

Les fonctions doivent être servies à une adresse HTTP qu'Inngest appelle. Les adaptateurs sont des points d'entrée séparés du paquet et il y en a plus d'une douzaine, dont inngest/next, inngest/express, inngest/fastify, inngest/hono, inngest/lambda, inngest/cloudflare, inngest/sveltekit et inngest/bun. Dans un projet Next.js, cela ressemble à ceci.

TSapp/api/inngest/route.ts
// app/api/inngest/route.ts
import { serve } from 'inngest/next'
import { inngest } from '@/src/inngest/client'
import { onboarding } from '@/src/inngest/functions/onboarding'

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [onboarding],
  signingKey: process.env.INNGEST_SIGNING_KEY
})

Envoyer un événement depuis le code de l'application est un appel à inngest.send. La méthode accepte un seul objet ou un tableau et renvoie les identifiants des événements acceptés. Un événement a un nom et un champ data, éventuellement aussi un id utilisé pour la déduplication et un ts avec ton propre horodatage.

Steps, retries et gestion des erreurs

Une étape (step) est l'unité de durabilité. Le résultat de chaque step.run est persisté côté serveur, et quand une fonction est relancée, les étapes déjà terminées ne s'exécutent pas une seconde fois mais renvoient le résultat stocké. C'est pourquoi le handler est invoqué plusieurs fois au cours d'une exécution plutôt qu'une seule fois du début à la fin. Le code entre les étapes s'exécute à chacune de ces invocations, donc tout ce qui a un effet de bord doit se trouver dans une étape.

Les outils d'étape disponibles sont step.run pour exécuter du code, step.sleep et step.sleepUntil pour attendre, step.waitForEvent pour se mettre en pause jusqu'à l'arrivée d'un événement correspondant, step.invoke pour appeler une autre fonction et recevoir son résultat, step.sendEvent pour envoyer un événement de façon durable et step.fetch pour les requêtes réseau. Il y a aussi step.ai.infer, qui déplace un appel de modèle de langage côté serveur Inngest.

Le retry est activé par défaut. Le champ retries accepte des valeurs de zéro à vingt et vaut quatre par défaut. Deux types d'exceptions changent le comportement du retry et tous deux sont exportés par le paquet principal.

TypeScript
import { NonRetriableError, RetryAfterError } from 'inngest'

export const syncInvoice = inngest.createFunction(
  {
    id: 'sync-invoice',
    triggers: [{ event: 'billing/invoice.created' }],
    retries: 8,
    onFailure: async ({ error, event }) => {
      await alerts.page('sync-invoice exhausted its retries', {
        message: error.message,
        eventId: event.data.event.id
      })
    }
  },
  async ({ event, step }) => {
    await step.run('push-to-accounting', async () => {
      const res = await fetch('https://api.accounting.example/invoices', {
        method: 'POST',
        body: JSON.stringify(event.data)
      })

      if (res.status === 422) {
        // the data is permanently wrong, a retry changes nothing
        throw new NonRetriableError(`Rejected: ${await res.text()}`)
      }

      if (res.status === 429) {
        const after = res.headers.get('retry-after') ?? '60'
        throw new RetryAfterError('Provider limit', `${after}s`)
      }

      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      return res.json()
    })
  }
)

NonRetriableError termine l'exécution immédiatement sans consommer les tentatives restantes. RetryAfterError repousse la tentative suivante du délai indiqué, ce qui est la bonne réaction à une réponse 429 portant un en-tête Retry-After. Le handler onFailure ne se déclenche qu'une fois toutes les tentatives épuisées, et c'est là que doit se placer une alerte à un humain.

L'annulation passe par cancelOn. Tu donnes le nom de l'événement d'annulation plus un champ match en notation pointée sur lequel les deux événements doivent concorder, ou une expression complète dans le champ if. Séparément, il y a un champ timeouts avec les sous-champs start et finish : le premier borne l'attente dans la file avant le début de l'exécution, le second la durée totale de l'exécution.

Le flow control, c'est pour cela que tu viens

Le flow control est ce qui distingue Inngest des outils plus simples de cette catégorie. Toutes les options ci-dessous sont des champs de l'objet de configuration de la fonction et toutes prennent une clé facultative, qui est une expression CEL évaluée pour chaque événement déclencheur. La clé compte le plus ici, car elle transforme une limite globale en une limite séparée pour chaque valeur de clé.

TypeScript
export const generateReport = inngest.createFunction(
  {
    id: 'generate-report',
    triggers: [{ event: 'reports/requested' }],

    // at most 5 concurrent runs per customer
    concurrency: [
      { limit: 5, key: 'event.data.customerId', scope: 'fn' },
      { limit: 50, scope: 'env' }
    ],

    // 100 new runs per minute, with 20 spare for a traffic spike
    throttle: { limit: 100, period: '1m', burst: 20 },

    // collapse a burst of edits to the same report into one run
    debounce: { period: '30s', key: 'event.data.reportId', timeout: '10m' },

    // premium customers ahead of the rest
    priority: { run: 'event.data.plan == "pro" ? 300 : 0' },

    // the same event within 24 hours triggers the function once
    idempotency: 'event.data.reportId'
  },
  async ({ event, step }) => {
    /* ... */
  }
)

Trois mécanismes se confondent, donc séparons-les explicitement. concurrency limite le nombre d'exécutions simultanées et prend un champ scope avec les valeurs fn, env ou account, les deux dernières exigeant une clé. throttle limite le nombre d'exécutions qui démarrent sur une période donnée, l'excédent attend dans la file, et le champ burst ajoute de la marge au-dessus de la limite pour un trafic irrégulier. rateLimit paraît semblable mais se comporte différemment : les événements en excès sont abandonnés plutôt que mis en file, donc il sert à supprimer le bruit, pas à lisser la charge.

S'y ajoutent deux mécanismes de regroupement. debounce retarde le démarrage d'une période donnée et relance le compte à rebours à chaque événement correspondant suivant, en exécutant la fonction avec le dernier. La période va d'une seconde à sept jours, et le champ timeout fixe une borne stricte au délai. batchEvents rassemble les événements en un lot et les remet à la fonction sous forme de tableau events, avec maxSize plafonné à cent et timeout entre une et soixante secondes.

Il y a aussi singleton avec un champ mode qui accepte skip ou cancel. Le premier mode ignore une nouvelle exécution si une est déjà en cours pour la même clé. Le second annule celle en cours et démarre la nouvelle. C'est le moyen le plus simple d'éviter que deux tâches de synchronisation pour la même ressource se marchent dessus.

Auto-hébergement et tarifs du cloud

L'auto-hébergement est pris en charge depuis la version 1.0 du serveur, et la version actuelle est la 1.43.0 du 20 août 2026. La documentation précise clairement que l'équipe de support d'Inngest ne garantit pas d'aide directe pour les instances auto-hébergées et renvoie vers les issues GitHub ou une discussion sur l'option entreprise. C'est une information à accepter d'avance plutôt qu'à découvrir pendant une panne.

Le serveur démarre avec une commande et n'a par défaut aucune dépendance externe. Il garde l'état dans SQLite dans le fichier ./.inngest/main.db et exécute un serveur Redis embarqué dans le même processus pour la file et l'état des exécutions, avec des instantanés périodiques dans SQLite. Cet arrangement ne passe pas à l'échelle au-delà d'un seul nœud, donc les installations de production y attachent des services externes.

docker-compose.yml
# docker-compose.yml
services:
  inngest:
    image: inngest/inngest
    command: inngest start
    ports:
      - '8288:8288'
      - '8289:8289'
    environment:
      # both keys must be hex strings with an even number of characters
      - INNGEST_EVENT_KEY=abcd1234
      - INNGEST_SIGNING_KEY=5678ef90
      - INNGEST_POSTGRES_URI=postgres://inngest:password@postgres:5432/inngest
      - INNGEST_REDIS_URI=redis://redis:6379
      - INNGEST_EXPERIMENTAL_PROM_METRICS=1
    depends_on:
      - postgres
      - redis

Le port 8288 sert le serveur et son interface, le port 8289 est la passerelle Connect pour les workers attachés en permanence. Chaque option de ligne de commande peut être fournie sous forme de variable d'environnement : remplace les tirets par des tirets bas, mets en majuscules et préfixe avec INNGEST_, donc --postgres-uri devient INNGEST_POSTGRES_URI. Le serveur expose aussi un point d'accès GET /metrics au format Prometheus, par défaut avec une seule jauge inngest_queue_depth, et les compteurs du cycle de vie des fonctions sont activés par l'option expérimentale montrée plus haut. L'authentification de ce point d'accès n'est pas configurée par défaut, donc ne l'expose pas publiquement.

L'application se connecte à ton propre serveur via INNGEST_DEV=0 et INNGEST_BASE_URL pointant vers l'adresse de l'instance, avec les clés d'événement et de signature. En local, tu travailles avec npx inngest-cli dev, qui lance un serveur de développement avec une interface et des traces d'exécution.

Dans la variante hébergée, l'unité de facturation est une exécution, définie comme une seule exécution de fonction plus chaque étape qu'elle contient. Une fonction avec cinq appels step.run consomme six unités par exécution, et ce multiplicateur est le chiffre le plus important à calculer pour ton propre projet. L'offre Hobby ne coûte rien et inclut 50 mille unités par mois, 5 étapes simultanées, 3 utilisateurs, 500 mille événements ingérés, une taille d'événement jusqu'à 256 KiB, un lot jusqu'à 5 événements et 24 heures d'historique de traces. Une fois le quota gratuit épuisé, l'exécution se met en pause au lieu de passer à une facturation à l'usage. L'offre Pro commence à 99 dollars par mois avec un million d'unités incluses, une facturation à l'usage jusqu'à vingt millions, cent étapes simultanées avec 25 dollars pour chaque tranche supplémentaire de 25, quinze utilisateurs avec 10 dollars par utilisateur supplémentaire, et sept jours d'historique de traces. L'intégration avec des systèmes d'observabilité externes est une ligne à 300 dollars dans la grille tarifaire, et la conformité HIPAA un complément à convenir. Le niveau Enterprise n'a pas de prix publié.

Inngest face aux alternatives

CritèreInngesttrigger.devTemporal
Modèle de déclenchementévénement, plusieurs destinatairesappel direct de la tâchedémarrage d'un workflow depuis un client
Licence du cœurSSPL avec Apache 2.0 différédivergence entre dépôt et paquetMIT
Flow controlthrottle, debounce, concurrency, singleton, priorityfiles et limites de concurrencepolitiques côté file de tâches
Où s'exécute le codedans ton application, appelé en HTTPsur l'infrastructure du fournisseur ou la tiennedans ton propre processus worker
Auto-hébergementpris en charge, sans garantie de supportpris en chargepris en charge, demande une base de données
Offre gratuite50 mille unités, puis une pauselimites de temps d'exécution et de tâchesseul Temporal Cloud est payant

Trigger.dev est l'équivalent le plus proche et la différence tient au modèle de déclenchement et à l'endroit où le code s'exécute physiquement. Là-bas, tu appelles une tâche par son nom et elle s'exécute sur l'infrastructure du fournisseur ; ici tu envoies un événement et ton propre serveur reçoit une requête HTTP. Si une tâche doit tourner une heure et consommer de la mémoire, le modèle d'Inngest est moins bon, car il charge ton application. Si tu veux le code des tâches dans le même dépôt et le même processus que le reste de l'application, il est meilleur.

Temporal joue dans une autre catégorie, tant pour les garanties que pour le coût de déploiement. Il donne une exécution durable complète avec un historique d'événements et un rejeu déterministe, mais demande de faire tourner des processus worker, de maintenir un cluster et d'accepter un modèle de programmation où le code du workflow doit être déterministe. Pour envoyer un e-mail de bienvenue après une inscription, cet outil est trop lourd.

La plateforme de déploiement elle-même mérite une réflexion séparée. Les fonctions serveur sur Vercel ont des limites de temps d'exécution, et Inngest les contourne en découpant le travail en étapes : chaque étape est une requête HTTP séparée, donc un processus de dix minutes se compose de nombreux appels courts. C'est un contournement sensé, mais cela signifie aussi que la surcharge réseau croît linéairement avec le nombre d'étapes.

Une catégorie voisine, quoique plus étroite, est couverte par Hookdeck : il n'exécute pas tes fonctions mais reçoit les webhooks d'autres systèmes, les met en file, les relance et te laisse inspecter la charge utile pendant le débogage. Cela peut être un complément sensé, car le problème des événements entrants perdus diffère du problème de l'exécution durable. Deux choses à savoir avant de le brancher : la bibliothèque TypeScript est en version 0.4.0 d'août 2024 et n'a pas de champ de licence dans le registre, il n'existe aucun client Python, et sur la page des tarifs la même ligne de facturation apparaît à trois tarifs différents.

Erreurs courantes

Un effet de bord en dehors d'une étape. Le code entre les appels step.run s'exécute à chaque requête au sein d'une même exécution. Une écriture en base de données placée là s'exécutera autant de fois que la fonction a d'étapes. Tout ce qui change l'état du monde doit se trouver dans une étape.

Renommer l'identifiant d'une étape pendant que des exécutions sont en cours. L'identifiant, c'est-à-dire le premier argument de step.run, est la clé par laquelle le résultat stocké est retrouvé. Le renommer pendant un déploiement signifie que les exécutions en cours ne retrouveront pas leur état et exécuteront à nouveau l'étape.

Confondre throttle et rateLimit. Le premier met l'excédent en file, le second le jette. Mettre rateLimit là où tu voulais lisser le trafic vers une API externe finit par des événements silencieusement abandonnés.

Une limite de concurrence sans clé. concurrency: { limit: 5 } signifie cinq exécutions au total, pas cinq par client. Sans champ key, un gros client bloquera la file pour tous les autres.

Chiffrer le système par exécutions plutôt que par unités. Une fonction découpée en douze petites étapes coûte treize unités par exécution. Le sur-découpage du travail en étapes est directement facturable ici.

Supposer que, parce que le projet est public, la licence est permissive. Le serveur est sous SSPL et construire ton propre service destiné aux clients par-dessus demande de lire la section treize avant de décider.

FAQ

Inngest est-il open source ?

Le code est public, mais la licence du serveur n'est pas approuvée par l'Open Source Initiative. Le fichier LICENSE.md du dépôt inngest/inngest est la Server Side Public License 1.0 avec une licence Apache 2.0 supplémentaire et irrévocable qui prend effet au troisième anniversaire de la mise à disposition d'une version donnée. La bibliothèque cliente inngest sur npm, en revanche, est sous Apache 2.0, confirmé à la fois par les métadonnées du registre et par le fichier à l'intérieur du paquet publié.

En quoi throttle, rateLimit et concurrency diffèrent-ils ?

throttle limite le nombre d'exécutions qui démarrent sur une période et met l'excédent en file, avec en option une marge dans le champ burst. rateLimit, dans la même situation, abandonne les événements en excès. concurrency ne regarde pas du tout le temps, seulement le nombre d'exécutions simultanées, et accepte une portée fn, env ou account.

Inngest peut-il fonctionner sans compte cloud ?

Oui. L'image inngest/inngest avec la commande inngest start lance un serveur complet, par défaut sur SQLite avec un Redis embarqué dans le même processus. Pour la production, tu y attaches un Postgres externe avec l'option --postgres-uri et un Redis externe avec --redis-uri. La documentation précise que le support technique pour de telles instances n'est pas garanti.

Comment le coût est-il calculé sur l'offre payante ?

L'unité de facturation est une exécution, c'est-à-dire une exécution de fonction plus chaque étape exécutée à l'intérieur. Une fonction de cinq étapes consomme six unités. L'offre Hobby donne 50 mille unités par mois et met l'exécution en pause quand elles sont épuisées, l'offre Pro commence à 99 dollars avec un million d'unités incluses et une facturation à l'usage au-delà.

Que se passe-t-il quand une fonction meurt à mi-chemin ?

Les étapes déjà terminées ont leur résultat stocké et ne s'exécuteront pas une seconde fois lors d'un retry. Par défaut, une fonction a quatre tentatives, et le champ retries accepte des valeurs de zéro à vingt. Lever NonRetriableError termine l'exécution immédiatement, RetryAfterError repousse la tentative suivante du délai indiqué, et une fois toutes les tentatives épuisées, le handler onFailure est invoqué.

Puis-je exécuter une fonction sans envoyer d'événement ?

Oui, c'est à cela que sert step.invoke, qui appelle une autre fonction et attend son résultat, ainsi que les références créées par referenceFunction, qui pointent vers une fonction vivant dans une autre application. Le modèle d'événements reste la valeur par défaut, mais l'invocation directe est disponible partout où tu as besoin d'une valeur renvoyée.

La documentation se trouve sur le site d'Inngest, les tarifs sur la page des offres, et le code du serveur dans le dépôt GitHub.

À lire aussi