v0.16.0

Version v0.16.0, dated October 5, 2026, is a feature release: the mock component and route advice for testing routes, OnException per-error-type handlers, and a persistent Saga with per-step timeout and opt-in crash recovery. It contains no breaking change.

Upgrade

Upgrade the core and each optional module you use together:

go get gitlab.com/tranchida/gocamel@v0.16.0
go get gitlab.com/tranchida/gocamel/components/kafka@v0.16.0

Every component and observability module at v0.16.0 requires core v0.16.0.

Mock component and route advice

The new mock component (stdlib, registered by default) is a producer-only endpoint that records a deep-copied snapshot of every exchange sent to it. Route.AdviceWith replaces static To() endpoint URIs of a built route before Start(), so a test can swap real endpoints for mocks without rebuilding the route:

func TestOrderRoute(t *testing.T) {
    ctx := gocamel.NewCamelContext()
    route, err := ctx.CreateRouteBuilder().
        From("direct:in").
        SetHeader("source", "test").
        To("kafka:orders").
        Build()
    require.NoError(t, err)

    // Swap the real endpoint for a mock between Build and Start.
    require.NoError(t, route.AdviceWith(map[string]string{"kafka:orders": "mock:orders"}))

    mock, err := ctx.GetMockEndpoint("mock:orders")
    require.NoError(t, err)
    mock.ExpectedMessageCount(1) // at least 1

    require.NoError(t, ctx.Start())
    t.Cleanup(func() { _ = ctx.Stop() })

    producer, err := ctx.GetProducer("direct:in")
    require.NoError(t, err)
    exchange := gocamel.NewExchange(context.Background())
    exchange.In.SetBody("order-1")
    require.NoError(t, producer.Send(exchange))

    require.NoError(t, mock.Wait(time.Second))
    assert.Equal(t, "order-1", mock.Body(0))
    source, _ := mock.Header(0, "source")
    assert.Equal(t, "test", source)
}

AdviceWith also substitutes multicast, Choice, LoadBalancer and Saga branches. It returns an error once the route is started, ignores unknown URIs, and does not substitute From(), ToD or other dynamic sends. See the components page for the full MockEndpoint API.

OnException

RouteBuilder.OnException(targets...) declares route-scoped error handlers selected by error type, like Apache Camel’s onException. Error values match with errors.Is; non-nil pointers to error or interface types (gocamel.ErrorType[*MyError]()) match with errors.As. The first matching clause in declaration order wins and replaces the route’s ErrorHandler for that error:

ctx.CreateRouteBuilder().
    OnException(gocamel.ErrorType[*ValidationError]()).
        Handled(true).              // stop routing, no error to the sender
        SetBody("invalid order").
        To("direct:invalid").
    End().
    OnException(io.ErrUnexpectedEOF).
        MaximumRedeliveries(3).     // redeliver the failed step
        RedeliveryDelay(100 * time.Millisecond).
        BackOffMultiplier(2).
        MaximumRedeliveryDelay(2 * time.Second).
        To("direct:recovery").
    End().
    From("direct:orders").
    To("http://backend/orders")

The failed step is redelivered first, then the clause’s processors run. Handled(true) stops routing without returning an error to the sender; Continued(true) resumes with the next step. Unmatched errors and already dead-lettered exchanges keep the existing ErrorHandler/DeadLetterChannel behaviour. A missing or invalid target fails Build(). Context-scoped clauses and OnWhen are not supported yet. See the EIP page for details.

Persistent Saga

The Saga EIP now checkpoints its state to a SagaRepository after each completed step and each compensation, keyed by the CamelSagaId header (a UUID is generated when absent). MemorySagaRepository is the default; SQLSagaRepository (root module, database/sql only, table gocamel_sagas) survives a process crash:

db, err := sql.Open("sqlite", "sagas.db") // any database/sql driver
if err != nil {
    return err
}
repo := gocamel.NewSQLSagaRepository(db, gocamel.SQLSagaOptions{})
if err := repo.InitDB(context.Background()); err != nil {
    return err
}

ctx.CreateRouteBuilder().
    From("direct:booking").
    Saga().
        Repository(repo).          // default: in-memory, lost on exit
        Timeout(5 * time.Second).  // bounds each action and compensation
        RecoverIncomplete(true).   // compensate leftovers at CamelContext.Start
        Action("direct:reserve-hotel", "direct:cancel-hotel").
        Action("direct:reserve-flight", "direct:cancel-flight").
    End().
    To("direct:booked")
  • Timeout(d): an action exceeding it fails with ErrSagaStepTimeout and the completed steps are compensated.
  • RecoverIncomplete(true) (opt-in): at CamelContext.Start, incomplete sagas are compensated last step first. When off, they are only logged as warnings. SagaProcessor.Recover(ctx, camelCtx) runs a recovery on demand.
  • A failed compensation stays in the repository for the next recovery. Compensation on recovery is at-least-once: compensations must be idempotent.
  • Enable RecoverIncomplete on a single instance when several processes share one database.
Warning

Only compensations declared by URI (Action(actionURI, compensationURI)) are recoverable after a restart. A Go function cannot be persisted: when recovery finds an ActionFunc compensation, it reports ErrSagaCompensationNotRecoverable in an ERROR log line (never skipped silently) and keeps the saga in the repository for manual handling. Declare every step that must survive a crash with Action.

Fixed

  • Saga: ActionFunc(action, nil) no longer registers a nil function as a compensation (which panicked, recovered, when the step had to be compensated); a nil compensation now means the step has nothing to undo.

See the CHANGELOG for the full list.

Upgrade notes

No breaking change: existing routes behave as in v0.15.0. Sagas use an in-memory repository by default, which keeps the previous in-process behaviour; the only visible difference is the CamelSagaId header, set on the exchange when it is absent.

Upgrading from v0.14.x? v0.15.0 made the Anthropic and Ollama header overrides require allowHeaderOverride=true: read the v0.15.0 release notes first.