Enterprise Integration Patterns

Overview

GoCamel implements the Enterprise Integration Patterns (EIP) from the classic book by Gregor Hohpe and Bobby Woolf.

Message Routing

Choice

Content-based routing with conditional branches.

builder.From("direct:start").
    Choice().
        When("${header.priority == 'high'}").
            Log("High priority: ${body}").
            To("direct:urgent").
        When("${header.type} == 'order'&& ${body['amount']} > 1000").
            Log("Large order").
            To("direct:large-orders").
        When("${header.type} == 'email'").
            To("direct:emails").
        Otherwise().
            Log("Default").
            To("direct:normal").
    EndChoice()

Syntax:

  • When(expression) - Adds a conditional branch
  • Otherwise() - Adds a default branch
  • EndChoice() - Ends the Choice block and adds it to the current container (the route, or a surrounding Split / Loop / Multicast so each part is evaluated)
  • End() - Alternative method

Expression Operators:

OperatorDescriptionExample
==Equal${header.type} == 'order'
!=Not equal${header.status} != 'error'
>Greater than${header.count} > 10
>=Greater or equal${header.count} >= 10
<Less than${header.price} < 100
<=Less or equal${header.price} <= 100
&&ANDa > 5 && b == 'x'
||ORa > 5 || b == 'y'

Filter

Filter messages based on a condition. Exchanges that do not match are silently dropped (ErrStopRouting). The drop only ends the current route: when that route was called through direct:, the caller carries on (as with an incomplete Aggregator or a Resequencer). Use Stop() to end the exchange everywhere.

// Simple Language expression (comparison inside ${...})
builder.From("direct:start").
    Filter("${header.type == 'order'}").
    To("direct:orders").
    Build()

// Go predicate
builder.From("direct:start").
    Filter(func(e *gocamel.Exchange) (bool, error) {
        body, ok := e.GetBodyAsString()
        return ok && body != "", nil
    }).
    To("direct:nonEmpty").
    Build()

Throttle

Rate-limit exchange processing to at most N messages per time window. Exchanges that exceed the rate are delayed, not dropped, until the window resets.

// Max 100 messages per second
builder.From("direct:start").
    Throttle(100, time.Second).
    To("direct:downstream").
    Build()

// Max 10 messages per 500ms (smoother than 1s window)
builder.From("direct:start").
    Throttle(10, 500*time.Millisecond).
    To("direct:api").
    Build()

Notes:

  • Uses a fixed-window counter; for smoother behaviour use smaller windows
  • Blocking: the goroutine sleeps until the window allows the exchange through
  • maxRequests and timePeriod must be greater than zero; invalid values return an error instead of blocking indefinitely
  • If the exchange context is cancelled while waiting for the next window, Process returns an error

Sample

Let only a sample of the exchanges through. Unlike Throttle, which delays exchanges, Sample drops the others silently, regardless of their content.

// At most one message per second (the first of each period passes)
builder.From("direct:sensor").
    Sample(time.Second).
    To("direct:dashboard").
    Build()

// One message out of every 100 (the first one passes)
builder.From("direct:sensor").
    SampleEvery(100).
    To("direct:dashboard").
    Build()

Notes:

  • Dropped exchanges stop with ErrStopRouting: they are not treated as failures
  • No background goroutine: only a mutex guards the timestamp or counter
  • Sample keeps the first exchange of each period, not the latest one
  • A non-positive period or count is reported by Route.Validate(); Process returns an error instead of passing everything

Delay

Pause exchange processing for a fixed or dynamically computed duration. The sleep respects context cancellation.

// Fixed delay
builder.From("direct:start").
    Delay(500 * time.Millisecond).
    To("direct:next").
    Build()

// Dynamic delay from a header
builder.From("direct:start").
    DelayFunc(func(e *gocamel.Exchange) (time.Duration, error) {
        ms, ok := e.GetHeaderAsInt("X-Delay-Ms")
        if !ok {
            return 0, nil  // no delay if header absent
        }
        return time.Duration(ms) * time.Millisecond, nil
    }).
    To("direct:next").
    Build()

Notes:

  • Blocking: the goroutine sleeps for the computed duration
  • If the exchange context is cancelled during the sleep, Process returns an error
  • Return 0 from DelayFunc to skip the delay for a given exchange
  • Passing nil to DelayFunc fails route construction; NewDelayerFunc(nil) remains constructible but returns a processing error instead of panicking

Content Enricher

Fetch additional data from an external resource and merge it into the current exchange.

// With aggregation strategy
type MergeStrategy struct{}

