Référence de configuration#

Cette page documente chaque clé que DurableBundle accepte dans config/packages/durable.yaml.

Termes employés plus bas (le glossaire définit chacun d’eux) :

• Une exécution est un déroulement durable d’un workflow.
• Le journal est l’enregistrement, en ajout seul, de tout ce qu’une exécution a décidé et reçu.
• Une activité est une unité d’effet de bord, comme un appel HTTP ou une écriture en base.
• Un worker est le processus qui rejoue les workflows et exécute les activités.
• Le rejeu est la façon dont une exécution reprend, en réexécutant le code du workflow depuis sa première ligne face au journal.

Toutes les clés et leur défaut#

Produit à partir de l’arbre de configuration du bundle par bin/console config:dump-reference durable ; un test du banc Symfony échoue quand ce bloc et l’arbre divergent. Les commentaires du bloc viennent du code et restent en anglais ; les sections ci-dessous disent à quoi sert chaque clé.

# Default configuration for extension with alias: "durable"
durable:

    # Where the journal lives. in_memory: one process. dbal: a SQL database (DUR030). temporal: the cluster at temporal.dsn. dbal with a temporal.dsn keeps the journal in SQL and uses the cluster to serve Nexus. Derived from the deprecated event_store.type and temporal.journal when unset.
    backend:              null # One of "in_memory"; "dbal"; "temporal"

    # DBAL backend: durable execution on a single SQL database, with no orchestration cluster (DUR030).
    dbal:

        # Service id of the Doctrine\DBAL\Connection to use
        connection:           doctrine.dbal.default_connection

        # Create the missing tables on the first write, never inside an open transaction. Set it to false as soon as doctrine/migrations holds the schema: otherwise the two mechanisms write one behind the other. bin/console durable:setup creates them either way.
        auto_setup:           true

        # Service id of the Symfony\Component\Lock\LockFactory that serialises the resumes of one execution
        lock_factory:         lock.factory

        # Accept a per-process lock store (flock, semaphore, in-memory). Only safe with exactly one worker: two workers holding a local lock replay the same execution at once.
        allow_local_lock:     false

        # Seconds a resume lock outlives a worker that died holding it. The pass refreshes it at every message it sends through the bus, so it must exceed the longest step of a pass, or a second worker replays the same execution in parallel.
        lock_ttl:             300.0
    event_store:
        type:                 null # One of "in_memory"; "dbal", Deprecated (Since gplanchat/durable-bundle 0.1.0-beta1: The "durable.event_store.type" option is deprecated: set durable.backend instead.)

        # Table of the dbal journal.
        table_name:           durable_events
    temporal:

        # A temporal://… DSN (for instance %env(DURABLE_DSN)%). When set, it turns on the native Temporal backend (gRPC); over ext-grpc when it is loaded, over curl (ext-curl) otherwise; temporal+http:// for the JSON gateway. No SQL/PDO.
        dsn:                  null

        # Write the DurableWorkflowName and DurableExecutionId search attributes on every start, so the run list can filter by workflow name and execution id. Register both on the namespace before turning this on: a server refuses a start that names an unregistered attribute.
        search_attributes:    false

        # A service id: the application's GuzzleHttp\ClientInterface, which transport=guzzle then uses: its proxy, TLS options and middleware apply to gRPC. Unused by any other transport; null builds a default client.
        guzzle_client:        null

        # A service id: the application's PSR-18 client, which transport=http (the JSON gateway) then uses instead of curl. Unused by any other transport.
        psr18_client:         null

        # A service id implementing both PSR-17 RequestFactoryInterface and StreamFactoryInterface (Guzzle's HttpFactory, nyholm's Psr17Factory). Defaults to psr18_client, which Symfony's Psr18Client satisfies on its own.
        psr17_factory:        null

        # A service id: the application's PayloadCodecInterface, which encodes every payload sent to Temporal and decodes every payload read (DUR055). The codec holds its own key, from the application's secrets or environment; Durable reads none. null sends payloads as they are.
        payload_codec:        null

        # false: the cluster is reachable, but the journal stays the one in event_store. An application serving a Nexus operation from a DBAL journal needs both, and there are not two sources of truth, since event_store says which one it is.
        journal:              null # Deprecated (Since gplanchat/durable-bundle 0.1.0-beta1: The "durable.temporal.journal" option is deprecated: set durable.backend instead.)
    activity_transport:

        # in_memory runs activities inside the workflow task; messenger routes them to transport_name.
        type:                 in_memory # One of "in_memory"; "messenger"

        # The Messenger transport activities go to when type is messenger.
        transport_name:       durable_activities
    messenger:

        # Ids of the Messenger buses the bundle installs its middleware on (resume lock, profiler). Empty, which is the default, installs them on every bus, and that is the historical behaviour. Naming buses avoids imposing a per-execution lock on the business command bus, which carries no durable message.
        buses:                []
    profiler:

        # Registers the execution trace, the web profiler panel and the observer on the hot path. Defaults to kernel.debug.
        enabled:              '%kernel.debug%'

    # Retry ceiling for every activity; an activity's own limit can only be stricter. 0: no ceiling.
    max_activity_retries: 0
    activity_contracts:

        # PSR-6 cache pool ID for activity contract metadata
        cache:                null

        # Class names of activity contracts to warm at cache warmup
        contracts:            []
    child_workflow:

        # true: child workflows are dispatched through Messenger; false: they run inside the parent task.
        async_messenger:      false
        parent_link_store:
            type:                 null # One of "in_memory"; "dbal", Deprecated (Since gplanchat/durable-bundle 0.1.0-beta1: The "durable.child_workflow.parent_link_store.type" option is deprecated: set durable.backend instead.)

            # Table of the dbal parent links.
            table_name:           durable_child_workflow_parent_link
    workflow_metadata:
        type:                 null # One of "in_memory"; "dbal", Deprecated (Since gplanchat/durable-bundle 0.1.0-beta1: The "durable.workflow_metadata.type" option is deprecated: set durable.backend instead.)

        # Table of the dbal workflow metadata.
        table_name:           durable_workflow_metadata

