Référence des Composants

Vue d’ensemble

Référence complète de tous les composants GoCamel disponibles. Les composants fournissent la connectivité à divers systèmes et services.

Composants Principaux

Direct

Routage synchrone en mémoire entre routes dans le même contexte.

// Consumer : reçoit depuis un endpoint direct
// Producer : envoie vers un endpoint direct
builder.From("direct:start").To("direct:process")

Les endpoints sont identifiés par leur nom uniquement — les paramètres de requête sont ignorés pour l’identité, donc direct:start et direct:start?x=1 correspondent au même endpoint. Un seul consumer par endpoint est autorisé.

Timer

Déclenchement périodique simple.

builder.From("timer:tick?period=5s")

Composants de Transfert de Fichiers

File

Opérations sur le système de fichiers local.

// Consumer (lecture)
builder.From("file://input?delete=true")

// Producer (écriture)
builder.To("file://output")

Verrou de lecture

Lorsqu’il surveille un répertoire, le consumer attend qu’un fichier nouvellement créé cesse de changer avant de le lire. fsnotify signale Create dès que l’inode existe — bien avant que l’écrivain ait terminé — si bien qu’une lecture immédiate livrait un corps tronqué (souvent vide) pour tout fichier non écrit de façon atomique : une redirection shell, une copie, un upload.

Le consumer échantillonne la taille et la date de modification toutes les 100 ms et lit dès que deux échantillons consécutifs coïncident, en abandonnant au bout de 10 secondes (le fichier est ignoré et un avertissement journalisé). C’est l’équivalent du readLock=changed de Camel.

FTP / FTPS

Transfert de fichiers via le protocole FTP.

// Consumer
builder.From("ftp://host:21/incoming?username=admin")

// Producer
builder.To("ftp://host:21/outgoing?binary=true")

Variables d’environnement :

• FTP_USERNAME - Nom d’utilisateur
• FTP_PASSWORD - Mot de passe

SFTP

Transfert de fichiers sécurisé via SSH.

builder.From("sftp://host:22/data?username=scott")

Méthodes d’authentification :

• Par mot de passe : via le paramètre password ou la variable d’environnement SFTP_PASSWORD
• Par clé : via le paramètre privateKeyFile ou SFTP_PRIVATE_KEY_FILE

SMB

Accès aux partages Windows/Samba.

builder.From("smb://server/share/folder?username=user")

Composants Réseau

HTTP

Support serveur et client HTTP.

// Consumer (serveur HTTP)
builder.From("http://localhost:8080/api")

// Producer (client HTTP)
builder.To("http://example.com/webhook")

// Avec options
builder.To("http://api.example.com/data?httpMethod=POST")

Authentification, TLS, limitation de débit (middleware consumer)

Le consumer HTTP est livré sans authentification. Ne l’exposez à un réseau non fiable que derrière un middleware qui applique le modèle de sécurité dont vous avez besoin (vérification de token, mTLS, OAuth, allowlist d’IP, rate limit, …). Installez le middleware sur le HTTPComponent avant le démarrage de la route :