func (s *MergeStrategy) Aggregate(original, enriched *gocamel.Exchange) *gocamel.Exchange {
    origBody, _ := original.GetBodyAsString()
    enrichBody, _ := enriched.GetBodyAsString()
    original.GetIn().SetBody(origBody + " enriched with: " + enrichBody)
    return original
}

builder.From("direct:start").
    Enrich("http://api.example.com/data", &MergeStrategy{}).
    To("direct:next").
    Build()

// Without strategy β€” replaces body with enrichment response
builder.From("direct:start").
    Enrich("direct:lookup", nil).
    To("direct:next").
    Build()

How it works:

  1. A copy of the current exchange is sent to the enrichment URI
  2. The response is received
  3. AggregationStrategy.Aggregate(original, response) merges the two
  4. If no strategy is provided, the response body replaces the original body

PollEnrich

Poll on-demand from a consumer endpoint (with timeout and optional aggregation strategy).

Supported endpoints are seda, chan, and custom implementations of PollingEndpoint. One call receives at most one exchange and leaves the queue open with its remaining messages intact. Endpoints without this contract, or queues with an existing consumer or concurrent poll, return an error before consuming a message. A zero timeout is non-blocking; a negative timeout waits until a message arrives or the exchange context is cancelled. A positive timeout leaves the original message unchanged when no message arrives.

// Poll from a queue with 2 seconds timeout and custom merge strategy
builder.From("direct:start").
    PollEnrich("seda:pending-orders", &MergeStrategy{}, 2*time.Second).
    To("direct:process")

// Non-blocking poll (timeout 0) replacing body
builder.From("direct:start").
    PollEnrichWithTimeout("chan:updates", 0).
    To("direct:process")

Message Validator

Validate in-flight messages against a predicate, failing the exchange with ErrValidationFailed if the condition is not met.

// Validate using Simple Language
builder.From("direct:start").
    Validate("${header.priority == 'high'}").
    To("direct:urgent")

// Validate using JSONPath
builder.From("direct:start").
    Validate(gocamel.JsonPath("$.user.active")).
    To("direct:active-users")

// Validate using custom function
builder.From("direct:start").
    ValidateFunc(func(e *gocamel.Exchange) bool {
        body, _ := e.GetBodyAsString()
        return len(body) > 0
    }).
    To("direct:output")

Idempotent Consumer

Prevent duplicate messages from being processed.

repo := gocamel.NewMemoryIdempotentRepository()

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

How it works:

  1. Evaluates the expression to get a unique key.
  2. Checks if the key exists in the repository.
  3. If not present, adds the key eagerly (blocking concurrent duplicates) and proceeds.
  4. If present, stops routing (ErrStopRouting).
  5. If the exchange later fails downstream, the key is removed from the repository again (via an exchange Synchronization), so a redelivery of the same message is processed instead of being dropped β€” at-least-once semantics.

Repositories:

  • NewMemoryIdempotentRepository(): In-memory store (default).
  • NewRedisIdempotentRepository(): Distributed store backed by Redis.
  • SQL-based repositories can be implemented via the IdempotentRepository interface.

Circuit Breaker

Protect routes from cascading failures when calling unstable external services.

builder.From("direct:start").
    CircuitBreaker().
        FailureThreshold(5).           // Open after 5 failures
        OpenTimeout(30 * time.Second).  // Stay open for 30s
        SuccessThreshold(2).           // Close after 2 successes in Half-Open
        Process(unstableProcessor).
        OnFallback().
            Log("Circuit open or failed, calling fallback").
            To("direct:fallback").
        End().
    End().
    To("direct:result").
    Build()

States:

  • Closed: Requests pass through. Failures are counted.
  • Open: Requests fail immediately or go to fallback.
  • Half-Open: After OpenTimeout, a single trial request at a time probes the downstream service; concurrent requests are diverted to the fallback as if the circuit were still open. Once SuccessThreshold successful probes complete, the circuit closes. If a probe fails, it opens again.

ErrStopRouting (Filter, incomplete aggregation, Stop EIP) is not a failure: it does not increment the failure count and does not open the circuit.


Load Balancer

Distribute messages across multiple endpoints.

builder.From("direct:start").
    LoadBalance().RoundRobin().
        To("direct:server1").
        To("direct:server2").
        To("direct:server3").
    End().
    Build()

Strategies:

  • RoundRobin(): Circular distribution (default).
  • Random(): Random distribution.
  • Custom(strategy): Provide a custom implementation of the LoadBalancerStrategy interface.

SEDA

Staged Event-Driven Architecture. Decouples producers and consumers using an internal queue (Go channel).