La valeur par défaut de activity_transport.type est in_memory. Si vous omettez la clé, les activités s’exécutent de façon synchrone dans la tâche de workflow, quel que soit le transport défini dans messenger.yaml. C’est pourquoi tous les exemples de ce site posent la clé explicitement. Voir activity_transport.

backend#

Où vit le journal. Une seule clé fixe le stockage du journal, des métadonnées de workflow et des liens parents, pour que les trois concordent et qu’une même exécution n’ait jamais deux sources de vérité.

dbal avec un temporal.dsn garde le journal en SQL et n’utilise le cluster que pour servir les opérations Nexus (des opérations servies par un autre service, qu’un workflow appelle comme une activité) ; voir Opérations Nexus.

Quand la configuration se contredit, la construction du conteneur échoue, avec le chemin durable dans le message. Deux cas provoquent cet échec : backend: temporal sans DSN, et une clé dépréciée ci-dessous qui dit autre chose que backend.

event_store.type, workflow_metadata.type, child_workflow.parent_link_store.type et temporal.journal sont dépréciées depuis 0.1.0-beta1 et seront retirées dans la prochaine version. Quand backend n’est pas défini, le bundle le déduit d’elles : une configuration existante continue donc de fonctionner et signale une dépréciation. UPGRADE.md en donne la traduction.

dbal#

La connexion et le verrou du backend SQL. Le bundle ne lit cette section que quand backend vaut dbal et l’ignore sinon : la laisser à ses valeurs par défaut ne coûte donc rien.

La page Backends décrit le compromis que fait ce backend et pourquoi il dépend du verrou.

event_store#

Où l’historique d’événements du workflow est stocké.

Stockage d’événements local sur le backend Temporal#

Avec backend: temporal, le stockage d’événements local est en mémoire, ce qui est la configuration attendue. TemporalReadThroughEventStore l’enveloppe et récupère à la demande, par le gRPC de Temporal (GetWorkflowExecutionHistory), les événements absents localement : le DataCollector du profileur Symfony fonctionne ainsi d’un processus à l’autre.

temporal#

Format du DSN#

temporal://HÔTE:PORT?namespace=ESPACE&journal_task_queue=FILE&activity_task_queue=FILE

Le schéma fixe le protocole de transport et le chiffrement :

Tout autre paramètre est une erreur, et le message le nomme : une coquille comme namesapce= ne retombe donc plus en silence sur l’espace de noms default. De même pour ca, cert, key ou api_key sans TLS. Avec un client PSR-18 remis à la passerelle JSON, le TLS relève de la configuration de ce client, et ca, cert et key sont des erreurs.

Exemple :

temporal://127.0.0.1:7233?namespace=default&journal_task_queue=durable-journal&activity_task_queue=durable-activities

Pour lire le DSN dans une variable d’environnement :

durable:
    temporal:
        dsn: '%env(DURABLE_DSN)%'

workflow_metadata#

Où sont stockés le type de workflow et sa charge utile initiale. Le bundle les retrouve par executionId quand il reprend une exécution.