http := gocamel.NewHTTPComponent()
http.SetMiddleware(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Header.Get("Authorization") != "Bearer "+os.Getenv("API_TOKEN") {
            http.Error(w, "non autorisé", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
})
ctx.AddComponent("http", http)

Le middleware enveloppe chaque handler installé par un consumer http:// dans ce contexte.

Sanitisation des headers sortants

Le producer HTTP (To) et le chemin de réponse du consumer rejettent les noms et valeurs de header contenant \r ou \n (CRLF) pour empêcher le HTTP response splitting (CWE-113). Un exchange qui tente de définir un tel header reçoit une erreur de la part de Send().

Headers de réponse

Le corps de la réponse provient de Out (ou de In si aucun Out n’a été défini, selon la sémantique InOut de Camel). Les corps []byte et string sont écrits tels quels ; tout autre corps non nil est écrit en utilisant sa représentation %v.

Comme le consumer copie tous les headers de la requête entrante sur l’exchange, une route qui ne définit pas Out répondrait avec les headers de la requête elle-même. Deux filtres l’en empêchent :

• Les headers entrants inchangés ne sont pas renvoyés. Un header qui revient identique à celui reçu est écarté : Cookie et Authorization ne sont donc jamais réfléchis vers le client. Un header posé ou modifié par la route est toujours émis.
• Les headers hop-by-hop et de cadrage ne sont jamais émis (Connection, Keep-Alive, Transfer-Encoding, Content-Length, Host, …). Renvoyer le Content-Length de la requête corrompait le cadrage de la réponse.

Le même filtre s’applique au producer : un pont From(http://...) → To(http://...) ne transmet donc pas le Content-Length ni le Host entrants au service amont.

Statut de la réponse

Une route fixe le code de statut via le header CamelHttpResponseCode sur le message de réponse (l’ancien header Status-Code reste accepté). Les valeurs hors de 100–599 sont ignorées :

builder.From("http://localhost:8080/api").
    ProcessFunc(func(e *gocamel.Exchange) error {
        e.GetOut().SetHeader(gocamel.CamelHttpResponseCode, 201)
        e.GetOut().SetHeader("Content-Type", "application/json")
        e.GetOut().SetBody(`{"created":true}`)
        return nil
    })

Gestion des erreurs du producer

Une réponse amont de statut ≥ 300 est une erreur (comportement par défaut d’Apache Camel). L’erreur enveloppe gocamel.ErrHTTPStatus, et le corps ainsi que les headers de la réponse restent publiés sur Out pour inspection :

if errors.Is(err, gocamel.ErrHTTPStatus) {
    code, _ := exchange.GetOut().GetHeader(gocamel.CamelHttpResponseCode)
    // code est un int ; le corps contient la charge utile d'erreur amont
}

Pour considérer toute réponse comme un succès et traiter le statut soi-même :

http := gocamel.NewHTTPComponent()
http.SetThrowExceptionOnFailure(false)

Le producer renseigne également CamelHttpResponseCode (int) et CamelHttpResponseText (ex. "500 Internal Server Error") sur Out.

Durcissement

• Le serveur embarqué définit un ReadHeaderTimeout de 10 secondes pour limiter les attaques de type slowloris.

• Les corps de requête et de réponse sont lus au travers d’une limite de taille — DefaultMaxBodySize (32 Mio) — afin qu’une charge utile surdimensionnée ne puisse pas épuiser la mémoire du processus (CWE-400). Une requête trop volumineuse reçoit un 413 Request Entity Too Large. Ajustez ou désactivez la limite par composant :

  http := gocamel.NewHTTPComponent()
  http.SetMaxBodySize(256 << 20) // 256 Mio ; <= 0 désactive la limite

• Les erreurs de route ne sont pas renvoyées au client : le handler répond par un 500 internal server error générique et journalise le détail, qui peut contenir du texte SQL, des chemins de fichiers ou des messages de driver.

Arrêt

La goroutine du consumer est suivie par un WaitGroup interne et Stop() attend que http.Server.Shutdown se termine (borné par un délai interne de 30 secondes) avant de retourner. Stop() est idempotent.

Net (TCP/UDP)

Sockets TCP et UDP bruts, construits sur la bibliothèque standard — l’équivalent Go des composants netty/mina d’Apache Camel. Le consumer écoute et alimente la route avec les messages entrants ; le producer se connecte et envoie le corps du message.

// Consumer (serveur) : requête-réponse sur TCP
builder.From("net:tcp://localhost:9090")

// Consumer (serveur) : UDP sans accusé de réception
builder.From("net:udp://localhost:9090?sync=false")

// Producer (client)
builder.To("net:tcp://localhost:9090")

Formes d’URI — net:tcp://hôte:port et net:tcp:hôte:port sont acceptées ; idem pour udp. Un hôte omis prend la valeur localhost. Le port 0 demande un port éphémère à l’OS : lisez l’adresse réellement liée via NetConsumer.Address().

Cadrage. TCP est un flux d’octets : le composant a donc besoin d’une limite de message. Avec textline=true (défaut), chaque ligne terminée par un saut de ligne est un message (le \r\n ou \n final est retiré). Avec textline=false, chaque lecture est un message. Les datagrammes UDP n’ont pas besoin de cadrage : chaque datagramme est un message.

// Serveur écho requête-réponse
builder.From("net:tcp://localhost:9090").
    ProcessFunc(func(e *gocamel.Exchange) error {
        body, _ := e.GetIn().GetBody().([]byte)
        e.GetOut().SetBody([]byte("echo: " + string(body)))
        return nil
    })

Headers. Le consumer définit CamelNetRemoteAddress et CamelNetLocalAddress (hôte:port) sur le message In.

Durcissement

• Les lectures de messages sont bornées par bufferSize. Un message textline plus long que la limite est une erreur de protocole : la connexion est fermée plutôt que de mettre en tampon des données illimitées (CWE-400). Les datagrammes UDP plus grands que la limite sont tronqués.
• La lecture de la réponse du producer en mode sync est bornée par bufferSize et par le délai timeout, afin qu’un pair muet ne puisse pas bloquer la route indéfiniment.
• Les paniques dans les processeurs de route sont contenues (ProcessSafely) : une route défectueuse échoue son exchange, jamais le consumer.

Composants de Messagerie

Telegram

Intégration de l’API Telegram Bot pour la réception et l’envoi de messages.

// Requis : définir la variable d'environnement TELEGRAM_AUTHORIZATIONTOKEN
ctx.AddComponent("telegram", gocamel.NewTelegramComponent())

// Consumer (mode webhook/polling)
builder.From("telegram:bots").Log("${body}")

// Producer (envoi de messages)
builder.To("telegram:bots")

Variables d’environnement :

• TELEGRAM_AUTHORIZATIONTOKEN - Token de l’API Bot

NATS

Messagerie asynchrone orientée événements avec NATS. Publisher et subscriber haute performance avec le client Go NATS.

ctx.AddComponent("nats", gocamel.NewNATSComponent())

// Consumer : subscription asynchrone réactive
builder.From("nats://orders?servers=nats://localhost:4222").
    ProcessFunc(func(e *gocamel.Exchange) error {
        // La charge utile NATS est reçue comme un slice d'octets
        payload := e.GetIn().GetBody().([]byte)
        fmt.Printf("Commande reçue : %s\n", string(payload))
        return nil
    })

// Producer : publier vers un sujet
builder.To("nats://orders?servers=nats://localhost:4222")

// Surcharger dynamiquement le sujet via un header
exchange.In.SetHeader(gocamel.CamelNATSSubject, "urgent-orders")

Headers d’Exchange :

• CamelNATSSubject - Sujet du message reçu ou sujet cible pour la publication.

Redis

Envoi de commandes (SET, GET, DEL, PUBLISH) ou abonnement aux canaux Redis Pub/Sub.

ctx.AddComponent("redis", gocamel.NewRedisComponent())

// Consumer : s'abonner à un canal Pub/Sub
builder.From("redis://localhost:6379?subscribe=true&channel=mychannel").
    Log("Message Pub/Sub reçu : ${body}")

// Producer : exécuter des commandes
builder.To("redis://localhost:6379?command=SET&key=mykey")

Commandes supportées :

• SET : Enregistre le corps de l’exchange comme valeur de key.
• GET : Récupère la valeur de key et l’écrit dans Out.Body.
• DEL : Supprime key et écrit le nombre de clés affectées dans Out.Body.
• PUBLISH : Publie le corps de l’exchange vers le canal/clé spécifié.

Headers d’Exchange (surcharge des paramètres URI) :

• CamelRedisCommand - La commande Redis à exécuter (ex. "GET").
• CamelRedisKey - La clé Redis cible.
• CamelRedisChannel - Canal Pub/Sub cible pour la publication ou canal source pour l’abonnement.

Dépôt Idempotent Redis

Le Dépôt Idempotent Redis fournit une implémentation distribuée de l’interface IdempotentRepository, permettant à plusieurs instances GoCamel dans un cluster de se coordonner et d’éviter le traitement de messages dupliqués.

import (
    "time"
    "github.com/redis/go-redis/v9"
)

rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
// Préfixe de clé "idempotent:" avec TTL d'expiration de 24 heures
repo := gocamel.NewRedisIdempotentRepository(rdb, "idempotent:", 24*time.Hour)

builder.From("direct:start").
    IdempotentConsumer("${header.MessageId}", repo).
    To("direct:process")

Go Channel

Composant d’intégration intra-processus natif et ultra-rapide utilisant les canaux Go natifs. Il permet de découpler les segments de route de manière asynchrone au sein du même processus.

ctx.AddComponent("chan", gocamel.NewChanComponent())

// Consumer : traite les exchanges de manière asynchrone depuis le canal
builder.From("chan:orders?bufferSize=500").
    To("direct:process-order")

// Producer : écrit une copie de l'exchange dans le canal de manière asynchrone
builder.To("chan:orders")

Notes :

• Les endpoints sont mis en cache par nom de canal : chaque producer et consumer utilisant le même nom partage un endpoint, et un seul consumer par canal est autorisé (un second From("chan:orders") échoue au démarrage).
• Les options URI sont appliquées lorsque l’endpoint est créé pour la première fois ; les références ultérieures avec des options différentes émettent un avertissement et réutilisent l’endpoint existant.

Composants IA

OpenAI

Intégration de l’API OpenAI pour ChatGPT/GPT-4.

ctx.AddComponent("openai", gocamel.NewOpenAIComponent())

// Producer uniquement - envoyer une requête de chat completion
endpoint, _ := ctx.CreateEndpoint("openai:chat?model=gpt-4")
producer, _ := endpoint.CreateProducer()

exchange := gocamel.NewExchange(context.Background())
exchange.GetIn().SetBody("Bonjour, comment allez-vous ?")
producer.Send(exchange)

fmt.Println(exchange.GetOut().GetBody()) // Réponse de l'IA

Variables d’environnement :

• OPENAI_AUTHORIZATIONTOKEN ou OPENAI_API_KEY - Clé API

Composants d’Ordonnancement

Cron

Ordonnancement avancé avec expressions cron ou intervalles simples.

ctx.AddComponent("cron", gocamel.NewCronComponent())

// Déclencheur cron (6 champs, incluant les secondes)
builder.From("cron://group/job?cron=0+*+*+*+*+*")

// Déclencheur à intervalle simple
builder.From("cron://poller?trigger.repeatInterval=5000")

Format d’expression cron (6 champs) :

second minute hour day month dayOfWeek
0 * * * * *  # Chaque minute
0 */5 * * * * # Toutes les 5 minutes
cron=0 0 12 * * *  # Chaque jour à midi

Headers d’Exchange :

• fireTime - Heure d’exécution du déclencheur
• nextFireTime - Prochaine heure planifiée
• triggerName - Identifiant du déclencheur

Composants de Messagerie Électronique

SMTP/SMTPS (Envoi)

Envoi d’emails via SMTP.

builder.To("smtps://smtp.gmail.com:465?to=recipient@example.com&subject=Bonjour")

IMAP/IMAPS (Réception)

Réception d’emails via IMAP avec support IDLE.

builder.From("imaps://imap.gmail.com:993?folderName=INBOX&idle=true")

POP3/POP3S (Réception)

Réception d’emails via POP3.

builder.From("pop3s://pop.gmail.com:995?username=user&password=pass")

Composants de Base de Données

SQL

Exécution de requêtes SQL via database/sql.

import (
    "database/sql"
    _ "github.com/mattn/go-sqlite3"
)

db, _ := sql.Open("sqlite3", "./app.db")

sqlComp := gocamel.NewSQLComponent()
sqlComp.RegisterDataSource("appdb", db)
ctx.AddComponent("sql", sqlComp)

// SELECT -> Out.Body = []map[string]any
builder.From("direct:list").
    To("sql://appdb?query=SELECT+id,name+FROM+users").
    Log("${body}")

// SELECT une seule ligne -> Out.Body = map[string]any
builder.From("direct:one").
    SetHeader(gocamel.SqlParameters, []any{42}).
    To("sql://appdb?query=SELECT+*+FROM+users+WHERE+id=?&outputType=SelectOne")

// INSERT/UPDATE/DELETE -> Out.Body = lignes affectées (int64)
builder.From("direct:insert").
    SetHeader(gocamel.SqlParameters, []any{"alice", "alice@example.com"}).
    To("sql://appdb?query=INSERT+INTO+users(name,email)+VALUES(?,?)")

Format d’URI :

sql://<datasourceName>?query=<SQL>
sql://logical?dataSourceRef=<datasourceName>&query=<SQL>

Paramètres de requête :

Fournis via le header CamelSqlParameters ou le corps comme []any.

// Requête fixée par la configuration (défaut, recommandé)
builder.To("sql://appdb?query=SELECT+*+FROM+users+WHERE+id=?")

// Requête fournie par message — uniquement avec des headers de confiance
builder.To("sql://appdb?allowHeaderOverride=true&query=SELECT+1")

Headers de sortie :

• CamelSqlRowCount - Lignes retournées/affectées
• CamelSqlColumnNames - Noms des colonnes (SELECT)

Corps du résultat :

Classification des requêtes :

Le choix entre exécution en lecture (jeu de résultats) et en écriture (lignes affectées) se fait sur le premier mot-clé, en ignorant les commentaires et parenthèses de tête. SELECT, WITH (CTE), VALUES, TABLE, SHOW, EXPLAIN, DESCRIBE et PRAGMA renvoient des lignes, tout comme une requête portant une clause RETURNING :

WITH recent AS (SELECT * FROM orders WHERE ts > ?)
SELECT id, total FROM recent          -- jeu de résultats
INSERT INTO users(name) VALUES (?) RETURNING id   -- jeu de résultats

SQL-Stored

Exécution de procédures stockées avec support des paramètres IN, OUT et INOUT.

import (
    "database/sql"
    _ "github.com/mattn/go-sqlite3"
)

db, _ := sql.Open("mysql", "user:pass@/mydb")

sqlStored := gocamel.NewSQLStoredComponent()
sqlStored.RegisterDataSource("mydb", db)
ctx.AddComponent("sql-stored", sqlStored)

// Appel simple avec paramètres IN
builder.From("direct:call").
    SetBody([]gocamel.StoredProcedureParam{
        {Name: "userId", Direction: gocamel.ParamDirectionIn, Value: 42},
    }).
    To("sql-stored://mydb?procedure=GET_USER_BY_ID").
    Log("${body}")

Format d’URI :

sql-stored://datasourceName?procedure=NAME
sql-stored://logical?dataSourceRef=dsName&procedure=NAME

Directions des paramètres :

Exemple :

params := []gocamel.StoredProcedureParam{
    {Name: "inParam", Direction: gocamel.ParamDirectionIn, Value: "input"},
    {Name: "outParam", Direction: gocamel.ParamDirectionOut},
    {Name: "inOutParam", Direction: gocamel.ParamDirectionInOut, Value: 123},
}

MongoDB

Intégration MongoDB pour les opérations CRUD. Producer uniquement.

Format d’URI

mongodb://connectionName?database=mydb&collection=mycoll&operation=find

Options

Par sécurité, remove refuse les filtres nuls ou vides. Définissez allowDeleteAll=true explicitement uniquement si la suppression de toute la collection est intentionnelle.

Headers d’entrée

Headers de sortie

Exemple

import (
    "context"
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
)

// Créer le composant
mongoComp := gocamel.NewMongoDBComponent()

// Se connecter
client, _ := mongo.Connect(context.Background(), options.Client().ApplyURI("mongodb://localhost:27017"))
conn := gocamel.CreateMongoDBConnection(client, "mongodb://localhost:27017", "mydb")
mongoComp.RegisterConnection("myconn", conn)

builder.WithComponent("mongodb", mongoComp)

// Insertion
builder.From("timer:tick?period=5s").
    SetBody(map[string]any{"name": "test", "value": 123}).
    To("mongodb://myconn?database=mydb&collection=items&operation=insert")

// Requête avec filtre
builder.From("direct:search").
    SetHeader(gocamel.CamelMongoDbCriteria, map[string]any{"status": "active"}).
    SetHeader(gocamel.CamelMongoDbLimit, 10).
    To("mongodb://myconn?database=mydb&collection=items&operation=find")

Composants de Transformation

XSLT

Transformation XML via feuille de style XSL.

builder.To("xslt:file://transform.xsl")

XSD

Validation de schéma XML.

builder.To("xsd:file://schema.xsd")

Template

Traitement de templates Go (inspiré d’Apache Camel Velocity).

// Template de base
builder.To("template:templates/email.tmpl")

// Avec cache
builder.To("template:templates/item.tmpl?contentCache=true")

// Template dynamique depuis un header
builder.To("template:default.tmpl?allowTemplateFromHeader=true")

Variables de template :

{{.Body}}              # Corps du message
{{.Headers.name}}      # Valeur de header
{{.Exchange.ID}}       # ID de l'Exchange
{{.Exchange.Created}}  # Horodatage de création

Fonctions de template :

{{.Body | upper}}
{{.Body | lower}}
{{.Body | trim}}
{{now | formatDate "2006-01-02 15:04:05"}}
{{"hello" | contains "ell"}}

Composants d’Exécution

Exec

Exécuter des commandes système.

builder.To("exec:ls -la")

Surcharges par message (opt-in) :

Quand allowHeaderOverride=true, ces headers surchargent les paramètres URI pour un seul message :

Sortie :

• Out.Body = stdout de la commande (également recopié sur In pour la rétrocompatibilité, afin qu’une route InOut voie la sortie de la commande)
• Header CamelExecExitValue = code de sortie
• Headers CamelExecStdout / CamelExecStderr = sortie brute de la commande

Configuration des Composants

Authentification

Les identifiants peuvent être fournis via des variables d’environnement :

// FTP avec variable d'environnement
builder.From("ftp://host?username=${env:FTP_USER}")

// Ou paramètre
builder.From("ftp://host?username=admin&password=${env:FTP_PASS}")

Options communes

De nombreux composants partagent des options d’interrogation communes :

// Interrogation de fichiers
builder.From("file://data?delay=10s&delete=true")

// Interrogation FTP
builder.From("ftp://host/incoming?delay=30s&include=*.xml")

Tableau Récapitulatif des Composants