// Consumer with concurrent workers
builder.From("seda:process?concurrentConsumers=5&size=1000").
    Log("Asynchronously processing: ${body}").
    To("direct:next")

// Producer
builder.To("seda:process")

How it works:

  1. The producer sends a copy of the exchange to an internal queue.
  2. The producer returns immediately (non-blocking if queue is not full).
  3. One or more consumer workers read from the queue and process the exchange.

Parameters:

  • size: The capacity of the internal queue (default 1000).
  • concurrentConsumers: The number of worker goroutines (default 1).
  • shutdownTimeout: How long Stop keeps processing the queued exchanges, in ms (default 30000; 0 discards them immediately).

Invalid values (negative size, non-positive concurrentConsumers) fall back to the defaults with a warning. Parameters are applied when the endpoint is first created; later references to the same queue name reuse the existing endpoint, and a reference with different options logs a warning.

Context. Workers process each exchange under the consumer’s context, not the sender’s. A route such as From("http://...").To("seda:work") returns as soon as the message is queued, which cancels the HTTP request context; the asynchronous leg is not affected and its HTTP calls, delays and SQL queries run normally.

Shutdown. Stop first rejects new sends (and unblocks producers waiting on a full queue), then lets the workers finish the exchanges already queued, for up to shutdownTimeout. It then cancels the consumer context; exchanges still queued are completed as failures. CamelContext.GracefulStop cancels the context up front, so it does not wait for the queue.


Resequencer

Reorder messages that arrived out of order based on a sequence number or timestamp.

builder.From("direct:start").
    Resequence("${header.seq}", 1). // Starts with sequence 1
        Timeout(500 * time.Millisecond).
        Log("Processing in order: ${header.seq}").
        To("direct:next").
    End()

How it works:

  1. Evaluates the expression to get the sequence number.
  2. If the sequence is the next expected one, it’s processed immediately.
  3. If it’s a future sequence, it’s buffered and sorted.
  4. If a gap persists longer than the Timeout, the resequencer skips the missing sequence and continues with the next available one in the buffer.

Notes:

  • Messages are delivered downstream through the resequencer’s internal pipeline (the steps between Resequence(...) and End()). The original exchange stops there (ErrStopRouting), so steps placed after End() never see out-of-order messages.
  • Delivery is serialized to guarantee ordering; downstream steps must not route back into the same resequencer.
  • Duplicate or outdated sequence numbers are dropped (logged as warnings).
  • A buffered exchange is delivered later, by another message or by the timeout: it runs downstream under the route’s lifecycle context, not the context of the request that brought it (which is usually over by then).
  • A message only fails for its own downstream error. The failure of another buffered exchange delivered in the same batch is logged; it is not reported to the message that triggered the delivery, and does not go through the route’s error handler.

Claim Check

Reduce the size of messages by storing the payload in an external repository and passing only a reference (key).

repo := gocamel.NewMemoryClaimCheckRepository()

builder.From("direct:start").
    // Store body and replace with key
    ClaimCheck(gocamel.ClaimCheckPush, "my-ticket", repo).
    To("direct:other-system"). // Only the key "my-ticket" is sent
    // Restore original body
    ClaimCheck(gocamel.ClaimCheckPop, "my-ticket", repo).
    To("direct:next")

Operations:

  • ClaimCheckPush: Stores the body and replaces it with a key. If no key is provided, one is generated.
  • ClaimCheckPop: Retrieves the data by key, restores the body, and removes it from the repository.
  • ClaimCheckGet: Retrieves the data by key and restores the body (keeps it in the repository).
  • ClaimCheckDiscard: Removes the data from the repository without restoring it.

Multicast

Send a copy of the message to multiple destinations.

builder.From("direct:start").
    Multicast().
        To("direct:archive").
        To("direct:audit").
        To("direct:analytics").
    End()

With Parallel Processing:

builder.From("direct:start").
    Multicast().ParallelProcessing().
        To("direct:branch1").
        To("direct:branch2").
        To("direct:branch3").
    End()

With Strategy:

strategy := &MyAggregationStrategy{}

builder.From("direct:start").
    Multicast().Strategy(strategy).
        To("direct:a").
        To("direct:b").
        To("direct:c").
    End()

Message Transformation

Splitter

Divide a message into parts.

builder.From("direct:start").
    Split(func(e *gocamel.Exchange) (any, error) {
        body := e.GetIn().GetBody().(string)
        // Split by comma
        return strings.Split(body, ","), nil
    }).
    Log("Processing part: ${body}").
    To("direct:process").
    End() // End Split

With Aggregation:

type StringJoinStrategy struct{}