activity_transport#

Comment le bundle achemine les messages d’activité, des tâches de workflow vers les gestionnaires d’activité.

Par défaut, les activités s’exécutent en ligne, dans la tâche de workflow. Définir durable_activities dans messenger.yaml ne le sélectionne pas. Sans type: messenger, le transport reste vide et l’activité s’exécute en ligne, sur le temps de la tâche de workflow et sans la sémantique de réessai que le transport apporte.

messenger#

durable:
    messenger:
        buses:
            - messenger.bus.durable

Les bus Messenger sur lesquels le bundle installe ses middlewares : le verrou de reprise DBAL, et le middleware de profil en debug.

Le défaut est tous les bus, ce que les versions précédentes faisaient sans condition. Un défaut plus fin n’est pas possible, car rien n’indique au bundle vers quel bus votre application route ResumeWorkflowMessage. Un mauvais choix retirerait le verrou de reprise du bus qui porte le travail, et les reprises perdraient la protection du verrou sans aucune erreur.

Nommer les bus vaut la peine dès que votre application en a plusieurs. Un bus de commandes métier ne transporte aucun message durable, et un verrou par exécution sur ce bus ajoute une contention inutile. Un identifiant qui ne nomme aucun bus déclaré lève une erreur à la compilation au lieu de ne rien faire en silence.

profiler#

Le panneau affiche ce qu’attend chaque exécution tracée, lu dans le catalogue des exécutions. Sur Temporal, cela coûte un appel DescribeWorkflowExecution par exécution de la requête profilée, deux pour une exécution que Durable n’a pas démarrée.

max_activity_retries#

durable:
    max_activity_retries: 3

Plafond sur les réessais automatiques, appliqué à chaque activité sur les backends in_memory, dbal, illuminate (Laravel), temporal et Magento Database : la RetryLimit propre à une activité ne peut qu’être plus stricte. Une valeur négative est une erreur de configuration. 0 signifie aucun plafond, et comme une activité sans RetryLimit réessaie indéfiniment (le défaut de Temporal), laisser les deux non définis revient à ce qu’une activité en échec ne fasse jamais échouer le workflow. Posez une borne par activité avec RetryLimit::ofAttempts() ou RetryLimit::once() ; voir Options et objets valeur. Sur le backend temporal, le worker de workflow écrit la limite la plus stricte dans la politique de réessais de l’activité.

Sous Laravel, la même clé dans config/durable.php ; sous Magento, l’argument maxActivityRetries de RuntimeFactory dans di.xml, que MagentoRuntime::run() lit sans DSN et que les workers du backend Magento Database lisent et que RuntimeFactory transmet au worker de workflow Temporal (voir le tableau des hôtes).

activity_contracts#

Le bundle peut mettre en cache, au préchauffage du conteneur, les métadonnées de contrat d’activité déjà résolues (noms de méthodes, attributs), ce qui évite le coût de la réflexion à l’exécution.

durable:
    activity_contracts:
        cache: cache.app
        contracts:
            - App\Workflow\Activity\OrderActivities
            - App\Workflow\Activity\NotificationActivities

child_workflow#

Comment sont lancés les workflows enfants (des exécutions démarrées par une autre exécution).

Configuration par environnement (when@)#

Pour changer de backend selon l’environnement, employez la syntaxe when@ de Symfony :

# En mémoire pour chaque environnement non redéfini plus bas
durable:
    backend: in_memory

# Temporal pour dev et prod
when@dev:
    durable:
        backend: temporal
        temporal:
            dsn: '%env(DURABLE_DSN)%'

when@prod:
    durable:
        backend: temporal
        temporal:
            dsn: '%env(DURABLE_DSN)%'

# En mémoire pour les tests, même si DURABLE_DSN est défini
when@test:
    durable:
        child_workflow:
            async_messenger: false

Les mêmes réglages sous Laravel et Magento#

Une ligne par réglage. La dernière colonne est une proposition en cours de revue (#357) : identique (le réglage existe sur chaque hôte qui peut s’en servir), propre à l’hôte (avec la raison), ou à ajouter. Magento atteint trois journaux : la mémoire, Temporal et son propre backend de base de données. Les lignes DBAL et Illuminate ne s’y appliquent pas.

Voir aussi#

• Backends compare les backends mémoire, SQL et Temporal : mise en place Docker, workers, paramètres du DSN.
• Premiers pas couvre la configuration du routage Messenger.
• Tester des workflows couvre DurableBundleTestTrait et la configuration de test en mémoire.