func (s *StringJoinStrategy) Aggregate(oldEx, newEx *gocamel.Exchange) *gocamel.Exchange {
    if oldEx == nil {
        return newEx
    }
    old := oldEx.GetIn().GetBody().(string)
    new := newEx.GetIn().GetBody().(string)
    oldEx.GetIn().SetBody(old + "," + new)
    return oldEx
}

strategy := &StringJoinStrategy{}

builder.From("direct:start").
    Split(splitter).Strategy(strategy).
        To("direct:process").
    End()

Parallel processing:

builder.From("file:/data/in").
    Split(lines).ParallelProcessing(true).MaxConcurrency(20). // default 10
        To("http://api/items").
    End()

Exchange Properties during Split:

PropertyTypeDescription
CamelSplitIndexintCurrent index (0-based)
CamelSplitSizeintTotal number of parts
CamelSplitCompleteboolLast part indicator
These properties are branch-scoped

They describe one part, not the whole message, and are removed when the aggregated result is published back onto the parent exchange. A processor placed after the Split does not see CamelSplitComplete=true left over from the last part, and a nested Split does not overwrite the bookkeeping of the enclosing one. The same rule applies to CamelMulticast*, CamelRecipientList* and CamelRoutingSlip*.

A []byte body is not a collection

Splitting a []byte body yields a single part, matching Apache Camel, which does not split byte[]. Treating it as a list produced one exchange per byte β€” a 10 KB payload became 10 000 exchanges. To divide binary content deliberately, split on a decoded value instead:

Split(func(e *gocamel.Exchange) (any, error) {
    return strings.Split(string(e.GetBody().([]byte)), "\n"), nil
})

Aggregator

Combine multiple messages into one.

At least one completion condition is required: SetCompletionSize, SetCompletionTimeout, or SetCompletionPredicate. Without one, Process returns an error instead of buffering forever.

// Define correlation expression and completion condition
correlationExpr := "${header.orderId}"
strategy := &OrderAggregationStrategy{}
repo := gocamel.NewMemoryAggregationRepository()

aggregator := gocamel.NewAggregator(correlationExpr, strategy, repo).
    SetCompletionSize(3).    // Complete when 3 messages received
    SetCompletionTimeout(5000) // Or after 5 seconds

builder.From("direct:start").
    Aggregate(aggregator).
        Log("Aggregated: ${body}").
    End()

Aggregation Strategy:

type OrderAggregationStrategy struct{}

func (s *OrderAggregationStrategy) Aggregate(
    oldExchange,
    newExchange *gocamel.Exchange,
) *gocamel.Exchange {
    if oldExchange == nil {
        // First message
        return newExchange
    }
    
    // Combine messages
    old := oldExchange.GetIn().GetBody().(Order)
    new := newExchange.GetIn().GetBody().(Order)
    
    old.Items = append(old.Items, new.Items...)
    old.Total += new.Total
    
    oldExchange.GetIn().SetBody(old)
    return oldExchange
}

Completion Conditions:

MethodDescription
SetCompletionSize(n)Complete after n messages
SetCompletionTimeout(ms)Complete after timeout
SetCompletionPredicate(fn)Complete when predicate returns true

Storage Options:

// In-memory (default)
repo := gocamel.NewMemoryAggregationRepository()

// SQLite persistence
repo := gocamel.NewSQLAggregationRepository(db, "schema")

When a route with a completion timeout starts, the groups already held by the repository get a full CompletionTimeout again: a group left pending by a stopped route, or persisted in SQL across a process restart, still expires instead of waiting forever for its size or predicate. Custom repositories get this by implementing ListableAggregationRepository (Keys).


Transformer

Transform message content.

// Set body directly
builder.From("direct:start").
    SetBody("Hello World")

// Set body via function
builder.From("direct:start").
    SetBodyFunc(func(e *gocamel.Exchange) (any, error) {
        input := e.GetIn().GetBody().(string)
        return strings.ToUpper(input), nil
    })

// Transform via Simple Language
builder.From("direct:start").
    SimpleSetBody("Processed: ${body} at ${date:now}")

Transform

A dedicated message transformation EIP that modifies the message body dynamically using a custom Go function or a Simple language expression.

// Transform using a custom Go function
builder.From("direct:start").
    Transform(func(e *gocamel.Exchange) (any, error) {
        input, _ := e.GetBodyAsString()
        return "Transformed: " + input, nil
    }).
    To("direct:output")

// Transform using a Simple Language expression
builder.From("direct:start").
    TransformSimple("Modified: ${body} and type is ${header.Type}").
    To("direct:output")

Messaging Systems

Pipeline

Sequential processing within multicast.

builder.From("direct:start").
    Multicast().
        Pipeline().
            Log("Step 1").
            To("direct:step1").
        End().
        Pipeline().
            Log("Step 2").
            To("direct:step2").
        End().
    End()

ToD (Dynamic To)

Send to dynamically computed endpoint.

// Header determines destination
builder.From("direct:start").
    SetHeader("dest", "direct:output").
    ToD("${header.dest}")

// URI with expression
builder.From("direct:start").
    ToD("file://output/${header.filename}")

Escaping. Exchange values are data, not URI syntax. Each value is escaped according to where its placeholder sits in the template (InterpolateURI):

  • in the query string, it is query-escaped, so a header such as a&allowHeaderOverride=true stays inside its option and cannot enable another one;
  • in the path, ? and # are escaped, so a value cannot start a query string.

A placeholder that stands for the whole URI or its scheme (ToD("${header.dest}")) is inserted as-is: the route explicitly lets exchange data choose the endpoint, so that data must come from a trusted source.

Each distinct URI keeps a started producer in the context’s producer cache, bounded to DefaultProducerCacheSize (1000) producers. Beyond that, the least recently used idle producers are stopped. Change the bound with CamelContext.SetProducerCacheSize(n) (n <= 0 = unbounded).


Recipient List

Send to multiple recipients computed at runtime.

// Recipients from header
builder.From("direct:start").
    SetHeader("recipients", "direct:a,direct:b,direct:c").
    RecipientList("${header.recipients}")

// Call the recipients concurrently, at most 5 at a time (default 10)
builder.From("direct:start").
    RecipientList("${header.recipients}").ParallelProcessing().MaxConcurrency(5).End()

Dynamic Router

Route an exchange through a sequence of endpoints resolved dynamically by calling a control function after each step. Routing ends when the function returns an empty string or nil.

// Using a Go function
builder.From("direct:start").
    DynamicRouter(func(e *gocamel.Exchange) (string, error) {
        // Decide next step based on state/content
        count, _ := e.GetProperty("step")
        e.SetProperty("step", count.(int) + 1)
        
        if count == 0 { return "direct:a", nil }
        if count == 1 { return "direct:b", nil }
        return "", nil // End routing
    })

// Using Simple Language
builder.From("direct:start").
    DynamicRouter("${header.nextEndpoint}")

How it works:

  1. Calls the control function/expression.
  2. If result is non-empty, sends exchange to that URI.
  3. Propagates output to input and repeats from step 1.

Routing Slip

Route an exchange through a dynamic sequence of endpoints. Unlike Recipient List, each step receives the output from the previous step.

// Routing slip from a header
builder.From("direct:start").
    RoutingSlip("${header.routingSlip}")

// Go function
builder.From("direct:start").
    RoutingSlip(func(e *gocamel.Exchange) ([]string, error) {
        return []string{"direct:validate", "direct:transform", "direct:send"}, nil
    })

Exchange Properties during Routing Slip:

PropertyTypeDescription
CamelRoutingSlipIndexintCurrent step index (0-based)
CamelRoutingSlipSizeintTotal number of routing steps
CamelRoutingSlipCompleteboolLast step indicator

Control Flow

Stop

Stop routing without error.

builder.From("direct:start").
    Choice().
        When("${header.skip} == true").
            Log("Skipping").
            Stop().
        Otherwise().
            To("direct:process").
    EndChoice()

Note: Subsequent processors won’t be executed. Unlike Filter, Stop() ends the whole exchange (it sets the CamelRouteStop property): a route that called this one through direct: stops too, and its Send returns ErrStopRouting.


Loop

Iterate a route segment a static or dynamic number of times.

// Static count
builder.From("direct:start").
    Loop(3).
        ProcessFunc(func(e *gocamel.Exchange) error {
            // Evaluated 3 times
            idx, _ := e.GetPropertyAsInt(gocamel.CamelLoopIndex)
            size, _ := e.GetPropertyAsInt(gocamel.CamelLoopSize)
            fmt.Printf("Processing loop index %d of %d\n", idx, size)
            return nil
        }).
    End().
    To("direct:output")

// Dynamic count from a Simple Language expression
builder.From("direct:start").
    LoopSimple("${header.LoopCount}").
        To("direct:process-item").
    End()

// Dynamic count from a Go function
builder.From("direct:start").
    LoopFunc(func(e *gocamel.Exchange) (int, error) {
        val, _ := e.GetHeaderAsInt("X-Max-Retries")
        return val, nil
    }).
        To("direct:retry-attempt").
    End()

Exchange Properties during Loop:

PropertyTypeDescription
CamelLoopIndexintCurrent iteration index (0-based)
CamelLoopSizeintTotal number of loop iterations
CamelLoopCompleteboolBoolean indicating if this is the last iteration

Note: Stop() inside a loop ends routing of the exchange: the steps after End() do not run. Any other stop signal raised in the loop body (Filter, Sample…) only ends the loop, and routing carries on after End().


Message Headers

SetHeader

// Set header directly
builder.SetHeader("X-Request-ID", uuid.New().String())

// Set header via Simple Language
builder.SimpleSetHeader("X-Timestamp", "${date:now}")

// Set multiple headers
builder.SetHeaders(map[string]any{
    "X-Trace-ID": traceId,
    "X-Request-Id": requestId,
})

// Set via function
builder.SetHeadersFunc(func(e *gocamel.Exchange) (map[string]any, error) {
    return map[string]any{
        "X-Generated": generateId(),
    }, nil
})

RemoveHeader

// Remove specific header
builder.RemoveHeader("X-Temp-ID")

// Remove by pattern
builder.RemoveHeaders("X-Debug*")

// Remove with exclusions
builder.RemoveHeaders("X-*", "X-Keep-This")

Exchange Properties

SetProperty

Exchange-scoped variables (not in message).

builder.SetProperty("correlationId", "abc-123")

builder.SetPropertyFunc("timestamp", func(e *gocamel.Exchange) (any, error) {
    return time.Now().UnixMilli(), nil
})

RemoveProperty

builder.RemoveProperty("temp")

builder.RemoveProperties("processing*")

Error Handling

Do-Try-Catch-Finally

Structured error handling within a route.

builder.From("direct:start").
    DoTry().
        To("http://unstable-service").
    DoCatch("connection refused").
        Log("Service is down, applying recovery").
        To("direct:recovery").
    DoCatch(""). // Catch all other errors
        Log("Unexpected error: ${exchangeProperty.CamelExceptionCaught}").
        To("direct:error-handler").
    DoFinally().
        Log("Processing finished (success or failure)").
    End().
    To("direct:next")

How it works:

  1. Executes the processors in the DoTry block.
  2. If an error occurs, it searches for a matching DoCatch block (empty string matches any error).
  3. If a match is found, the error is considered “handled” and routing continues after the DoTry block (unless the catch block itself fails).
  4. The DoFinally block is always executed, regardless of whether an error occurred or was caught.

Route error handler and Dead Letter Channel

A route-level ErrorHandler receives every error a step returns. Its return value drives the route:

  • nil asks the route to retry the failed step (redelivery). It does not mean “ignore the error and continue”: the route gives up after MaxErrorHandlerRetries (10000) consecutive retries of the same step and returns an error wrapping ErrTooManyRetries.
  • an error wrapping ErrStopRouting ends routing without failing the exchange.
  • any other error fails the exchange.

DeadLetterChannel retries up to MaxRedeliveries, then sends the exchange to the dead letter endpoint and, by default, still returns the original error to the consumer (the HTTP consumer answers 500). With DeadLetterHandled(true) a dead-lettered exchange counts as handled, as in Apache Camel:

builder.From("http://0.0.0.0:8080/orders").
    DeadLetterChannel("seda:dead", gocamel.MaxRedeliveries(3), gocamel.DeadLetterHandled(true)).
    To("direct:process")

OnException

OnException declares route-scoped handlers selected by error type, like Apache Camel’s onException. Each clause lists one or more targets:

  • an error value (a sentinel such as io.EOF) matches with errors.Is;
  • a non-nil pointer to an error or interface type matches with errors.As: gocamel.ErrorType[*MyError]() (same as new(*MyError)), &MyValueError{} for a value-receiver error, gocamel.ErrorType[net.Error](). A &MyError{} whose Error method has a pointer receiver is an error value and only matches itself.

A missing, nil or unsupported target fails Build().

builder.
    OnException(gocamel.ErrorType[*ValidationError]()).
        Handled(true).
        SetBody("invalid order").
    End().
    OnException(io.ErrUnexpectedEOF, syscall.ECONNRESET).
        MaximumRedeliveries(3).
        RedeliveryDelay(100 * time.Millisecond).
        To("direct:recovery").
    End().
    From("direct:orders").
    To("http://backend/orders")

How it works:

  1. When a top-level route step fails, the clauses are tried in declaration order and the first matching one wins: declare specific clauses first.
  2. A matched clause replaces the route’s ErrorHandler for that error. The failed step is redelivered up to MaximumRedeliveries times (default 0), waiting RedeliveryDelay (default 1 s) multiplied by BackOffMultiplier (default 2, use 1 for a fixed delay) at each attempt, capped by MaximumRedeliveryDelay (default 60 s). The wait aborts when the exchange’s context is cancelled.
  3. If the step still fails, the clause’s processors (Process, ProcessFunc, To, SetBody, SetHeader, Log) run on the message the step received, with the CamelExceptionCaught, CamelRedeliveryCounter and CamelFailureRouteId properties set.
  4. Then:
    • Handled(true): routing stops (no further route step runs) and no error reaches the consumer or sender, which receives the exchange as left by the handler. The route returns an error wrapping ErrStopRouting and the original error.
    • Continued(true): routing continues with the next step as if the error had not occurred; that step receives the handler’s output. Continued takes precedence over Handled.
    • neither (default): the original error propagates.
  5. If a handler processor fails, its error (wrapping the original one) is returned instead.

Unmatched errors keep the ErrorHandler/DeadLetterChannel behaviour. An exchange already dead-lettered (IsDeadLettered), e.g. by a route called via direct: that propagates the original error, never triggers a clause: its failure has already been taken care of.

Limitations: clauses are route-scoped (no context-wide OnException yet), match errors returned by top-level steps only β€” a redelivery re-runs the whole top-level step, e.g. a whole Split block β€” and have no OnWhen predicate.


Transactions & Sagas

Saga

The Saga EIP provides a mechanism to coordinate a series of local transactions across distributed services without locking databases. It defines a set of actions and their corresponding compensating actions (rollbacks).

If any action in the Saga block fails or returns an error, the Saga orchestrator automatically triggers the compensating steps for all completed actions in reverse order (LIFO - Last In, First Out). Action panics are recovered and treated as failures (compensations still run). ErrStopRouting from an action stops the saga without compensation β€” it is a control signal, not a failure.

builder.From("direct:saga-route").
    Saga().
        // Action 1: Reserve Hotel. Compensation 1: Cancel Hotel.
        Action("direct:reserve-hotel", "direct:cancel-hotel").
        // Action 2: Reserve Flight. Compensation 2: Cancel Flight.
        Action("direct:reserve-flight", "direct:cancel-flight").
    End().
    To("direct:saga-completed")

You can also use custom Go functions for actions and compensations directly using ActionFunc:

builder.From("direct:saga-route").
    Saga().
        ActionFunc(
            func(e *gocamel.Exchange) error {
                // Reserve booking
                return nil
            },
            func(e *gocamel.Exchange) error {
                // Cancel/compensate booking
                return nil
            },
        ).
    End()

A nil compensation in ActionFunc means the step has nothing to undo.

Persistent saga state and recovery

Each saga runs under an ID taken from the CamelSagaId header (a UUID is generated and set on the header when it is absent). After every action whose step has a compensation, the saga checkpoints its state to a SagaRepository: the list of pending compensations plus a snapshot of the In message (body and headers). It saves again after each compensation, and removes the state once the saga has completed or been fully compensated. A compensation that fails stays in the repository so a later recovery can retry it.

db, _ := sql.Open("sqlite", "sagas.db") // any database/sql driver
repo := gocamel.NewSQLSagaRepository(db, gocamel.SQLSagaOptions{}) // table gocamel_sagas
_ = repo.InitDB(context.Background())

builder.From("direct:saga-route").
    Saga().
        Repository(repo).              // default: in-memory (lost on process exit)
        Timeout(5 * time.Second).      // bound on each action and compensation
        RecoverIncomplete(true).       // opt-in recovery at CamelContext.Start
        Action("direct:reserve-hotel", "direct:cancel-hotel").
        Action("direct:reserve-flight", "direct:cancel-flight").
    End()
OptionDefaultEffect
Repository(repo)MemorySagaRepositoryWhere the state is persisted. SQLSagaRepository (root module, database/sql only β€” bring your own driver) survives a process crash.
Timeout(d)0 (none)Bounds each action and each compensation. An action exceeding it fails with ErrSagaStepTimeout (wrapping context.DeadlineExceeded) and the completed steps are compensated; the timed-out step itself is not, as for any failed step. The step runs on a copy of the exchange whose Context carries the deadline: a step that ignores its context keeps running in the background after the timeout, and its result is discarded.
RecoverIncomplete(true)offAt CamelContext.Start, once every route is started, incomplete sagas found in the repository are compensated last step first. When off, each incomplete saga is only logged as a warning telling how to enable recovery.

Recovery sends each compensation to its URI through the context’s producer cache, with an exchange rebuilt from the last checkpoint’s message and the CamelSagaId header. SagaProcessor.Recover(ctx, camelCtx) runs it on demand. Sagas still running in the current process are never recovered.

Warning

Only compensations declared by endpoint URI survive a process restart. A compensation passed to ActionFunc is a Go function: it cannot be serialised, so after a restart there is nothing to rebuild it from. Such steps are still persisted (as InProcessCompensation), and when recovery meets one it reports ErrSagaCompensationNotRecoverable in an ERROR log line naming the saga and step β€” it never skips it silently β€” and keeps it in the repository, status COMPENSATING, for manual handling. The remaining URI compensations of that saga still run. Declare steps that must be recoverable with Action(actionURI, compensationURI).

Delivery guarantees. The checkpoint is written after the action returns and before the next action starts. A crash between an action and its checkpoint loses that step (its compensation does not run on recovery); a crash after a compensation and before the state update runs that compensation again. Compensation on recovery is therefore at-least-once for checkpointed steps: compensations must be idempotent. If a checkpoint cannot be saved, the saga fails and compensates its completed steps, including the one just completed.

Persistence format. SQLSagaRepository stores the state as JSON (saga_id, status, state, updated_at as Unix nanoseconds): message body and header values must be JSON-serialisable and come back as JSON types (numbers as float64, []byte as a base64 string). ListIncomplete returns at most DefaultSagaListLimit (1000) sagas, oldest first; the rest are picked up by a later start once earlier ones are resolved.

Limits. A saga nested in another saga’s action gets its own ID (the enclosing saga’s header is restored afterwards); sagas are not propagated or joined across routes. Recovery does not coordinate several processes sharing one database: enable RecoverIncomplete on a single instance, otherwise one process may compensate a saga another is still running.


Message Tracking & Diagnostics

Message History

The Message History EIP enables tracing the chronological journey of a message as it flows through the various route nodes and processors.

To enable tracking for a route, invoke .EnableMessageHistory() on your route builder. You can then retrieve and inspect the history using gocamel.GetMessageHistory(exchange).

// 1. Enable tracking in the route definition
builder.From("direct:start").
    EnableMessageHistory().
    SetBody("Hello GoCamel").
    TransformSimple("Modified: ${body}").
    To("direct:output")

// 2. Retrieve history inside a downstream processor
builder.From("direct:output").
    ProcessFunc(func(e *gocamel.Exchange) error {
        history := gocamel.GetMessageHistory(e)
        for i, entry := range history {
            fmt.Printf("[%d] Route: %s | Processor: %T | Time: %s\n", 
                i, entry.RouteID, entry.Processor, entry.Timestamp.Format(time.RFC3339))
        }
        return nil
    })

EIP Pattern Summary

PatternCategoryDescription
ChoiceRoutingContent-based routing
FilterRoutingConditional filtering
Idempotent ConsumerRoutingPrevent duplicate messages
Circuit BreakerRoutingResilience pattern for failures
Load BalancerRoutingLoad distribution across endpoints
Dynamic RouterRoutingDynamic decision-based routing
ResequencerRoutingReorder messages by sequence
Claim CheckRoutingStore payload and pass reference
ThrottleRoutingRate limiting
DelayRoutingPause before next step
SampleRoutingKeep a sample, drop the rest
MulticastRoutingMultiple destinations
Recipient ListRoutingDynamic recipient routing
Routing SlipRoutingDynamic sequential routing
Wire TapRoutingAsync fire-and-forget copy
SplitTransformationMessage splitting
AggregateTransformationMessage aggregation
Content EnricherTransformationEnrich with external data
TransformTransformationContent transformation
ToDEndpointDynamic endpoint
StopControlStop routing
DoTryControlTry-Catch-Finally error handling
SetHeaderHeadersHeader manipulation
SetPropertyPropertiesExchange properties
LoopControlIterate with static/dynamic counter
SagaControlSaga transactional pattern
Message HistoryDiagnosticsTrack message processing trace

Branch completion and aggregation

Split, Multicast and RecipientList complete each processed branch on success or failure, including idempotency rollback callbacks. Parallel branches copy supported mutable bodies, including each split part, before workers start. Custom mutable types still require application-defined copying or immutable use. Workers finish before aggregation begins; the strategy is called serially in input order, and strategy panics become ErrProcessorPanic errors. Sequential processing stops at the first failing branch. A parallel Split or RecipientList runs at most MaxConcurrency(n) branches at a time (default DefaultMaxConcurrency, 10): both expand from message content, so an unbounded fan-out would start one goroutine per element. A parallel Multicast runs all its branches at once, their number being fixed by the route.

Invalid Resequence expressions accumulate a build error while leaving the DSL chain usable; Timeout, Capacity and End do not panic because an earlier expression was invalid.